@@ -1,13 +1,14 @@
 # Pre-cutover Export Correctness Implementation Plan
 
-**Status:** Phases 1–5 complete (export gate fails closed; device resolution / day bad-channel merge; Hardware Config wiring + identity safety; schema-valid device output — integer IDs end-to-end, required device fields, per-shank offsets, no stray keys, ntrode-/group-ID uniqueness; subject/session completeness + DANDI — weight/description collected, timestamp DOB, Latin-binomial species + no-slash ids, required `experiment_description`, and an in-Overview subject repair surface). Phases 6–11 not started in this main plan; Phase 8.5 has been added as the pre-QA domain-boundary hardening gate. Workflow discoverability/mental-model concerns are now recorded as an explicit Phase 11 input in [workflow-clarity-design.md](workflow-clarity-design.md). Note: an interim refinement made electrode-group `location` optional in the editor and then reverted to required-with-targeted-default per lab decision (see overview.md / REFACTOR_CHANGELOG).
+**Status:** Phases 1–5 are recorded as complete in this plan snapshot (export gate fails closed; device resolution / day bad-channel merge; Hardware Config wiring + identity safety; schema-valid device output — integer IDs end-to-end, required device fields, per-shank offsets, no stray keys, ntrode-/group-ID uniqueness; subject/session completeness + DANDI — weight/description collected, timestamp DOB, Latin-binomial species + no-slash ids, required `experiment_description`, and an in-Overview subject repair surface). Later phase implementation status should be verified from the current branch and changelog; Phase 8.5 is the pre-QA domain-boundary hardening gate and Phase 8.6 is the pre-QA workflow-clarity/setup-UX gate. Note: an interim refinement made electrode-group `location` optional in the editor and then reverted to required-with-targeted-default per lab decision (see overview.md / REFACTOR_CHANGELOG).
 
 The new multi-page workspace UI can currently hand `trodes_to_nwb` a YAML file that is
 silently wrong — missing electrode probes, missing day-level bad-channel marks, schema-invalid
 device IDs, or a date-of-birth the schema rejects — with no error shown to the user. This plan
 closes those export-correctness defects so the workspace path produces valid, complete metadata,
 and hardens the surrounding import and persistence edges. **Scope note:** phases 1–8 are the
-export-correctness fixes; Phase 8.5 is behavior-preserving pre-QA architecture hardening; phases 9–11
+export-correctness fixes; Phase 8.5 is behavior-preserving pre-QA architecture hardening; Phase 8.6
+makes the user workflow and setup UX understandable before browser QA; phases 9–11
 extend the plan to pre-cutover **QA and UX readiness** (browser regression QA, a Claude-executable
 usability/behavior audit, and a professional-UX-polish audit) so the workspace is not only correct but
 coherent and safe for repeated scientific use. It is the correctness
@@ -42,6 +43,7 @@ For agent invocation, **load only the slice you need**:
   - [phase-7-import-persistence-hardening.md](phase-7-import-persistence-hardening.md) — **P2:** the shared nested-error-path fix (workspace gate messages) + the explicitly scoped legacy partial-import exception; guard the empty-blob load crash and the failed-autosave unsaved-work gap.
   - [phase-8-optogenetics-correctness.md](phase-8-optogenetics-correctness.md) — **P1 (opto sessions):** add/verify the workspace opto entry path, fix the trodes_to_nwb opto key mismatches (`optogenetic_stimulation_software`, `volume_in_uL`) with a schema-safe transition, and validate all-or-nothing completeness so an opto session isn't silently dropped.
   - [phase-8-5-domain-boundaries-ownership-cleanup.md](phase-8-5-domain-boundaries-ownership-cleanup.md) — **pre-QA architecture hardening:** move app-wide validation/repair routing and converter semantics out of page modules, extract the riskiest workspace transitions into pure helpers, and add architecture guard tests before Playwright verifies the integrated path.
-  - [phase-9-playwright-qa-pass.md](phase-9-playwright-qa-pass.md) — **browser regression QA:** add a Playwright workspace regression suite and runbook that exercise the corrected Phases 1–8.5 flows in a real browser: mistake-prevention UX, repair navigation, export gating/preflight/download, persistence recovery, and opto on/off behavior.
+  - [phase-8-6-workflow-clarity-setup-ux.md](phase-8-6-workflow-clarity-setup-ux.md) — **pre-QA workflow clarity:** add a domain-backed setup/readiness model and align Animal Workspace, Animal Editor, Day Devices, reconfiguration, Validation, and Export around the user's workflow so electrode setup and existing-data review are discoverable before Playwright QA.
+  - [phase-9-playwright-qa-pass.md](phase-9-playwright-qa-pass.md) — **browser regression QA:** add a Playwright workspace regression suite and runbook that exercise the corrected Phases 1–8.6 flows in a real browser: mistake-prevention UX, repair navigation, export gating/preflight/download, persistence recovery, workflow clarity, and opto on/off behavior.
   - [phase-10-claude-usability-behavior-audit.md](phase-10-claude-usability-behavior-audit.md) — **Claude-executable usability/proper-behavior audit:** run scripted scenario matrices, mistake injection, UI/state/export triangulation, keyboard/viewport checks, and produce a findings/fix log before cutover.
   - [phase-11-professional-ux-polish-audit.md](phase-11-professional-ux-polish-audit.md) — **professional UX polish audit (not the v3 cutover phase):** run a Claude-executable workflow-clarity, design-system, interaction-consistency, accessibility, content, responsive-layout, and perceived-performance pass with fixes/findings.
@@ -10,6 +10,73 @@ Plan disposition: the pre-QA subset of this review is now incorporated as
 Treat the phase file as the executable source of truth. This note remains the architectural rationale and
 should be refreshed at the start of Phase 8.5 before code changes begin.
 
+## Refreshed inventory at Phase 8.5 start (verified against the branch)
+
+The review below predates phases 1–8 in wording but is structurally accurate. Verified current state
+before extraction, with the exact symbols/targets each task moves:
+
+- **App-wide validation/repair routing lives in `src/pages/DayEditor/validation.js`** (906 lines). It
+  exports `validateDay`, `computeStepStatus`, `computeDevicesStatus`, `computeEpochsStatus`,
+  `dayOverrideIssues`, `groupErrorsByStep`, `stepIdForIssue`, `repairTargetForIssue`,
+  `animalEditorStepForFieldPath`, `STEP_LABELS`, `SURFACE_BY_CODE`, `ANIMAL_EDITOR_STEPS`, plus the
+  page-only field-blur helper `validateField`. Phase 8 added opto/fs_gui routing here
+  (`SURFACE_BY_CODE.partial_configuration/multiple_excitation_sources`, the `fs_gui` branches in
+  `stepIdForIssue`/`deriveSurfaceFromPath`, the Optogenetics entry in `ANIMAL_EDITOR_STEPS`) — that
+  routing moves intact.
+  - **Consumers (verified):** same-folder `DayEditorStepper` (`computeStepStatus`), `ExportStep`
+    (`computeStepStatus`, `validateDay`, `STEP_LABELS`), `OverviewStep` (`validateField` — page-only,
+    stays), `RepairActions` (`repairTargetForIssue`, `STEP_LABELS`), `ValidationStep`
+    (`groupErrorsByStep`, `validateDay`); and the two **cross-page (sibling) importers that are the
+    real violations** — `pages/AnimalEditor/AnimalEditorStepper.jsx`
+    (`animalEditorStepForFieldPath`) and `pages/ValidationSummary/index.jsx` (`computeStepStatus`).
+  - **Task 1 target:** move everything except `validateField` to `src/domain/validation.js`; repoint
+    all consumers (including Day Editor's own) at the domain module; leave `validateField` in
+    `pages/DayEditor/validation.js`.
+- **Bad-channel + override converter semantics live in render bodies (Task 2 targets):**
+  - `pages/DayEditor/BadChannelsEditor.jsx` — multi-shank detection (`getProbeShanks().length > 1 &&
+    ntrodes.length > 1`), later-row mark translation (`translateLaterRowMarks`), the probe-wide
+    migration union (`handleProbeWideToggle`), and invalid-mark detection.
+  - `pages/AnimalEditor/ChannelMapEditor.jsx` — the same multi-shank/translation/migration logic plus
+    `validateChannelMaps` (probe-local range, multi-shank first-row, scalar-tolerance).
+  - `pages/DayEditor/DevicesStep.jsx` — `validateBadChannels` (multi-shank first-row range) and the
+    malformed/stale/shadowing override-cleanup decisions (`wholeOverridesMalformed`,
+    `badChannelContainerMalformed`, `staleOverrideKeys`, `corruptValueKeys`, `presentGeometryKeys`),
+    which **mirror `dayOverrideIssues`**.
+  - **Task 2 target:** pure `src/domain/badChannels.js` (multi-shank rule, later-row translation,
+    probe-wide map build, invalid-mark interpretation, range check) and `src/domain/deviceOverrides.js`
+    (`classifyDeviceOverrides`), with a test that the classifier corresponds 1:1 to `dayOverrideIssues`.
+- **At Phase 8.5 start, risky workspace transitions lived inline in `src/state/useWorkspace.js`
+  (Task 3 targets):** the `updateAnimal` devices branch (mirrors the edit into the latest snapshot,
+  lines ~228-248), the reconfiguration snapshot/apply actions, `rebuildConfigurationHistory`, `createDay`,
+  and `updateDay`'s malformed-session guard. The completed Phase 8.5 cleanup moved the transition recipes
+  into `src/state/workspaceTransitions.js`, made the atomic `createConfigurationSnapshotAndApplyForward`
+  the only public reconfiguration action, removed the orphaned two-action store API, and pins new days to
+  the latest snapshot's actual version rather than the history length. Electrode-group/channel-map mutation
+  recipes still live in
+  `pages/AnimalEditor/AnimalEditorStepper.jsx` (`handleSaveGroup`, `confirmDeleteGroup`,
+  `handleCopyConfirm`, `handleSaveChannelMap`).
+  - **Task 3 target:** pure `src/state/workspaceTransitions.js` with the four named transitions;
+    `useWorkspace` keeps hydration, autosave, debounce, localStorage, the existence-check throws, and
+    the `workspaceRef`/version-return orchestration.
+- **`src/state/repairCommands.js`** is the executable-repair executor (current command set:
+  `resetDayCollection`, `resetAnimalCameras`, `resetDataAcqDevice`, `rebuildConfigurationHistory`,
+  `resetDeviceOverrides`, `removeDeviceOverrideKey`, `resetBadChannelOverrides`,
+  `removeBadChannelOverrideKey`, `resetDaySession`) — already a state-layer module; not moved.
+- **`pages/DayEditor/shadowExport.js`** is pure export-truth behavior (encoder-stability check) that a
+  sibling page (`ValidationSummary`) imports cross-folder. **Task 1/4 target:** move to
+  `src/domain/shadowExport.js` so no page imports export-truth from a sibling page.
+
+### Deferred at Phase 8.5 (recorded, not expanded)
+
+- **Issue #4 (legacy/workspace facade in `store.js`)** — legacy-path relocation/removal is explicitly
+  out of scope for this phase (and gated on the v3 cutover). Not touched.
+- **Issue #5 (schema-aligned types)** — type generation/sync is deferred to post-cutover per the phase
+  scope guard; only done if type drift directly blocks the phase (it does not).
+- **`pages/DayEditor/SaveIndicator.jsx`** is a shared **presentational** component imported by
+  `AnimalEditor/HardwareConfigStep`. It is not app-wide domain behavior, so relocating it to
+  `src/components` is out of this phase's scope; the architecture guard allowlists this single
+  presentational cross-page import and forbids all others.
+
 ## Verdict
 
 The app is moving in the right direction, but it is not yet cleanly organized. The recent
 
@@ -33,14 +33,16 @@ fixed at record time — pinning matches the science.)
   surface. `updateAnimal({ devices })` writes **both** `animal.devices` **and**
   `configurationHistory[latest].devices`, keeping them in sync. *This is the new behavior that fixes the
   P0:* configuring probes now flows into version 1's snapshot, so days pinned to it export the probes.
-- **`createDay`** pins `day.configurationVersion = animal.configurationHistory.length` (the latest
-  version) — already its behavior (`useWorkspace.js:410-433`); now that version actually holds the config.
+- **`createDay`** pins `day.configurationVersion` to the latest snapshot's actual version number (not the
+  history length, so non-contiguous repaired histories still pin to a resolvable version). Now that latest
+  version actually holds the config.
 - **Reconfiguration is fork-before-edit** (the explicit freeze the High-severity review finding asked
   for). The wizard's "Reconfigure from day X" action, run **before** the user edits the new geometry:
-  1. `addConfigurationSnapshot(animal.id, { devices: clone(latest snapshot), … })` → a new version N+1
-     that starts **identical** to the current config (returns N+1 — the v3-plan return-value contract).
-  2. `applyConfigurationForward(animal.id, N+1, [day X … end])` → repoints the chosen days to N+1.
-  3. Set `animal.devices` to mirror version N+1 (the new latest).
+  1. `createConfigurationSnapshotAndApplyForward(animal.id, { devices: clone(latest snapshot), ... }, [day X ... end])`
+     creates a new version N+1 that starts **identical** to the current config and repoints the chosen days
+     to it in one atomic transition.
+  2. `animal.devices` is already the mirror of that cloned latest config. When the user edits geometry after
+     the fork, `updateAnimal({ devices })` writes the mirror and the new latest snapshot together.
 
   Now days **before** X stay pinned to version N (its snapshot frozen with the *old* config), and days
   **X…end** are on N+1. When the user then edits geometry in the Animal Editor, `updateAnimal` writes
@@ -61,10 +63,11 @@ copy-on-write-per-keystroke and no draft layer — the fork is the single, expli
 The Phase-10.5 wizard currently reads already-edited `animal.devices` as `nextConfig` and renders a
 live-vs-snapshot diff. Under model B that diff is dropped (your call: "apply the current configuration to
 days X–Y" with no diff). The wizard becomes a **fork-point selector**: pick the boundary day + the day
-range, confirm, fork (steps 1–3 above); geometry is then edited in the Animal Editor against the new
-latest version. Keep the existing `addConfigurationSnapshot` / `applyConfigurationForward` actions and
-the returned-version contract; only the wizard's call order and its UI change. Keep
-`reconfigWorkflow.integration.test.js` / `ReconfigWizard.test.jsx` green, updated to the model.
+range, confirm, fork with the atomic action above; geometry is then edited in the Animal Editor against the new
+latest version. The public store entry point is `createConfigurationSnapshotAndApplyForward`; the old
+two-action store API (`addConfigurationSnapshot` then `applyConfigurationForward`) has been removed as
+production-dead. Keep the pure transition helpers and `reconfigWorkflow.integration.test.js` /
+`ReconfigWizard.test.jsx` green, updated to the atomic model.
 
 ### What phase 2 must prove