docs: add QUICK_REF + workflow OS + 2026Q1 roadmap

docs/QUICK_REF.md

@@ -0,0 +1,74 @@
+# Atomizer QUICK_REF
+
+> 2-page maximum intent: fastest lookup for humans + Claude Code.
+> If it grows, split into WORKFLOWS/* and PROTOCOLS/*.
+
+_Last updated: 2026-01-29 (Mario)_
+
+---
+
+## 0) Non-negotiables (Safety / Correctness)
+
+### NX process safety
+- **NEVER** kill `ugraf.exe` / user NX sessions directly.
+- Only close NX using **NXSessionManager.close_nx_if_allowed()** (sessions we started).
+
+### Study derivation
+- When creating a new study version: **COPY the working `run_optimization.py` first**. Never rewrite from scratch.
+
+### Relative WFE
+- **NEVER** compute relative WFE as `abs(RMS_a - RMS_b)`.
+- Always use `extract_relative()` (node-by-node difference → Zernike fit → RMS).
+
+### CMA-ES baseline
+- `CmaEsSampler(x0=...)` does **not** evaluate baseline first.
+- Always `study.enqueue_trial(x0)` when baseline must be trial 0.
+
+---
+
+## 1) Canonical workflow order (UI + docs)
+
+**Create → Validate → Run → Analyze → Report → Deliver**
+
+Canvas is a **visual validation layer**. Spec is the source of truth.
+
+---
+
+## 2) Single source of truth: AtomizerSpec v2.0
+
+- Published spec: `studies/<topic>/<study>/atomizer_spec.json`
+- Canvas edges are for visual validation; truth is in:
+  - `objective.source.*`
+  - `constraint.source.*`
+
+---
+
+## 3) Save strategy (S2)
+
+- **Draft**: autosaved locally (browser storage)
+- **Publish**: explicit action that writes to `atomizer_spec.json`
+
+---
+
+## 4) Key folders
+
+- `optimization_engine/` core logic
+- `atomizer-dashboard/` UI + backend
+- `knowledge_base/lac/` learnings (failures/workarounds/patterns)
+- `studies/` studies
+
+---
+
+## 5) Session start (Claude Code)
+
+1. Read `PROJECT_STATUS.md`
+2. Read `knowledge_base/lac/session_insights/failure.jsonl`
+3. Read this file (`docs/QUICK_REF.md`)
+
+---
+
+## 6) References
+
+- Deep protocols: `docs/protocols/`
+- System instructions: `CLAUDE.md`
+- Project coordination: `PROJECT_STATUS.md`

docs/ROADMAP/2026Q1_CREATE_WIZARD.md

@@ -0,0 +1,29 @@
+# Roadmap 2026 Q1 — Create Wizard + Spec/Canvas Foundation
+
+_Last updated: 2026-01-29 (Mario)_
+
+## Milestone M1 — Spec/Canvas is deterministic (Foundation)
+- [ ] Frontend has `lib/spec` converters (specToNodes/specToEdges)
+- [ ] Objective/constraint `source` is truth
+- [ ] Edges are projections of `source`
+- [ ] Node positions persist
+
+## Milestone M2 — Draft + Publish (S2)
+- [ ] DraftManager local autosave
+- [ ] Publish writes server spec with hash check
+- [ ] Conflict banner behavior defined
+
+## Milestone M3 — Create Wizard v1 (Files + Introspection + Validate + Publish)
+- [ ] `/create` route + stepper
+- [ ] Files step w/ dependency tree + `_i.prt` warnings
+- [ ] Introspection step w/ expressions list + DV selection
+- [ ] Validate step (checklist + parameters table + canvas)
+- [ ] Publish step (create study folder + write README)
+
+## Milestone M4 — Create Wizard v2 (Context + Draft + Interview)
+- [ ] Context scan + bundle
+- [ ] Draft endpoint
+- [ ] Interview engine integration
+
+## Notes
+- Canvas stays as validation layer; spec remains the executable truth.

docs/WORKFLOWS/ANALYZE.md

@@ -0,0 +1,11 @@
+# Workflow: ANALYZE
+
+_Last updated: 2026-01-29 (Mario)_
+
+## Goal
+Explore results + generate insights.
+
+## UI
+- Results overview
+- Insights bank (generate HTML artifacts)
+- Claude-assisted interpretation

docs/WORKFLOWS/CREATE.md

@@ -0,0 +1,26 @@
+# Workflow: CREATE (Study Creation)
+
+_Last updated: 2026-01-29 (Mario)_
+
+## Goal
+Create a new study via the **Create Wizard**:
+
+Files → Introspection → Context → Draft → Interview → Validate → Publish
+
+## Source of truth
+- Draft spec (local): browser storage
+- Published spec: `atomizer_spec.json`
+
+## Outputs required (DoD)
+- `atomizer_spec.json` (published)
+- `README.md` (auto-generated)
+- Study folder structure created
+
+## Key rules
+- Don’t ask user for info we can introspect.
+- Ask only gap questions.
+- Canvas is validation (gimmick), not the authoring source.
+
+## See also
+- PKM: TECH-SPEC-Create-Wizard-Blueprint
+- PKM: TECH-SPEC-Canvas-Study-Sync

docs/WORKFLOWS/DELIVER.md

@@ -0,0 +1,13 @@
+# Workflow: DELIVER
+
+_Last updated: 2026-01-29 (Mario)_
+
+## Goal
+Package everything for client delivery:
+- report
+- optimized model files
+- optional insights html bundle
+- optional DB/logs
+
+## Also
+Archive study + capture learnings in LAC.

docs/WORKFLOWS/REPORT.md

@@ -0,0 +1,12 @@
+# Workflow: REPORT
+
+_Last updated: 2026-01-29 (Mario)_
+
+## Goal
+Generate client-ready artifacts:
+- Markdown
+- HTML
+- PDF (Atomizer branded template)
+
+## Notes
+Report generation should be deterministic, with Claude optional for narrative additions.

docs/WORKFLOWS/RUN.md

@@ -0,0 +1,16 @@
+# Workflow: RUN
+
+_Last updated: 2026-01-29 (Mario)_
+
+## Goal
+Start and reliably track long-running optimizations.
+
+## Requirements
+- Published `atomizer_spec.json`
+- Backend can start/stop processes safely
+
+## UI
+- Live status + progress
+- Convergence
+- Best trial summary
+- Safe stop

docs/WORKFLOWS/VALIDATE.md

@@ -0,0 +1,20 @@
+# Workflow: VALIDATE
+
+_Last updated: 2026-01-29 (Mario)_
+
+## Goal
+Give the user confidence that the study will run correctly:
+- correct model chain
+- DV bounds sane
+- objectives/constraints correctly sourced
+- spec is runnable
+
+## Primary UI
+- Checklist + Parameters table
+
+## Secondary UI
+- Canvas visualization
+
+## Outputs
+- Validation report (errors/warnings)
+- "Ready to Run" state