auto: daily sync

projects/hydrotech-beam/USER_GUIDE.md

@@ -0,0 +1,65 @@
+# Hydrotech Beam — User Guide (Living)
+
+> Audience: Antoine, future users, and Atomizer agents/bots.
+> Status: Living document — update after each meaningful run/decision.
+
+## 1) Purpose
+This guide explains how to run Hydrotech Beam studies safely and reproducibly, how to interpret outputs, and how to avoid common pitfalls (backend mix-up, sync conflicts, stale results).
+
+## 2) Quick Start
+
+### Study folder
+`C:\Users\antoi\Atomizer\Projects\hydrotech-beam\studies\01_doe_landscape`
+
+### Core command (real NX run)
+```powershell
+python .\run_doe.py --backend nxopen --model-dir "<PATH_TO_NX_MODELS>" --clean --study-name hydrotech_beam_doe_phase1_real
+```
+
+### Dev/testing command (fake physics)
+```powershell
+python .\run_doe.py --backend stub --clean --study-name hydrotech_beam_doe_phase1_stub
+```
+
+⚠️ `stub` is synthetic. Do **not** use stub outputs for engineering decisions.
+
+## 3) Critical Rules
+1. Always specify `--backend` explicitly (never rely on defaults).
+2. Before a decision review, confirm whether results are from `nxopen` or `stub`.
+3. Keep result artifacts clean (archive conflicts, avoid mixed appended runs unless intentional).
+4. After every run, write a run log entry (template below).
+
+## 4) Run Log Template (required)
+Copy this into `DECISIONS.md` or project log after every run:
+
+```md
+## Run Record — YYYY-MM-DD HH:MM
+- Operator:
+- Command:
+- Backend: nxopen | stub
+- Model dir:
+- Study name:
+- Constraints: displacement=__ mm, stress=__ MPa
+- Result summary: total=__, solved=__, geo_infeasible=__, feasible=__
+- Gate check: PASS | FAIL
+- Notes/issues:
+- Next action:
+```
+
+## 5) Playbooks
+- `playbooks/NX_REAL_RUN.md` — clean real run checklist + validation
+- `playbooks/DOE.md` — DOE execution and gate rules
+- `playbooks/SYNCTHING_RECOVERY.md` — sync conflict and stale data recovery
+
+## 6) Current Known Pitfalls
+- `run_doe.py` default backend is `stub` unless overridden.
+- Mixing old + new runs in same DB/file can produce misleading totals.
+- Syncthing conflict files (`*.sync-conflict-*`) can silently fork truth.
+- NX expression names must match exactly (e.g., typo-sensitive names in model).
+
+## 7) Ownership
+- CEO (Antoine): go/no-go and final technical decisions.
+- Manager: orchestration + process + documentation enforcement.
+- Study Builder: run scripts and settings correctness.
+- Tech Lead: engineering validity of constraints and interpretation.
+- Auditor: quality gate before external conclusions.