forgecad 0.9.5 → 0.9.7

package/dist/docs-raw/AI/usage.md

@@ -172,9 +172,10 @@ Only add details after the proportions and assembly relationships are correct.
 
 Do not accept a model just because it renders. CAD quality comes from command evidence:
 
-- `forgecad run` confirms the script executes and reports geometry diagnostics.
+- `forgecad run` confirms the script executes and reports the fast inner-loop build summary.
 - `forgecad render 3d` gives visual views from deterministic cameras.
 - `forgecad render inspect` checks object masks, collisions, thickness, sections, depth, normals, and connectivity.
+- `forgecad inspect mechanical-integrity` checks assembly-level verification intent and optional collision evidence.
 - `forgecad check params` catches broken parameter ranges.
 - `forgecad export ...` verifies the actual manufacturing or interchange output.
 
@@ -184,12 +185,15 @@ The CLI is not just a launcher. It gives the agent a measurable feedback loop.
 
 | Need | Command | What it gives the agent |
 |---|---|---|
-| Execute and validate a model | `forgecad run model.forge.js` | Object summaries, volumes, bounds, construction history, parameters, verification results, collisions, spatial relationships, and solver diagnostics. |
+| Execute and validate a model | `forgecad run model.forge.js` | Fast red/green execution feedback: returned object names, parameters, verification results, script logs, and timing. |
+| Inspect run details | `forgecad run model.forge.js --details --history --features` | Per-object volumes and bounds, construction history, and feature tallies when those details are worth the extra work. |
 | Debug imports | `forgecad run model.forge.js --debug-imports` | Import resolution and module-loading diagnostics for multi-file projects. |
 | Compare geometry backends | `forgecad run model.forge.js --backend occt` | Runs against a specific backend when exact geometry or backend parity matters. |
 | Test physical connectivity | `forgecad run model.forge.js --connectivity` | Connected-component reporting for assemblies and printable parts. |
+| Check spatial relationships | `forgecad run model.forge.js --spatial bounded` | Opt-in directional relationships and bounded collision intersections during a run. |
 | Override parameters | `forgecad run model.forge.js -p "Width=120"` | Checks a model at a specific parameter value without editing source. |
 | Sweep parameter ranges | `forgecad check params model.forge.js --samples 12` | Finds parameter values that crash, collapse geometry, or introduce new collisions. |
+| Inspect mechanical integrity | `forgecad inspect mechanical-integrity model.forge.js --collisions` | Assembly-level verification, expected component counts, and collision evidence for acceptance gates. |
 | Produce visual evidence | `forgecad render 3d model.forge.js --camera iso` | PNG viewport renders from deterministic camera angles. |
 | Inspect geometry channels | `forgecad render inspect model.forge.js --channels rgb,mask,collisions,thickness --force` | A bundle with manifest plus RGB, mask, collision, wall-thickness, depth, normal, connectivity, distance, and section channels. |
 | Export manufacturing files | `forgecad export stl model.forge.js` and `forgecad export 3mf model.forge.js` | Mesh exports for 3D printing. |
@@ -262,6 +266,7 @@ For mechanisms, dense assemblies, printable parts, or anything safety-adjacent:
 
 ```bash
 forgecad run model.forge.js --connectivity
+forgecad inspect mechanical-integrity model.forge.js --collisions
 forgecad render inspect model.forge.js --channels rgb,mask,collisions,thickness,section --force
 forgecad check params model.forge.js --samples 12
 ```

package/dist/docs-raw/CLI.md

@@ -67,50 +67,63 @@ Execute scripts and produce images headless — no browser window. Renders use C
 
 ### `forgecad run`
 
-Execute a Forge script and print full geometry diagnostics — object summary, collision detection, spatial analysis, verification results, and solver profiling.
+Execute a Forge script quickly and print the inner-loop build summary: returned objects, verification results, parameters, and timing.
 
-The primary validation command. Runs your script with the real geometry kernel (no browser needed) and prints a comprehensive report:
+The fast validation command. Runs your script with the real geometry kernel (no browser needed) and reports whether it built, which objects came back, any `verify.*` results, parameter values, script logs, and elapsed script time. This is the command agents should run frequently while editing a model.
 
-**Object summary** — lists every named shape with its volume, bounding box, and body count. For constrained sketches, shows solver status (FULLY / UNDER / OVER constrained), DOF, and error residuals. Problematic constraints (conflicting, redundant, or high-residual) are flagged individually.
+**Fast by default** — a bare `forgecad run model.forge.js` does not compute per-object volumes, bounding boxes, construction history, feature tallies, spatial relationships, collision intersections, or solver profiles. Those diagnostics are useful, but they are no longer part of the hot path.
 
-**Construction history** — shows the build sequence for each shape (primitives, operations, modifications) so you can verify the modeling intent.
+**Opt-in diagnostics** — use `--details` for volume/bounding-box/object geometry summaries, `--history` for the construction tree, `--features` for feature tallies, `--solver-profile` for constraint solver timing, or `--full` for the legacy rich report. Use `--spatial bounded|exact` only when you want directional relationships and collision intersections from the run command itself.
 
-**Feature summary** — tallies geometry features across all objects (e.g. `3 extrude, 2 fillet, 1 chamfer`).
+**Verification results** — runs any `verify.*` checks in the script and reports pass/fail with expected vs actual values. Verification failures remain non-fatal so the model can still render and be inspected.
 
-**Verification results** — runs any `verify.*` checks in the script and reports pass/fail with expected vs actual values.
+**Physical connectivity** — pass `--connectivity` to list physically connected components across visible objects. Overlapping bbox candidates are checked with exact geometry by default, while bbox-only contact is treated as evidence rather than proof of one connected component. This helps answer whether the model is one continuous assembly or several separate islands.
 
-**Automatic collision detection** — performs an all-pairs collision check on every named shape. For each pair whose bounding boxes overlap, computes the boolean intersection and reports overlap above 0.1 mm³:
-
-```
-⚠ COLLISION: bolt ∩ base (shared vol: 42.3mm³)
-```
-
-Intra-group pairs (same assembly group) and mock-to-mock pairs are skipped. If a part passes through a boolean-subtracted hole, no collision is reported — the material is gone.
+**Quality preset** — pass `--quality live|default|high` to select the same geometry quality profile used by the editor and export tools. `live` is the fastest preset for large audit models.
 
-**Spatial analysis** — reports directional relationships and gap distances between nearby objects (e.g. `bracket is ABOVE base (gap: 5mm)`). Exact pairwise collision intersections run by default only for bounded scenes; use `--spatial exact` for exhaustive collision checks or `--spatial off` to skip this section.
+For deeper confidence gates, prefer `forgecad inspect mechanical-integrity`, `forgecad check print`, `forgecad check params`, or `forgecad render inspect` instead of turning `run` back into a catch-all audit command.
 
-**Physical connectivity** — pass `--connectivity` to list physically connected components across visible objects. Overlapping or touching bboxes are joined within `--connectivity-tolerance` (default `0.05` model units); use collision inspection for exact positive-volume overlaps. This helps answer whether the model is one continuous assembly or several separate islands.
+```bash
+forgecad run examples/api/static-assembly-connectors.forge.js
+forgecad run examples/api/static-assembly-connectors.forge.js --focus
+forgecad run examples/api/static-assembly-connectors.forge.js --focus "Bench.Slat*"
+forgecad run examples/api/static-assembly-connectors.forge.js --hide "Bench.Slat0,Bench.Slat1"
+forgecad run examples/api/static-assembly-connectors.forge.js --details --history
+forgecad run examples/api/static-assembly-connectors.forge.js --spatial bounded
+forgecad run examples/api/static-assembly-connectors.forge.js --full
+forgecad run examples/products/cup.forge.js --connectivity
+forgecad run examples/products/cup.forge.js --journeys
+forgecad run examples/products/cup.forge.js --backend occt
+forgecad run examples/products/cup.forge.js --backend truck --quality live
+forgecad run examples/products/cup.forge.js --debug-imports
+forgecad run examples/products/cup.forge.js -p "Wall Thickness=3" -p "Body Height=200"
+forgecad run examples/constraints/06-complex-spectrogram.forge.js --solver-debug-out tmp/spectrogram-debug
+```
 
-**Quality preset** — pass `--quality live|default|high` to select the same geometry quality profile used by the editor and export tools. `live` is the fastest preset for large audit models.
+### Object Filtering: `--focus` and `--hide`
 
-**Parameters** — lists all declared parameters with their current values. Overridden values are marked with `*`.
+Several CLI commands can filter the visible object set without changing model code: `run`, `render 3d`, `render wireframe`, `render inspect`, `capture`, and `check print`.
 
-**Solver profiling** — when constraint solving occurs, shows timing breakdown (clone, solve, redundancy detection, surface building) and solver internals.
+Use `forgecad run model.forge.js --quality live` to list returned object names quickly, then pass those names to `--focus` or `--hide`.
 
 ```bash
-forgecad run examples/cup.forge.js
-forgecad run examples/cup.forge.js --focus
-forgecad run examples/cup.forge.js --focus bracket,hinge
-forgecad run examples/cup.forge.js --hide "wall,bolt"
-forgecad run examples/cup.forge.js --connectivity
-forgecad run examples/cup.forge.js --journeys
-forgecad run examples/cup.forge.js --backend occt
-forgecad run examples/cup.forge.js --backend truck --quality live
-forgecad run examples/cup.forge.js --debug-imports
-forgecad run examples/cup.forge.js -p "Wall Thickness=3" -p "Body Height=200"
-forgecad run examples/constraints/06-complex-spectrogram.forge.js --solver-debug-out tmp/spectrogram-debug
+forgecad run examples/api/static-assembly-connectors.forge.js --quality live
+forgecad render 3d examples/api/static-assembly-connectors.forge.js bench.png --focus "Bench.*"
+forgecad render 3d examples/api/static-assembly-connectors.forge.js slats.png --focus "Bench.Slat*"
+forgecad render inspect examples/api/static-assembly-connectors.forge.js out/bench-inspect --channels rgb,mask --hide "Bench.Slat0,Bench.Slat1" --force
 ```
 
+Rules:
+
+- A bare `--focus` hides mock objects and keeps real objects.
+- `--focus name1,name2` renders only matching objects.
+- `--hide name1,name2` removes matching objects from the visible scene.
+- Matching is case-insensitive and supports `*` / `?` globs.
+- `--focus` and `--hide` are mutually exclusive.
+- Filtering happens after the script runs; it does not avoid evaluating the full model.
+- Filtering works on returned object names. For grouped children, use concrete child names or globs like `Bench.*`.
+- If a model unions many parts into one returned shape, the original parts cannot be isolated by CLI filtering.
+
 ### `forgecad render`
 
 Render a Forge scene. Use a subcommand — `3d`, `inspect`, `views`, `section`, `wireframe`, `sketch`, or `hq`.
@@ -127,13 +140,13 @@ Render a Forge scene. Use a subcommand — `3d`, `inspect`, `views`, `section`,
 - `render hq` — path-traced via Blender Cycles, for documentation and marketing shots
 
 ```bash
-forgecad render 3d examples/cup.forge.js
+forgecad render 3d examples/products/cup.forge.js
 forgecad render inspect examples/api/static-assembly-connectors.forge.js --channels rgb,mask
 forgecad render inspect channels
-forgecad render views examples/cup.forge.js
-forgecad render wireframe examples/cup.forge.js
+forgecad render views examples/products/cup.forge.js
+forgecad render wireframe examples/products/cup.forge.js
 forgecad render section examples/furniture/01-table.forge.js --plane XZ
-forgecad render hq examples/cup.forge.js --preset dramatic
+forgecad render hq examples/products/cup.forge.js --preset dramatic
 ```
 
 ### `forgecad render 3d`
@@ -149,10 +162,10 @@ Use `--edges=<off|thin|bold>` to control the edge overlay. For a pure wireframe
 This is the standard way to visually verify geometry from the CLI or in agent workflows. For higher quality (path-traced, materials, HDRI lighting), use `render hq` instead.
 
 ```bash
-forgecad render 3d examples/cup.forge.js
-forgecad render 3d examples/cup.forge.js --focus
-forgecad render 3d examples/cup.forge.js --focus bracket
-forgecad render 3d examples/cup.forge.js --hide "wall,bolt"
+forgecad render 3d examples/products/cup.forge.js
+forgecad render 3d examples/api/static-assembly-connectors.forge.js --focus
+forgecad render 3d examples/api/static-assembly-connectors.forge.js --focus "Bench.Slat*"
+forgecad render 3d examples/api/static-assembly-connectors.forge.js --hide "Bench.Slat0,Bench.Slat1"
 forgecad render 3d model.forge.js --view hero
 forgecad render 3d model.forge.js --camera 45:30
 forgecad render 3d model.forge.js --camera "proj=perspective;pos=200,-160,120;target=0,0,20;up=0,0,1;fov=38"
@@ -186,7 +199,7 @@ For bundle layout, channel encodings, and manifest semantics, see [Inspection Bu
 
 ```bash
 forgecad render inspect examples/api/static-assembly-connectors.forge.js --channels rgb,mask
-forgecad render inspect examples/api/static-assembly-connectors.forge.js out/bench-inspect --channels collisions --focus Bench
+forgecad render inspect examples/api/static-assembly-connectors.forge.js out/bench-inspect --channels collisions --focus "Bench.*"
 forgecad render inspect examples/api/static-assembly-connectors.forge.js --channels rgb,mask,collisions --hide "Bench.Slat0" --force
 ```
 
@@ -206,8 +219,8 @@ Render a Forge scene as a wireframe (edges only, no shading).
 Same as `render 3d` but renders only the edge geometry — no shaded surfaces. Useful for construction-style documentation or highlighting structural features without material detail.
 
 ```bash
-forgecad render wireframe examples/cup.forge.js
-forgecad render wireframe examples/cup.forge.js --camera iso
+forgecad render wireframe examples/products/cup.forge.js
+forgecad render wireframe examples/products/cup.forge.js --camera iso
 ```
 
 ### `forgecad render hq` **\[Pro\]**
@@ -221,12 +234,12 @@ Choose a `--preset` for the look: `studio` (neutral product shot), `dramatic` (h
 Output defaults to `<script-name>-hq.png`. Great for documentation, marketing renders, and social media.
 
 ```bash
-forgecad render hq examples/cup.forge.js
-forgecad render hq examples/cup.forge.js hero.png --preset dramatic --samples 1024
-forgecad render hq examples/cup.forge.js hero.png --view hero
-forgecad render hq examples/cup.forge.js hero.png --camera-json camera.json
-forgecad render hq examples/cup.forge.js --preset clay --size 2048
-forgecad render hq examples/cup.forge.js --transparent --preset glass
+forgecad render hq examples/products/cup.forge.js
+forgecad render hq examples/products/cup.forge.js hero.png --preset dramatic --samples 1024
+forgecad render hq examples/products/cup.forge.js hero.png --view hero
+forgecad render hq examples/products/cup.forge.js hero.png --camera-json camera.json
+forgecad render hq examples/products/cup.forge.js --preset clay --size 2048
+forgecad render hq examples/products/cup.forge.js --transparent --preset glass
 ```
 
 ### `forgecad capture gif|mp4` **\[Pro\]**
@@ -236,13 +249,13 @@ Animated orbit or joint playback.
 Renders an animated sequence by either orbiting the camera around the model or playing back a `jointsView` animation. Use `--capture orbit` (default) for a turntable rotation, `--capture animation --animation <name>` to play a named joints clip, or `--capture section-sweep` to move a clipping plane through the model. Supports `--cut-plane` to animate with a static cross-section visible. Use `--view`, `--camera`, `--camera-json`, or `--scene <file>` to choose the orbit base camera or the fixed camera for animations and section sweeps.
 
 ```bash
-forgecad capture gif examples/cup.forge.js
+forgecad capture gif examples/products/cup.forge.js
 forgecad capture gif examples/3d-printer.forge.js out/section.gif --cut-plane "Front Section"
 forgecad capture gif model.forge.js out/raw.gif --param "Output=raw-sdf"
 forgecad capture gif model.forge.js out/front.gif --camera front
 forgecad capture gif model.forge.js out/hero.gif --view hero
 forgecad capture gif examples/3d-printer.forge.js out/sweep.gif --capture section-sweep --sweep-plane YZ
-forgecad capture mp4 examples/cup.forge.js
+forgecad capture mp4 examples/products/cup.forge.js
 forgecad capture mp4 examples/api/runtime-joints-view.forge.js out/step.mp4 --capture animation --animation Step
 forgecad capture mp4 model.forge.js out/raw.mp4 --param "Output=raw-sdf"
 forgecad capture mp4 model.forge.js out/front.mp4 --camera front
@@ -276,8 +289,8 @@ forgecad render section examples/furniture/01-table.forge.js out/bold.svg --edge
 
 | Option | Description |
 |--------|-------------|
-| `--focus <names>` | Focus: no arg hides mocks; comma-separated names shows only those |
-| `--hide <names>` | Hide comma-separated object names |
+| `--focus <names>` | Focus: no arg hides mocks; comma-separated names/globs show only those |
+| `--hide <names>` | Hide comma-separated object names/globs |
 | `--camera <front\|back\|side\|right\|top\|iso\|az:el\|az:el:dist\|spec>` | Camera preset, spherical (az:el), or full spec such as `proj=perspective;pos=x,y,z;target=x,y,z;up=x,y,z;fov=45`. Repeatable. |
 | `--camera-json <file>` | Exact viewport camera JSON file |
 | `--view <name>` | Named camera view declared by the model with scene({ views }) |
@@ -299,7 +312,8 @@ forgecad render section examples/furniture/01-table.forge.js out/bold.svg --edge
 | `--min-thickness <mm>` | Critical thickness threshold in model units |
 | `--warn-thickness <mm>` | Warning thickness threshold in model units |
 | `--max-thickness <mm>` | Thick/blue heatmap threshold in model units |
-| `--thickness-samples <n>` | Maximum sampled triangles per object |
+| `--thickness-samples <n>` | Maximum thickness point samples per object |
+| `--roughness-samples <n>` | Maximum roughness point samples per object |
 | `--preset <name>` | Material/lighting preset |
 | `--width <px>` | Output width in pixels |
 | `--height <px>` | Output height in pixels |
@@ -530,7 +544,7 @@ forgecad skill one-file ~/Desktop/forgecad-context.md
 forgecad skill flattened-files ~/Desktop/forgecad-skills
 ```
 
-> **Workflow:** Agent writes the model -> `forgecad run` validates it -> `forgecad check print` catches printability risks -> `forgecad render inspect` produces visual evidence -> `forgecad check params` sweeps parameter robustness -> export ships the result. All in the terminal.
+> **Workflow:** Agent writes the model -> `forgecad run` validates it -> `forgecad inspect mechanical-integrity` catches disconnected AI-slop patterns -> `forgecad check print` catches printability risks -> `forgecad render inspect` produces visual evidence -> `forgecad check params` sweeps parameter robustness -> export ships the result. All in the terminal.
 
 ## Validation
 
@@ -551,6 +565,20 @@ forgecad check print model.forge.js --min-wall 1.2 --warn-wall 2
 forgecad check print model.forge.js --expect-components 1 -p "Wall Thickness=3"
 ```
 
+### `forgecad inspect mechanical-integrity`
+
+Inspect generated ForgeCAD models for mechanical integrity failures.
+
+Scans a Forge script or a folder of generated projects and runs a mechanical integrity inspection. The inspection flags timeouts, runtime errors, missing `verify.*` checks, missing executed mechanical-interface checks, fragmented named groups, uncontracted manual assemblies, optional positive-volume object collisions, and excessive physical component counts when requested. Markdown details include suggested repair patterns such as connector-authored mates, bolted service covers, pinned levers, captured slides, hinges, clevis joints, retained shafts, and seated bearings. When `--collisions` is enabled, the Markdown details list the largest overlapping object pairs by volume so agents can repair the highest-risk interfaces first. Exact collision checks use a default 40-pair bbox-overlap budget and 30s exact-check time budget; exhausting either budget fails the file instead of silently passing a partial check.
+
+```bash
+forgecad inspect mechanical-integrity path/to/generated-models
+forgecad inspect mechanical-integrity path/to/model/main.forge.js --min-verifications 2
+forgecad inspect mechanical-integrity path/to/model/main.forge.js --collisions
+forgecad inspect mechanical-integrity path/to/generated-models --collisions --collision-pair-limit 250
+forgecad inspect mechanical-integrity path/to/generated-models --json --timeout-ms 40000 --jobs 4
+```
+
 ### `forgecad check params`
 
 Sweep parameter ranges and report runtime failures, degeneracy, and new collisions.
@@ -574,6 +602,7 @@ forgecad check params path/to/model.forge.js --samples 12
 | Command | Description |
 |---------|-------------|
 | `check suite` | Run the repo invariant suite, with smoke and full profiles for the fast merge lane vs the broader regression sweep. |
+| `inspect mechanical-integrity` | Inspect generated ForgeCAD models for mechanical integrity failures. |
 | `check runtime-globals` | Ensure the script sandbox does not add new lowercase injected globals. |
 | `check transforms` | Run transform and assembly invariants. |
 | `check dimensions` | Run dimension propagation invariants. |
@@ -617,7 +646,7 @@ The CLI is free for core workflows and exports. Production outputs are free to r
 
 | Free | Production outputs | Pro |
 |------|--------------------|-----|
-| `run`, `dev`, `studio`, `render 3d`, `export stl`, `export 3mf`, `export svg`, `check print`, `check params`, `check suite` | `cut-list`, `export sketch-pdf`, `export step`, `export brep`, `export gcode`, `export sdf`, `export urdf`, `export report`, `export cutting-layout` are free to run; Pro covers commercial use. | `render hq`, `capture gif`, `capture mp4` |
+| `run`, `dev`, `studio`, `render 3d`, `export stl`, `export 3mf`, `export svg`, `check print`, `check params`, `inspect mechanical-integrity`, `check suite` | `cut-list`, `export sketch-pdf`, `export step`, `export brep`, `export gcode`, `export sdf`, `export urdf`, `export report`, `export cutting-layout` are free to run; Pro covers commercial use. | `render hq`, `capture gif`, `capture mp4` |
 
 ```bash
 forgecad license                    # Check signed-in account status

package/dist/docs-raw/beta-operations.md

@@ -36,6 +36,10 @@ All of these are thin wrappers around `scripts/beta.sh` /
 `scripts/beta-local.sh`. They exist for operator ergonomics only; regular
 ForgeCAD users never see them in the public product CLI.
 
+Production has the matching `npm run prod:*` shortcuts in `scripts/prod.sh`
+for the same reason: muscle memory should be environment-prefixed, even though
+production is normally deployed by GitHub Actions on `mainline`.
+
 **Useful overrides**:
 - `FORGE_BETA_DEPLOY_CONFIG` — alternate Kamal config path
 - `FORGE_BETA_DESTINATION` — alternate Kamal destination name (default `beta`)
@@ -242,6 +246,11 @@ for the isolation win.
    callback to the prod app.
 2. Create a **new** Google OAuth client (OAuth 2.0 client ID, web app).
    Authorised redirect URI `https://beta.forgecad.io/auth/callback/google`.
+
+   Use Google Auth Platform → Clients in the Google Cloud Console for this.
+   Do not use `gcloud iam oauth-clients`; that command creates IAM/IAP OAuth
+   application resources, not the normal Google Sign-In web client that
+   ForgeCAD's `/auth/callback/google` flow expects.
 3. Add the four secrets to `.kamal/secrets.beta`:
 
    ```bash

package/dist/docs-raw/coding.md

@@ -19,7 +19,7 @@ npm run preview      # Preview production build
 ### CLI Tools
 ```bash
 forgecad export svg examples/constraints/01-fully-constrained-rect.forge.js  # Export sketch to SVG
-forgecad render 3d examples/cup.forge.js         # Render to PNG (Puppeteer + Chrome)
+forgecad render 3d examples/products/cup.forge.js # Render to PNG (Puppeteer + Chrome)
 ```
 
 See [CLI.md](../CLI.md) for full CLI documentation.

package/dist/docs-raw/deployment.md

@@ -55,26 +55,25 @@ All containers share the `kamal` Docker network. The web container reaches the b
 
 ```bash
 # Deploy prod web app (zero-downtime rolling update)
-kamal deploy
+npm run prod:deploy
 
 # Deploy prod backend compute server
-kamal deploy -c config/deploy.backend.yml
+npm run prod:deploy:backend
 
 # Deploy both prod services
-kamal deploy && kamal deploy -c config/deploy.backend.yml
+npm run prod:deploy:all
 
 # Deploy the same commit to beta (run BEFORE prod)
-kamal deploy -d beta
-
-# Same flow via the beta operator wrapper
 npm run beta:deploy
+
+# Open the environment after a deploy
 npm run beta:smoke
+npm run prod:smoke
 ```
 
-Recommended flow for a change: merge to `mainline` → `kamal deploy -d beta`
-→ verify on `beta.forgecad.io` → `kamal deploy`
-(prod). See [beta-operations.md](beta-operations.md) for the full beta
-runbook.
+Recommended flow for a change: merge to `mainline` → `npm run beta:deploy`
+→ verify on `beta.forgecad.io` → `npm run prod:deploy`.
+See [beta-operations.md](beta-operations.md) for the full beta runbook.
 
 Kamal builds the Docker image on the server via SSH (`builder: remote:`), pushes to GHCR, pulls on the server, starts the new container, waits for healthcheck, switches traffic, stops old container. Zero downtime.
 
@@ -90,16 +89,16 @@ Push to `mainline` triggers `.github/workflows/deploy.yml` which runs `kamal dep
 ssh hetzner 'docker ps -a --format "{{.Names}}\t{{.Status}}" | grep "^forgecad-web-" | sed -E "s/^forgecad-web-([a-f0-9]+)(_replaced_[^[:space:]]+)?\t/\1\t/"'
 
 # Roll the web app back to the last known-good version:
-kamal rollback <VERSION>
+npm run prod:rollback -- <VERSION>
 
 # Backend rollback:
-kamal rollback -c config/deploy.backend.yml <VERSION>
+npm run prod:rollback:backend -- <VERSION>
 ```
 
 Example:
 
 ```bash
-kamal rollback db9c49b058aaa379d9d622456cb249f9b0ddc335
+npm run prod:rollback -- db9c49b058aaa379d9d622456cb249f9b0ddc335
 ```
 
 Use the most recent healthy version from the `docker ps -a` output above. The
@@ -126,10 +125,22 @@ version is the hex suffix in the Kamal container name, e.g.
 
 ## Operator Shortcuts
 
-Routine beta admin work is wrapped by repo-local scripts so the flow stays
-safe and memorable without changing the public ForgeCAD user CLI:
+Routine production and beta admin work is wrapped by repo-local scripts so the
+flow stays safe and memorable without changing the public ForgeCAD user CLI:
 
 ```bash
+npm run prod:deploy
+npm run prod:smoke
+npm run prod:deploy:backend
+npm run prod:deploy:all
+npm run prod:rollback -- <VERSION>
+npm run prod:logs
+npm run prod:logs:backend
+npm run prod:shell
+npm run prod:db
+npm run prod:health
+npm run prod:errors -- web 1000
+
 npm run beta:setup
 npm run beta:deploy
 npm run beta:smoke
@@ -142,6 +153,10 @@ npm run beta:local
 `FORGE_ENVIRONMENT=beta` backend on localhost, so you can open the browser and
 judge the UX without touching Cloudflare.
 
+These package scripts are thin wrappers around `scripts/prod.sh`,
+`scripts/beta.sh`, and Kamal. Use raw Kamal commands when debugging Kamal
+itself; otherwise prefer the environment-prefixed shortcuts.
+
 ---
 
 ## Environment Variables
@@ -267,10 +282,10 @@ Use the observability stack first for incidents:
 SSH access: `ssh hetzner` (see `~/.ssh/config`).
 
 ```bash
-# Kamal commands (run from project root locally)
-kamal app logs                                     # web app logs
-kamal app logs -c config/deploy.backend.yml        # backend logs
-kamal app exec -i bash                             # shell into web container
+# Kamal-backed commands (run from project root locally)
+npm run prod:logs                                  # web app logs
+npm run prod:logs:backend                          # backend logs
+npm run prod:shell                                 # shell into web container
 kamal proxy details                                # proxy routing info
 
 # Direct SSH
@@ -281,10 +296,10 @@ ssh hetzner "df -h / && free -h"
 ### Production scripts
 
 ```bash
-bash scripts/prod/health.sh                # containers, disk, memory
-bash scripts/prod/logs.sh [lines] [pattern]  # app logs
-bash scripts/prod/errors.sh [lines]        # error logs only
-bash scripts/prod/db.sh "SELECT ..."       # run SQL query
+npm run prod:health                        # containers, disk, memory
+npm run prod:errors -- web 1000            # error logs only
+npm run prod:db                            # interactive psql via Kamal
+bash scripts/prod/db.sh "SELECT ..."       # one-shot SQL query
 ```
 
 ### Email not delivered