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