docs: 1.0 documentation restructure

Split root CLAUDE.md into 19 per-directory files scoped to their source area.
Roll v0 history into docs/ARCHIVE.md; retire CONTEXT.md, CONTEXT-ARCHIVE.md,
PLAN.md, COMPLETED.md. Move plan docs under docs/. Rescue 9 live deferrals
into docs/TODO.md.

docs/product/midi-playback.md

@@ -2,10 +2,11 @@
 
 Framing for a **MIDI-triggered audio sampler** that plays back ReaSampler's captured
 banks. This began as a discussion-shaping doc; with all forks now settled it has become
-the **product framing behind a scoped phase**. Its build roadmap lives in **PLAN.md
-§Phase S** and its authoritative spec in **CONTEXT.md §Phase S** — this doc holds the
-*why* (the plugin-format reasoning, the bare-VST3-vs-JUCE assessment, the settled
-decision record).
+the **product framing behind a scoped phase**. Its build roadmap lives in
+**`docs/ARCHIVE.md` §Phase S** and its authoritative spec in
+**`src/core/instrument/CLAUDE.md`** and **`src/shell/instrument/CLAUDE.md`** — this
+doc holds the *why* (the plugin-format reasoning, the bare-VST3-vs-JUCE assessment, the
+settled decision record).
 
 Status: framed by product-designer (2026-07-26), **revised 2026-07-27 (r11)**. r11 records the
 **Sample-face recomposition** (Daniel's post-landing DAW pass, 2026-07-27): all linear sliders →
@@ -42,10 +43,11 @@ demoted to an opt-in Zones panel — see the r6 Addendum in §4. r6 also settles
 S1–S6 instrument: the product name **ReaSampler 9000** and the **"better than RS5K" UX
 overhaul** (Phase S points S10–S13) — see the r5 Addendum in §4. r4 (below) settled the four
 residual forks D-A..D-D. The
-"no PLAN.md footprint" era is **over** — with D-A through D-D settled (below), the
+"no landed-roadmap footprint" era is **over** — with D-A through D-D settled (below), the
 instrument was scoped into **Phase S** (codename Daniel's: "S" for Sampler, because "D"
-collides with the existing Design View phase). **PLAN.md §Phase S is now the
-authoritative roadmap; CONTEXT.md §Phase S is the authoritative spec.** This doc is the
+collides with the existing Design View phase). **`docs/ARCHIVE.md` §Phase S now records
+the landed roadmap; `src/core/instrument/CLAUDE.md` and `src/shell/instrument/CLAUDE.md`
+are the authoritative spec.** This doc is the
 framing/decision record they point back to. Prior revisions (a) established that a REAPER
 *extension* cannot be a MIDI instrument, (b) corrected a material omission — REAPER's
 **VST-host bridge**, which lets a VST3 plugin *hosted inside REAPER* call back into
@@ -410,8 +412,8 @@ it doesn't carry" — is unchanged. What the bridge settles is *where that mappi
 between extension and instrument as **live shared `"reasampler"` state**, not a file one
 writes and the other re-parses.
 
-**What the current index carries** (from `bank_model`'s `Sample`, per CONTEXT.md §Data
-model): id, display name, relative path, source range, channel count, sample rate,
+**What the current index carries** (from `bank_model`'s `Sample`): id, display name,
+relative path, source range, channel count, sample rate,
 length, capture tempo, an **optional key**, peak/RMS/LUFS, content hash, tier,
 provenance, timestamp. Notably it *already* has an optional key field and capture
 tempo — the seeds of pitch-mapping are there.
@@ -426,8 +428,8 @@ tempo — the seeds of pitch-mapping are there.
   to velocity zones).
 - **Round-robin groups** (cycle through N samples on repeated same-note hits).
 - **Loop points** (sustain loop start/end for held notes; sample-accurate,
-  zero-crossing-aware — CONTEXT already flags loop/zero-crossing handling as
-  day-one-relevant for wavetable material).
+  zero-crossing-aware — loop/zero-crossing handling is day-one-relevant for
+  wavetable material).
 - **Amplitude envelope** (ADSR) and optionally filter/pitch envelopes.
 - **Tuning/gain trim** per sample.
 
@@ -559,7 +561,7 @@ ReaSampler-native way to build it and it's assumed, not debated, going forward.
 
 All four residual decisions are now called. Each is marked **SETTLED** with Daniel's
 choice and the reasoning kept as the record of *why* — do not re-litigate. They are
-scoped into **PLAN.md §Phase S** / **CONTEXT.md §Phase S**.
+scoped into **`docs/ARCHIVE.md` §Phase S** / **`src/core/instrument/CLAUDE.md`**.
 
 **D-A — SETTLED: bare Steinberg VST3 SDK + LICE editor (no JUCE).** *(The central fork.
 §1a is the assessment that fed it. The sub-question — who draws the editor? — was the
@@ -649,7 +651,7 @@ After Phase S was scoped (D-A..D-D), Daniel set two further directions. These ar
 **settled directions**, not open forks — specced as new Phase S points (S7–S9), not
 re-litigated. Recorded here per the doc's settled-decisions convention.
 
-**D-E — Channel mode: mono | stereo, per-instance, bus-negotiated (→ PLAN.md S7).**
+**D-E — Channel mode: mono | stereo, per-instance, bus-negotiated (→ `docs/ARCHIVE.md` §S7).**
 Captures are often stereo; the current mono downmix is a Tier-0 simplification. The
 engine gets a **per-instance channel-mode toggle (1 mono / 2 stereo)** that "works with
 the REAPER audio bus automatically" — the VST3 declares/negotiates its output bus
@@ -662,8 +664,8 @@ Cross-mode policy: mono-source-in-stereo → dual-mono; stereo-source-in-mono
 never a bank fact). Sequenced **first after the editor/embed work** because it touches the
 engine Daniel smoke-tests.
 
-**Ingest routes through the bank — "option 1"; the extension owns ingest (→ PLAN.md
-S8 + S9).** Loading a sample into the sampler is **one gesture**: capture/import-into-bank
+**Ingest routes through the bank — "option 1"; the extension owns ingest (→
+`docs/ARCHIVE.md` §S8 + §S9).** Loading a sample into the sampler is **one gesture**: capture/import-into-bank
 + auto-assign to the active instance. The **extension owns ingest** (it has arrange
 access, Media-Explorer access, and the drop-target surface on its own panels); the
 **instrument stays a read-only bank consumer** — it never captures or imports. Sub-parts,
@@ -690,7 +692,7 @@ with the honest SDK reality verified against the vendored headers:
 
 *The genuine spikes flagged (not decisions Daniel owes, just build-time unknowns):* the
 ME merely-selected-file read (b), and the drop-onto-editor cross-artifact relay (c). Both
-are honestly-flagged as spikes in PLAN.md S8, not promised.
+are honestly-flagged as spikes in `docs/ARCHIVE.md` §S8, not promised.
 
 ### Addendum — product name + UX overhaul (Daniel, 2026-07-26, post-S1–S6 DAW test)
 
@@ -700,7 +702,7 @@ open forks (the two flagged forks below are the only calls left to Daniel).
 
 **The instrument's product name is `ReaSampler 9000`.** The extension stays **ReaSampler**
 (capture + organization); the instrument is **ReaSampler 9000** (playback). Propagation is
-a checklist item (PLAN.md §Phase S — product name; CONTEXT.md §Product name): the VST3
+recorded in `docs/ARCHIVE.md` §Phase S — product name: the VST3
 class **display name** string, the `IPlugView` editor title band (today "ReaSampler
 Instrument"), the S6 embed-strip label, and the docs. **Compat guard (load-bearing):** the
 **VST3 class UID must NOT change** — instances in saved projects key off it; a UID change
@@ -747,8 +749,9 @@ names the editor as the wound.
 
 After the r5 UX-overhaul directive was specced (keymap-first S10), Daniel reframed the
 workflow before S10 was implemented. This **revises S10** and settles S-NAME-1. Settled
-directions, not open forks — recorded here per the doc's settled-decisions convention; PLAN.md
-§S10 and CONTEXT.md §Phase S (workflow hierarchy) carry the spec.
+directions, not open forks — recorded here per the doc's settled-decisions convention;
+`docs/ARCHIVE.md` §S10 records what landed and `src/core/instrument/CLAUDE.md` (the
+editor `ui/` modules) documents the current architecture.
 
 **The reframe, verbatim (Daniel, 2026-07-26):** *"We need to think hard about the workflow
 with this plugin. Have a giant list of 'item' blocks is visually useless. When the plugin is
@@ -806,8 +809,8 @@ partly on filename, fall back to keeping the filename and record that as shipped
 
 Daniel directed a set of engine features for the sampler, specced as **new Phase S points
 S15 (Trigger vs Gate) and S16 (pitch envelope)**. **The feature set is settled** — recorded
-here per the doc's settled-decisions convention; PLAN.md §S15/S16 and CONTEXT.md §Sampling
-modes carry the spec. Two forks are flagged with leans (S15-F1 choke, S15-F2 param
+here per the doc's settled-decisions convention; `docs/ARCHIVE.md` §S15 / §S16 records what
+landed and `src/core/instrument/CLAUDE.md` §Sampling modes documents the current spec. Two forks are flagged with leans (S15-F1 choke, S15-F2 param
 granularity); the WDL question was resolved by inspection.
 
 **Directive, verbatim (Daniel, 2026-07-26):** *"let's have product spec out some features
@@ -927,9 +930,10 @@ This reshapes S16 and **flips the r7 WDL verdict** on `WDL_SimplePitchShifter`.
    `process` allocation; measure per-voice CPU + onset latency against the polyphony cap. Treat
    S16's Preserve-engine point as the phase's next real DSP spike, not a thin envelope add-on.
 
-**Where the spec lives:** PLAN.md §S16 (reshaped to "pitch engine modes + pitch envelope",
-with forks S16-F1/F2 and the corrected WDL finding) and the S15 × S16 interaction note;
-CONTEXT.md §Pitch engine modes — Varispeed vs Preserve + the corrected WDL surface finding.
+**Where the spec lives:** `docs/ARCHIVE.md` §S16 (reshaped to "pitch engine modes + pitch
+envelope", with forks S16-F1/F2 and the corrected WDL finding) and the S15 × S16
+interaction note; `src/core/instrument/CLAUDE.md` §Sampling modes — Varispeed vs Preserve
++ the WDL surface finding.
 
 ### Addendum — VST channel isolation (Daniel, 2026-07-26)
 
@@ -972,9 +976,9 @@ with or right after the in-flight waves (S9 ext_keys, S15/S16 processor/editor)
    channel's banks; stable-project + beta-VST = clean empty (not error); the S-NAME-1
    rename/rebind test extends to the beta UID.
 
-**Where the spec lives:** PLAN.md §S18; CONTEXT.md §VST3 channel identity — the UID pair + the
-pairing surface. The pairing surface's data half is already load-bearing V4 machinery; S18
-adds only the identity fork on top.
+**Where the spec lives:** `docs/ARCHIVE.md` §S18; `src/shell/instrument/CLAUDE.md` §VST3
+channel identity — the UID pair + the pairing surface. The pairing surface's data half is
+already load-bearing V4 machinery; S18 adds only the identity fork on top.
 
 ---
 
@@ -986,8 +990,9 @@ good — but the two-view editor (today's "Browser" + "Zones" toggle) misallocat
 the default window is undersized for a 1080p world, and the drop-a-capture-onto-FX gesture is
 broken in practice. The directive: **make the one job — pick a capture, tune it, play it —
 fast, easy, and fun. Style is a critical ingredient. No spreadsheet aesthetics.** These are the
-`r9` calls. Authoritative spec: **CONTEXT.md §Phase S — editor view-model redesign (S-VIEW)**;
-build roadmap: **PLAN.md §Phase S — editor view-model redesign**.
+`r9` calls. Current architecture: **`src/core/instrument/CLAUDE.md`** and
+**`src/shell/instrument/CLAUDE.md`**; landed record: **`docs/ARCHIVE.md` §Phase S — editor
+view-model redesign**.
 
 **The reference devices (the north star for control density).** Daniel named Ableton **Simpler**
 and a Kilohearts/Phase-Plant **sampler group** as the composition targets. Both share one
@@ -1021,7 +1026,7 @@ grammar, and it is the grammar the redesign adopts:
    loading a new one is a distinct act), not a three-way radio. *Why the reframe matters:* it
    makes "I just want to play this capture" the zero-click default, and "I want a different one"
    a single deliberate gesture, instead of making the user re-choose their whole stance every
-   time. See CONTEXT.md §S-VIEW for the precise navigation model.
+   time. See `docs/ARCHIVE.md` §S-VIEW-1 for the precise navigation model as landed.
 
 2. **The Sample view earns the hero treatment; Browse gets ruthlessly cut.** Browse today
    carries a waveform preview, root-note piano-roll, loop-point labels, a track-root message, and
@@ -1037,10 +1042,10 @@ grammar, and it is the grammar the redesign adopts:
 3. **Two engineering prerequisites, framed but routed to implementation.** The **drop-to-FX bug**
    (dropping a capture onto a track's FX chain does not instantiate + init ReaSampler 9000) and
    the **undersized default window** are not design decisions — they are a bug and a one-line
-   default. Both are framed in CONTEXT.md §S-VIEW with the SDK reality swept (drop-to-FX: the S17
-   machinery is SDK-correct, so this is a *diagnosis* task, not a redesign; window size: the
-   `getSize`/`checkSizeConstraint` mechanism is verified), and both are flagged for
-   staff-engineer, not for a product fork.
+   default. Both are recorded landed in `docs/ARCHIVE.md` §S-VIEW-BUG-1 (drop-to-FX: the S17
+   machinery is SDK-correct, so this is a *diagnosis* task, not a redesign) and §S-VIEW-SIZE-1
+   (window size: the `getSize`/`checkSizeConstraint` mechanism is verified), and both were
+   flagged for staff-engineer, not for a product fork.
 
 **New parameters this introduces (both instrument performance state, D-B — never bank facts):**
 
@@ -1064,7 +1069,7 @@ grammar, and it is the grammar the redesign adopts:
   new top-level `previewVelocity` field), **not** the extension's `persist` project ext-state —
   that module is REAPER-project-scoped and extension-owned, so it would make the level
   project-global instead of per-instance and route an instrument concern through a bank-read-only
-  seam. See CONTEXT.md §S-VIEW for the round-trip and back-compat lift. This is what makes the
+  seam. See `docs/ARCHIVE.md` §S-VIEW-4 for the round-trip and back-compat lift as landed. This is what makes the
   preview button *fun*: tap it hard or soft without reaching for a controller — and it remembers.
 
 **Two visual components the redesign commits to:**
@@ -1101,8 +1106,10 @@ persisted fields is not a compat event; saved instances rebind and restore. And
 (extended additively — `keyTrack` per-zone, `previewVelocity` per-instance via an envelope bump to
 v6, both with back-compat defaults on read) are the same load-bearing core.
 
-**Where the spec lives:** CONTEXT.md §Phase S — editor view-model redesign (S-VIEW); PLAN.md
-§Phase S — editor view-model redesign. This Addendum is the *why*; those are the *what/how*.
+**Where the spec lives:** `src/core/instrument/CLAUDE.md` (envelope overlay, key-tracking,
+preview-velocity ownership) documents the current architecture; `docs/ARCHIVE.md` §Phase S
+— editor view-model redesign records what landed (S-VIEW-1 through S-VIEW-10). This
+Addendum is the *why*; those are the *what/how*.
 
 ---
 
@@ -1217,8 +1224,9 @@ for preview velocity — a different struct on a different version axis). Concre
   the L1 kit, routing mouse through `velocity_curve`), gated on the foundation track and composing
   with the S-VIEW-2 Sample face + S-VIEW-3 envelope-overlay work.
 
-**Where the spec lives:** CONTEXT.md §Phase S — editor view-model redesign (S-VIEW), velocity-curve
-sub-section; PLAN.md §Phase S — editor view-model redesign (S-VIEW-9/S-VIEW-10 + fork R10-F1). This
+**Where the spec lives:** `src/core/instrument/CLAUDE.md` (the `velocity_curve` module, its
+engine application point, and its ownership rules) documents the current architecture;
+`docs/ARCHIVE.md` §S-VIEW-9 / §S-VIEW-10 records what landed (fork R10-F1 resolved). This
 Addendum is the *why*; those are the *what/how*.
 
 ---
@@ -1278,11 +1286,13 @@ recomposition of *existing* controls; no new params, no component-state bump, VS
 unchanged. All drawing through the L1 kit by palette role; all layout/hit-test in new pure modules
 (`knob_deck`, `curve_popup` — mirrors of `action_bar`/`overflow_menu`); the knobs and the hero's
 envelope nodes remain two surfaces on one param model (S-VIEW-F2's structural sync, untouched).
-The full inventory contract (every landed element → its r11 home) is in the CONTEXT.md spec.
+The full inventory of what landed (every element → its r11 home) is recorded in
+`docs/ARCHIVE.md` §FB1 and §FB2.
 
-**Where the spec lives:** CONTEXT.md §Phase S — editor view-model redesign (S-VIEW) → "The
-Sample-face recomposition (r11)"; PLAN.md §Phase S — editor Wave B (S-VIEW-11/12/13 + forks
-R11-F1/R11-F2). This Addendum is the *why*; those are the *what/how*.
+**Where the spec lives:** `src/core/instrument/CLAUDE.md` (the `knob_deck`/`curve_popup`/
+`master_gain` modules) documents the current architecture; `docs/ARCHIVE.md` §FB1 and §FB2
+record what landed (S-VIEW-11/12/13 + forks R11-F1/R11-F2 resolved). This Addendum is the
+*why*; those are the *what/how*.
 
 ---
 
@@ -1329,7 +1339,8 @@ Post-DAW-test directives (2026-07-26; see the "product name + UX overhaul" Adden
    frameworks), DS-2 (Direction B "Neon Console" + Direction C's spectral keyboard strip), and
    DS-3 (thorough panel layout) are all **SETTLED (2026-07-26)**. Framing + palette + the three
    visual directions + forks: `docs/product/visual-design-language.md` (on `dev`); roadmap +
-   spec: **PLAN.md §Phase L + CONTEXT.md §Phase L** (on `dev`). **S10–S13 build with the
+   spec: **`docs/ARCHIVE.md` §Phase L** (landed record) and **`src/core/ui/CLAUDE.md`**
+   (current architecture) (on `dev`). **S10–S13 build with the
    current drawing and adopt the L1 kit when it lands — not gated on Phase L.** Answers
    Daniel's "the VST is dogshit / temple os / does Cockos have a toolkit" (2026-07-26,
    post-S1–S6 DAW test).
@@ -1350,15 +1361,16 @@ Post-DAW-test directives (2026-07-26; see the "product name + UX overhaul" Adden
     S15-F1 (choke, held) / S15-F2 (param granularity, lean per-zone). Feature set settled;
     the engine default is Daniel's fork.
 
-**Authoritative from here:** **PLAN.md §Phase S** is the roadmap (S1–S6 the original
-dependency chain: spike → `Sample` fields → pure sampler core → Tier 0 → Tier 1 → embedded
-UI; then **S7** stereo, **S8** ingest, **S9** change-detection, **S10–S13** the ReaSampler
-9000 UX overhaul, **S15/S16** the Trigger-vs-Gate + pitch-engine-modes engine features);
-**CONTEXT.md §Phase S** is the spec (seam-field semantics, scope contracts, the channel-mode
-/ ingest / bank-generation / sampling-mode / pitch-engine contracts, the UX-overhaul spec,
-the product-name convention, the pure/shell split, the WDL finding, the must-verify
-SDK/bridge surfaces). This doc is the framing/decision record they point back to. The "no
-PLAN.md footprint" era is over.
+**Authoritative from here:** **`docs/ARCHIVE.md` §Phase S** is the landed roadmap (S1–S6
+the original dependency chain: spike → `Sample` fields → pure sampler core → Tier 0 → Tier
+1 → embedded UI; then **S7** stereo, **S8** ingest, **S9** change-detection, **S10–S13** the
+ReaSampler 9000 UX overhaul, **S15/S16** the Trigger-vs-Gate + pitch-engine-modes engine
+features); **`src/core/instrument/CLAUDE.md`**, **`src/shell/instrument/CLAUDE.md`**, and
+**`src/core/wire/CLAUDE.md`** are the current spec (seam-field semantics, scope contracts,
+the channel-mode / ingest / bank-generation / sampling-mode / pitch-engine contracts, the
+UX-overhaul spec, the product-name convention, the pure/shell split, the WDL finding, the
+must-verify SDK/bridge surfaces). This doc is the framing/decision record they point back
+to. The "no landed-roadmap footprint" era is over.
 
 ---