docs: add QUICK_REF + workflow OS + 2026Q1 roadmap

PROJECT_STATUS.md

@@ -0,0 +1,104 @@
+# PROJECT_STATUS.md
+
+> **Bridge document for Mario (Clawdbot) ↔ Claude Code coordination**
+> 
+> Both AIs should read this at session start. Update when priorities change.
+
+*Last updated: 2026-01-27 by Mario*
+
+---
+
+## Current Focus
+
+**Phase**: Foundation (Phase 1)
+**Sprint**: 2026-01-27 to 2026-02-03
+
+### This Week's Priorities
+
+1. 🔴 **Dashboard Pain Points** — Antoine to document what's broken/missing
+2. 🔴 **QUICK_REF.md** — Mario drafting simplified protocol reference
+3. 🔴 **CONTEXT.md** — Mario drafting session initialization (like Clawdbot's AGENTS.md)
+4. 🟡 **LAC → Git Protocol** — Ensure learnings are committed after sessions
+
+### Blocked
+
+- Phase 2 (Dashboard) waiting on pain point documentation
+
+---
+
+## Active Decisions
+
+| Decision | Summary | Date |
+|----------|---------|------|
+| Full Partnership | Mario = PM, reviewer, architect. Antoine = developer, NX. | 2026-01-27 |
+| Dashboard on Windows | Keep simple for now, hybrid architecture later | 2026-01-27 |
+| Adopt Clawdbot Patterns | MEMORY.md, QUICK_REF.md, simplified CLAUDE.md | 2026-01-27 |
+
+---
+
+## For Claude Code
+
+When starting a session:
+
+1. ✅ Read CLAUDE.md (system instructions)
+2. ✅ Read PROJECT_STATUS.md (this file — current priorities)
+3. ✅ Read `knowledge_base/lac/session_insights/failure.jsonl` (critical lessons)
+4. 🔲 After session: Commit any new LAC insights to Git
+
+### LAC Commit Protocol (NEW)
+
+After each significant session, commit LAC changes:
+
+```bash
+cd Atomizer
+git add knowledge_base/lac/
+git commit -m "lac: Session insights from YYYY-MM-DD"
+git push origin main && git push github main
+```
+
+This ensures Mario can see what Claude Code learned.
+
+---
+
+## For Mario (Clawdbot)
+
+When checking on Atomizer:
+
+1. Pull latest from Gitea: `cd /home/papa/repos/Atomizer && git pull`
+2. Check `knowledge_base/lac/session_insights/` for new learnings
+3. Update tracking files in `/home/papa/clawd/memory/atomizer/`
+4. Update this file if priorities change
+
+### Heartbeat Check (Add to HEARTBEAT.md)
+
+```markdown
+### Atomizer Check (weekly)
+- git pull Atomizer repo
+- Check for new LAC insights
+- Review recent commits
+- Update roadmap if needed
+```
+
+---
+
+## Recent Activity
+
+| Date | Activity | Who |
+|------|----------|-----|
+| 2026-01-27 | Created master plan in PKM | Mario |
+| 2026-01-27 | Created tracking files | Mario |
+| 2026-01-27 | ACKed Atomizer project | Mario |
+| 2026-01-27 | Canvas V3.1 improvements | Claude Code (prior) |
+
+---
+
+## Links
+
+- **Master Plan**: `/home/papa/obsidian-vault/2-Projects/Atomizer-AtomasteAI/Development/ATOMIZER-NEXT-LEVEL-MASTERPLAN.md`
+- **Mario's Tracking**: `/home/papa/clawd/memory/atomizer/`
+- **LAC Insights**: `knowledge_base/lac/session_insights/`
+- **Full Roadmap**: See Master Plan in PKM
+
+---
+
+*This file lives in the repo. Both AIs can read it. Only update when priorities change.*

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