Repository layout (engine-first)

Product unit: the engine

engines/
  quan_loncar_v1/          # stable internal product engine
    ENGINE.yaml
    README.md
    package/               # physics + FDTD + optimizer
    campaigns/             # named strategies
    runs/                  # execution artifacts
    notes/                 # engine-local lab notes
    lineage/               # optional historical packages
  design23_v1/             # stable Design 23
  majumdar_lab/            # lab multilayer stack
  _archive/                # non-product historical trees

Campaigns and runs attach to the engine. Top-level campaigns/ and runs/ hold compatibility symlinks for older local scripts. Public dashboards are durable real-file mirrors at /hub/runs/<id>/dashboard/, all served by the single hub process.

Rules

1. Same package, new seed/objective → new campaign + new run under that engine.
2. Different physics major → new engine version or forked engine id.
3. Finished runs are never overwritten for a different objective.
4. Customer delivery = fork an entire engine tree (engines/<customer>_v1), customize, and iterate on the fork. No shared mutable package across customers.
5. We do not maintain a separate customer-projects layer until we have customers.

Hub & docs

Surface	Command / URL
Hub catalog + persistent dashboards	python tools/publish_hub.py → /hub/
Docs site	python tools/build_docs_site.py
New run	python tools/new_run.py --engine design23_v1 --campaign pure_bfgs_maxQ_diagFDTD