diff --git a/README.md b/README.md
index 6b9a575..bfbaf51 100644
--- a/README.md
+++ b/README.md
@@ -61,6 +61,13 @@ $ pytheory demo
 
 >>> Key("C", "major").pivot_chords(Key("G", "major"))
 ['A minor', 'B minor', 'C major', 'D major', 'E minor', 'G major']
+
+>>> Chord.from_tones("C", "E", "G").forte_number
+'3-11'
+
+>>> from pytheory.scales import Scale
+>>> Scale.recommend("C", "Eb", "F", "Gb", "G", "Bb", top=3)
+[('C', 'blues', 1.0), ...]
 ```
 
 ## Composition
@@ -89,11 +96,11 @@ score.repeat("chorus", times=2)
 
 ## 10 Synth Waveforms
 
-sine, saw, triangle, square, pulse, FM, noise, supersaw, PWM slow, PWM fast
+sine, saw, triangle, square, pulse, FM, noise, supersaw, PWM slow, PWM fast — with detune, stereo pan, and spread.
 
 ## 58 Drum Patterns
 
-rock, jazz, bebop, bossa nova, salsa, samba, afrobeat, funk, reggae, house, trap, metal, drum and bass — and 45 more. Plus 21 fill presets.
+rock, jazz, bebop, bossa nova, salsa, samba, afrobeat, funk, reggae, house, trap, metal, drum and bass — and 45 more. Plus 21 fill presets. Stereo panned like a real kit.
 
 ## 6 Effects with Automation
 
@@ -110,7 +117,7 @@ lead.set(lowpass=4000, distortion=0.9)
 lead.lfo("lowpass", rate=0.5, min=400, max=3000, bars=8)
 ```
 
-Signal chain: distortion → chorus → lowpass → delay → reverb
+Signal chain: distortion → chorus → lowpass → delay → reverb. Sidechain compression. Master bus compressor/limiter. Stereo output.
 
 ## Convolution Reverb
 
@@ -132,6 +139,7 @@ Guitar (8 tunings), bass, ukulele, mandolin family, violin family, banjo, harp,
 ## Command Line
 
 ```
+$ pytheory repl                            # interactive scratchpad
 $ pytheory demo                            # hear a generated track
 $ pytheory key G major                     # explore a key
 $ pytheory identify Cmaj7                  # analyze a chord symbol
diff --git a/docs/guide/cli.rst b/docs/guide/cli.rst
index b2b2421..e3d47dd 100644
--- a/docs/guide/cli.rst
+++ b/docs/guide/cli.rst
@@ -4,6 +4,14 @@ Command-Line Interface
 PyTheory includes a CLI for music theory lookups, composition, and
 playback — all from the terminal.
 
+Interactive REPL
+----------------
+
+For extended exploration, the REPL is a music theory scratchpad with
+tab completion. See the :doc:`repl` guide for details::
+
+    $ pytheory repl
+
 Demo
 ----
 
diff --git a/docs/guide/drums.rst b/docs/guide/drums.rst
index c497f99..fadfc32 100644
--- a/docs/guide/drums.rst
+++ b/docs/guide/drums.rst
@@ -16,6 +16,11 @@ Every sound is generated from waveforms; no samples needed.
 Drum Sounds
 -----------
 
+Every drum sound is stereo-panned like a real kit — kick and snare
+center, hi-hat right, crash left, toms spread across the field,
+percussion instruments placed naturally. Put on headphones and you'll
+hear the kit in front of you.
+
 The ``DrumSound`` enum maps to General MIDI percussion note numbers:
 
 .. code-block:: pycon
diff --git a/docs/guide/playback.rst b/docs/guide/playback.rst
index fad97db..3d159e9 100644
--- a/docs/guide/playback.rst
+++ b/docs/guide/playback.rst
@@ -47,7 +47,12 @@ Optional parameters for synth, envelope, and temperament:
 play_score() -- Full Arrangements
 ---------------------------------
 
-Plays a ``Score`` with all its parts and drums mixed together:
+Plays a ``Score`` with all its parts and drums mixed together.
+Output is **stereo** — each part is panned according to its ``pan``
+setting, drums are stereo-panned like a real kit, and reverb tails
+have natural stereo width. A **master bus compressor/limiter** (4:1
+ratio, brick-wall at 0.95) is applied to prevent clipping and make
+the mix louder and punchier:
 
 .. code-block:: python
 
diff --git a/docs/guide/quickstart.rst b/docs/guide/quickstart.rst
index 21e949e..4a73a46 100644
--- a/docs/guide/quickstart.rst
+++ b/docs/guide/quickstart.rst
@@ -208,32 +208,35 @@ What's in the Box
 -----------------
 
 **Theory** — tones, scales (40+ across 6 musical systems), chords
-(17 types, Roman numeral analysis, tension scoring, voice leading),
-keys (detection, signatures, modulation paths, borrowed chords).
+(17 types, Roman numeral analysis, figured bass, tension scoring,
+voice leading, pitch class sets with Forte numbers), keys (detection,
+signatures, modulation paths, borrowed chords), scale recommendation.
 
 **Sequencing** — Score, Part, Duration, TimeSignature. Arpeggiator
 with 5 patterns. Legato with pitch glide. Per-note velocity. Swing.
 Tempo changes. Fade in/out. Song sections with repeat. Humanize.
 
 **Synthesis** — 10 waveforms: sine, saw, triangle, square, pulse, FM,
-noise, supersaw, PWM slow, PWM fast. 8 ADSR envelopes.
+noise, supersaw, PWM slow, PWM fast. 8 ADSR envelopes. Detune.
+Stereo pan and spread.
 
 **Effects** — distortion, chorus, lowpass filter (with resonance),
-delay, reverb (algorithmic + 7 convolution presets including
+delay, reverb (algorithmic + 7 stereo convolution presets including
 Taj Mahal with 12-second tail). All per-part with automation and
-LFO modulation. Sidechain compression.
+LFO modulation. Sidechain compression. Master bus compressor/limiter.
 
 **Drums** — 58 pattern presets (rock, jazz, salsa, bossa nova,
 afrobeat, house, trap, and 50+ more). 21 fill presets. 27 synthesized
-drum voices.
+drum voices with stereo panning.
 
 **Instruments** — 25 presets (guitar with 8 tunings, bass, ukulele,
 mandolin family, violin family, banjo, harp, oud, sitar, erhu, and
 more) with chord fingering generation and scale diagrams.
 
-**Export** — MIDI, WAV, real-time playback.
+**Output** — stereo playback, WAV export, MIDI export.
 
-**CLI** — ``pytheory demo``, ``pytheory key``, ``pytheory chord``,
+**Interface** — REPL with tab completion (``pytheory repl``), CLI with
+15 commands. ``pytheory demo``, ``pytheory key``, ``pytheory chord``,
 ``pytheory identify``, ``pytheory midi``, ``pytheory play``, and more.
 
 Where to Go Next
diff --git a/docs/index.rst b/docs/index.rst
index 51edc18..dcbae3c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -73,15 +73,18 @@ What's Inside
 -------------
 
 - **Theory** — tones, scales (40+ across 6 systems), chords (17 types),
-  keys, Roman numeral analysis, modulation, voice leading
+  keys, Roman numeral analysis, figured bass, pitch class sets (Forte
+  numbers), scale recommendation, modulation, voice leading
 - **Sequencing** — Score, Parts, arpeggiator, legato/glide, velocity,
-  swing, humanize, tempo changes, song sections
-- **Synthesis** — 10 waveforms, 8 envelopes, 58 drum patterns, 21 fills
-- **Effects** — reverb (algorithmic + 7 convolution IRs), delay, lowpass,
-  distortion, chorus, sidechain, automation, LFOs
+  swing, humanize, tempo changes, song sections with repeat
+- **Synthesis** — 10 waveforms, 8 envelopes, detune, stereo pan/spread,
+  58 drum patterns (stereo panned), 21 fills
+- **Effects** — reverb (algorithmic + 7 convolution IRs, stereo), delay,
+  lowpass (with resonance), distortion, chorus, sidechain compression,
+  automation, LFOs. Master bus compressor/limiter
 - **Instruments** — 25 presets with fingering generation
-- **Export** — MIDI, WAV, real-time playback
-- **CLI** — ``pytheory demo``, ``key``, ``chord``, ``midi``, ``play``, and more
+- **Output** — stereo playback, WAV, MIDI export
+- **Interface** — REPL with tab completion, CLI (15 commands), ``pytheory demo``
 - **AI-friendly** — Claude Code can compose
   and play music through PyTheory from natural language