---
description: Layout, forbidden paths, doc sync across README / CONFIG / code
alwaysApply: true
---

# Project layout and documentation discipline (CelerisLab)

## Source tree (authoritative roles)

- [`src/CelerisLab/simulation.py`](src/CelerisLab/simulation.py): Top-level orchestration API (`Simulation`).
- [`src/CelerisLab/config.py`](src/CelerisLab/config.py): `LBMConfig` / `BodyConfig`, load/validate JSON.
- [`src/CelerisLab/configs/`](src/CelerisLab/configs/): JSON defaults and [`CONFIG.md`](src/CelerisLab/configs/CONFIG.md) (human-oriented parameter reference).
- [`src/CelerisLab/cuda/`](src/CelerisLab/cuda/): CUDA context, compile pipeline, **generation** of `lbm/kernels/config/*.h`.
- [`src/CelerisLab/lbm/`](src/CelerisLab/lbm/): Python field/stepper; [`lbm/kernels/`](src/CelerisLab/lbm/kernels/) holds `.cu` / `.cuh` implementation.
- [`src/CelerisLab/body/`](src/CelerisLab/body/): Rigid-style objects, `ObjectManager`, GPU sync for IBM/sensors.
- [`src/CelerisLab/common/`](src/CelerisLab/common/): Shared host utilities (checkpoint, preprocess, …).

Future domains (flexible solids, particles, etc.) should get **new packages** under `src/CelerisLab/` (e.g. `flex/`, `particle/`) and, if they need GPU code, sibling trees under a clear namespace — not ad-hoc files at repo root.

## Do not edit by hand

- `src/CelerisLab/lbm/kernels/config/*.h` — generated by the compiler from `LBMConfig`; change [`cuda/compiler_v2.py`](src/CelerisLab/cuda/compiler_v2.py) and JSON/schema instead.
- `**/*.ptx` — build artifact.

## Low-value context for agents

- [`legacy/`](legacy/): superseded; do not extend.
- [`ref/`](ref/): external reference trees; not part of the shipping package.

(Also listed in [`.cursorignore`](.cursorignore) to save indexing cost.)

## Configuration and documentation sync (critical)

Agents often update one layer and leave others stale. After changing **any** of the following, reconcile **all** that apply in the same task or an immediately following doc-only commit:

1. **JSON keys or shape** in `configs/config_lbm.json` / `config_body.json`
2. **Fields or validation** in `config.py`
3. **Generated macro names or tiers** in `compiler_v2.py` → `kernels/config/*.h`
4. **[`configs/CONFIG.md`](src/CelerisLab/configs/CONFIG.md)** — tables and “config → code” diagram
5. **[`README.md`](README.md)** — Quick Start JSON example, API bullets, Project Layout if paths change
6. **Docstrings** on `Simulation` and other public entry points if behavior or parameters change

Goal: one mental model — README example, CONFIG.md, and actual loader agree.

## Tests

- Behavioral changes should touch or add coverage under [`tests/`](tests/) when feasible.