livepilot 1.26.0 → 1.26.1

package/livepilot/skills/livepilot-arrangement/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: livepilot-arrangement
+description: Constructive arrangement — actually building song structure in Ableton. Use when the user asks to "arrange", "structure a song", "add an intro", "build a verse", "create sections", "scene to arrangement", "record to arrangement", or wants to place clips on the timeline or organize scenes. For analysis of existing structure ("improve transitions", "detect motifs", "analyze composition"), use livepilot-composition-engine instead.
+---
+
+# Arrangement — Song Structure and Session Organization
+
+Organize clips into scenes, build arrangements on the timeline, navigate with cue points, and record performances in Ableton Live.
+
+## Session View vs Arrangement View
+
+Ableton has two complementary views:
+
+- **Session view** — a grid of clip slots organized by track (columns) and scene (rows). Clips loop independently. Fire scenes to trigger rows of clips simultaneously. Use for jamming, live performance, and building ideas.
+- **Arrangement view** — a linear timeline where clips play in sequence from left to right. Use for final song structure, recording automation, and export.
+
+Use `back_to_arranger` to switch from session playback to arrangement playback. When session clips are playing, they override arrangement content on their tracks.
+
+## Scene Workflow
+
+Scenes are horizontal rows in session view. Each scene can trigger all its clips at once.
+
+### Creating and Managing Scenes
+
+- `create_scene(index)` — insert a new scene at the given position
+- `set_scene_name(scene_index, name)` — name scenes after song sections: "Intro", "Verse 1", "Chorus", "Bridge", "Drop", "Outro"
+- `set_scene_color(scene_index, color_index)` — color-code sections (0-69 palette). Use consistent colors: green for verses, red for choruses, blue for bridges.
+- `set_scene_tempo(scene_index, tempo)` — set a per-scene tempo change (triggers when scene fires)
+- `duplicate_scene(scene_index)` — copy a scene for variations. Duplicate, rename, then modify clips in the copy.
+- `delete_scene(scene_index)` — remove a scene
+
+### Firing and Monitoring
+
+- `fire_scene(scene_index)` — launch all clips in a scene simultaneously
+- `fire_scene_clips(scene_index)` — launch only the clips that exist in a scene (skips empty slots)
+- `stop_all_clips` — stop everything in session view
+- `get_playing_clips` — see which clips are currently playing across all tracks
+
+### Scene Inspection
+
+- `get_scenes_info` — list all scenes with names, tempos, and colors
+- `get_scene_matrix` — see which clips exist in which slots across the entire session grid. Returns a track-by-scene matrix showing clip presence, names, and states.
+
+## Arrangement View
+
+Build linear song structures on the timeline.
+
+### Creating Arrangement Clips
+
+- `create_arrangement_clip(track_index, clip_slot_index, start_time, length)` — duplicate a session clip into Arrangement View at a specific beat position
+- `create_native_arrangement_clip(track_index, start_time, length)` — create arrangement clip with full automation envelope (12.1.10+)
+- `set_arrangement_clip_name(track_index, clip_index, name)` — name arrangement clips for clarity
+- `force_arrangement()` — force all tracks to play from arrangement (not session clips)
+
+### Arrangement Notes
+
+- `add_arrangement_notes(track_index, clip_index, notes)` — write MIDI notes into an arrangement clip
+- `get_arrangement_notes(track_index, clip_index)` — read notes from an arrangement clip
+- `remove_arrangement_notes(track_index, clip_index, start_time, duration, pitch_start, pitch_end)` — clear notes in a region
+- `remove_arrangement_notes_by_id(track_index, clip_index, note_ids)` — surgical deletion
+- `modify_arrangement_notes(track_index, clip_index, modifications)` — update existing notes by ID
+- `duplicate_arrangement_notes(track_index, clip_index, time_offset)` — copy notes forward
+- `transpose_arrangement_notes(track_index, clip_index, semitones, start_time, duration)` — pitch shift a region
+
+### Arrangement Clips Inspection
+
+- `get_arrangement_clips(track_index)` — list all clips on a track's arrangement timeline with positions, lengths, and names
+
+### Arrangement Automation
+
+- `set_arrangement_automation(track_index, parameter_name, points)` — write automation on the arrangement timeline. Points are `[{time, value}, ...]` pairs at absolute beat positions.
+
+**Live LOM limitation (BUG-2026-04-22 #1b):** `set_arrangement_automation` only succeeds on arrangement clips that *already* have an envelope for the target parameter (typically clips recorded interactively or duplicated from session). For programmatically-created arrangement clips (via `create_arrangement_clip` or `create_native_arrangement_clip`), the Python LOM does NOT expose a path to create new automation breakpoints — this is a Live API limitation, not a LivePilot bug. Live's docs explicitly state `Clip.automation_envelope` returns None for arrangement clips, and only `value_at_time` exists for reading.
+
+When the tool errors with "Direct envelope access is not supported for programmatically-created arrangement clips," reach for one of two patterns:
+
+1. **Session-clip + record path** (programmatic + manual record):
+   - Build the automation on a session clip via `set_clip_automation` (works fully — session clips support `create_automation_envelope`).
+   - Tell the user: arm the track, switch to arrangement view, start recording at the target position, fire the session clip, stop recording when it completes. Live records the parameter changes into the arrangement track lane.
+
+2. **Section-clip path** (no envelope, stepped values):
+   - Slice the arrangement into multiple clips at section boundaries.
+   - Set per-clip volume / parameter values per section using regular `set_track_volume` or `set_device_parameter` between clips.
+   - Trades smooth automation for discrete steps but works fully programmatically.
+
+For sweeps that absolutely need to be smooth and programmatic (filter cutoff arcs, send swells), use pattern 1 and accept that the agent has to hand off the record step to the user.
+
+## Navigation
+
+### Transport Position
+
+- `jump_to_time(beat_time)` — move the playback cursor to a specific beat position on the timeline
+- `start_playback` / `stop_playback` / `continue_playback` — basic transport control
+
+### Cue Points
+
+Cue points are markers on the arrangement timeline for quick navigation.
+
+- `toggle_cue_point` — add or remove a cue point at the current playback position
+- `get_cue_points` — list all cue points with their beat positions and names
+- `jump_to_cue(cue_index)` — jump to a specific cue point by index
+
+Use cue points to mark section boundaries: place one at beat 0 (Intro), beat 16 (Verse), beat 48 (Chorus), etc. This makes navigation fast during arrangement.
+
+## Recording
+
+### Live Recording
+
+- `start_recording` — begin recording into the arrangement or session (depends on which view is active and which tracks are armed)
+- `stop_recording` — stop recording
+- `capture_midi` — retroactive MIDI capture. Grabs whatever was played on armed MIDI tracks even if recording was not active. Live 12 keeps a buffer of recent MIDI input.
+
+### Recording Workflow
+
+1. Arm tracks with `set_track_arm(track_index, arm=true)`
+2. Optionally set input monitoring with `set_track_input_monitoring(track_index, mode)`
+3. `start_recording` — records into arrangement if in arrangement view, into session slots if in session view
+4. Play or trigger clips
+5. `stop_recording` — finalize the take
+
+For retroactive capture: if the user just played something without recording, call `capture_midi` immediately to grab it.
+
+## Section Analysis
+
+- `get_section_graph` — infer song structure from scene names and clip arrangement. Returns a graph of sections with their relationships, durations, and transitions.
+- `analyze_composition` — deeper structural analysis including phrase lengths, repetition patterns, and harmonic arcs
+- `get_phrase_grid` — see how phrases align across tracks
+
+Use `get_section_graph` to understand the current form before adding new sections. It helps identify what is missing (e.g., no bridge, no outro, chorus only appears once).
+
+## Common Song Structures
+
+When building arrangements, use these as starting templates:
+
+- **Pop:** Intro - Verse - Chorus - Verse - Chorus - Bridge - Chorus - Outro
+- **EDM/Dance:** Intro (16 bars) - Build - Drop (16) - Break (8) - Build - Drop (16) - Outro (8)
+- **Hip-hop:** Intro - Verse (16 bars) - Hook (8) - Verse (16) - Hook (8) - Bridge - Hook - Outro
+- **Lo-fi:** Intro (4) - A (8) - B (8) - A (8) - B variation (8) - Outro (4)
+
+Adapt these to the user's needs. Use `plan_arrangement` from the planner domain for algorithmic structure suggestions, and `transform_section` to create variations of existing sections.
+
+## Section-Aware Sample Roles
+
+`plan_arrangement` returns `sample_hints` per section — suggested roles for sample-based elements:
+
+| Section | Default Hints |
+|---------|--------------|
+| Intro | `texture_bed`, `fill_one_shot` |
+| Verse | `texture_bed`, `fill_one_shot` |
+| Build | `transition_fx`, `texture_bed` |
+| Chorus/Drop | `hook_sample`, `break_layer`, `fill_one_shot` |
+| Bridge/Breakdown | `texture_bed`, `transition_fx` |
+| Outro | `texture_bed`, `fill_one_shot` |
+
+Use `plan_sample_workflow(section_type=..., desired_role=...)` to generate concrete sample plans for each role. Use `plan_slice_workflow(intent=..., target_section=...)` for slice-based patterns.
+
+## When to hand off to composition-engine
+
+This skill covers **constructive** arrangement. For analytical work — scoring a proposed move, analyzing transitions, inspecting the harmony field, detecting motifs, transforming sections — invoke `livepilot-composition-engine`. Don't re-implement its tools here; they are documented there with full context.
+
+## Reference
+
+Supporting references live in the `livepilot-core` skill's `references/` directory:
+- `livepilot-core/references/ableton-workflow-patterns.md` — session/arrangement workflows, song structures by genre, follow actions, clip launch modes, export settings

package/livepilot/skills/livepilot-composition-engine/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: livepilot-composition-engine
+description: Compositional analysis, transition planning, and translation checking — the diagnostic/analytical side of form. Use when the user wants to "analyze song structure", "improve transitions", "check song flow", "detect motifs", "transform a section", or "score phrase impact". For constructive arrangement work (arrange, build a verse, add an intro, scene-to-arrangement), use livepilot-arrangement instead.
+---
+
+# Composition Engine — Structure, Transitions, and Form
+
+The composition engine operates three sub-engines: compositional analysis (structure and motifs), transition planning (section-to-section flow), and translation checking (how the mix survives different playback systems). It also provides form-level tools for emotional arc and arrangement planning.
+
+## Atlas-first reflex (v1.23.x+, MANDATORY before any creative move)
+
+Before producing ANY creative response, query the user's atlas overlays. The corpus contains 337 entries across 3 namespaces, plus 3,917 parameter-level JSON sidecars — far richer than anything inferable from training data alone.
+
+**Query order:**
+
+1. **`extension_atlas_search(namespace="packs", query=<intent>)`** — pack identity, signature workflows, hidden gems, anti-patterns, notable presets with macro deep-data, demo projects
+2. **`extension_atlas_search(namespace="packs", query=<intent>, entity_type="cross_pack_workflow")`** — multi-pack signature recipes (15 entries: dub-techno spectral drone bed, BoC decayed pad, Mica Levi orchestral dread, etc.)
+3. **`extension_atlas_search(namespace="m4l-devices", query=<sonic descriptor>)`** — M4L instrument/effect/midi-effect device catalog (155 entries)
+4. **`atlas_search(...)`** — bundled atlas (Core Library, fallback)
+
+**Multi-grain traversal:**
+
+When an aesthetic-level query lands a pack-level result, AUTO-DRILL: pack → its `notable_presets` → those preset macro states → load via `load_browser_item`. Don't stop at "I found a relevant pack" — drill to the actual preset/parameter level the user can immediately use.
+
+```python
+# Example — agent received "evolving polyrhythmic ambient at 120 BPM, build the section arc"
+hit = extension_atlas_search(namespace="packs", query="evolving polyrhythmic ambient generative")
+# → midi_tools_by_philip_meyer + drone_lab + cross-pack workflows for generative form
+
+workflow = extension_atlas_get("packs", "dub_techno_spectral_drone_bed")
+# → reveals signal_flow: HDG → PitchLoop89 cross-feedback → Convolution Reverb
+
+drone_lab = extension_atlas_get("packs", "drone_lab")
+# → notable_presets reveals Razor Wire Drone with macros Filter Control=108, Movement=53...
+
+# Now plan the section/transition with concrete preset names + macro values, not vague descriptions
+```
+
+**When the user mentions a producer or pack by name:**
+
+- "BoC sublime pad" → atlas hit: `boc_decayed_pad` cross-pack-workflow + `inspired_by_nature` pack
+- "Henke spectral chain" → atlas hit: `pitchloop89` + `granulator_iii` + 2 Henke cross-pack workflows
+- "Mica Levi orchestral dread" → atlas hit: `mica_levi_orchestral_dread` workflow + the orchestral suite packs
+- "Drone Lab" → atlas hit: `drone_lab` pack + 4 Drone Lab demo_project entries
+
+The atlas knows the user's installed library at parameter depth. **Producer-anchor queries land specific moves, not vague descriptions.**
+
+**Anti-pattern surfacing:**
+
+Every pack entry has an `anti_patterns` body field listing "don't reach for this when X." Surface the relevant anti-pattern when proposing a move so the user knows the move's domain. (E.g. "Drone Lab is sustain-only — don't use for percussive content.")
+
+**For deliberately rule-breaking creative requests** ("eclectic", "ignore the limits", "weird combo", "mix incompatible aesthetics"): enter **Eclectic Mode** inside this composition loop. Anti-patterns become prompt tension rather than guardrails: keep hard safety and protected-user constraints, then pair one normally-avoided formal idea with one identity-preserving anchor. Do not route to a private or missing skill.
+
+## Composition Sub-Engine
+
+Analyze and transform the structural elements of a track.
+
+### Analysis Flow
+
+1. Call `analyze_composition` — runs a full structural pass returning sections, motifs, phrase grid, and form classification
+2. Call `get_section_graph` — returns the section map: intro, verse, chorus, bridge, drop, breakdown, outro with bar ranges
+3. Call `get_phrase_grid` — returns the rhythmic and melodic phrase boundaries within each section
+4. Call `get_motif_graph` — returns detected melodic and rhythmic motifs with their occurrence locations and transformation history
+
+### Transformation
+
+Once you understand the structure:
+
+- `transform_motif(motif_id, transformation)` — apply a transformation to a detected motif. Transformations include: inversion, retrograde, augmentation, diminution, transposition, fragmentation, sequence
+- `transform_section(section_id, transformation)` — apply a structural transformation to an entire section. Transformations include: extend, compress, strip_down, build_up, reharmonize, rhythmic_variation
+
+Always capture before state with `get_notes` or `get_arrangement_notes` before transforming. Evaluate the result with `evaluate_composition_move`.
+
+### Motif Work
+
+The motif graph tracks recurring melodic and rhythmic patterns:
+
+- Each motif has an `id`, `pitches`, `rhythms`, `first_occurrence`, and `occurrences` list
+- Related motifs are linked by transformation edges (e.g., motif_2 is an inversion of motif_1)
+- Use the motif graph to ensure thematic coherence — transformations should derive from existing material
+
+## Transition Sub-Engine
+
+Plan and execute smooth transitions between sections.
+
+### Transition Flow
+
+1. `analyze_transition(from_section, to_section)` — examine the current transition between two sections. Returns energy delta, timbral shift, harmonic distance, and detected issues
+2. `plan_transition(from_section, to_section)` — generate a transition plan based on detected issues. Returns an ordered list of moves (filter sweeps, risers, drum drops, fills, automation curves)
+3. `score_transition(from_section, to_section)` — rate the current transition quality (0.0-1.0) with breakdown by energy, harmony, rhythm, and timbral continuity
+4. Execute the planned moves using appropriate tools (`set_clip_automation`, `add_notes`, `set_device_parameter`, `apply_automation_shape`)
+5. `evaluate_composition_move` — judge whether the transition improved
+
+See `references/transition-archetypes.md` for common transition patterns and when to use each.
+
+### Transition Principles
+
+- Energy changes should be gradual unless a hard cut is intentional
+- Harmonic transitions need a pivot chord or shared tone
+- Rhythmic transitions benefit from a fill or break at the boundary
+- Timbral shifts should start 1-2 bars before the section change
+- The most effective transitions prepare the listener's ear before the change lands
+
+## Translation Sub-Engine
+
+Check how the mix translates across playback systems.
+
+### Translation Flow
+
+1. `check_translation` — run translation analysis on the current mix
+2. `get_translation_issues` — return specific problems:
+   - **mono_collapse**: elements that disappear or phase-cancel in mono playback
+   - **spectral_consistency**: frequency balance shifts between monitoring contexts
+   - **low_end_translation**: bass content that may vanish on small speakers
+   - **loudness_consistency**: perceived loudness variation across systems
+
+Translation issues feed back into the mix engine — a mono collapse issue becomes a stereo_width critic issue for the mix loop.
+
+## Form Sub-Engine
+
+High-level arrangement and emotional arc tools.
+
+### Form Flow
+
+1. `get_emotional_arc` — map the energy/intensity curve across the entire track, identifying peaks, valleys, and plateaus
+2. `plan_arrangement` — generate an arrangement plan based on the current form, suggesting section order, lengths, and energy targets
+3. `apply_gesture_template` — apply a predefined arrangement gesture (build, drop, breakdown, outro_fade, intro_build) to a bar range
+
+See `references/form-patterns.md` for common song forms and energy curves by genre.
+
+### Arrangement Principles
+
+- Every section should have a clear purpose: introduce, develop, contrast, resolve, release
+- The energy arc should have at least one clear peak — flat energy across the entire track lacks emotional impact
+- Contrast drives interest: loud/quiet, dense/sparse, bright/dark
+- Repetition builds familiarity but needs variation to avoid fatigue — transform on repeat, do not copy verbatim
+- Transitions are as important as sections — budget time for them in the arrangement
+
+## Combining Sub-Engines
+
+A typical compositional improvement session:
+
+1. `analyze_composition` to understand current structure
+2. `get_emotional_arc` to see the energy shape
+3. Identify the weakest section or transition
+4. Use the transition sub-engine to fix section boundaries
+5. Use motif transformations to add thematic development
+6. `check_translation` to verify the changes survive mono/small speakers
+7. `evaluate_composition_move` after each change
+
+Always work one change at a time. Verify and evaluate before moving to the next intervention.

package/livepilot/skills/livepilot-composition-engine/references/form-patterns.md

@@ -0,0 +1,97 @@
+# Form Patterns Reference
+
+Common song forms and energy curves used by `plan_arrangement` and `get_emotional_arc`.
+
+## Standard Forms
+
+### verse_chorus (Pop / Rock / R&B)
+```
+Intro (4-8 bars) -> Verse 1 (8-16) -> Pre-Chorus (4-8) -> Chorus 1 (8-16)
+-> Verse 2 (8-16) -> Pre-Chorus (4-8) -> Chorus 2 (8-16)
+-> Bridge (8) -> Final Chorus (8-16) -> Outro (4-8)
+```
+Energy curve: low -> medium -> high -> medium -> high -> peak -> fade
+
+### drop_form (EDM / House / Techno)
+```
+Intro (16-32 bars) -> Build 1 (8-16) -> Drop 1 (16-32)
+-> Breakdown (8-16) -> Build 2 (8-16) -> Drop 2 (16-32)
+-> Outro (8-16)
+```
+Energy curve: building -> peak -> valley -> building -> peak -> fade
+
+### through_composed (Ambient / Cinematic / Experimental)
+```
+Section A (variable) -> Section B (variable) -> Section C (variable) -> ...
+```
+No repeating sections. Energy curve follows the narrative arc. Each section introduces new material.
+
+### aaba (Jazz / Classic Pop)
+```
+A (8 bars) -> A (8) -> B (8) -> A (8)
+```
+Energy curve: establish -> reinforce -> contrast -> resolve
+
+### rondo (Classical-influenced / Progressive)
+```
+A -> B -> A -> C -> A -> D -> A
+```
+Recurring theme (A) alternates with contrasting episodes. Energy varies per episode.
+
+### loop_form (Hip-Hop / Trap / Lo-Fi)
+```
+Intro (4-8) -> Loop (4-8 bars, repeated throughout)
+Verse 1 over loop -> Hook over loop -> Verse 2 over loop -> Hook -> Outro
+```
+Energy modulation through vocal density and arrangement layering, not harmonic progression.
+
+## Energy Curve Targets
+
+The emotional arc maps energy on a 0.0-1.0 scale across the track duration.
+
+### Peak-Valley Model
+Most effective for dance and pop music:
+- At least one peak reaching 0.8-1.0
+- At least one valley dropping to 0.2-0.4
+- Energy delta between adjacent sections: 0.15-0.4
+- Gradual builds (4+ bars) feel more natural than instant jumps
+
+### Plateau Model
+For ambient, drone, and minimalist music:
+- Energy stays within a narrow band (0.3-0.6)
+- Changes are subtle: timbral, textural, not dynamic
+- Slow evolution over minutes, not bars
+
+### Escalation Model
+For builds, film scoring, and progressive tracks:
+- Monotonically increasing energy from 0.1 to 1.0
+- Each section is louder, denser, or brighter than the previous
+- No significant drops until the final resolution
+
+## Section Energy Targets by Genre
+
+| Section | Pop | EDM | Hip-Hop | Ambient |
+|---------|-----|-----|---------|---------|
+| Intro | 0.2 | 0.3 | 0.3 | 0.2 |
+| Verse | 0.4 | 0.4 | 0.5 | 0.3 |
+| Pre-Chorus | 0.6 | 0.6 | — | — |
+| Chorus/Drop | 0.8 | 1.0 | 0.7 | 0.5 |
+| Bridge | 0.5 | — | 0.4 | 0.4 |
+| Breakdown | — | 0.2 | — | 0.3 |
+| Outro | 0.3 | 0.2 | 0.2 | 0.1 |
+
+## Section Length Guidelines
+
+- **4 bars**: minimum for a recognizable section (short intros, transitions)
+- **8 bars**: standard phrase length, feels complete for most sections
+- **16 bars**: full development, typical for verses and choruses in electronic music
+- **32 bars**: extended development for drops, long builds, or ambient passages
+- **Odd lengths** (6, 10, 12 bars): create subtle tension and asymmetry — use intentionally
+
+## Arrangement Planning Rules
+
+1. Start from the emotional peak and work backwards — place the climax first, then build toward it
+2. Every section serves one of five functions: introduce, develop, contrast, climax, resolve
+3. Do not repeat a section more than 3 times without significant variation
+4. The first 30 seconds determine whether the listener stays — make them count
+5. Endings matter — an abrupt end can be intentional, but a trailing reverb wash is rarely wrong

package/livepilot/skills/livepilot-composition-engine/references/transition-archetypes.md

@@ -0,0 +1,102 @@
+# Transition Archetypes Reference
+
+Common transition patterns returned by `plan_transition` and usable with `apply_gesture_template`.
+
+## Energy-Up Transitions
+
+### riser_sweep
+A filter or noise sweep that builds energy into the next section.
+
+- Duration: 2-8 bars
+- Implementation: ascending automation on filter cutoff (20% to 100%) plus optional white noise riser
+- Best for: verse-to-chorus, breakdown-to-drop
+- Tools: `set_clip_automation`, `apply_automation_shape(track_index, clip_index, parameter_type="device", curve_type="exponential", start=0, end=1)`
+
+### drum_build
+Progressive addition of percussion layers leading to the downbeat.
+
+- Duration: 2-4 bars
+- Implementation: add hi-hat rolls (increasing density), snare fills, kick pattern intensification
+- Best for: pre-chorus builds, intro-to-verse
+- Tools: `add_notes` for fill patterns, `set_track_volume` automation for gradual volume increase
+
+### harmonic_tension
+Build tension through suspended or unresolved harmony before resolving at the section boundary.
+
+- Duration: 1-4 bars
+- Implementation: sus4 or dominant 7th chord sustained over the transition, resolving on beat 1 of the new section
+- Best for: verse-to-chorus, bridge-to-final-chorus
+- Tools: `modify_notes` to alter chord voicings, `add_notes` for tension tones
+
+### stacking
+Gradually add instrumental layers, one per bar or phrase, building density.
+
+- Duration: 4-16 bars
+- Implementation: unmute tracks in sequence (percussion first, then bass, then harmony, then leads)
+- Best for: intro builds, post-breakdown rebuilds
+- Tools: `set_clip_automation` on track volume, `set_track_mute` for discrete layer adds
+
+## Energy-Down Transitions
+
+### strip_down
+Remove elements one by one to reduce energy before a quieter section.
+
+- Duration: 2-8 bars
+- Implementation: mute layers in reverse order of importance (effects first, then leads, then harmony, keeping bass and kick last)
+- Best for: chorus-to-verse, pre-breakdown
+- Tools: `set_track_mute`, `set_track_volume` automation with gradual decrease
+
+### filter_close
+Low-pass filter sweep closing down to muffle the sound.
+
+- Duration: 2-4 bars
+- Implementation: descending automation on master or bus filter cutoff (100% to 20-30%)
+- Best for: section endings, transitions to breakdowns
+- Tools: `set_clip_automation`, `apply_automation_shape(track_index, clip_index, parameter_type="device", curve_type="exponential", start=1, end=0)`
+
+### reverb_wash
+Increase reverb wet level to blur the previous section into the next.
+
+- Duration: 1-2 bars
+- Implementation: automate send level to reverb return (0% to 60-80%), then cut dry signal on beat 1
+- Best for: hard section changes where you want continuity of space
+- Tools: `set_track_send` automation, `set_clip_automation`
+
+## Neutral Transitions
+
+### hard_cut
+Instant transition with no preparation. The contrast itself creates impact.
+
+- Duration: 0 bars (instantaneous)
+- Implementation: no transition processing — the sections simply abut
+- Best for: drop entries after silence, genre-specific style (punk, some electronic)
+- Constraint: works best when the energy delta is extreme (silence to loud, or vice versa)
+
+### crossfade
+Gradual overlap of outgoing and incoming sections.
+
+- Duration: 1-4 bars
+- Implementation: outgoing section fades out while incoming fades in, overlapping by the crossfade duration
+- Best for: ambient, cinematic, smooth genre transitions
+- Tools: `set_clip_automation` on track volumes with opposing curves
+
+### fill_break
+A drum fill followed by a brief silence (1-2 beats) before the new section.
+
+- Duration: 1 bar
+- Implementation: drum fill on the last bar, then all instruments drop for 1-2 beats, new section enters on beat 3 or 4
+- Best for: rock, pop, funk section transitions
+- Tools: `add_notes` for the fill, `set_track_mute` or volume automation for the gap
+
+## Choosing the Right Archetype
+
+| From -> To | Recommended | Alternative |
+|------------|-------------|-------------|
+| Intro -> Verse | stacking | drum_build |
+| Verse -> Chorus | riser_sweep, drum_build | harmonic_tension |
+| Chorus -> Verse | strip_down | filter_close |
+| Verse -> Bridge | harmonic_tension | strip_down |
+| Bridge -> Final Chorus | riser_sweep + drum_build | harmonic_tension |
+| Chorus -> Breakdown | strip_down, hard_cut | filter_close |
+| Breakdown -> Drop | riser_sweep | drum_build + stacking |
+| Any -> Outro | strip_down, reverb_wash | filter_close |