docs(foundry): kitgate/restage in the quickstart, and the two periodicity caveats

Anyone reading a periodicity number needs to know it was length-biased before the fix
and that its floor is per-role — otherwise the vox column looks like a disaster.

tools/foundry/README.md

@@ -147,8 +147,23 @@ for it (TODO #20).
 
 ```bash
 cd tools/foundry
-python3 -m engine.stempack "<pack dir>" --tracks MAREA ANGIE --jobs 3 --out /tmp/cut
-python3 -m engine.kitcheck /tmp/cut/fred_kits.json      # audit what landed
+python3 -m engine.stempack "<pack dir>" --jobs 9 --no-link --out /tmp/cut   # cut
+python3 kitgate.py /tmp/cut/fred_kits.json                                 # gate
+python3 kitgate.py /tmp/cut/fred_kits.json --link                          # …then link
+```
+
+Cut with `--no-link` and let `kitgate.py` decide. It re-runs `grade` over the written
+files (same verdict by a different code path — a disagreement means one of them is
+wrong), runs the `kitcheck` audit, and checks for **bank shadowing before anything is
+linked**: `loadSoundFiles` defaults to `appendToExisting = false`, so a folder whose
+basename matches an existing bank frees that bank's buffers and takes the name, with no
+error and no symptom except an old track playing the wrong sound.
+
+`restage.py` applies the same kit-wide gain staging to kits already on disk — including
+hand-cut ones, which carry whatever level their source had:
+
+```bash
+python3 restage.py --all-under ~/Work/Sound/Samples --dry-run
 ```
 
 One kit per **track × role family** (`fred_marea_drums`, `fred_marea_vox`), files named
@@ -179,6 +194,14 @@ zero crossings, so chops land near 1.0 while loops pay 0.35 on seam and 0.25 on
 consistency. Head to head, chops take every slot: measured on ME, chops 0.993–0.999,
 loops 0.841–0.881, and the vocal kit came out as three stabs with no loops in it.
 
+**Stage the level, because `amp = gain^4`.** Producer stems come off a loud master —
+MAREA's ALL DRUMS and KIT both peak at +0.2 dBFS — so a loop cut from them arrives at full
+scale, which `grade` calls clipping and SuperDirt cannot use: `# gain 1.2` is +7.6 dB and
+the orbit clips the moment you touch it. Kits land with their hottest file at −6 dBFS, as
+**one gain for the whole kit** (per-file normalisation would make a sparse hat loop as loud
+as a full drum bus and throw away the balance two loops from one kit otherwise have for
+free) and **never boosting** (a quiet stem is quiet on purpose).
+
 **The label is evidence, not truth — and neither is the measurement.** `roles.py` maps
 the pack's ~40 role tokens to a family and then measures the stem. Presence and bass are
 decided by measurement (a stem under −40 dBFS peak has nothing in it; "all energy under
@@ -201,6 +224,15 @@ in the wrong kit, silently. Disagreements are reported rather than resolved.
   three sounds is a worse kit than three. Dedup runs at export; `kitcheck` re-checks with
   the same fingerprint and threshold so the two cannot disagree.
 
+Two things about the periodicity test are worth knowing before reading its numbers.
+Autocorrelation at lag *k* has only *N−k* overlapping frames, so normalising by `ac[0]`
+scores identical material lower the shorter the loop — measured 0.418 / 0.623 / 0.754 at
+2 / 4 / 8 bars on a perfect click track, which is length, not rhythm. And the floor is
+**per family**, because the medians split hard by role (drums 0.754, fx 0.549, tonal 0.214,
+bass 0.173, vox 0.087): a drum loop that does not repeat at the bar is broken, while a sung
+phrase that does not repeat within itself is a sung phrase. One threshold for both condemned
+12 of 20 vocal loops for being vocal.
+
 ## Engine roadmap — engine1 → engine2
 
 The separation backend is a **registry** (`engine/separate.py`); the CLI/GUI ask