# Engineering Notebook reproduction guide

**Status: draft software and CAD workflow.** This guide lets a reader reproduce the current illustrative geometry and static website. It does not authorize printing, assembly, distribution, or a physical performance claim.

## Source and versions

- Website source: this repository's `src/`, `public/`, `scripts/`, `tests/`, `package.json`, and locked `package-lock.json`. Node.js must satisfy `>=22.12.0`; the continuous build uses Node.js 24. `npm ci` uses the locked Astro, Three.js, and other web dependency versions.
- Editable geometry: `engineering/cad/generate.py` and `engineering/parameters/notebook-provisional-r0.json`. The parameter revision is **provisional**. The optional generator uses Python 3.12 and the pinned `cadquery==2.8.0` from `engineering/cad/requirements.txt`.
- Geometry convention: millimeters in a right-handed XY plane, fixed pivot `O=(0,0,0)`, positive angles counterclockwise from +X viewed from +Z. The GLB exporter rotates the CAD +Z-up convention to glTF +Y-up and applies a 0.001 root scale to convert millimeters to web meters. The mechanism uses the right-hand slider branch documented in `engineering/docs/mechanism-model.md`.

## Rebuild the site

From a clean checkout of the intended revision:

```sh
npm ci
npm test
npm run check
npm run build
npm run verify
npm run release:validate
```

The static site is written to `dist/`. A local production preview is `npm run preview`. `npm run build` validates the Joint Lab, measured-publication gates, release catalog, and model references before rendering pages. No physical data is generated by this build.

## Regenerate the internal draft CAD package

From the repository root, with Python 3.12 available:

```sh
python3.12 -m venv /tmp/teletraan-cad
/tmp/teletraan-cad/bin/python -m pip install -r engineering/cad/requirements.txt
/tmp/teletraan-cad/bin/python -m unittest discover engineering/cad -p 'test_*.py'
/tmp/teletraan-cad/bin/python engineering/cad/generate.py
npm run cad:validate-draft
```

The generator writes ignored output under `engineering/build/notebook-provisional-r0/`. Its manifest records the parameter and source hashes, parts, units, assembly STEP/GLB files, candidate STL/3MF files, and named pivots. The CAD guide at `engineering/cad/README.md` documents regeneration of a subset and revision changes. Keep edited parameters and newly generated artifacts under a new revision ID; preserve the earlier design log.

## Printing and assembly limits

The draft calls for a nominal 3 mm pivot and an M3 washer/nut friction concept. Fastener lengths, material, spring and ball specifications, preload, printer, nozzle, layer height, orientation, slicer profile, and supplier parts have not been chosen. The 0.1 mm diametral clearance in the parameter file is a **candidate**; coupon holes of 3.0, 3.1, 3.2, and 3.3 mm are test candidates, not validated print tolerances. Print and measure the coupon before choosing a fit. The internal plans at `engineering/print/draft-review-plan.md` and `engineering/hardware/draft-hardware-plan.md` list the missing checks; they are not manufacturing instructions or a bill of materials.

STEP is an exchange format, STL/3MF are candidate print geometry, and GLB is a visualization format. A valid export, passing software test, or positive illustrative clearance result does not establish printability, strength, mechanism fit, load performance, or physical clearance.

## Evidence and release gate

Raw Joint Lab and mechanism CSV templates are blank. Real observations require specimen, revision, conditions, dated records, review, and matching public copies through `engineering/data/validation-publication.json`. The website calculates torque, model predictions, and errors from approved raw rows; it does not treat browser interaction as a measurement.

`engineering/data/release-catalog.v1.json` lists every public notebook download. Available files are byte-checked against their source. Generated binaries remain internal until their revision, physical fit, provenance, and rights are reviewed. The catalog's complete state additionally requires both physical studies and all core artifacts. The rights decision for CAD/hardware, software, documentation, and data is still pending; no license for the existing website is asserted here. Availability for reading or downloading does not grant reuse rights.