forgecad 0.9.5 → 0.9.6

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`)

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

package/dist/docs-raw/generated/concepts.md

@@ -7,7 +7,7 @@ Every public API function belongs to one of 16 fundamental concepts. This docume
 - **[C1: Primitive Construction](#c1-primitive-construction)** — Create geometry from parameters — no input geometry required. *(76 functions)*
 - **[C2: Boolean Combination](#c2-boolean-combination)** — Combine same-dimension geometry using CSG set operations. *(6 functions)*
 - **[C3: Rigid Transform](#c3-rigid-transform)** — Reposition or reorient geometry without changing its shape. *(3 functions)*
-- **[C4: Dimensional Promotion](#c4-dimensional-promotion)** — Convert a 2D profile into a 3D solid (extrude, revolve, loft, sweep). *(30 functions)*
+- **[C4: Dimensional Promotion](#c4-dimensional-promotion)** — Convert a 2D profile into a 3D solid (extrude, revolve, loft, sweep). *(40 functions)*
 - **[C5: Topology Query](#c5-topology-query)** — Select or inspect named faces and edges on a shape. *(3 functions)*
 - **[C6: Edge Feature](#c6-edge-feature)** — Modify edges of a solid — fillets, chamfers, draft, offset. *(7 functions)*
 - **[C7: Pattern Replication](#c7-pattern-replication)** — Duplicate geometry in regular arrangements (linear, circular, mirror). *(6 functions)*
@@ -1002,6 +1002,87 @@ composeChain(...steps: TransformInput[]): Transform
 
 Convert a 2D profile into a 3D solid (extrude, revolve, loft, sweep).
 
+#### `Loft.station()` — Create a loft station from a 2D profile and an axis position.
+
+```ts
+Loft.station(profile: Sketch, position: number): LoftStation
+```
+
+`LoftStation`: `{ profile: Sketch, position: number }`
+
+#### `Loft.leftRail()` — Create a guide rail that constrains the section-local negative-X side.
+
+```ts
+Loft.leftRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+`LoftGuideRail`: `{ side: LoftGuideRailSide, path: LoftGuideRailPath }`
+
+#### `Loft.rightRail()` — Create a guide rail that constrains the section-local positive-X side.
+
+```ts
+Loft.rightRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.frontRail()` — Create a guide rail that constrains the section-local positive-Y side.
+
+```ts
+Loft.frontRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.backRail()` — Create a guide rail that constrains the section-local negative-Y side.
+
+```ts
+Loft.backRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.centerRail()` — Create a guide rail that moves section centers along the loft.
+
+```ts
+Loft.centerRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.pathOnXz()` — Place a 2D guide path onto the XZ plane.
+
+The path's first coordinate becomes X and its second coordinate becomes Z. Use this for left/right silhouette rails authored with `path()` or `constrainedSketch()`.
+
+```ts
+Loft.pathOnXz(path: LoftPath2D, y?: number): Vec3[]
+```
+
+#### `Loft.pathOnYz()` — Place a 2D guide path onto the YZ plane.
+
+The path's first coordinate becomes Y and its second coordinate becomes Z. Use this for front/back crown rails authored with `path()` or `constrainedSketch()`.
+
+```ts
+Loft.pathOnYz(path: LoftPath2D, x?: number): Vec3[]
+```
+
+#### `Loft.pathOnXy()` — Place a 2D guide path onto the XY plane.
+
+The path's first coordinate becomes X and its second coordinate becomes Y. Use this when lofting along X or Y and a rail lives in a horizontal sketch plane.
+
+```ts
+Loft.pathOnXy(path: LoftPath2D, z?: number): Vec3[]
+```
+
+#### `Loft.withGuideRails()` — Loft through profile stations while forcing generated sections to follow guide rails.
+
+Stations define the cross-section family. Guide rails define the side or center paths the loft must pass through. With opposite side rails, the section is scaled to touch both rails. With one side rail, the section keeps its interpolated size unless a center rail is also present.
+
+```ts
+Loft.withGuideRails(stations: LoftStation[], rails: LoftGuideRail[], options?: LoftWithGuideRailsOptions): Shape
+```
+
+**`LoftOptions`**
+- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
+- `boundsPadding?: number` — Optional extra bounds padding.
+
+**`LoftWithGuideRailsOptions`** extends LoftOptions
+- `axis?: LoftAxis` — Primary station axis. Default Z.
+- `samples?: number` — Number of generated loft stations including ends. Default scales with station count.
+- `railSamples?: number` — Number of points sampled from curve-backed rails before axis interpolation. Default 64.
+
 #### `Analysis.EdgeContinuity()`
 
 ```ts
@@ -1312,10 +1393,6 @@ Performance note: loft is significantly heavier than primitive/extrude/revolve.
 loft(profiles: Sketch[], heights: number[], options?: LoftOptions): Shape
 ```
 
-**`LoftOptions`**
-- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
-- `boundsPadding?: number` — Optional extra bounds padding.
-
 #### `loftAlongSpine()` — Loft between multiple profiles positioned along an arbitrary 3D spine curve.
 
 Unlike loft() which only supports Z heights, loftAlongSpine() places each profile at a position along a 3D spine, oriented perpendicular to the spine tangent. This enables lofting along curved paths — e.g., a wing root-to-tip transition that follows a swept-back leading edge.

package/dist/docs-raw/generated/curves.md

@@ -9,7 +9,7 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 
 ## Contents
 
-- [Curves & Surfacing](#curves-surfacing) — `hermiteTransitionG2`, `nurbs3d`, `spline2d`, `spline3d`, `loft`, `loftAlongSpine`, `sweep`, `variableSweep`, `nurbsSurface`, `surfacePatch`, `transitionCurve`, `transitionSurface`, `connectEdges`
+- [Curves & Surfacing](#curves-surfacing) — `Loft.station`, `Loft.leftRail`, `Loft.rightRail`, `Loft.frontRail`, `Loft.backRail`, `Loft.centerRail`, `Loft.pathOnXz`, `Loft.pathOnYz`, `Loft.pathOnXy`, `Loft.withGuideRails`, `hermiteTransitionG2`, `nurbs3d`, `spline2d`, `spline3d`, `loft`, `loftAlongSpine`, `sweep`, `variableSweep`, `nurbsSurface`, `surfacePatch`, `transitionCurve`, `transitionSurface`, `connectEdges`
 - [Surface Members](#surface-members) — `surfaceBand`, `SurfaceBody`
 - [Curve3D](#curve3d)
 - [NurbsCurve3D](#nurbscurve3d)
@@ -52,6 +52,87 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 
 ### Curves & Surfacing
 
+#### `Loft.station()` — Create a loft station from a 2D profile and an axis position.
+
+```ts
+Loft.station(profile: Sketch, position: number): LoftStation
+```
+
+`LoftStation`: `{ profile: Sketch, position: number }`
+
+#### `Loft.leftRail()` — Create a guide rail that constrains the section-local negative-X side.
+
+```ts
+Loft.leftRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+`LoftGuideRail`: `{ side: LoftGuideRailSide, path: LoftGuideRailPath }`
+
+#### `Loft.rightRail()` — Create a guide rail that constrains the section-local positive-X side.
+
+```ts
+Loft.rightRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.frontRail()` — Create a guide rail that constrains the section-local positive-Y side.
+
+```ts
+Loft.frontRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.backRail()` — Create a guide rail that constrains the section-local negative-Y side.
+
+```ts
+Loft.backRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.centerRail()` — Create a guide rail that moves section centers along the loft.
+
+```ts
+Loft.centerRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.pathOnXz()` — Place a 2D guide path onto the XZ plane.
+
+The path's first coordinate becomes X and its second coordinate becomes Z. Use this for left/right silhouette rails authored with [`path()`](/docs/sketch#path) or [`constrainedSketch()`](/docs/sketch#constrainedsketch).
+
+```ts
+Loft.pathOnXz(path: LoftPath2D, y?: number): Vec3[]
+```
+
+#### `Loft.pathOnYz()` — Place a 2D guide path onto the YZ plane.
+
+The path's first coordinate becomes Y and its second coordinate becomes Z. Use this for front/back crown rails authored with [`path()`](/docs/sketch#path) or [`constrainedSketch()`](/docs/sketch#constrainedsketch).
+
+```ts
+Loft.pathOnYz(path: LoftPath2D, x?: number): Vec3[]
+```
+
+#### `Loft.pathOnXy()` — Place a 2D guide path onto the XY plane.
+
+The path's first coordinate becomes X and its second coordinate becomes Y. Use this when lofting along X or Y and a rail lives in a horizontal sketch plane.
+
+```ts
+Loft.pathOnXy(path: LoftPath2D, z?: number): Vec3[]
+```
+
+#### `Loft.withGuideRails()` — Loft through profile stations while forcing generated sections to follow guide rails.
+
+Stations define the cross-section family. Guide rails define the side or center paths the loft must pass through. With opposite side rails, the section is scaled to touch both rails. With one side rail, the section keeps its interpolated size unless a center rail is also present.
+
+```ts
+Loft.withGuideRails(stations: LoftStation[], rails: LoftGuideRail[], options?: LoftWithGuideRailsOptions): Shape
+```
+
+**`LoftOptions`**
+- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
+- `boundsPadding?: number` — Optional extra bounds padding.
+
+**`LoftWithGuideRailsOptions`** extends LoftOptions
+- `axis?: LoftAxis` — Primary station axis. Default Z.
+- `samples?: number` — Number of generated loft stations including ends. Default scales with station count.
+- `railSamples?: number` — Number of points sampled from curve-backed rails before axis interpolation. Default 64.
+
 #### `hermiteTransitionG2()` — Create a quintic Hermite transition curve between two edge endpoints (G2 continuity).
 
 The curve starts at `a.point` tangent to `a.tangent` with curvature `a.curvature`, and ends at `b.point` tangent to `b.tangent` with curvature `b.curvature`, with smooth G2-continuous interpolation matching position, tangent, and curvature.
@@ -140,10 +221,6 @@ Performance note: loft is significantly heavier than primitive/extrude/revolve.
 loft(profiles: Sketch[], heights: number[], options?: LoftOptions): Shape
 ```
 
-**`LoftOptions`**
-- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
-- `boundsPadding?: number` — Optional extra bounds padding.
-
 #### `loftAlongSpine()` — Loft between multiple profiles positioned along an arbitrary 3D spine curve.
 
 Unlike loft() which only supports Z heights, loftAlongSpine() places each profile at a position along a 3D spine, oriented perpendicular to the spine tangent. This enables lofting along curved paths — e.g., a wing root-to-tip transition that follows a swept-back leading edge.
@@ -821,6 +898,21 @@ path().moveTo(0,0).lineTo(10,0).lineTo(10,5).mirror('x').close()
 mirror(axis: "x" | "y" | [ number, number ]): this
 ```
 
+#### `toPolyline()` — Return the open path as a sampled 2D polyline.
+
+This is for construction geometry such as guide rails, measured centerlines, and curve-driven helpers where the authored path should stay open instead of becoming a filled sketch or stroked profile.
+
+```ts
+const rail = path()
+  .moveTo(24, 0)
+  .bezierTo(32, 44, 28, 92, 18, 120)
+  .toPolyline();
+```
+
+```ts
+toPolyline(): [ number, number ][]
+```
+
 #### `closeOffset()` — Close the path and return an offset version of the filled Sketch. Positive delta expands outward, negative shrinks inward.
 
 ```ts

package/dist/docs-raw/generated/sketch.md

@@ -1457,7 +1457,15 @@ detectArrangement(): Sketch[]
 #### `detectArrangementRegion()` — Select the single arrangement region that contains the given seed point. Throws if no region contains the seed.
 
 ```ts
-detectArrangementRegion(seed: [ number, number ]): Sketch
+detectArrangementRegion(_seed: [ number, number ]): Sketch
+```
+
+#### `toPolyline()` — Return the solved constrained path as a sampled 2D polyline.
+
+Use this when a construction rail was authored with `constrainedSketch()` and should feed another operation such as `Loft.pathOnXz(...)`. The sketch must contain exactly one profile path.
+
+```ts
+toPolyline(samples?: number): [ number, number ][]
 ```
 
 #### `withUpdatedConstraint()` — Re-solve the sketch after changing the value of one existing constraint.

package/dist/docs-raw/guides/inspection-bundles.md

@@ -190,9 +190,15 @@ root = largest component by body count, object count, then bbox volume
 rootDistance = shortest accumulated gap distance from root component
 ```
 
+For large scenes the manifest does not materialize the complete component gap
+graph, because that graph is quadratic in the number of components. The
+`gapEdgeCount` field reports the logical complete-graph edge count used by the
+analysis. `gapEdges` stores a compact evidence subset containing nearest-gap
+and root-parent edges.
+
 The PNG colors components from green at the root/near distances through yellow to
 red at the farthest rooted component. The manifest stores the root component,
-maximum rooted distance, complete component gap edge list, nearest-gap data, and
+maximum rooted distance, compact gap edge evidence, nearest-gap data, and
 shortest-path parent fields. The current v1 metric is bbox-based: it measures air
 gaps between component bounding boxes, not exact closest mesh-surface distance.
 
@@ -209,8 +215,8 @@ collision = boolean intersection volume > 0.1mm^3
 ```
 
 The manifest stores the inspected objects, collision pair names/ids, overlap
-volume, warnings, render style, and each collision finding's `groupIndex`,
-`color`, and `hex`. Exact interior pixels can be matched against
+volume, broadphase counters, warnings, render style, and each collision finding's
+`groupIndex`, `color`, and `hex`. Exact interior pixels can be matched against
 `manifest.channels.collisions.collisions[].color`; antialiased edges may blend
 with the ghosted source geometry. If `--focus PartA,PartB` is used, everything
 except those objects is hidden, `PartA` and `PartB` are ghosted, and their

package/dist/docs-raw/runbook.md

@@ -25,7 +25,7 @@ For platform feature docs (auth, projects, sharing, admin, email) see [platform/
 | SSH to production | `ssh hetzner` |
 | Open observability UI | Connect to Tailscale, then open `http://100.118.68.93:3000` |
 | Check observability stack | `bash scripts/prod/observability-status.sh` |
-| Roll back bad web deploy | `kamal rollback <VERSION>` |
+| Roll back bad web deploy | `npm run prod:rollback -- <VERSION>` |
 | Verify npm tarball in Docker | `npm run release:docker:all` |
 
 ---
@@ -375,13 +375,13 @@ user flows, roll back to the previous healthy web version immediately:
 
 ```bash
 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/"'
-kamal rollback <VERSION>
+npm run prod:rollback -- <VERSION>
 ```
 
 Example:
 
 ```bash
-kamal rollback db9c49b058aaa379d9d622456cb249f9b0ddc335
+npm run prod:rollback -- db9c49b058aaa379d9d622456cb249f9b0ddc335
 ```
 
 After rollback, verify a real user-facing path, not just `/api/health`. For

package/dist/index.html

@@ -55,7 +55,7 @@
       * { margin: 0; padding: 0; box-sizing: border-box; }
       html, body, #root { width: 100%; min-height: 100%; background: var(--fc-bg); color: var(--fc-text); font-family: system-ui, -apple-system, sans-serif; }
     </style>
-    <script type="module" crossorigin src="/assets/app-CFy7g5WP.js"></script>
+    <script type="module" crossorigin src="/assets/app-Dl9ymBWC.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/app-CsHnaBWt.css">
   </head>
   <body>

package/dist/sitemap.xml

@@ -2,37 +2,37 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
   <url>
     <loc>https://forgecad.io/</loc>
-    <lastmod>2026-05-16</lastmod>
+    <lastmod>2026-05-17</lastmod>
     <changefreq>weekly</changefreq>
     <priority>1.0</priority>
   </url>
   <url>
     <loc>https://forgecad.io/docs</loc>
-    <lastmod>2026-05-16</lastmod>
+    <lastmod>2026-05-17</lastmod>
     <changefreq>weekly</changefreq>
     <priority>0.8</priority>
   </url>
   <url>
     <loc>https://forgecad.io/blog</loc>
-    <lastmod>2026-05-16</lastmod>
+    <lastmod>2026-05-17</lastmod>
     <changefreq>weekly</changefreq>
     <priority>0.7</priority>
   </url>
   <url>
     <loc>https://forgecad.io/pricing</loc>
-    <lastmod>2026-05-16</lastmod>
+    <lastmod>2026-05-17</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.6</priority>
   </url>
   <url>
     <loc>https://forgecad.io/examples</loc>
-    <lastmod>2026-05-16</lastmod>
+    <lastmod>2026-05-17</lastmod>
     <changefreq>weekly</changefreq>
     <priority>0.6</priority>
   </url>
   <url>
     <loc>https://forgecad.io/blog/hello-forgecad-io</loc>
-    <lastmod>2026-05-16</lastmod>
+    <lastmod>2026-05-17</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.5</priority>
   </url>