Document bounded multigrid and add public remap example

docs/synchronized_leaf_remap.md

@@ -1,8 +1,9 @@
 # Synchronized leaf G remap and manual continuation
 
 This is a CPU state-transfer component, **not a runtime adaptive solver**.
-It changes only a separated L2 rectangle set in a three-level, body-free,
-periodic hierarchy. L0/L1 topology, relaxation parameters, direction order,
+It changes only a separated L2 rectangle set in a three-level periodic
+hierarchy, either body-free or with stationary Circles/Jets in unchanged pinned
+L2 rectangles (see below). L0/L1 topology, relaxation parameters, direction order,
 physical frame and completed time remain unchanged. Existing geometry checks
 validate child support/nesting and separation. The CPU helper itself adds no CUDA, scheduler, allocator, boundary handling,
 collision or ghost refill. A bounded runtime adapter is described below.
@@ -29,11 +30,12 @@ origin is retained. Physical lower edges are `origin + spacing*(x,y)` on L0,
 `origin + spacing*(parent.fine_origin + (x,y)/4)` on L2.
 
 Factory options `coarse_boundary` and `objects` must declare `"periodic"` and
-an empty body collection (all levels). LBMConfig's channel settings do not
+an empty L0/L1 body collection; use `child_objects`/`child_jets` for pinned L2
+bodies. LBMConfig's channel settings do not
 select this operator's boundary mode. Geometry metadata is factory-created;
 manual mutation/forging of metadata is unsupported. Caller certifies the
-actual state has no bodies/forcing, that all device work and old readers are
-quiescent, and that inputs are the **current owned-leaf postcollision G**.
+actual state has no undeclared bodies or forcing, that all device work and old
+readers are quiescent, and that inputs are the **current owned-leaf postcollision G**.
 Count/phase stamps check consistency, not freshness or active-buffer identity.
 
 `current_g` is three NumPy Q-major arrays `(9,ny,nx)`. For blocked inputs,
@@ -73,8 +75,9 @@ PYTHONPATH=src python -m unittest discover -s tests/unit -p 'test_synchronized_r
 
 `replacement = current.remap_child(rectangles)` returns a new ready
 `FixedPatchStepper` at the **same absolute step_count**. It supports only
-body-free periodic three-level runs whose existing L2 uses
-`child_rectangles_in_parent`. Scalar or union L1 parents are supported; scalar
+periodic three-level runs whose existing L2 uses
+`child_rectangles_in_parent`, either body-free or under the pinned-body rules below.
+Scalar or union L1 parents are supported; scalar
 `child=` is deliberately rejected. L0/L1, relaxation and block sizes stay fixed.
 No tagger, scheduler, in-place replacement, or general rollback is provided.
 
@@ -105,9 +108,9 @@ and geometry, and candidate/source failure cleanup. GPU tests are predeclared
 in `tests/validation/multigrid/test_runtime_child_remap_gpu.py`: identity next
 step bitwise, shifted A→B→A with two intervals between changes, uniform moving
 and nonequilibrium states, exact CPU remap and overlap, both buffers reset,
-finite leaves, exact masks and absolute counts. They were not run on the CPU
-host. The separate independent FP64 capture/replay gate is max population
-error **3e-6**, with exact masks; remap mass/momentum allow FP32 roundoff.
+finite leaves, exact masks and absolute counts. These are GPU execution gates,
+not CPU-mock results. The separate body-free independent FP64 capture/replay
+gate is max population error **3e-6**, with exact masks; remap mass/momentum allow FP32 roundoff.
 Per-population conservation is not an advancement target under collision.
 
 ### Bounded pinned-body extension
@@ -155,6 +158,28 @@ Multiple-body CPU coverage: `tests/unit/test_multiple_pinned_remap.py`.
 two independently updated Jets, variable fluid-region counts and add/move/remove
 immediate comparisons with CPU transfer. All nine solid-excluded area-weighted
 population integrals, exact overlap and nonleaf NaNs are checked.
-These new GPU cases have **not been run here**. They do not establish evolution
-accuracy. A 3e-6 FP32-vs-FP64 evolution gate requires a separate independent
-BFL reference; the body-free replay gate above does not establish that claim.
+These transfer/equivalence cases do not establish evolution accuracy. Historical
+pinned-body FP64 replay uses actual L1 feeds: it checks conditional L2 evolution,
+not an independent whole-body solver or whole-hierarchy accuracy. The body-free
+replay gate above does not establish that stronger claim either.
+
+## Small runnable usage example
+
+[`examples/multigrid_remap.py`](../examples/multigrid_remap.py) keeps the original
+root-frame Circle/Jet definitions, moves a fluid-only L2 rectangle, checks fluid
+leaves with geometry-derived masks and retires both old/new owners before their
+shared context. `--verify-jet` adds a temporary control solely to compare the
+next step against an explicitly set live amplitude; normal use needs no control.
+
+```sh
+# Host-only: no CUDA import or allocation.
+PYTHONPATH=src python examples/multigrid_remap.py --check-geometry
+# Horsea: select an approved idle physical GPU; it becomes logical device 0.
+PYTHONPATH="$PWD/src" CUDA_VISIBLE_DEVICES=0 python examples/multigrid_remap.py --verify-jet
+```
+
+The new example has passed host geometry and syntax/import checks only; its GPU
+run is pending Horsea. Expected scope: base counts 2 before/after remap, then 5;
+finite positive-density fluid leaves, NaN nonleaves, and exact next-step control
+agreement. This is a short public-API smoke run, not a physical accuracy test.
+No flowfiles are written.