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.

src/shell/actions/CLAUDE.md

@@ -0,0 +1,53 @@
+# src/shell/actions — bindable REAPER actions, drag/drop shells, ingest
+
+## Scope
+
+The bindable action families routed through REAPER's `command_id`/`gaccel`/
+`hookcommand` contract (Design View toggle actions, bank actions, the prune
+action, and the shared registration plumbing/table), plus the OS drag-out and
+FX-drop shells, plus the extension-side ingest-through-the-bank shell. This is
+where user-facing REAPER actions and OS-level drag/drop live; the underlying
+mutation logic (bank verbs, prune's orphan computation, view-mode reconciliation)
+is owned by other directories and only skinned here.
+
+## Invariants
+
+- **Ingest is an extension act; the instrument is a read-only bank consumer.** Any
+  instrument code path that captures, imports, inserts a timeline item, or writes
+  back into the bank is a bug — the instrument reads and plays only.
+- **Ingest NEVER inserts a timeline item.** Arrange capture→bank→assign reuses the
+  existing capture add-path and assigns the resulting `Sample` id to the target
+  instance; it never places anything on the timeline — capture/placement
+  separation is load-bearing here same as everywhere else. Only the arrange-capture
+  surface writes the `assignment_request` wire; Media-Explorer import and file-drop
+  onto the bank panel do not, and neither affects a live instance's selection.
+- **Every bank index verb wraps its mutation in a batched REAPER undo point**
+  (`Undo_BeginBlock2`/`EndBlock2`, `UNDO_STATE_MISCCFG`) so one bank operation is
+  one Ctrl-Z.
+- **The prune action is the ONLY file-deletion action in the system**; it opens no
+  undo point (file deletion is not REAPER-undoable). It halts on
+  `abortedUnreadableUsage` and prints the offending `rsusage_*` key names.
+
+## Modules
+
+- `shell/actions` (`action_registry` / `design_view_actions` / `bank_actions` / `prune_action`) — the bindable action families, all routed via the `command_id`/`gaccel`/`hookcommand` contract. `action_registry` owns the shared registration plumbing (interned channel-qualified id strings; register and mirror-unregister present the identical pointer) **and the Q-W6 registration TABLE**: `main.cpp`'s own family (capture scopes, panel toggle, insert, batch, realtime, recapture, version) is one `ActionTableRow` array — suffix, phrase, flat function-pointer handler — that registration, hookcommand dispatch, and the unload mirror-unregister all iterate, so adding an action touches the table only (OCP). Bank mutations flow through the promptless `shell/bank_ops` verbs (`bankOp*` + `persistBankOp`, taking `ReaSamplerSession&`), which the panel menus and `bank_actions` consume as thin UX skins. **Every bank index verb wraps its mutation in a batched REAPER undo point (`Undo_BeginBlock2`/`EndBlock2`, `UNDO_STATE_MISCCFG`) so one bank operation is one Ctrl-Z.** The prune action (`prune_action`, `BANK_PRUNE_FOLDER`) is **the ONLY file-deletion action in the system**; it opens no undo point (file deletion is not REAPER-undoable). **pS-usage:** `BANK_PRUNE_FOLDER` halts on `abortedUnreadableUsage` and prints the offending `rsusage_*` key names with clear instructions.
+- `drag_out_win` — OS drag-out shell: Windows OLE `DoDragDrop`/`CF_HDROP`, copy-only (`DROPEFFECT_MOVE` not offered); macOS/Linux via `SWELL_InitiateDragDropOfFileList`.
+- `instrument_drop_win` — FX-button drop shell: resolves a screen point to a track + FX-surface hotspot, then adds a ReaSampler 9000 instance and applies the dragged capture's state via a transient `.vstpreset` + `TrackFX_SetPreset` (the former `TrackFX_SetNamedConfigParm` "vst_chunk" write was silently unappliable for VST3). Exposes `loadInstrumentOntoTrack` (inner half, no own undo block) and `performInstrumentDrop` (wraps in its own undo block). **Never captures, never writes the bank, never inserts a timeline item.**
+- `ingest` — ingest-through-the-bank shell on the EXTENSION side: three surfaces — (1) arrange capture→bank→assign (bindable action), (2) Media-Explorer import→bank→instrument on the selected track, (3) file drop onto the bank panel→bank only. Only surface (1) writes the `assignment_request` ext-state wire. **ingest NEVER inserts a timeline item.**
+
+## Gotchas
+
+- **Structural wart, not yet fixed:** `ingest.cpp` / `ingest.h`, plus `ext_keys.h`
+  and `resource.h`, physically live at `src/` root rather than under
+  `shell/actions/` — Phase Q's reorg did not re-home these files into
+  `core/`/`shell/`/`app/`. `ingest` is documented here as its nearest sibling by
+  role, but the files themselves are not in this directory. This is a code
+  organization issue, not a documentation one — see Open questions in the
+  originating dispatch report.
+- Media-Explorer import is single-file, pull-on-action (`OpenMediaExplorer` +
+  `MediaExplorerGetLastPlayedFileInfo`) — there is no enumerate-selected-files or
+  register-a-drop-handler API on the Media Explorer surface.
+- REAPER exposes no drag-drop registration API; drop handling is only on
+  ReaSampler's own HWNDs (`WM_DROPFILES`/`IDropTarget` on the docked `bank_panel`).
+  A drop onto the VST3 editor window relaying to the extension is an unproven
+  spike, not a shipped path.