forgecad 0.9.14 → 0.9.15

package/dist/docs-raw/deployment.md

@@ -1,374 +0,0 @@
----
----
-
-# ForgeCAD Deployment & Environment
-
-See also the **[Runbook](runbook.md)** for day-to-day operations, testing, troubleshooting, and API reference.
-See **[Observability](platform/observability.md)** for the incident debugging workflow, dashboards, logs, metrics, and stack access.
-
-ForgeCAD runs on a **Hetzner VPS** deployed via **[Kamal 2](https://kamal-deploy.org)**. Kamal handles zero-downtime rolling deploys, TLS, and container orchestration.
-
-**Environments:**
-
-| Env | URL | Config | Postgres accessory | Purpose |
-|-----|-----|--------|--------------------|---------|
-| **production** | https://forgecad.io | `config/deploy.yml` | `forgecad-postgres` | Real users |
-| **beta** | https://beta.forgecad.io | `config/deploy.beta.yml` | `forgecad-postgres-beta` | Staging; every change lands here before prod |
-
-Beta runs on the same VPS as prod, fully isolated at the process level —
-separate containers, separate volumes, separate secrets, separate JWT keys.
-See [beta-operations.md](beta-operations.md) for the full runbook.
-
-**Kamal configs, Docker images:**
-
-| Config | Dockerfile | Service | Image |
-|--------|-----------|---------|-------|
-| `config/deploy.yml` | `Dockerfile` | `forgecad` (web, prod) | `ghcr.io/kostard/forgecad-web` |
-| `config/deploy.beta.yml` | `Dockerfile` | `forgecad-beta` (web, beta) | `ghcr.io/kostard/forgecad-web` |
-| `config/deploy.backend.yml` | `Dockerfile.backend` | `forgecad-backend` (compute) | `ghcr.io/kostard/forgecad-backend` |
-
-**Architecture:**
-
-```
-Cloudflare (TLS termination, "Full Strict" + Origin Certificate)
-  │
-  └─ kamal-proxy (:443/:80)           ← TLS with Cloudflare Origin Cert
-       │
-       ├─ forgecad web container       ← Fastify app (Node.js) on :5173
-       │    │
-       │    ├─ Serves SPA (dist/)      ← Vite-built React frontend
-       │    ├─ API routes (/api/*)     ← Auth, projects, files
-       │    ├─ Metrics listener        ← Internal-only Prometheus scrape on :9464
-       │    └─ connects to ──────────► postgresql accessory
-       │
-       └─ forgecad-backend container   ← Compute server on :4510
-            └─ ForgeCAD kernel (Node.js + WASM)
-
-Volume: forgecad-project-data          ← User project files on disk
-```
-
-All containers share the `kamal` Docker network. The web container reaches the backend via the network alias `forgecad-backend`. Postgres is a Kamal accessory — never restarted on app deploys.
-
----
-
-## Deploying
-
-```bash
-# Deploy prod web app (zero-downtime rolling update)
-npm run prod:deploy
-
-# Deploy prod backend compute server
-npm run prod:deploy:backend
-
-# Deploy both prod services
-npm run prod:deploy:all
-
-# Deploy the same commit to beta (run BEFORE prod)
-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` → `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.
-
-### Auto-deploy via CI
-
-Push to `mainline` triggers `.github/workflows/deploy.yml` which runs `kamal deploy` (and optionally the backend). The GitHub Action SSHs into Hetzner and orchestrates the build there — no GitHub Actions compute used for building.
-
-### Rollback
-
-```bash
-# Some Kamal installs require an explicit version argument.
-# List recent prod web versions on Hetzner:
-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:
-npm run prod:rollback -- <VERSION>
-
-# Backend rollback:
-npm run prod:rollback:backend -- <VERSION>
-```
-
-Example:
-
-```bash
-npm run prod:rollback -- db9c49b058aaa379d9d622456cb249f9b0ddc335
-```
-
-Use the most recent healthy version from the `docker ps -a` output above. The
-version is the hex suffix in the Kamal container name, e.g.
-`forgecad-web-<VERSION>`.
-
----
-
-## Configuration Files
-
-| File | Purpose | Gitignored? |
-|------|---------|-------------|
-| `config/deploy.yml` | Kamal config for prod web app + postgres accessory | No |
-| `config/deploy.beta.yml` | Kamal config for beta web app + its own postgres accessory | No |
-| `config/deploy.backend.yml` | Kamal config for backend compute (prod) | No |
-| `.kamal/secrets` | Production secrets (DB, JWT, OAuth, email, registry) | Yes |
-| `.kamal/secrets.beta` | Beta secrets — must differ from prod | Yes |
-| `.kamal/secrets.beta.example` | Template for `.kamal/secrets.beta` | No |
-| `.kamal/certs/origin-cert.pem` | Cloudflare Origin Certificate (shared prod + beta, needs `*.forgecad.io` SAN) | Yes |
-| `.kamal/certs/origin-key.pem` | Cloudflare Origin Private Key | Yes |
-| `.github/workflows/deploy.yml` | CI deploy pipeline (prod only — beta is manual) | No |
-
----
-
-## Operator Shortcuts
-
-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
-npm run beta:logs
-npm run beta:refresh
-npm run beta:local
-```
-
-`beta:local` is the local-only smoke path: it launches a hosted frontend plus
-`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
-
-### Server Core
-
-| Variable | Required | Default | Purpose |
-|----------|----------|---------|---------|
-| `NODE_ENV` | no | `development` | Set to `production` for deployed instances |
-| `FORGE_ENVIRONMENT` | no | `production` | `production`, `beta`, or `development`. Drives the BETA banner in the UI and the `/api/health` response. Independent of `NODE_ENV`. |
-| `FORGE_PORT` | no | `5173` | HTTP port the server listens on |
-| `FORGE_HOST` | no | `127.0.0.1` | Bind address. Use `0.0.0.0` in Docker |
-| `FORGE_METRICS_PORT` | no | `9464` | Internal Prometheus metrics listener port |
-| `FORGE_METRICS_HOST` | no | `127.0.0.1` | Bind address for the internal metrics listener |
-| `FORGE_DIST_DIR` | no | — | Path to Vite build output. In Docker: `/app/dist` |
-
-### Database
-
-ForgeCAD uses PostgreSQL 16 for users, projects, sessions, and audit logs. The database schema is managed by Drizzle ORM with auto-migrations on server startup.
-
-| Variable | Required | Default | Purpose |
-|----------|----------|---------|---------|
-| `FORGE_DB_URL` | **yes** | — | PostgreSQL connection string |
-| `FORGE_DB_SLOW_QUERY_MS` | no | `250` | Slow-query threshold for DB warning logs and metrics |
-
-In Kamal, Postgres runs as an accessory with the hostname `forgecad-postgres` on the `kamal` Docker network:
-```
-FORGE_DB_URL=postgresql://<user>:<pass>@forgecad-postgres:5432/forgecad
-```
-
-### Authentication
-
-| Variable | Required | Default | Purpose |
-|----------|----------|---------|---------|
-| `FORGE_JWT_SECRET` | **yes** | — | HMAC key for signing JWT tokens. Generate: `openssl rand -base64 32` |
-| `FORGE_JWT_ACCESS_EXPIRES` | no | `15m` | Access token lifetime |
-| `FORGE_JWT_REFRESH_EXPIRES` | no | `7d` | Refresh token lifetime |
-
-### CORS & Public URL
-
-| Variable | Required | Default | Purpose |
-|----------|----------|---------|---------|
-| `FORGE_ALLOWED_ORIGINS` | no | `http://localhost:5173` | Comma-separated CORS origins |
-| `FORGE_APP_URL` | no | `http://localhost:5173` | Public base URL for email links |
-
-### OAuth Providers
-
-| Variable | Required | Default | Purpose |
-|----------|----------|---------|---------|
-| `GITHUB_CLIENT_ID` | no | — | GitHub OAuth app client ID |
-| `GITHUB_CLIENT_SECRET` | no | — | GitHub OAuth app client secret |
-| `GOOGLE_CLIENT_ID` | no | — | Google OAuth client ID |
-| `GOOGLE_CLIENT_SECRET` | no | — | Google OAuth client secret |
-
-### Email Delivery
-
-| Variable | Required | Default | Purpose |
-|----------|----------|---------|---------|
-| `RESEND_API_KEY` | no | — | API key from resend.com. Without it, emails logged to stdout |
-| `FORGE_EMAIL_FROM` | no | `ForgeCAD <noreply@forgecad.io>` | Sender address |
-
-### File Storage
-
-| Variable | Required | Default | Purpose |
-|----------|----------|---------|---------|
-| `FORGE_STORAGE_ROOT` | no | `/data/projects` | Root directory for user project files |
-
-In Docker, this is backed by the `forgecad-project-data` volume.
-
-### Backend Compute
-
-| Variable | Required | Default | Purpose |
-|----------|----------|---------|---------|
-| `FORGE_COMPUTE_URL` | no | `http://localhost:4510` | Backend server address (from Fastify's perspective) |
-| `FORGE_BACKEND_PORT` | no | `4510` | Backend server listen port |
-
-In Kamal, the web app reaches the backend via `http://forgecad-backend:4510` (Docker network alias).
-
----
-
-## Secrets Management
-
-Secrets are stored in `.kamal/secrets` (gitignored). Kamal reads this file as a shell script — you can use `$(cat ...)` for multi-line values like TLS certificates:
-
-```bash
-FORGE_JWT_SECRET=your-secret-here
-FORGE_DB_URL=postgresql://user:pass@forgecad-postgres:5432/forgecad
-CLOUDFLARE_ORIGIN_CERT=$(cat .kamal/certs/origin-cert.pem)
-CLOUDFLARE_ORIGIN_KEY=$(cat .kamal/certs/origin-key.pem)
-KAMAL_REGISTRY_PASSWORD=ghp_your_github_pat
-```
-
-For CI deploys, secrets are passed as GitHub Actions secrets (see `.github/workflows/deploy.yml`).
-
----
-
-## TLS / SSL
-
-TLS is handled by **Cloudflare** (edge termination) + **Cloudflare Origin Certificate** (origin authentication).
-
-- Cloudflare SSL mode: **Full (Strict)**
-- Origin cert stored in `.kamal/certs/` (gitignored, 15-year validity)
-- kamal-proxy serves the Origin Certificate to Cloudflare
-- `forward_headers: true` in proxy config passes `X-Forwarded-For` from Cloudflare
-
-To regenerate the Origin Certificate: Cloudflare dashboard → SSL/TLS → Origin Server → Create Certificate (PEM format, hostnames: `*.forgecad.io` and `forgecad.io`).
-
----
-
-## Database Migrations
-
-Migrations run automatically on server startup (`server/db/migrate.ts`). No manual database setup needed — the ForgeCAD server creates all tables on first boot.
-
----
-
-## Debugging Production
-
-Use the observability stack first for incidents:
-
-- [runbook.md](runbook.md#observability-first-incident-workflow)
-- [platform/observability.md](platform/observability.md)
-
-SSH access: `ssh hetzner` (see `~/.ssh/config`).
-
-```bash
-# 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
-ssh hetzner "docker ps --format 'table {{.Names}}\t{{.Status}}' | grep -E 'forgecad|kamal'"
-ssh hetzner "df -h / && free -h"
-```
-
-### Production scripts
-
-```bash
-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
-
-If `RESEND_API_KEY` is empty, emails are logged to stdout instead of sent. Check:
-```bash
-kamal app exec "env | grep RESEND"
-```
-
----
-
-## Local Development
-
-### Quick start (editor only, no auth)
-
-```bash
-npm run dev
-```
-
-No database, no login. For geometry, sketches, viewer work.
-
-### Full stack (auth, database, landing page, docs, blog)
-
-```bash
-# Terminal 1: start PostgreSQL
-npm run dev:db
-
-# Terminal 2: start Fastify API server (port 5174)
-npm run dev:server
-
-# Terminal 3: start Vite dev server (port 5173, proxies /api to 5174)
-npm run dev:studio
-```
-
-To stop the database: `npm run dev:db:stop`
-
-**Dev credentials** (hardcoded in `dev:server`, never used in production):
-- Database: `forgecad:forgecad@localhost:5432/forgecad`
-- JWT secret: `dev-secret-do-not-use-in-production`
-
-### Production build locally
-
-```bash
-npm run dev:db        # start PostgreSQL (once)
-npm run dev:prod      # tsc + vite build + run Fastify server
-```
-
----
-
-## Kamal Setup Notes
-
-**Prerequisites for deploying from a new machine:**
-1. Ruby (3.1+): `brew install ruby`
-2. Kamal: `gem install kamal`
-3. Docker + buildx: `brew install docker` + buildx plugin
-4. Colima (macOS): `brew install colima && colima start`
-5. SSH access to Hetzner: `ssh hetzner` must work
-6. `.kamal/secrets` populated with production values
-7. `.kamal/certs/` with Cloudflare Origin Certificate PEM files
-
-**Kamal paths (Homebrew Ruby on macOS):**
-```
-/opt/homebrew/opt/ruby/bin
-/opt/homebrew/lib/ruby/gems/4.0.0/bin/kamal
-```
-
-Add to fish: `fish_add_path /opt/homebrew/opt/ruby/bin /opt/homebrew/lib/ruby/gems/4.0.0/bin`
-
-**Server requirements:**
-- Docker installed
-- Login shell must be bash (not fish): `sudo chsh -s /bin/bash <user>`
-- Docker logged into GHCR: `docker login ghcr.io -u KoStard`

package/dist/docs-raw/guides/skill-maintenance.md

@@ -1,161 +0,0 @@
----
-skill-group: dev-skill
-skill-order: 1
----
-
-# Skill System Maintenance
-
-ForgeCAD ships an AI agent skill that teaches language models how to author `.forge.js` models. The skill has two variants:
-
-- **Standard** (`forgecad skill install`) — model-authoring docs only. Shipped to users.
-- **Dev** (`forgecad skill install --dev`) — everything above plus internals (compiler, solver, sketch pipeline, coding conventions, full CLI). For developers building ForgeCAD itself.
-
-## Architecture
-
-```
-docs/permanent/           ← source of truth for all docs
-scripts/build-forgecad-skill.mjs  ← reads docs, emits skill artifacts
-dist-skill/
-  SKILL.md                ← standard skill ({{SKILL_DIR}} placeholders)
-  SKILL-dev.md            ← dev skill (same, with extra sections)
-  CONTEXT.md              ← one-file paste target for chat UIs
-  docs/                   ← full docs tree, copied from docs/permanent/
-  library/                ← namespaced companion skills for `skill install`
-docs/permanent/skills/    ← generated website pages for installable skills
-src/pages/generatedSkillSections.ts ← generated docs sidebar/search manifest
-skills/forgecad/SKILL.md  ← in-repo dev SKILL.md (relative paths)
-skills/*/SKILL.md         ← companion workflow skills, tagged for public export
-```
-
-At install time (`forge-skill.ts`), the `{{SKILL_DIR}}` placeholder is replaced with the actual install directory (for example `~/.agents/skills/forgecad`), and the docs tree is copied alongside.
-
-## Adding a New Doc to the Skill
-
-1. Write the doc under `docs/permanent/` (e.g. `docs/permanent/API/core/my-feature.md`).
-2. Add YAML frontmatter at the top declaring which skill group it belongs to:
-   ```yaml
-   ---
-   skill-group: core
-   skill-order: 5
-   ---
-   ```
-3. Run `npm run refresh` — this rebuilds CLI, types, docs, and skill in the correct order.
-4. Run `node dist-cli/forgecad.js skill install` (or `--dev`) to install locally.
-
-`skill install` copies the already-built `dist-skill` artifacts. It does not rebuild them. If you are working from a checkout, run `npm run build:skill:forgecad` or `npm run refresh` before installing.
-
-`forgecad skill flattened-files <output-folder>` also reads the already-built `dist-skill` artifacts. It writes `forgecad.md` plus one Markdown file per bundled companion skill, appending extra files under filename-prefixed sections so each skill can be moved around as a single file.
-
-The build script discovers docs by scanning `docs/permanent/` for files with `skill-group` frontmatter. No hardcoded file lists to update.
-
-### Frontmatter fields
-
-| Field | Required | Default | Description |
-|-------|----------|---------|-------------|
-| `skill-group` | Yes | — | Group name (must match `GROUP_REGISTRY` in build script) |
-| `skill-order` | No | 50 | Sort order within the group |
-
-### Inclusion rules
-
-- **`skill-group: <name>`** — included in SKILL.md (index) and CONTEXT.md (inlined).
-- **`skill-group: dev-<name>`** — dev-only, appears in SKILL-dev.md only.
-- **No `skill-group`** — not part of the skill at all.
-
-### Adding a new group
-
-If you need a new group, add it to `GROUP_REGISTRY` in `scripts/build-forgecad-skill.mjs` with a title, guidance, and order number.
-
-## Companion Skill Public Export
-
-ForgeCAD also keeps companion workflow skills under `skills/`. These are the prompts and operating procedures used around the core modeling skill: build-brief preparation, model authoring, render inspection, print-time optimization, public project workflows, and similar.
-
-Each companion skill declares whether it can be mirrored to the public repository:
-
-```yaml
----
-name: forgecad-make-a-model
-description: Create new ForgeCAD (.forge.js) models...
-forgecad-public: true
----
-```
-
-Use `forgecad-public: true` for skills that help people reproduce ForgeCAD modeling workflows. Use `forgecad-public: false` for operational, private, or personal-process skills.
-
-To list the public set:
-
-```bash
-npm run sync:public-skills -- --list
-```
-
-To copy the public README source, rebuild the generated `forgecad` skill, build the installable companion library, and copy all public skills into the sibling public repo:
-
-```bash
-npm run sync:public-skills
-```
-
-End users install the core skill and namespaced companion library from the npm package with:
-
-```bash
-forgecad skill install
-```
-
-Public companion skill folder names are the installed names. Use the `forgecad-*` prefix directly in `skills/` for public skills, for example `skills/forgecad-prepare-prompt/`, `skills/forgecad-make-a-model/`, and `skills/forgecad-lld/`. The build step copies these folders into `dist-skill/library/` without renaming them.
-
-The sync script writes:
-
-- `README.md` in the public repo from this repo's `public-kit/README.md`
-- `skills/README.md` in this repo, listing public and private/internal skills
-- `skills/README.md` in the public repo, listing only exported skills
-- `skills/forgecad/` in the public repo from `dist-skill/`, so `forgecad skill install --core-only` remains available as the simple generated skill path
-- every other public skill from `skills/<skill-name>/`
-
-The skill build also writes the website-facing skill docs:
-
-- `docs/permanent/skills/index.md`
-- one page per installable skill under `docs/permanent/skills/<skill-name>.md`
-- `src/pages/generatedSkillSections.ts`, which powers the React docs sidebar, index cards, keyboard navigation, and search list
-
-Those pages are generated from the same `forgecad-public: true` skill set used for `dist-skill/library/`, so a public companion skill should never be installable without also appearing in the docs.
-
-## Adding Dev-Only Docs
-
-Use a `skill-group` with a `dev-` prefix (e.g. `dev-compiler`, `dev-solver`, `dev-conventions`). These appear in `SKILL-dev.md` but not in `SKILL.md` or `CONTEXT.md`. Use this for:
-
-- Compiler/solver internals
-- Coding conventions and PR guidelines
-- Full CLI reference (vs the slim user-facing docs)
-
-## Deciding Standard vs Dev
-
-| Question | If yes → |
-|----------|----------|
-| Does a model author need this to build `.forge.js` files? | Standard |
-| Does it describe internal architecture (compiler, solver, pipeline)? | Dev only |
-| Does it cover team process (coding standards, releases, CI)? | Dev only |
-| Is it repo-only developer tooling (`npm run check:suite`, `sdf`, debug flags)? | Dev only |
-
-## Orphan files
-
-Current `skill install` removes the installed `~/.agents/skills/forgecad/docs/` directory before copying the built docs tree, so normal installs should not leave doc orphans. If a machine used an older installer or files were edited manually, stale copies can still exist and should be deleted.
-
-To check for orphans:
-```bash
-for f in $(find ~/.agents/skills/forgecad/docs -name '*.md'); do
-  echo "$f" | grep -q '/generated/' && continue
-  base=$(echo "$f" | sed "s|$HOME/.agents/skills/forgecad/docs/|docs/permanent/|")
-  [ -f "$base" ] || echo "ORPHAN: $f"
-done
-```
-
-Delete any orphans found. They're stale copies that can mislead agents with outdated information.
-
-## Verifying
-
-After changes, check that the build succeeds and the doc counts look right:
-
-```bash
-npm run refresh
-node dist-cli/forgecad.js skill install --dev  # verify dev install
-```
-
-The build script prints the number of indexed source files. Verify new docs are counted.

package/dist/docs-raw/guides/surface-members.md

@@ -1,82 +0,0 @@
-# Surface Members: Straps, Inlays, Guards, And Structural Bands
-
-Surface members are for physical material that follows a carrier surface: bottle-cage arms, razor grip inlays, brace ribs, prop guards, helmet vents, and similar curved product structures.
-
-Use this layer when the model has:
-
-- a carrier surface such as a cylinder, plane, or `ProductSkin`
-- paths or bands that live in carrier-local coordinates
-- member-local section thickness, edge radius, slots, cutouts, lips, cups, or ribs
-- explicit joins between named members
-
-Do not use it for ordinary boxes, simple extrusions, sheet-metal bends, exact machined faces, or free-floating assemblies with normal connector placement.
-
-## Core Vocabulary
-
-`Carrier` owns surface coordinates and frames. The first carriers are `Carrier.cylinder(name)`, `Carrier.plane(name)`, and `Carrier.productSkin(skin)`. `Carrier.mesh(name)` and `Carrier.scan(name)` are reserved stubs that fail with direct guidance until arbitrary mesh/scan parameterization exists.
-
-`SurfaceBody(name)` is the main public builder for this layer. `SurfaceMembers.Body(name)` is the namespaced alias for the same builder; use the direct `SurfaceBody` form in examples where the model is mainly a surface-member graph. There is intentionally no lowercase `ribbonBody()` global in this primitive layer.
-
-`SurfacePath` samples carrier-local coordinates into continuous 3D frames. Cylinder paths use degrees and handle seam wrapping without user trigonometry. ProductSkin paths stay on one side; use `Carrier.productSkin(skin).sideTransition(fromSide, toSide, { v, name })` for one adjacent side boundary, `sideTransitionChain([from, middle, to], { v, name })` for named boundary pairs, or `sideRoute({ sides, from, to, v, name })` to generate ready-to-use per-side segment endpoints. Transition `v` is normalized from 0 to 1; names must be non-empty when provided; returned boundary coordinates are verified as coincident. These helpers create matching side-local coordinates so you can split the detail into one member per side and join named transition anchors through `SurfaceBody.join(...)`.
-
-`SurfaceBand` is a widened path footprint. It supports constant, station, eased, and function width profiles, records member-local hole/cut-region intent through `.withHole(name, { length, width, along, across })`, and exposes boundaries and cap intent before geometry lowering.
-
-`SurfaceBody` owns named members and joins. Members can be `band()` or `plate()`. Features are attached to members before lowering, so a slot or cutout belongs to a member-local coordinate system instead of a global boolean recipe.
-
-`buildWithDiagnostics()` returns a serializable member graph with endpoint, sampled landing, sampled band-boundary, named rounded slot/cutout feature-center, and explicit named surface-coordinate anchors from `.anchorAt(name, coordinateOrAnchor)`. Named anchors must be unique within a member. Diagnostics include a stable `code` field for agent repair loops; inspect `code` rather than matching prose. Joins must reference existing, distinct member names; invalid sources, targets, self-joins, raw wildcard joins, and conflicting duplicate radii fail directly. Join diagnostics report the nearest endpoint pair, landing candidate, or selected named anchor pair and distance, plus conflict warnings for too-small spans, too-large radii, insufficient overlap, and opposed normals. Close endpoint-to-endpoint joins and close `.join(a, b).betweenAnchors(fromAnchor, toAnchor)` joins lower into limited round connector geometry. Endpoint-to-band and endpoint-to-plate landing joins lower into surface-oriented pad connector geometry. `autoJoinAtSharedAnchors()` lowers only unambiguous shared endpoint pairs and warns when more than two members share a point. Farther, missing-anchor, or ambiguous joins remain diagnostic-only until topology-preserving trimming and blends exist.
-
-`buildDebug()` returns the normal member shapes plus visible anchor markers, join connection/radius markers, band centerlines, band boundary rails, sampled frame axes, rounded slot/cutout feature outlines, rib-pattern crossbars, and lip/cup profile rails, alongside the same diagnostics and IR.
-
-Bands report region diagnostics when center coordinates exceed carrier bounds, when ProductSkin side boundaries are crossed, when cylinder band width crosses z bounds, and when simple plane/cylinder boundary polylines self-intersect. These warnings use repair-oriented codes such as `region.centerOutOfBounds`, `region.productSkinBoundaryOutOfBounds`, `region.zBoundaryOutOfBounds`, and `region.boundarySelfIntersection` instead of forcing agents to parse English. The compiler reports these warnings instead of silently treating clipped or crossing geometry as valid.
-
-`Product.ribbon()` and `Product.surface(...).ribbon(...)` remain the compatibility path for simple one-side conformal NURBS ribbons on a `ProductSkin`. Use `Carrier.productSkin(skin)` plus `SurfaceBody` when the same skin detail needs member-local features, repeated ribs, explicit joins, mirrored members, or the same primitive vocabulary as bottle cages and guards.
-
-## Example
-
-For a minimal guard, use a cylinder carrier, one authored strut, its mirror, and an explicit join to a front hoop:
-
-```js
-const envelope = Carrier.cylinder("guard-envelope").diameter(84).height(36).clearance(2);
-
-const guard = SurfaceBody("simple-guard")
-  .carrier(envelope)
-  .member("left-strut")
-  .band()
-  .path(envelope.path().from({ angle: -132, z: 6 }).to({ angle: -58, z: 18 }))
-  .section({ width: 5.5, thickness: 2.8, edgeRadius: 0.6 })
-  .member("right-strut")
-  .mirrorOf("left-strut")
-  .member("front-hoop")
-  .band()
-  .path(envelope.path().around({ z: 18, fromAngle: -58, toAngle: 58 }))
-  .section({ width: 6.2, thickness: 3, edgeRadius: 0.7 })
-  .join("left-strut", "front-hoop").blend({ radius: 3.2 })
-  .join("right-strut", "front-hoop").blend({ radius: 3.2 })
-  .build();
-```
-
-```js
-const bottle = Carrier.cylinder("bottle").diameter(74).height(170).clearance(1.5);
-
-const cage = SurfaceBody("cage")
-  .carrier(bottle)
-  .member("left-arm")
-  .band()
-  .path(bottle.path()
-    .from({ angle: -145, z: 18 })
-    .through({ angle: -80, z: 72 })
-    .to({ angle: -34, z: 112 }))
-  .section({ width: 10, thickness: 5, edgeRadius: 1 })
-  .member("right-arm")
-  .mirrorOf("left-arm")
-  .join("left-arm", "right-arm").blend({ radius: 5, style: "structural" })
-  .build();
-
-return cage;
-```
-
-The API is intentionally blueprint-first: common paths should not require `Math.sin`, `Math.cos`, raw matrices, or hand-built overlap solids.
-
-## Current Limits
-
-The first compiler lowers members as deterministic sampled mesh solids. Bands support square, rounded, and tapered end caps; extended-to-junction caps remain explicit join intent until the junction compiler can trim/extend members. Plate-local rounded slots/cutouts, plate counterbores, band-local rounded cutouts, band rib patterns, lip/cup profile rails, and cup cradle webs are lowered as real mesh features, including variable-width and variable-thickness band footprints. Close endpoint junctions, unambiguous auto shared-endpoint junctions, and selected named-anchor junctions are lowered as small round connector solids at actual anchors; sampled band/plate landing junctions lower as surface-oriented pad connector solids. More advanced cup retention shapes, member trimming, and topology-preserving junction blends are still graph/diagnostic intent, so unsupported high-order transitions should be decomposed or left as future work rather than hidden behind silent fallbacks.