@pikaa-ai/pikaa 0.2.5 → 0.3.0

package/skills/lab-hardware-cad/references/labware-adapters.md

@@ -0,0 +1,190 @@
+# Labware adapters, holders, and racks
+
+Parts that receive standard consumables: microplates, cuvettes, tubes, slides, dishes.
+
+The governing principle: **where a published standard exists, design to the standard; where it
+does not, require a measurement.** Microplate footprints are standardised. Well geometry, skirt
+profiles, tube dimensions, and lid fits are not.
+
+Verified dimensions live in `assets/standards.json`. Query them rather than copying numbers:
+
+```bash
+python scripts/check.py standards --show slas-microplate-footprint
+```
+
+## Microplates (ANSI/SLAS 1-4)
+
+Four documents split the plate geometry. All are ANSI-approved and were reaffirmed in 2012.
+
+| Document | Governs | Key numbers |
+| --- | --- | --- |
+| ANSI/SLAS 1-2004 | Footprint | 127.76 x 85.48 mm ±0.25; corner radius 3.18 ±1.6 mm |
+| ANSI/SLAS 2-2004 | Height | 14.35 ±0.25 mm, resting plane to top of perimeter wells |
+| ANSI/SLAS 3-2004 | Bottom outside flange | Short 2.41, medium 6.10, tall 7.62 mm, each ±0.38 |
+| ANSI/SLAS 4-2004 | Well positions | 96-well: 9.0 mm pitch, A1 at 14.38 mm from left, 11.24 mm from top |
+
+### Designing a plate pocket
+
+Three traps, in the order people fall into them.
+
+**1. Design to maximum material, not to nominal.** A plate at the top of tolerance is
+127.76 + 0.25 = 128.01 mm. A pocket cut at 127.76 + clearance will jam on roughly half the plates
+you try. Compute:
+
+```python
+plate_l_mm = 127.76      # ANSI/SLAS 1-2004 nominal
+plate_tol_mm = 0.25      # ANSI/SLAS 1-2004
+fit_clearance_mm = 0.40  # per side; FDM, see fabrication-limits.md
+pocket_l_mm = plate_l_mm + plate_tol_mm + 2 * fit_clearance_mm   # 128.81
+```
+
+**2. The corner radius tolerance is enormous — and it bounds the pocket radius from above,
+not below.** 3.18 ±1.6 mm means a real plate corner is anywhere from 1.58 to 4.78 mm. Get the
+direction right: a plate corner is **convex**, a pocket fillet is **concave material bulging
+inward**, so a *sharp* internal pocket corner always clears a rounded plate — the unused corner is
+empty space. It is a pocket fillet *larger* than the plate's corner radius that binds: the bulge
+occupies space the plate needs. Sizing the fillet to the plate's maximum corner radius is
+therefore exactly backwards — it binds every plate except those at the top of the corner
+tolerance.
+
+The safe options, best first:
+
+- **Corner relief** (a small slot or bore cut past each corner) — always clears, prints and mills
+  cleanly, and is the standard fix.
+- **Fillet no larger than the plate's minimum corner radius** (1.58 mm for SLAS plates) — clears
+  every conforming plate in every position.
+- A larger fillet only if `R ≤ r_min + ~3.4 × per-side clearance` — the geometry only recovers the
+  intrusion when the plate stays roughly centred, so treat this as a last resort and say so.
+
+```python
+with BuildPart() as pocket:
+    # ... pocket geometry ...
+    # relief bores just outside each pocket corner: clears any conforming corner radius
+    with Locations(*corner_relief_centres()):
+        Hole(radius=2.0)
+```
+
+**3. Height depends on the flange, not just the plate.** ANSI/SLAS 3 standardises three flange
+heights. A carrier that grips the flange must be told which one. Ask; do not assume medium.
+
+### Well grid
+
+For a part that must reach individual wells — a magnet block, a lid with access holes, a light
+guide — lay out from the plate's outline corner, not from the plate centre:
+
+```python
+a1_x_mm, a1_y_mm, pitch_mm = 14.38, 11.24, 9.0   # ANSI/SLAS 4-2004, 96-well
+locations = [
+    (a1_x_mm + pitch_mm * col, a1_y_mm + pitch_mm * row)
+    for row in range(8) for col in range(12)
+]
+```
+
+The standard's positional tolerance is a **0.70 mm diameter zone** around each nominal centre, not
+a ±0.70 mm band. A feature that must clear every well needs at least 0.35 mm of radial margin on
+top of your own process tolerance.
+
+384-well pitch is 4.5 mm and 1536-well pitch is 2.25 mm. **The A1 offsets for those formats in
+`standards.json` are marked unverified** — they were derived, not read from the document. Read
+ANSI/SLAS 4-2004 before relying on them.
+
+### What the standards do not fix
+
+Well diameter, well depth, well bottom shape (flat, round, conical), skirt height, lid geometry,
+optical bottom thickness, and deep-well plate height. All vary by manufacturer and product line.
+If the part touches any of these, get the vendor drawing or measure it.
+
+## Cuvettes
+
+The standard macro cuvette is a convention rather than a published standard, but it is close to
+universal: **12.5 x 12.5 mm external, 45 mm tall, 1.25 mm wall, 10 mm optical path**.
+
+Design notes:
+
+- Holders should be generous or compliant. Because no document fixes the tolerance, a 0.1 mm
+  interference fit designed against nominal will fail on some suppliers' cuvettes.
+- Semi-micro and micro cuvettes keep the 12.5 mm external footprint but change internal geometry
+  and often height. A holder designed for the external footprint accommodates all of them; one
+  designed around the sample volume does not.
+- Cuvettes are usually held with a spring or leaf on one face so the two optical faces register
+  against fixed datums. Copy that: locate on two adjacent faces, preload from the opposite corner.
+  A four-sided pocket with clearance lets the cuvette rotate and shifts the path length.
+- **Never print the optical path.** Printed surfaces scatter. The cuvette provides the optical
+  faces; the holder provides position only, and must not obstruct the beam window.
+
+## Tubes
+
+Tube dimensions are **not standardised** and differ measurably between suppliers, and often
+between product lines from the same supplier. Approximate outside diameters near the tube rim:
+
+| Tube | Approximate OD | Note |
+| --- | --- | --- |
+| 0.2 mL PCR | 6 mm | Often supplied in strips or as a 96-format plate |
+| 1.5 mL microcentrifuge | 11 mm | Rim is wider than the body; the body tapers |
+| 2.0 mL microcentrifuge | 11 mm | Same rim as 1.5 mL, taller body |
+| 15 mL conical | 17 mm | Cap is wider than the tube |
+| 50 mL conical | 30 mm | Cap is wider than the tube |
+
+**Treat every number in this table as a starting point for a first article, not a design input.**
+Ask the user for the supplier and catalogue number, or ask them to measure with calipers. Then
+design a rack that holds the tube by the **rim or the cap**, which is dimensionally stable, rather
+than by the tapered body, which is not.
+
+For a rack, the useful pattern is a through-hole sized to the body plus clearance and a counterbore
+that catches the rim, so the tube hangs rather than bottoms out.
+
+## Microscope slides and coverslips
+
+Standard slide: **75 x 25 mm, 1.0 mm thick** (ISO 8037-1 covers slide dimensions; thickness classes
+vary, and 1.0-1.2 mm is typical). Coverslips are specified by thickness number, not dimension:
+#1 is roughly 0.13-0.17 mm and #1.5 roughly 0.16-0.19 mm.
+
+Objective working distance is unforgiving. A holder that adds even 0.2 mm under the slide can put
+the sample outside a high-NA objective's working distance. Design slide holders so the slide
+registers directly against the stage datum, with the holder clamping from above.
+
+## Petri dishes and stage inserts
+
+Standard dish outside diameters are approximately 35, 60, 90, and 100 mm, but the flange profile
+and lid fit vary. Dishes are also slightly out of round. Locate on three points rather than a
+continuous circular pocket: a three-point nest is insensitive to ovality, a close-fitting bore is
+not.
+
+For stage inserts, the interface that matters is the **microscope stage opening**, which is
+instrument-specific and must be measured. Many stages accept a standard SLAS-footprint insert;
+confirm before assuming it.
+
+## Checks to run
+
+Declare the pocket in the model's `interfaces()` and let the check read it:
+
+```bash
+python scripts/gen.py carrier_model.py --outdir out/
+python scripts/check.py interfaces out/carrier.manifest.json
+```
+
+**Do not point `check.py fit` at the carrier's STEP.** `fit` measures the outer bounding box, which
+for a carrier is the outside of its walls — 6 mm larger than the pocket here — so it fails against
+the plate footprint no matter how correct the pocket is. The dimension that matters is internal, so
+it has to be declared, not measured from the envelope.
+
+To check the number by hand instead:
+
+```bash
+python scripts/check.py fit --standard slas-microplate-footprint \
+  --intent envelope --clearance 0.8 --value footprint_length=128.81
+```
+
+`--intent envelope` checks one-sided against maximum material condition, and `--clearance` is the
+total intended clearance: 0.40 mm per side is 0.80 mm. Passing means the pocket is the size you
+intended, not that the plate fits — only a test print shows that.
+
+Then always run `snapshot.py` and confirm the pocket is on the face you meant.
+
+## Sources
+
+- ANSI/SLAS 1-2004 (R2012) Footprint Dimensions — <https://www.slas.org/SLAS/assets/File/public/standards/ANSI_SLAS_1-2004_FootprintDimensions.pdf>
+- ANSI/SLAS 2-2004 (R2012) Height Dimensions — <https://www.slas.org/SLAS/assets/File/public/standards/ANSI_SLAS_2-2004_HeightDimensions.pdf>
+- ANSI/SLAS 3-2004 (R2012) Bottom Outside Flange Dimensions — <https://www.slas.org/SLAS/assets/File/public/standards/ANSI_SLAS_3-2004_BottomOutsideFlangeDimensions.pdf>
+- ANSI/SLAS 4-2004 (R2012) Well Positions — <https://www.slas.org/SLAS/assets/File/public/standards/ANSI_SLAS_4-2004_WellPositions.pdf>
+- SLAS microplate standards overview — <https://www.slas.org/education/ansi-slas-microplate-standards/>

package/skills/lab-hardware-cad/references/microfluidics.md

@@ -0,0 +1,157 @@
+# Microfluidic chips, molds, and flow cells
+
+Channel networks, soft-lithography molds, printed chips, gaskets, and manifolds.
+
+## First: decide what you are actually modelling
+
+This is the error that wastes the most time in microfluidic CAD. Three different objects get
+called "the chip":
+
+| Object | Channels are | Made by |
+| --- | --- | --- |
+| **Mold / master** | **Raised ridges** (positive relief) | Photolithography on a wafer, SLA print, or micromilling |
+| **Cast chip** | **Recessed grooves** (negative of the mold) | PDMS cast against the mold, then bonded to a substrate |
+| **Directly-fabricated chip** | **Recessed grooves or enclosed lumens** | Printed, milled, or laser-cut directly |
+
+A model that is correct as a chip is exactly wrong as a mold. Put the polarity in the module
+docstring and in a named parameter, and **verify it numerically, not by eye**: inverted polarity
+is invisible in the bounding box, the volume, and the validity check — and at typical channel
+scale (a 0.3 mm ridge on a 40+ mm part) it is invisible in an outline render too, because raised
+and recessed features draw the same edges. Declare it as geometry checks instead
+(`references/build123d-patterns.md`): a `material` region where the ridge must stand above the
+casting surface, and a `clear` region over the rest of that layer — a groove fails the first,
+an inverted full-area layer fails the second. For a one-off question,
+`check.py probe <step> --box ... --expect material` answers it without editing the model. State
+the measured relief height in the report. Use the snapshot for layout and connectivity, which
+it does show well.
+
+```python
+polarity = "mold"   # "mold" = raised ridges; "chip" = recessed grooves
+```
+
+If casting PDMS, the mold also needs a **surrounding wall or a casting frame** to contain the
+uncured polymer, and enough flat land around the features for the cast part to release.
+
+## Channel cross-section and aspect ratio
+
+Channels are usually rectangular because that is what planar fabrication produces. Two failure
+modes bound the aspect ratio, and both are geometric:
+
+- **Roof sag / collapse** — a channel much wider than it is tall has an unsupported ceiling. In
+  PDMS the roof bows down and can stick to the floor. Commonly cited guidance keeps
+  **width : height below roughly 10 : 1**; wide channels need support pillars.
+- **Sidewall collapse** — a mold ridge much taller than it is wide falls over or fails to release.
+  Keep **height : width below roughly 10 : 1** on the mold.
+
+Treat both as rules of thumb, not guarantees: the real limits depend on PDMS mixing ratio, cure
+schedule, and applied pressure. For anything load-bearing or high-pressure, prototype.
+
+Also keep **channel-to-channel spacing at least the channel height**, so the wall between two
+channels does not deflect or leak, and leave a flat **bonding land** — typically 1 mm or more of
+uninterrupted flat surface around the network perimeter — for plasma or adhesive bonding.
+
+## Minimum features by process
+
+Achievable feature size drives the entire design, and the range across processes is three orders
+of magnitude. Confirm against your specific tool before committing.
+
+| Process | Practical minimum channel | Notes |
+| --- | --- | --- |
+| SU-8 photolithography | ~1-10 µm wide, 1-200+ µm tall | The reference process for soft lithography. Feature height is set by spin speed and resist grade. |
+| Two-photon / µSLA | ~10-50 µm | Small build volume, slow, expensive. |
+| Desktop SLA / DLP | ~200-500 µm | Uncured resin is very hard to clear from smaller lumens. Enclosed channels below ~0.5 mm frequently print blocked. |
+| Micromilling | ~100 µm | Set by end-mill diameter; depth limited by tool aspect ratio. Leaves tool marks that scatter light. |
+| FDM | Not suitable for sealed channels | Layer porosity leaks. Use only for holders and manifolds. |
+| Laser-cut film / gasket | ~200 µm | Excellent for stacked-layer devices and gaskets. |
+
+**Design enclosed printed channels for drainage.** Every lumen needs a path for uncured resin to
+escape, and orientation on the build plate determines whether it drains. If the user is printing,
+say which way up.
+
+## Ports and tubing
+
+The port is where most chips leak. Options, roughly in order of how common they are in a research
+lab:
+
+- **Direct tubing insertion** — a bore slightly *under* the tubing OD so the tubing seals by
+  interference. For 1/16 inch OD tubing (1.5875 mm), a bore around 1.5 mm in PDMS is typical. This
+  works in elastomer and fails in rigid printed parts, which crack instead of gripping.
+- **Luer taper** — the standard syringe interface, a **6% taper** (ISO 80369-7 supersedes the
+  legacy ISO 594 series for medical use). Convenient, low pressure only. If you model a Luer taper,
+  get the profile from the standard, not from memory.
+- **Threaded fittings** — flat-bottom **1/4-28 UNF** is the common lab standard for low-pressure
+  fluidics; **10-32 coned** is used at higher pressures. These need a tapped or heat-set-insert
+  port and a matching flat sealing face.
+- **Barbs** — reliable with soft tubing and a clamp, bulky.
+
+Whichever you choose, the sealing surface must be **flat and normal to the port axis**. A port
+face left at a printed layer angle will not seal.
+
+## Dead volume
+
+Dead volume dominates the response time of any perfusion or gradient device, and it is trivially
+computable, so compute it rather than estimating:
+
+```
+V = pi * r^2 * L                # round tubing / bore
+V = w * h * L                   # rectangular channel
+```
+
+Report the volume of every connecting bore alongside the channel network volume. A 20 mm long
+1 mm bore holds ~15.7 µL, which is often larger than the entire channel network it feeds.
+
+## Flow regime sanity check
+
+Microfluidic flow is almost always laminar, but state it rather than assuming:
+
+```
+Re = rho * v * D_h / mu
+D_h = 2 * w * h / (w + h)       # hydraulic diameter, rectangular channel
+```
+
+For water in a 100 µm channel at 1 mm/s, Re is of order 0.1 — deeply laminar, so mixing is
+diffusive only. If the design depends on mixing, it needs a mixer geometry (serpentine,
+herringbone, or split-and-recombine); relying on turbulence will not work at these scales.
+
+Pressure drop for a rectangular channel scales steeply with the smaller dimension. **Halving
+channel height raises pressure drop by roughly an order of magnitude.** Check that the intended
+pump or syringe can actually deliver it before finalising the cross-section.
+
+## Material and optical constraints
+
+- **PDMS** absorbs small hydrophobic molecules and is gas-permeable. Both are sometimes features
+  (oxygenation in organ-on-chip) and sometimes fatal to an assay (drug studies).
+- **SLA resins** are frequently cytotoxic uncured and often still after a nominal cure. For cell
+  work, require post-cure plus a documented biocompatibility check, or use a different process.
+  See `references/fabrication-limits.md`.
+- **Autofluorescence** matters for any fluorescence readout. Most printed resins autofluoresce
+  strongly. Image through glass or a thin COC/COP film, not through printed material.
+- **Optical path**: printed and milled surfaces scatter. Any imaging window should be a bonded
+  coverslip or film, and the model must specify its thickness so the objective working distance
+  works out.
+
+## Checks to run
+
+```bash
+python scripts/gen.py chip_model.py --outdir out/
+python scripts/check.py facts out/chip.step
+python scripts/snapshot.py out/chip.step --out out/chip.png
+```
+
+`facts` gives the volume; compare it against your hand-computed channel volume as an independent
+check that the network is actually open and connected. A network modelled as a solid rather than a
+cavity shows up immediately as a volume far larger than expected.
+
+Then read the snapshot and confirm, explicitly:
+
+1. **Polarity** — ridges for a mold, grooves for a chip.
+2. Every port lands on the channel it should, and passes fully through to the surface.
+3. The bonding land is continuous around the network.
+4. No channel has been closed off or consumed by a fillet.
+
+## Sources
+
+- ISO 80369-7 (Luer connectors for intravascular applications) supersedes the ISO 594 series.
+  Obtain the taper profile from the standard itself.
+- Aspect-ratio and spacing guidance here is standard soft-lithography practice; the numerical
+  limits are rules of thumb and depend on material and process. Prototype before committing.

package/skills/lab-hardware-cad/references/optomechanics.md

@@ -0,0 +1,148 @@
+# Optomechanical mounts and breadboard hardware
+
+Parts that bolt to an optical table, join a cage system, hold an optic or a sample in a beam path,
+or carry a camera or objective.
+
+Verified dimensions are in `assets/standards.json`:
+
+```bash
+python scripts/check.py standards --show optical-breadboard-metric
+python scripts/check.py standards --show cage-system-30mm
+python scripts/check.py standards --show sm1-lens-tube-thread
+```
+
+## Ask which system before you model anything
+
+**Metric and imperial optical hardware are not interchangeable, and the difference is small enough
+to look like a rounding error and large enough to prevent assembly.**
+
+| | Metric | Imperial |
+| --- | --- | --- |
+| Grid pitch | 25.0 mm | 25.4 mm (1 inch) |
+| Tapped hole | M6 x 1.0 | 1/4-20 UNC |
+| Typical border | 12.5 mm | 12.7 mm |
+
+Over a four-hole span the grids differ by **1.6 mm** — far more than any clearance hole absorbs.
+There is no way to infer which the user has from the request. Ask. If the answer is unavailable,
+model the mounting features as **slots along the bolt line** rather than round holes, which
+tolerates both, and say that is what you did and why.
+
+## Mounting to the table
+
+- Use **clearance holes, not tapped holes**, in the part. The table is tapped; the part is
+  clearanced. For M6 use 6.6 mm (normal fit) in a printed part rather than 6.4 mm — printed holes
+  come out undersize.
+- **Counterbore for the screw head** if the part surface must stay clear: roughly 11 mm diameter
+  for an M6 socket head cap screw, 11.2 mm for 1/4-20.
+- **Never rely on more than two holes to locate a part.** Grid tolerance plus print tolerance means
+  a rigid four-hole pattern will bind. Round hole + slot is the standard fix: one hole locates, the
+  slot takes up the error.
+- Printed parts are compliant. For anything where pointing stability matters, a printed mount is a
+  prototyping aid, not a final part — thermal drift and creep in polymer are large compared with
+  optical alignment tolerances. Say so when recommending one.
+
+## Posts and pedestals
+
+Common conventions, which vary by vendor — **confirm against the catalogue before use**:
+
+- Imperial posts are Ø1/2 inch (12.7 mm), typically tapped 8-32 at one end with a 1/4-20 stud or
+  clearance at the other.
+- Metric posts are Ø12 mm, typically tapped M4 with an M6 interface to the table.
+- A post-holder plus post is height-adjustable but adds a compliant joint; a pedestal or a
+  solid machined riser is stiffer.
+
+**Beam height** is a project-wide constant, not a per-part choice. Every mount on the table must
+put its optic at the same height. Common conventions are 3 inches (76.2 mm) or 100 mm, but this is
+a lab-by-lab choice. Ask for the number, define it once as `beam_height_mm`, and derive every
+mount's optic centre from it.
+
+## 30 mm cage system
+
+The dominant convention for small free-space assemblies:
+
+- **Rod spacing 30.0 mm** on a square, centred on the optical axis.
+- **Rods Ø6 mm** (ER series).
+- Standard cage plates are 0.35 inch (8.9 mm) thick.
+
+For a custom cage plate: place four bores on a 30 mm square, put the aperture at the **centroid**
+of those four bores, and bore them for a free-sliding fit **at your process's clearance**
+(fabrication-limits.md): about 6.2 mm CNC, 6.4 mm SLA, 6.8 mm FDM. 6.1 mm is a reamed-metal
+number — printed bores come out undersize, and four bores on a common square over-constrain each
+other, so tighter is not better here. A cage plate that binds on the rods is worse than useless
+because it transmits stress into the whole assembly.
+
+Cage plates stack along the rods, so a custom plate's thickness directly consumes optical path
+length. Budget it.
+
+## Lens tube threads (SM series)
+
+**SM1 is a 1.035 inch-40 thread**, which holds Ø1 inch (25.4 mm) optics. That is a **0.635 mm
+pitch**.
+
+**Do not print SM threads.** A 0.635 mm pitch is at or below the practical resolution of FDM and
+marginal on desktop SLA; a printed SM1 thread will either not engage or will gall and shed
+particles into the beam path. Instead:
+
+- bore a clearance hole and use a purchased SM1 adapter or retaining ring, or
+- design for a threaded metal insert, or
+- clamp the optic directly with a retaining flange and screws.
+
+If the design truly requires a printed thread, say explicitly that it needs test printing and is
+likely to fail.
+
+## Holding an optic
+
+- **Never clamp an optic on its clear aperture.** Contact only the outer annulus of the face or the
+  edge. Define `clear_aperture_mm` as a named parameter and confirm in the snapshot that nothing
+  intrudes on it.
+- Three-point contact is kinematically correct and does not deform the optic. A continuous
+  circular seat over-constrains it and induces stress birefringence, which matters for
+  polarisation work.
+- Leave clearance for thermal expansion. A metal-in-polymer mount that is a press fit at 20 °C can
+  crack or bind across a temperature swing.
+- Retaining forces should be light and distributed. A single set screw pressing on glass is a way
+  to chip glass.
+
+## Stray light and scatter
+
+Geometry is not the whole design here, and a STEP file cannot show any of this:
+
+- Printed surfaces scatter strongly. Any surface that sees the beam should be baffled, angled away
+  from the optical axis, or treated.
+- **Black does not mean non-reflective.** Black resin and black filament are often quite specular.
+  Specify a genuinely absorbing surface treatment where it matters.
+- Thread and layer lines act as diffraction structures near a focus.
+- For fluorescence work, printed material near the sample can autofluoresce into the detection
+  path.
+
+Flag these to the user; do not silently assume a printed enclosure is light-tight.
+
+## Checks to run
+
+```bash
+python scripts/gen.py mount_model.py --outdir out/
+python scripts/check.py facts out/mount.step
+python scripts/check.py interfaces out/mount.manifest.json
+python scripts/snapshot.py out/mount.step --out out/mount.png
+```
+
+Declare the grid pitch, rod spacing, and bore diameters in the model's `interfaces()` against
+`optical-breadboard-metric`, `optical-breadboard-imperial`, or `cage-system-30mm`, so the check
+catches a 25.0-for-25.4 substitution rather than leaving it to a reader.
+
+There is still **no automatic bolt-pattern check** — the interface check compares dimensions, not
+hole positions. Compute the pattern in the model from a named `grid_pitch_mm` constant, and confirm
+in the snapshot that:
+
+1. All mounting holes are present and pass fully through.
+2. The optic aperture is centred where you intended, and unobstructed.
+3. Counterbores are on the accessible face.
+4. Nothing intrudes into the clear aperture or the beam path.
+
+## Sources
+
+- Thorlabs imperial and metric threading — <https://www.thorlabs.com/imperial-and-metric-threading>
+- Thorlabs standard 30 mm cage plates — <https://www.thorlabs.com/newgrouppage9.cfm?objectgroup_ID=2273>
+- Thorlabs SM1 lens tube compatible cage plates — <https://www.thorlabs.com/newgrouppage9.cfm?objectgroup_id=4114>
+- Post dimensions, beam heights, and vendor-specific thread conventions in this file are common
+  conventions rather than published standards. Confirm against the catalogue.

package/skills/lab-hardware-cad/references/validation.md

@@ -0,0 +1,132 @@
+# Pre-fabrication validation checklist
+
+Work through this before telling a user a part is ready to fabricate. Each item names the failure
+it catches, because a checklist without consequences gets skipped.
+
+## 1. Provenance
+
+- [ ] The STEP was produced by `gen.py` from the current model source.
+      *Catches: a stale artifact that no longer matches the code you just edited.*
+- [ ] A `*.manifest.json` exists alongside it, and its `source.sha256` matches the model file.
+      *Catches: silently editing an exported STEP, which makes the design unreproducible.*
+- [ ] The manifest's `interfaces` block lists every dimension a bundled standard covers, and its
+      values are the ones the model computed after any `--param` override. Empty is correct only
+      when nothing on the part mates with a bundled standard — and then every interface dimension
+      is named as unchecked in the report instead.
+      *Catches: a static `INTERFACES` list frozen at import, recording pre-override numbers; and
+      an interface that silently escaped checking.*
+- [ ] Every parameter in the model is named with units.
+      *Catches: the bare `12.7` nobody can later identify as half an inch.*
+
+```bash
+python scripts/gen.py part_model.py --outdir out/
+```
+
+## 2. Geometry is sound
+
+- [ ] `is_valid` is true.
+      *Catches: self-intersecting or non-manifold solids that slicers and CAM silently mangle.*
+- [ ] `solid_count` is what you expect — usually 1.
+      *Catches: a boolean that failed and left two disjoint lumps, or a feature floating free of
+      the body.*
+- [ ] Volume is plausible for the part's size and wall thickness.
+      *Catches: a cavity modelled solid, or a subtract that did nothing.*
+- [ ] Every geometric requirement in the request is declared in `checks()` and passes — clear
+      regions for what must pass through or fit in, material regions for what must remain,
+      bbox bounds for stated size limits.
+      *Catches: a recess that swallowed its screw seat, a pocket the mating part cannot enter,
+      a beam corridor with a wall in it, a feature a fillet silently ate — all invisible to
+      `is_valid` and the bounding box.*
+
+```bash
+python scripts/check.py facts out/part.step
+python scripts/check.py geometry out/part.step --model part_model.py
+```
+
+## 3. Interfaces
+
+- [ ] Every interface dimension has a written source: a standard ID, a vendor drawing, or a user
+      measurement. **None came from memory.**
+      *Catches: the single most expensive failure mode in this skill.*
+- [ ] Every interface covered by a standard is declared in the model's `interfaces()` and passes
+      `check.py interfaces`.
+      *Catches: an interface nobody checked because the outer bounding box could not see it.*
+- [ ] Features that receive a standardised component use `intent: "envelope"`.
+      *Catches: a pocket sized to nominal, which fits only the smaller half of conforming parts.*
+- [ ] Any standard entry marked `verified: false` was confirmed against the primary document, or
+      the user was told it is unconfirmed.
+      *Catches: propagating a derived number as if it were read from the standard.*
+- [ ] Metric vs imperial is confirmed where both exist, and no expression mixes them.
+      *Catches: the 25.0 vs 25.4 mm grid error, which accumulates to 1.6 mm over four holes.*
+- [ ] Interfaces not covered by any bundled standard — a vendor drawing, a measurement — were
+      reported to the user as unchecked, with the number and its source.
+      *Catches: a silent gap where the automatic check simply had nothing to say.*
+
+```bash
+python scripts/check.py interfaces out/part.manifest.json
+
+# one dimension by hand, when it is not declared in the model
+python scripts/check.py fit --standard <id> --intent envelope --clearance <mm> --value <dim>=<mm>
+```
+
+## 4. Fits and assembly
+
+- [ ] Every mating dimension has a deliberate clearance chosen for the process.
+      *Catches: nominal-to-nominal fits, which do not assemble.*
+- [ ] Multi-part assemblies were checked for interference.
+      *Catches: parts that overlap in CAD and therefore cannot exist together.*
+- [ ] Rigid multi-hole mounting patterns have at least one slot.
+      *Catches: a four-hole bolt pattern binding on accumulated tolerance.*
+
+```bash
+python scripts/check.py clearance out/a.step out/b.step --min 0.3
+```
+
+## 5. Manufacturability
+
+- [ ] Minimum wall and feature sizes are within the chosen process (`fabrication-limits.md`).
+- [ ] Print or machining orientation is stated, and load runs along layers, not across them.
+- [ ] Threads use inserts or captive nuts rather than printed threads, unless coarse.
+- [ ] Enclosed cavities have a drain path for resin, and support-free access where possible.
+- [ ] Milled internal corners have relief for the tool radius.
+
+## 6. Material
+
+- [ ] Material is compatible with the **cleaning agent**, not only the sample.
+      *Catches: acrylic crazing on 70% ethanol; PLA distorting in an autoclave.*
+- [ ] Sterilisation method is stated and the material actually survives it.
+- [ ] Anything contacting cells, tissue, or animals has a justified material, or contact is
+      designed out.
+      *Catches: assuming a printed resin part is cell-safe.*
+- [ ] Optical requirements — autofluorescence, scatter, transmission — are addressed if the part is
+      near a beam or a detector.
+
+## 7. Visual review — mandatory
+
+- [ ] A snapshot was rendered **and read** after the most recent generation.
+- [ ] Confirmed in the image: features on the intended faces; correct mold/chip polarity; every
+      port, bore, and boss present, inside the body, and passing through; nothing consumed by a
+      fillet; clear apertures unobstructed.
+
+```bash
+python scripts/snapshot.py out/part.step --out out/part.png
+```
+
+**This step is never waived by the numeric checks passing.** `is_valid: true` with a correct
+bounding box is fully consistent with a pocket cut on the wrong face or an inverted mold. Those
+errors are obvious in the picture and invisible in the numbers.
+
+## 8. Report
+
+Give the user, explicitly:
+
+1. Process and material, and why.
+2. Every interface dimension with its source and tolerance.
+3. Clearances chosen, and the fit class they came from.
+4. What the snapshot showed — described, not merely "a snapshot was generated".
+5. Every check that did not pass, and every dimension you could not verify.
+6. A recommendation to print a test coupon of the critical interface before committing to the full
+   part, whenever the design depends on a fit.
+
+State the unverified items plainly. A part list with one honest "this dimension needs
+confirmation" is far more useful than a confident one that is silently wrong.