diff --git a/README.md b/README.md
index be6501f..cdf1a9b 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,38 @@
 # ReaSampler
 
-A native C++ REAPER extension that captures any arbitrary audio source into a
-per-project **sample bank** (cached files + a docked grid), decoupled from the
-arrange view, with keyboard/MIDI-bindable capture and placement. Built as a
-precision tool: deterministic, non-destructive, no clutter.
+Version 1.4.0 · License: GNU AGPL v3 (see `LICENSE`)
+
+A per-project audio sample-bank capture tool for REAPER, built as two artifacts: a
+native C++ REAPER extension (`reaper_reasampler`) and a Windows-only VST3 sampler
+instrument (`reasampler_9000.vst3`, ReaSampler 9000). It captures any arbitrary audio
+source into a per-project **sample bank** (cached files + a docked grid), decoupled
+from the arrange view, with keyboard/MIDI-bindable capture and placement. It is
+designed as a precision tool: deterministic captures, non-destructive by
+construction, no auto-inserted clutter.
+
+## Status
+
+Under active development, not yet formally released.
 
 ## The two artifacts
 
 **`reaper_reasampler`** — the REAPER extension. Captures audio into a named,
-per-project sample bank, displays it in a docked panel, and provides bindable
-actions for capture and placement.
+per-project sample bank and provides bindable actions across the workflow: offline
+and realtime capture (with cancel), batch capture (per selected item or per razor
+area), recapture-from-source, capture-and-assign to a live instrument instance,
+insert with an opt-in tempo-conform variant, the resample-bake landing action,
+multi-bank management (pool, activate, evacuate, move, copy, delete), prune/reclaim,
+provenance and lineage tracking, Design View, and ingest via drag-out, arrange-drop,
+and instrument-drop. All of it surfaces in a docked bank panel.
 
 **ReaSampler 9000** (`reasampler_9000.vst3`) — a Windows-only VST3 sampler
-instrument that plays bank captures back across a MIDI keyboard. The VST3 target
-(`reasampler_vst`) is gated on the vendored `vendor/vst3sdk` slice; configure
-quietly omits it if the slice is absent.
+instrument that plays bank captures back across a MIDI keyboard. Since
+`ComponentState` v10 it is self-contained: it decodes samples from its own
+persisted references and plays with the extension absent, treating the bank as a
+browsing source rather than a runtime dependency. The VST3 target
+(`reasampler_vst`) is gated on `WIN32 AND EXISTS .../pluginfactory.cpp` — omitted
+on macOS/Linux even when the vendored `vendor/vst3sdk` slice is present, and
+quietly omitted anywhere the slice itself is absent.
 
 A **beta channel** build is available via `-DREASAMPLER_CHANNEL=beta` at configure
 time, producing `reaper_reasampler_beta` and `reasampler_9000_beta.vst3`. The two
@@ -27,8 +45,35 @@ and adds an index entry. It **never** puts an item in the arrange view. Placemen
 is a distinct, on-demand action. Any code path that auto-inserts a capture into the
 timeline violates the purpose of the tool.
 
+## Prerequisites
+
+- CMake ≥ 3.19
+- A C++17 compiler
+- Windows + MSVC to build the VST3 target (`reasampler_vst`) — the REAPER extension
+  itself is cross-platform
+- PHP, to run the SWELL resource-generation step on macOS/Linux (below)
+
+## Platform support
+
+The REAPER extension targets Windows, macOS, and Linux; ReaSampler 9000 (the VST3
+instrument) is Windows-only.
+
+| Platform | Extension | VST3 instrument |
+|---|---|---|
+| Windows | Builds with no extra steps | Builds when `vendor/vst3sdk` is present |
+| macOS | Builds, but dialogs need the manual SWELL resgen step below plus hand-uncommenting the `APPLE` `target_sources` block in `src/app/CMakeLists.txt` | Not built (Windows-only gate) |
+| Linux | Same manual resgen + hand-uncomment requirement as macOS, against its own commented block | Not built (Windows-only gate) |
+
+A macOS/Linux build that skips the resgen-and-uncomment step compiles cleanly
+without dialogs and without a warning — this is expected, not a bug.
+
 ## One-time setup
 
+A plain `git clone --recursive` also works, but it pulls every nested submodule of
+`vendor/vst3sdk` (including `vstgui4`, `tutorials`, `doc`, `cmake` — none of which
+this project links against). The steps below pull only the three submodules
+actually needed:
+
     git submodule update --init
 
 Vendors three submodules:
@@ -43,10 +88,25 @@ Vendors three submodules:
 
     cmake -B build -S .
     cmake --build build
-    ctest --test-dir build
+    ctest --test-dir build -C Debug
 
-Pure modules have `<module>_tests` targets that run without REAPER or a DAW.
-`CMakeLists.txt` is the authoritative list of all targets.
+On a multi-config generator (Visual Studio, Xcode), `cmake --build build` with no
+`--config` builds **Debug** — nothing in this build sets `CMAKE_BUILD_TYPE` or an
+optimization flag, so that's the default. The `-C Debug` above is required on a
+multi-config generator too: without it, `ctest` silently reports every test as "Not
+Run" instead of running them. Single-config generators (Ninja, Make) need neither
+flag.
+
+Pure `core/` modules each have a corresponding `<module>_tests` executable target
+that runs without REAPER or a DAW. Targets are declared per-directory — each
+`src/**/CMakeLists.txt` owns its own libraries and test targets, pulled in via
+`add_subdirectory` from the root `CMakeLists.txt`, which itself declares no targets
+directly.
+
+Installing or judging performance requires the Release config explicitly:
+
+    cmake --build build --config Release
+    ctest --test-dir build -C Release
 
 ### Beta channel
 
@@ -60,33 +120,59 @@ Pure modules have `<module>_tests` targets that run without REAPER or a DAW.
     php vendor/WDL/WDL/swell/swell_resgen.php src/resource.rc   # macOS; Linux reuses the output
 
 Add the generated file to the appropriate `APPLE` / Linux `target_sources` block in
-CMakeLists.txt. The SWS extension build is the canonical reference for this step.
+`src/app/CMakeLists.txt` (both are commented out by default). The SWS extension
+build is the canonical reference for this step.
 
 ## Install
 
-Copy the built binary into REAPER's `UserPlugins/` folder
-(Options → Show REAPER resource path), then **restart REAPER**. Extensions load at
-startup only; there is no hot reload.
+There is no hot reload; REAPER loads extensions at startup only.
+
+**Extension** — copy the **Release** build's `reaper_reasampler` binary
+(`build/Release/` on a multi-config generator — not the default `Debug/` output)
+into REAPER's `UserPlugins/` folder (Options → Show REAPER resource path), then
+restart REAPER.
+
+**VST3 instrument** — copy the **Release** build's `reasampler_9000.vst3` into the
+system VST3 folder (`C:\Program Files\Common Files\VST3` on Windows) — a different
+destination from the extension, not `UserPlugins/`. REAPER picks it up on its next
+plugin rescan.
 
 ## Repo layout
 
-The codebase is organized around one discipline: **pure, REAPER-free testable core
-split from REAPER-facing shells**.
+The codebase is organized around one discipline: **pure, REAPER/VST3-SDK-free
+testable core, split from the REAPER- and VST3-facing shells that touch those host
+types.**
 
-- `src/` — pure core modules (no REAPER types, unit-testable outside the DAW) and
-  REAPER-facing shells (extension entry point, panel, actions, capture backends, etc.)
-- `src/vst/` — the VST3 instrument: pure voice engine + zone payload + editor UI
-  pure modules, and the VST3 shells
-- `tests/` — unit tests for the pure core modules
+- `src/app/` — the REAPER extension's entry point (`main.cpp` only)
+- `src/core/` — pure modules, no REAPER or VST3 SDK types, each with a
+  `<module>_tests` target: `audio/`, `capture/`, `instrument/` (further split into
+  `bake/`, `engine/filter/`, `engine/loop/`, `map/`, `note/`, `ui/`), `json/`,
+  `model/`, `reclaim/`, `tracking/`, `ui/`, `util/`, `version/`, `view/`, `wire/`
+- `src/shell/` — REAPER/VST3-facing shells: `actions/`, `bank_ops/`, `capture/`,
+  `instrument/` (the ReaSampler 9000 VST3 shells), `panel/`, `persist/`, `view/`
+- `src/resource.rc`, `src/resource.h`, `src/ext_keys.h` — root-level build inputs
+  not claimed by any one subdirectory
+- `tests/` — unit test sources for the pure `core/` modules
+- `cmake/` — shared CMake target-declaration helpers
+- `docs/` — plan-style docs and product-design docs (see Further reading, below)
 - `vendor/` — git submodules
 
 See `CLAUDE.md` for the full module inventory, architectural contracts, and the
-precise boundary between pure core and REAPER-facing shells.
+precise boundary between pure core and REAPER/VST3-facing shells; each `src/**/`
+directory also carries its own `CLAUDE.md` with that area's own module list and
+invariants.
+
+## License
+
+GNU AGPL v3, copyright Daniel Harvey. See `LICENSE`.
 
 ## Further reading
 
 - `CLAUDE.md` — architecture, module inventory, and build/API contracts
-- `CONTEXT.md` — the authoritative spec (large: ~186k — grep the relevant section rather than reading whole)
-- `CONTEXT-ARCHIVE.md` — build detail for landed work
-- `PLAN.md` — roadmap
-- `COMPLETED.md` — landed milestones
+- `docs/PLAN.md` — the active roadmap
+- `docs/COMPLETED.md` — landed milestones for the current (1.x) cycle
+- `docs/TODO.md` — deferred follow-ups, with the reason each was deferred
+- `docs/TODO-1.0.md` — the raw 1.x work list this cycle's plan was structured from
+- `docs/ARCHIVE.md` — pre-1.0 history
+- `docs/cmake-cheatsheet.md` — a standalone build-system reference
+- `docs/product/` — the product-design reasoning behind each phase