Public repo: neutral wording for private references, CI scan, Dependabot

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

.github/workflows/ci.yml

@@ -43,3 +43,14 @@ jobs:
           top=$(grep -m1 -E '^## [0-9]+\.[0-9]+\.[0-9]+' CHANGELOG.md | sed -E 's/^## ([0-9]+\.[0-9]+\.[0-9]+).*/\1/')
           tag=${GITHUB_REF_NAME#v}
           [ "$top" = "$tag" ] || { echo "CHANGELOG top is $top, tag is $tag"; exit 1; }
+
+  private-refs:
+    name: No private references
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Scan tracked files
+        run: |
+          if git grep -n -I -E '_archive|CLAUDE\.md|memcap|macEM-suite|setup-python-refs' -- ':!.gitignore' ':!.github/workflows/ci.yml'; then
+            echo "Private references above; this repo is public."; exit 1
+          fi

.github/workflows/docs.yml

@@ -2,7 +2,7 @@
 # published to GitHub Pages at https://mac4dstem.github.io/CuboKit/documentation/ on every tag.
 # On a pull request the site is built and uploaded as an artifact only, so a broken catalog fails before the tag.
 #
-# No swift-docc-plugin: the kit takes no package dependencies (CLAUDE.md). `xcodebuild docbuild` builds the archives
+# No swift-docc-plugin: the kit takes no package dependencies. `xcodebuild docbuild` builds the archives
 # from the package's own schemes; `docc merge` (Xcode 16+) joins them. Needs Pages enabled with source "GitHub Actions"
 # (repository Settings > Pages). Pattern first proposed for CuboKit; the other kits copy it with their module list.
 name: Docs

Sources/CuboStrain/ConsensusNumerics.swift

@@ -269,7 +269,7 @@ enum ConsensusNumerics {
     /// peaks. Basis row for a peak is [1, h, k]; solves the 3×3 normal
     /// equations for each of the x and y coordinates.
     ///
-    /// DEVIATION (measured 2026-08-04, ../_archive/mac4DSTEM/tools/training-dataset-campaign parity):
+    /// DEVIATION (measured 2026-08-04, training-dataset campaign parity):
     /// py4DSTEM's fit_lattice_vectors multiplies both the design matrix and
     /// the data by the intensity weight before lstsq, which minimizes
     /// Σ w²·r². These normal equations weight by w once, minimizing Σ w·r² —

Tests/Fixtures/README.md

@@ -3,7 +3,7 @@
 One row per committed fixture file under `Tests/*/Fixtures/`: size, the script under `tools/` that names it (the generator or its
 pin script; a few scripts write a whole directory; a script found only by file-name prefix, tool-folder name or test module is marked so), and a note where the origin is not the kit's own pinned reference. 152 files.
 
-Licence: every fixture is generated from this kit's own code and the pinned Python reference (see `CLAUDE.md`, Reference) and ships under the kit's GPL-3.0-or-later licence, except the rows marked *third party*. Nothing here is the owner's data: the committed text fixtures carry no owner path or name (checked by search), and real datasets are read from `$MACEM_DATA` and never copied into the repo.
+Licence: every fixture is generated from this kit's own code and the pinned Python reference (named in the README) and ships under the kit's GPL-3.0-or-later licence, except the rows marked *third party*. Nothing here is the owner's data: the committed text fixtures carry no owner path or name (checked by search), and real datasets are read from `$MACEM_DATA` and never copied into the repo.
 
 ## Needs an origin line
 

docs/bragg.md

@@ -149,5 +149,5 @@ measurement), pinned to scipy in `GaussianEdgeTests`.
 Regenerate from a suite worktree:
 
 ```sh
-../../tools/memcap.sh -- ../../References/python/py4dstem/bin/python -I -B tools/bragg/pins.py
+../../References/python/py4dstem/bin/python -I -B tools/bragg/pins.py
 ```

docs/embedding.md

@@ -94,14 +94,14 @@ numerics (sliced from the git object at the commit above, access qualifiers remo
 cancellation token and error type) with `swiftc`, then runs them. It never imports or executes CuboEmbedding.
 
 ```sh
-../../tools/memcap.sh -- ../../References/CuboKit/py4dstem-venv/bin/python -I -B tools/embedding/pins.py
+../../References/CuboKit/py4dstem-venv/bin/python -I -B tools/embedding/pins.py
 ```
 
 It checks Python 3.12.4, NumPy 2.5.0 and scikit-learn 1.4.2 and records versions, SHA256 of the scikit-learn sources and of
 the app file in `Fixtures/embedding.json`. Data: planted-spectrum Gaussian matrices (60 × 8, and 6 × 10 with fewer rows than
 columns), three Gaussian blobs (90 × 3), a pattern set with a negative count, an all-zero pattern, and a detector smaller
 than the binned size. Cases cover an empty cluster in iteration 1, the iteration cap, and the centre-shift stop. Binary
-little-endian f64, 41 KB in all. The oracle peaked at 371 MB under the 8 GB memcap.
+little-endian f64, 41 KB in all. The oracle peaked at 371 MB under an 8 GB memory cap.
 
 Measured gaps against tolerances (tests print them):
 

docs/hot-pixels.md

@@ -25,7 +25,7 @@ input/intermediate mean, nonfinite/unrepresentable threshold or rank outside
 Regenerate from this worktree:
 
 ```sh
-MPLCONFIGDIR="$PWD/.build/matplotlib" ../../tools/memcap.sh -- ../../References/python/py4dstem/bin/python -I -B tools/hot-pixels/pins.py
+MPLCONFIGDIR="$PWD/.build/matplotlib" ../../References/python/py4dstem/bin/python -I -B tools/hot-pixels/pins.py
 ```
 
 The generator verifies the pinned commit, installed oracle source bytes, Python

docs/idpc.md

@@ -23,7 +23,7 @@ The result is projected phase in radians up to its fixed zero-mean gauge.
 Regeneration from this worktree:
 
 ```sh
-MPLCONFIGDIR="$PWD/.build/matplotlib" ../../tools/memcap.sh -- ../../References/python/py4dstem/bin/python -I -B tools/idpc/pins.py
+MPLCONFIGDIR="$PWD/.build/matplotlib" ../../References/python/py4dstem/bin/python -I -B tools/idpc/pins.py
 ```
 
 Fixtures cover 7×10 periodic with anisotropic sampling, 8×8 at 2× padding and

docs/parallax-alignment.md

@@ -39,7 +39,7 @@ files to it. Versions are enforced and recorded in `Tests/CuboParallaxTests/Fixt
 Python 3.12.4, NumPy 2.5.0, SciPy 1.18.0, py4DSTEM 0.14.19. Regenerate from the package root:
 
 ```sh
-../tools/memcap.sh -- ../References/python/py4dstem/bin/python -I -B tools/parallax/pins.py
+../References/python/py4dstem/bin/python -I -B tools/parallax/pins.py
 ```
 
 Four small three-frame stacks cover integer/wrapped shifts (8 × 10), fractional shifts on odd axes

docs/ptycho.md

@@ -14,7 +14,7 @@ See the module's DocC Scope for the precise supported subset.
 Regenerate from this worktree:
 
 ```sh
-MPLCONFIGDIR="$PWD/.build/matplotlib" ../../tools/memcap.sh -- ../../References/python/py4dstem/bin/python -I -B tools/ptycho/pins.py
+MPLCONFIGDIR="$PWD/.build/matplotlib" ../../References/python/py4dstem/bin/python -I -B tools/ptycho/pins.py
 ```
 
 The script verifies py4DSTEM f050d207 / 0.14.19, NumPy 2.5.0, and the installed

docs/strain.md

@@ -66,7 +66,7 @@ minimal value shims. It never imports or executes CuboStrain to generate pins.
 Regenerate from a suite worktree:
 
 ```sh
-../../tools/memcap.sh -- ../../References/python/py4dstem/bin/python -I -B tools/strain/pins.py
+../../References/python/py4dstem/bin/python -I -B tools/strain/pins.py
 ```
 
 The generator checks Python 3.12.4, NumPy 2.5.0, py4DSTEM 0.14.19, the reference
@@ -75,7 +75,7 @@ unequal-intensity noise that distinguishes weighting, a reference population
 that distinguishes MAD rejection, repeated vector clusters, and peaks measured
 on public `small_datacube.dm4` crop [0,0,200:312,200:312]. Its input SHA256 and
 source SHA256 are in `Fixtures/strain.json`. Numeric arrays are little-endian
-binary f64, under 5 KB total. Oracle execution under the 8 GB memcap peaked at
+binary f64, under 5 KB total. Oracle execution under an 8 GB memory cap peaked at
 689 MB. The Swift source oracle is also a descendant of that capped process.
 
 Absolute tolerance 1e-10 for primary fits/strains (no bit-exact claim across SVD
@@ -130,7 +130,7 @@ would index out of range or return NaN, the kit refuses with the reason.
 `tools/strain/mapping_pins.py` (a sibling of `pins.py`, which is unchanged, as are its fixtures) runs py4DSTEM's real
 `BraggVectors.histogram`, `StrainMap.choose_basis_vectors`, `fit_basis_vectors` and `get_strain` (Agg backend, the
 plots discarded) and `get_maxima_2D`, and writes `Tests/CuboStrainTests/Fixtures/map_*.f64` and `strain_mapping.json`
-(61 little-endian f64 arrays, 277 KB; the oracle peaked at 199 MB under the 8 GB memcap). Datasets:
+(61 little-endian f64 arrays, 277 KB; the oracle peaked at 199 MB under an 8 GB memory cap). Datasets:
 
 - d1: noise-free planted lattice (7 x 8 scan, 48 x 48 detector, fractional origin, non-orthogonal reference lattice,
   planted exx, eyy, exy, theta ramps, columns 0 to 2 exactly unstrained).

tools/benchmarks/bench.py

@@ -1,7 +1,7 @@
 """py4DSTEM side of the CuboKit benchmark, and the merge into docs/benchmarks.md.
-Run from the suite folder (one benchmark at a time machine-wide, under memcap):
-  tools/memcap.sh -- References/python/py4dstem/bin/python -I -B CuboKit/tools/benchmarks/bench.py make   <dir>    # writes <dir>/{small,mid,typical}.npy
-  tools/memcap.sh -- References/python/py4dstem/bin/python -I -B CuboKit/tools/benchmarks/bench.py python <dir>    # writes <dir>/python.json
+Run from the suite folder (one benchmark at a time machine-wide, under a memory cap):
+  References/python/py4dstem/bin/python -I -B CuboKit/tools/benchmarks/bench.py make   <dir>    # writes <dir>/{small,mid,typical}.npy
+  References/python/py4dstem/bin/python -I -B CuboKit/tools/benchmarks/bench.py python <dir>    # writes <dir>/python.json
   CUBOKIT_BENCH_DIR=<dir> swift test -c release --filter BenchmarkHarness                            # writes <dir>/swift.json
   References/python/py4dstem/bin/python -I -B CuboKit/tools/benchmarks/bench.py merge <dir>                       # prints the markdown table
 Speed round (docs/benchmarks.md): `bench.py speed <dir> [calls]` prints one `SPEED name median_ms= best_ms=` line per case for the Python side (default 15 calls);

tools/bragg/pins.py

@@ -1,5 +1,5 @@
-"""Generate CuboBragg pins. Run with memcap and the pinned venv, from the package root:
-../../tools/memcap.sh -- ../../References/python/py4dstem/bin/python -I -B tools/bragg/pins.py
+"""Generate CuboBragg pins. Run under a memory cap with the pinned venv, from the package root:
+../../References/python/py4dstem/bin/python -I -B tools/bragg/pins.py
 
 Two independent oracles, neither is Swift written for the kit:
   1. py4DSTEM 0.14.19 (f050d207) `find_Bragg_disks`, called as a public function, is the primary reference.

tools/braggmask/pins.py

@@ -1,5 +1,5 @@
 """Pinned py4DSTEM DataCube.get_braggmask and get_local_ave_dp (braggmask and plain). Run from the suite folder:
-  tools/memcap.sh -- References/python/py4dstem/bin/python -I -B CuboKit/tools/braggmask/pins.py
+  References/python/py4dstem/bin/python -I -B CuboKit/tools/braggmask/pins.py
 Output: CuboKit/Tests/CuboBraggTests/Fixtures/braggmask.json
 """
 from pathlib import Path

tools/calibration/pins.py

@@ -1,8 +1,8 @@
 """Pinned py4DSTEM calibration model and cube reshaping: DataCube.calibrate (dim vectors, meshgrids, qxxs),
 Calibration setters, and preprocess.set_scan_shape, swap_RQ, swap_Rxy, swap_Qxy, bin_data_real, thin_data_real,
 pad_data_diffraction, resample_data_diffraction (bilinear), median_filter_masked_pixels on a Float32 DataCube.
-Run from the suite folder (References/python/py4dstem from tools/setup-python-refs.sh):
-  tools/memcap.sh -- References/python/py4dstem/bin/python -I -B CuboKit/tools/calibration/pins.py
+Run from the suite folder (References/python/py4dstem, a pinned venv):
+  References/python/py4dstem/bin/python -I -B CuboKit/tools/calibration/pins.py
 Output: CuboKit/Tests/CuboCoreTests/Fixtures/calibration.json
 """
 from pathlib import Path

tools/classification/pins.py

@@ -3,7 +3,7 @@
 produced by py4DSTEM itself on small planted inputs; no CuboKit Swift is used. Run from the CuboKit folder with the suite's
 reference environment under the memory cap:
 
-    ../tools/memcap.sh -- ../References/python/py4dstem/bin/python -I -B tools/classification/pins.py [featurization|classification|virtualimage|all]
+    ../References/python/py4dstem/bin/python -I -B tools/classification/pins.py [featurization|classification|virtualimage|all]
 
 Outputs (floats as repr, so they round-trip exactly):
     Tests/CuboEmbeddingTests/Fixtures/featurization.json

tools/cubeview/pins.py

@@ -1,6 +1,6 @@
 """Pinned py4DSTEM crop and bin: preprocess.crop_data_real, crop_data_diffraction, bin_data_diffraction on a Float32 DataCube.
 Run from the kit root:
-  ../tools/memcap.sh -- ../References/python/py4dstem/bin/python -I -B tools/cubeview/pins.py
+  ../References/python/py4dstem/bin/python -I -B tools/cubeview/pins.py
 Output: Tests/CuboCoreTests/Fixtures/cubeview.json
 """
 from pathlib import Path

tools/dpcviews/pins.py

@@ -1,6 +1,6 @@
 """NumPy reference for the DPC views: magnitude np.hypot and the CoM angle np.angle(x + 1j y), as py4DSTEM's
 show_complex_CoM builds the complex CoM (`com_x + 1j*com_y`, x = first axis). Wrapped to [0, 2 pi) with +0 canonical.
-Run from the kit root:  ../tools/memcap.sh -- ../References/python/py4dstem/bin/python -I -B tools/dpcviews/pins.py
+Run from the kit root:  ../References/python/py4dstem/bin/python -I -B tools/dpcviews/pins.py
 Output: Tests/CuboPhaseTests/Fixtures/dpcviews.json
 """
 from pathlib import Path

tools/embedding/pins.py

@@ -1,7 +1,7 @@
-"""Generate CuboEmbedding pins. Run with memcap and the OLD pinned venv (scikit-learn 1.4.2; References/python/py4dstem has 1.9.1,
+"""Generate CuboEmbedding pins. Run under a memory cap with the OLD pinned venv (scikit-learn 1.4.2; References/python/py4dstem has 1.9.1,
 whose PCA fixtures differ, so a regeneration there is a fixture move of its own):
 
-    ../../tools/memcap.sh -- ../../References/CuboKit/py4dstem-venv/bin/python -I -B tools/embedding/pins.py
+    ../../References/CuboKit/py4dstem-venv/bin/python -I -B tools/embedding/pins.py
 
 Primary pins come from scikit-learn (PCA svd_solver="full", KMeans init=<array>, n_init=1, algorithm="lloyd").
 App pins come from the ORIGINAL mac4DSTEM DiffractionEmbedding.swift at APP: its numeric helpers are sliced out of the

tools/hot-pixels/pins.py

@@ -1,5 +1,5 @@
 """Actual pinned py4DSTEM DataCube.filter_hot_pixels; Float32 cube semantics.
-Run under ../../tools/memcap.sh using the pinned isolated Python venv.
+Run under a memory cap using the pinned isolated Python venv.
 """
 from pathlib import Path
 import json, subprocess, platform

tools/idpc/pins.py

@@ -1,7 +1,7 @@
 """NumPy float64 transcription of the app's Fourier-integration iDPC.
 This is NOT py4DSTEM iterative DPC. Periodic/centered zero-padded boundary,
 mean subtraction before padding and after cropping, regularized inverse gradient.
-Run with the pinned venv under ../../tools/memcap.sh, from this worktree.
+Run with the pinned venv under a memory cap, from this worktree.
 """
 from pathlib import Path
 import json, platform, hashlib, subprocess

tools/origin/trimmed_pins.py

@@ -1,6 +1,6 @@
 """Pins for OriginFit.fitTrimmed: the MAD-trimmed origin fit of mac4DSTEM's calibration (OriginCalibration.fitOriginTrimmed).
 Run from the kit root:
-  MPLCONFIGDIR="$PWD/.build/matplotlib" ../tools/memcap.sh -- ../References/python/py4dstem/bin/python -I -B tools/origin/trimmed_pins.py
+  MPLCONFIGDIR="$PWD/.build/matplotlib" ../References/python/py4dstem/bin/python -I -B tools/origin/trimmed_pins.py
 Two references, both recorded in the fixture:
  * `app`: a line-by-line NumPy transcription of the app's Swift source (mac4DSTEM origin/main, Core/Analysis/OriginCalibration.swift,
    `fitOriginTrimmed` and `fit2D`), in Float32 where the app is Float (residuals, median, MAD, cutoff, RMS), the least-squares surface in

tools/parallax/pins.py

@@ -1,5 +1,5 @@
 """Regenerate with the pinned venv, from the package root:
-../tools/memcap.sh -- ../References/python/py4dstem/bin/python -I -B tools/parallax/pins.py
+../References/python/py4dstem/bin/python -I -B tools/parallax/pins.py
 
 Only public py4DSTEM test data is cropped; no owner's dataset is copied.
 """

tools/parallax/preprocess_pins.py

@@ -1,4 +1,4 @@
-"""Pinned Parallax.preprocess oracle; run with suite memcap and pinned Python -I -B."""
+"""Pinned Parallax.preprocess oracle; run under a memory cap and pinned Python -I -B."""
 import json, platform, subprocess, hashlib
 from pathlib import Path
 import numpy as np

tools/parallax/reconstruct_pins.py

@@ -1,7 +1,7 @@
 """Pinned Parallax.reconstruct oracle (alignment schedule, regularised shifts, running average) and one end-to-end
 subpixel case. Real py4DSTEM `Parallax(...).preprocess().reconstruct()` on small synthetic bright-field cubes.
 From the clone root:
-  ../../tools/memcap.sh -- ../References/python/py4dstem/bin/python -I -B tools/parallax/reconstruct_pins.py
+  ../References/python/py4dstem/bin/python -I -B tools/parallax/reconstruct_pins.py
 Bright-field disks are small (at most 16 groups per bin): NumPy sorts up to 16 elements with a stable insertion sort.
 Planted data: one smooth random object seen through every bright-field pixel with a linear shift of the pixel offset
 (a parallax of defocus type), so correlation maxima are unique (no float32 ties). For every bin the script asserts

tools/parallax/subpixel_pins.py

@@ -1,5 +1,5 @@
 """Pinned subpixel_alignment KDE oracle (bilinear and Lanczos deposition, Gaussian blur, sinc low-pass, default factor
-heuristic). Position correction is not pinned here. Run with the pinned venv, python -I -B, under tools/memcap.sh."""
+heuristic). Position correction is not pinned here. Run with the pinned venv, python -I -B, under a memory cap."""
 import json, warnings
 from pathlib import Path
 src=Path(__file__).with_name('aberration_pins.py').read_text().split("cases=[]")[0]

tools/polar-ellipse/pins.py

@@ -3,8 +3,8 @@
 Calls py4DSTEM itself: PolarDatacube, DataCube.get_radial_bkgrnd / get_radial_bksb_dp / get_local_ave_dp(radial_bksb=True),
 fit_ellipse_1D, fit_ellipse_amorphous_ring, constrain_degenerate_ellipse, ellipse_err, double_sided_gaussian(_fiterr),
 convert_ellipse_params(_r), fourier_resample and resample_data_diffraction(method="fourier").
-Run from the suite folder (References/python/py4dstem from tools/setup-python-refs.sh):
-  tools/memcap.sh -- References/python/py4dstem/bin/python -I -B CuboKit/tools/polar-ellipse/pins.py
+Run from the suite folder (References/python/py4dstem, a pinned venv):
+  References/python/py4dstem/bin/python -I -B CuboKit/tools/polar-ellipse/pins.py
 Output: CuboKit/Tests/CuboVirtualTests/Fixtures/polar-radial-pins.json and CuboKit/Tests/CuboCoreTests/Fixtures/ellipse-resample-pins.json
 Conventions: py4DSTEM's x is the kit's ROW and y its COLUMN, so the (x0, y0, a, b, theta) here are the kit's (row, column, a, b, theta)
 with theta of the major axis from the +row axis towards the +column axis. planted.py measures theta of the major axis from +column

tools/ptycho/engines_pins.py

@@ -1,6 +1,6 @@
 """Pinned py4DSTEM oracle for the mixed-state and multislice CPU engines (CuboPtycho).
 Run from the kit root:
-  MPLCONFIGDIR="$PWD/.build/matplotlib" ../tools/memcap.sh -- ../References/python/py4dstem/bin/python -I -B tools/ptycho/engines_pins.py
+  MPLCONFIGDIR="$PWD/.build/matplotlib" ../References/python/py4dstem/bin/python -I -B tools/ptycho/engines_pins.py
 The real MixedstatePtychography / MultislicePtychography classes run `reconstruct` on numerically injected preprocessing state
 (the same method as tools/ptycho/pins.py); orthogonalisation, probe initialisation (seeded NumPy RNG) and the propagator
 arrays are also called directly. Output: Tests/CuboPtychoTests/Fixtures/engines.json

tools/ptycho/odd_pins.py

@@ -1,6 +1,6 @@
 """Pinned py4DSTEM oracle for ODD, non-square detector / probe / object sizes (CuboPtycho preprocessing and the three engines).
 Run from the kit root:
-  MPLCONFIGDIR="$PWD/.build/matplotlib" ../tools/memcap.sh -- ../References/python/py4dstem/bin/python -I -B tools/ptycho/odd_pins.py
+  MPLCONFIGDIR="$PWD/.build/matplotlib" ../References/python/py4dstem/bin/python -I -B tools/ptycho/odd_pins.py
 Same method as preprocess_pins.py and engines_pins.py (real py4DSTEM methods on numerically injected state; the engine data go
 through py4DSTEM's _normalize_diffraction_intensities), with a 15 x 13 probe on a 31 x 29 object (single, mixed, multislice) and a
 9 x 7 detector in the preprocessing pin. Odd lengths change fftfreq (no Nyquist bin), the corner-centred patch offsets, the