# 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`