docs

Signed-off-by: stroblme <stroblme@posteo.de>

docs/adding-symbols.md

@@ -1,7 +1,8 @@
 # Adding symbols
 
-The routine task: the app needs an OCCT class this binding does not expose yet.
-Read [design.md](design.md) first if you are touching the machinery instead.
+The routine task: the application consuming this binding needs an OCCT class
+that isn't exposed yet. Read [design.md](design.md) first if you're touching
+the machinery instead.
 
 ## 1. Find what is missing
 
@@ -11,9 +12,9 @@ python tools/inventory.py --check                      # what the wheel lacks, b
 python tools/inventory.py --methods --only BRepAdaptor # what to bind on each class
 ```
 
-`--check` groups gaps by module, which is how increments are scoped. It only
-sees symbols reached through an import (`TopExp.MapShapes_s`), so it answers
-*which* classes to bind but not *what* to bind on them.
+`--check` groups gaps by module, a natural way to scope a batch of work. It
+only sees symbols reached through an import (`TopExp.MapShapes_s`), so it
+answers *which* classes to bind but not *what* to bind on them.
 
 `--methods` answers the second question: it resolves variables assigned
 straight from a constructor and reports the methods called on them, plus
@@ -65,12 +66,12 @@ only in that a base class must precede its derived classes.
   `BRepClass3d_SolidClassifier`, `BRepExtrema_DistShapeShape`, `GCPnts_*`,
   `BRepBuilderAPI_Transform` — bind exactly as stock does.
 - **Enum** → `nb::is_arithmetic()` and `.export_values()`.
-- **`Message_ProgressRange` parameters** → omit them. The app never passes one
-  (no `OCP.Message` import anywhere), and leaving them out keeps signatures
-  small. Add the module if `--check` ever reports it.
+- **`Message_ProgressRange` parameters** → omit them unless a caller actually
+  needs one; `inventory.py --check` will tell you if that changes. Leaving
+  them out keeps signatures small.
 - **Out-parameters** stay out-parameters. `BRep_Tool.Triangulation_s(F, L)`
-  writes through `L` because the app calls it that way; returning a tuple would
-  be tidier and wrong.
+  writes through `L`, matching upstream — returning a tuple would look tidier
+  and would break the fidelity this binding exists to keep.
 
 When in doubt about a signature, ask the stock wheel rather than guessing:
 
@@ -109,18 +110,18 @@ make publish
 tools/parity_venv.sh && python tools/inventory.py --check
 ```
 
-**The app's own tests cannot gate an individual increment.** `backend/tests/
-conftest.py` imports `n3xd.main`, which pulls in the whole app and therefore the
-whole OCP surface, so every backend test fails at collection until the last
-module is bound. Increments are gated here instead: `tools/gen_fixtures.py`
-records reference values from the *stock* wheel (counts, `Modified`/`Generated`/
-`IsDeleted` history maps, measured floats) into `tests/data/manifest.json`, and
-`tests/test_inc<N>_*.py` reproduces the same constructions under our wheel.
-Counts and history maps must match exactly; floats compare at rel 1e-9.
+**The consuming app's own tests can't gate a single addition.** It imports
+the whole application, and therefore the whole `OCP` surface, so every one of
+its tests fails at collection until the last module you're adding is bound.
+Fixtures close that gap instead: `tools/gen_fixtures.py` records reference
+values from the *stock* wheel (counts, `Modified`/`Generated`/`IsDeleted`
+history maps, measured floats) into `tests/data/manifest.json`, and tests
+like `tests/test_inc1_modeling.py` reproduce the same constructions under
+this wheel. Counts and history maps must match exactly; floats compare at
+rel 1e-9.
 
-The app's full suite is the **Inc 4** gate, run in the parity venv, alongside
-`pytest -m perf` and `backend/tools/rebuild_sweep.py --diff` over the project
-store.
+Once everything the app needs is bound, the real gate is running its full
+test suite against this wheel through the parity venv.
 
 ## Adding to `n3xd_ocp` instead