forgecad 0.9.13 → 0.9.15

package/dist/docs-raw/API/README.md

@@ -1,16 +0,0 @@
-# ForgeCAD API Documentation
-
-API documentation lives in **JSDoc on source methods** (the single source of truth). The auto-generated docs in [`generated/`](../generated/) are extracted from JSDoc by `npm run gen:docs`.
-
-## What's here
-
-| Path | Purpose |
-|------|---------|
-| `core/concepts.md` | Cross-cutting mental model: execution model, coordinate system, color behavior, face label lifecycle |
-| `core/sdf-*.md` | SDF modeling (dev-only) |
-| `generated/*.md` | Auto-generated API reference per module — do not edit by hand |
-
-## Adjacent Documentation
-
-- **[`../guides/`](../guides/)** — Conceptual orientation: coordinate system, conventions, recipes
-- **[`../internals/`](../internals/)** — Engine internals for ForgeCAD contributors (dev-only)

package/dist/docs-raw/API/core/concepts.md

@@ -1,118 +0,0 @@
----
-skill-group: core
-skill-order: 1
----
-
-# ForgeCAD Core Concepts
-
-ForgeCAD scripts are JavaScript that returns geometry. The forge API is globally available — no imports needed.
-
-```javascript
-const width = param("Width", 50, { min: 20, max: 100, unit: "mm" });
-return box(width, 30, 10);
-```
-
-## Injected Runtime Names
-
-ForgeCAD API functions and classes are injected into every `.forge.js` script. Use them directly; do not import or destructure ForgeCAD API names from helper files.
-
-```javascript
-// BAD — `bom` and `bomToCsv` are already built-in runtime names.
-const { bom, bomToCsv } = require("./bom.js");
-
-// GOOD — use the built-in directly.
-bom(4, "M4 bolt");
-
-// GOOD — keep project helpers under their own local name.
-const bomHelpers = require("./bom.js");
-bomHelpers.addFasteners(...);
-```
-
-Top-level declarations such as `const bom = ...`, `let scene = ...`, or `class Shape {}` collide with the injected runtime names. If you need a local helper, choose a project-specific name like `projectBom`, `sceneConfig`, or `makeShape`.
-
-## Execution Model
-
-- Scripts re-execute on every parameter change (400ms debounce)
-- Geometry operations are **immutable** — shapes, sketches, groups, imported assemblies, and wood boards return new values instead of modifying in place
-- Must return one of: `Shape`, `Sketch`, `ShapeGroup`, `Assembly`, `SolvedAssembly`, `SdfShape`, `Array` of renderables, `Array` of `{ name, tags?, shape?, sketch?, group?, color? }`, or a **metadata object** (see below)
-
-Top-level assembly scripts can return an unsolved `Assembly` directly; ForgeCAD solves it at default joint values for display. Return `assembly.solve(state)` when you want a specific pose. Do not call `.toGroup()` just to make an assembly render — use `.toGroup()` only when you specifically need `ShapeGroup` composition, group-style transforms, or named-child lookup.
-
-### Metadata Object Return
-
-A script can return a plain object whose values include renderable geometry alongside non-renderable metadata. All renderable entries (Shape, Sketch, ShapeGroup, Assembly, SolvedAssembly, SdfShape, or Array of named objects) are rendered; non-renderable entries are silently skipped. This is useful for multi-file projects where a part needs to publish interface data (bolt positions, dimensions) to other files:
-
-When importing project files, include the full extension in every relative path: `require('./motor-mount.forge.js')` for model files and `require('./helpers.js')` for plain helper modules. ForgeCAD resolves project imports by exact path and does not infer `.forge.js` or `.js` from `require('./motor-mount')`.
-
-```javascript
-// motor-mount.forge.js — renders standalone, exports metadata via require()
-const holePositions = [[17, 15], [-29, 15], [17, -15], [-29, -15]];
-return {
-  shape: mount.color('#556B2F'),                        // rendered
-  bolts: { dia: 5.3, pos: holePositions },              // metadata — skipped in render, available via require()
-};
-
-// base-body.forge.js — imports mount, accesses .bolts
-const mount = require('./motor-mount.forge.js');
-for (const [x, y] of mount.bolts.pos) { ... }          // use metadata
-// mount.shape is the Shape if you need it in an assembly
-```
-
-Arrays inside the object are also rendered:
-
-```javascript
-return {
-  parts: [{ name: 'Left', shape: leftShape }, { name: 'Right', shape: rightShape }],
-  armWidth: 6,  // metadata
-};
-```
-
-Named return objects and named `group(...)` children can include `tags`. Tags are viewport metadata: they do not affect geometry, exports, face labels, or BOM rows, but the command palette can hide, show only, or focus every object with a selected tag.
-
-```javascript
-return [
-  { name: 'Base Plate', tags: ['printed', 'structural'], shape: base },
-  { name: 'M4 Bolt A', tags: 'fastener', shape: boltA },
-  { name: 'M4 Bolt B', tags: 'fastener', shape: boltB },
-];
-```
-
-## Coordinate System
-
-Z-up right-handed: X = left/right, Y = forward/back, Z = up/down.
-
-## Colors
-
-`.color(hex)` works on `Shape` and `Sketch`. Colors survive transforms. Boolean operations return a single result shape, so only the first operand's color survives.
-
-**`union()` merges shapes into one solid mesh** — later operands do not keep separate colors or identities. Use `group(...)` or return named objects instead when you want separate parts:
-
-```javascript
-return [
-  { name: "Base", shape: box(100, 100, 5), color: "#888888" },
-  { name: "Column", shape: cylinder(50, 10).translate(50, 50, 5), color: "#4488cc" },
-];
-```
-
-## Face Operations
-
-Shapes carry semantic face labels through their lifecycle. The flow is:
-
-1. **Primitives** assign canonical names — `box()` gives you `top`, `bottom`, `side-left`, etc.; `cylinder()` gives `top`, `bottom`, `side`.
-2. **Extrusions** inherit labels from the sketch and add `top`/`bottom`.
-3. **Transforms** (translate, rotate, scale, mirror) preserve all labels.
-4. **Booleans** preserve labels from the first operand where geometry survives.
-
-You resolve labels to geometry with `.face(name)` or `.face(query)` — see the Shape class docs for the full query API. Operations like `.pocket()`, `.boss()`, `.hole()`, and `faceProfile()` all consume face references.
-
-## Text vs Viewport Labels
-
-Default to no explanatory text inside CAD geometry. A ForgeCAD model should represent the physical artifact, not a labeled teaching diagram. Explain the design through file names, named return objects, comments, BOM entries, inspection bundles, and companion docs.
-
-Use `text2d()` only when the letters are part of the real object: raised branding, engraving, serial plates, keyboard legends, gauge ticks, connector labels, service arrows, scale markings, or exported manufacturing markings. `text2d()` builds filled sketch geometry from font outlines, so it can make exact/OCCT workflows slower.
-
-Use `Viewport.label(text, [x, y, z], options)` only for temporary review, debug, tutorial, or explicitly requested presentation views. Render labels are annotations only: they do not create meshes, do not export, do not enter the B-rep path, and do not add face labels. Do not use viewport labels to compensate for unclear geometry in the final model.
-
-## SDF Modeling
-
-For organic shapes, smooth blending, TPMS lattices, and surface deformations. Return `SdfShape` values directly, or return a plain object/array tree of SDF leaves, for native raymarch preview. Use `.toShape()` or `toShape(...)` only when you need mesh-backed CAD/export behavior. See [sdf-primitives.md](sdf-primitives.md).

package/dist/docs-raw/INDEX.md

@@ -1,138 +0,0 @@
-# ForgeCAD Documentation
-
-Start here if you are new to ForgeCAD, setting up the CLI, or giving a project to an AI coding agent.
-
-## The Happy Path
-
-ForgeCAD works best when every model lives in a real project folder:
-
-```bash
-npm install -g forgecad
-forgecad login
-mkdir spool-adapter
-cd spool-adapter
-forgecad project init "Spool Adapter"
-forgecad new adapter --template part
-forgecad studio .
-```
-
-Then let your AI agent work inside that same folder, validate the model from the terminal, and push the result back to the browser:
-
-```bash
-forgecad run adapter.forge.js
-forgecad inspect fit interference adapter.forge.js --camera iso
-forgecad check print adapter.forge.js --json
-forgecad project push
-forgecad project open
-```
-
-`forgecad studio` always needs an explicit project path. Use `.` for the current project. Do not point it at `~`, your whole desktop, downloads, or a huge source tree; ForgeCAD and AI agents need a small folder containing only the model, helper files, references, and generated evidence for that project.
-
-## Start Here
-
-- **[Welcome](welcome.md)** - First model, project setup, local editor, browser sync, and the AI-assisted loop.
-- **[AI Usage](AI/usage.md)** - Approved models, project-first agent setup, skill installation, quality prompts, validation evidence, and media ideas.
-- **[CLI Reference](CLI.md)** - Install, login, create projects, open local studios, run scripts, render, inspect, export, publish, and sync.
-
-## Project Workflow
-
-Use this section when the question is "how do I actually start?"
-
-- **Create a new hosted project locally**: `forgecad project init "Project Name"` creates the remote project, writes `forgecad.json`, and uploads any existing local `.forge.js`, `.js`, and `.svg` files.
-- **Clone an existing hosted project**: `forgecad project clone <slug>` downloads files and writes `forgecad.json`.
-- **Open the local editor**: `forgecad studio .` opens the installed local editor around the current project folder.
-- **Sync back to the browser**: `forgecad project push` uploads local changes for an initialized project. It does not create a remote project from a random folder; run `project init` first.
-
-## Product Strategy
-
-Product-first context for PM judgement, future bets, markets, workflows, and business direction. These docs intentionally avoid coding nuance; use the API reference and ForgeCAD skills for exact modeling APIs.
-
-- **[Product Docs Map](product/README.md)** - Theme index for product-first docs
-- **[Vision](product/vision.md)** - ForgeCAD as an AI-native interface layer for physical design
-- **[Founder Story](product/founder-story.md)** - Origin story and why AI needs an expressive CAD interface
-- **[API As Product Language](product/api-as-product-language.md)** - Why API vocabulary is product strategy
-- **[Product Loop](product/product-loop.md)** - Human goal, AI-authored code, validation, inspection, export
-- **[User Segments](product/user-segments.md)** - Makers, daily users, technical evaluators, partners, and enterprise AI-CAD users
-- **[Creative Manufacturing](product/creative-manufacturing.md)** - First wedge around useful custom physical objects
-- **[Manufacturing Workflows](product/manufacturing-workflows.md)** - 3D printing, laser cutting, CNC, furniture, robotics, and output routes
-- **[Competitive Positioning](product/competitive-positioning.md)** - How ForgeCAD differs from CAD-as-code, traditional CAD, Zoo/KCL, and prompt-to-CAD
-- **[Business Model](product/business-model.md)** - Pro, embedded commerce, OEM/partner, and enterprise pilot paths
-- **[Strategic Decisions](product/strategic-decisions.md)** - Product decision filters for future ideas
-- **[First Account Onboarding](product/onboarding-first-experience.md)** - Tactical source of truth for new-account first-run behavior
-- **[User Outreach Email Templates](product/user-outreach-email-templates.md)** - Founder-style user discovery and onboarding outreach
-
-## API Reference
-
-For users writing `.forge.js` scripts.
-
-- **[API Overview](API/README.md)** - Reading plan and orientation
-- **[Core](generated/core.md)** - Primitives, booleans, transforms, colors, materials, patterns, and shape operations
-- **[Sketches](generated/sketch.md)** - 2D geometry, constraints, profiles, extrusion, offsets, and sketch-driven modeling
-- **[Curves & Surfaces](generated/curves.md)** - Splines, lofts, sweeps, ruled surfaces, and exact surface workflows
-- **[Assembly](generated/assembly.md)** - Parts, connectors, joints, kinematics, collision checks, and exploded views
-- **[Output](generated/output.md)** - Exports, reports, BOMs, dimensions, robot packages, G-code, and manufacturing outputs
-- **[Library](generated/lib.md)** - Gears, fasteners, pipes, pulleys, belts, springs, and reusable helpers
-- **[Sheet Metal](generated/sheet-metal.md)** - Bends, flanges, flat patterns, reliefs, and sheet workflows
-- **[Viewport](generated/viewport.md)** - Cameras, animations, labels, views, and scene controls
-- **[SDF](generated/sdf.md)** - Organic fields, TPMS structures, smooth booleans, and implicit geometry
-- **[Concepts](generated/concepts.md)** - Semantic data structures and conceptual building blocks
-- **[Core Concepts](API/core/concepts.md)** - Permanent notes for core modeling concepts
-
-## Guides
-
-Techniques and conventions for model authors.
-
-- **[Coordinate System](guides/coordinate-system.md)** - Z-up convention, axis orientation
-- **[Geometry Conventions](guides/geometry-conventions.md)** - Winding order, depth, normals
-- **[Positioning](guides/positioning.md)** - Connectors, `matchTo()`, and placement strategies
-- **[Modeling Recipes](guides/modeling-recipes.md)** - Common patterns, iteration, multi-file composition
-- **[Joint Design](guides/joint-design.md)** - Connectors, joints, and mechanisms
-- **[Inspection Bundles](guides/inspection-bundles.md)** - `inspect <family> <mode>` bundle layout, evidence encodings, manifest semantics, and agent workflow
-- **[Component Model](component-model.md)** - Recommended assembly structure for multi-part projects
-- **[Skill Maintenance](guides/skill-maintenance.md)** - AI skill build process, `npm run refresh`
-
-## Platform
-
-Technical documentation for the hosted service at forgecad.io.
-
-- **[System Architecture](platform/architecture.md)** - Stack overview, URL routes, Docker topology, security
-- **[Authentication](platform/auth.md)** - JWT tokens, OAuth, registration, password reset, session management
-- **[Projects & Files](platform/projects.md)** - Project CRUD, member roles, file storage, storage quotas, SSE watching
-- **[Model Sharing](platform/sharing.md)** - Publishing, public URLs, embeds, gist/URL/inline sharing
-- **[Admin Dashboard](platform/admin.md)** - Admin panel, audit log, user management
-- **[Email Delivery](platform/email.md)** - Resend setup, verification emails, password reset emails
-
-## Development And Operations
-
-For contributors developing, deploying, or operating ForgeCAD.
-
-- **[Runbook](runbook.md)** - Dev server commands, local stack setup, health checks, production SSH, incident workflow, troubleshooting
-- **[Deployment & Environment](deployment.md)** - Kamal architecture, environment variables, deploy/rollback flow, database migrations
-- **[Observability](platform/observability.md)** - Grafana, Loki, Prometheus, Uptime Kuma, dashboards, logs, metrics, incident debugging
-- **[Releasing](RELEASING.md)** - npm version, publish workflow, GitHub Releases
-- **[RL Environments](rl-environments.md)** - AI-lab reconstruction gym contract, scoring payload, Docker workflow, and maintenance checklist
-- **[CLI Monetization & Licensing](cli-monetization.md)** - Free vs Pro tiers, license activation, feature gating strategy
-- **[Coding Guidelines](coding.md)** - Project structure, workflow, adding new features
-- **[Coding Best Practices](coding-best-practices.md)** - TypeScript, React, performance, self-review
-- **[Agent-Native API Design](agent-native-api.md)** - Why ForgeCAD solves AI-authored CAD with stronger domain APIs, not prompt-only specialization
-- **[Blueprint-First Design](blueprint-first.md)** - Intent-driven API design
-
-## Engine Internals
-
-For contributors working on ForgeCAD's core engine.
-
-- **[Backend Vocabulary](internals/backend-vocabulary.md)** - Canonical terms for compile plans, backends, capabilities, and routes
-- **[Compiler](internals/compiler.md)** - Multi-backend architecture, compile plans, lowering
-- **[Constraint Solver](internals/constraint-solver.md)** - Solver pipeline, architecture, Levenberg-Marquardt
-- **[Solver Quality](internals/constraint-solver-quality.md)** - Tunable vs architectural parameters
-- **[2D Sketch Pipeline](internals/sketch-2d-pipeline.md)** - Two-track export, ProfileCompilePlan
-
-## Processes
-
-Operational procedures for multi-agent development and investigations.
-
-- **[GitHub Issue Triage](../processes/GITHUB_ISSUE_TRIAGE.md)**
-- **[Multi-Agent Development](../processes/MULTI_AGENT_DEVELOPMENT.md)**
-- **[Program Lead](../processes/PROGRAM-LEAD.md)**
-- **[AI Investigation Projects](../processes/AI_INVESTIGATION_PROJECTS.md)**
-- **[Benchmark SOP](../processes/README_BENCHMARK_SOP.md)**

package/dist/docs-raw/RELEASING.md

@@ -1,87 +0,0 @@
----
----
-
-# Releasing ForgeCAD
-
-## Quick Release
-
-```bash
-npm version patch          # or minor / major
-git push && git push --tags
-```
-
-That's it. GitHub Actions handles the rest:
-- Builds everything (solver WASM + TypeScript + Vite + CLI + skills)
-- Runs the full test suite
-- Publishes to npm
-- Creates a GitHub Release with auto-generated notes
-- Production (forgecad.io) deploys automatically via GitHub Actions + Kamal on push to `mainline`
-
-## Version Levels
-
-| Command | When | Example |
-|---------|------|---------|
-| `npm version patch` | Bug fixes, small changes | 0.1.5 → 0.1.6 |
-| `npm version minor` | New features | 0.1.5 → 0.2.0 |
-| `npm version major` | Breaking changes | 0.1.5 → 1.0.0 |
-
-`npm version` automatically:
-1. Updates `version` in `package.json`
-2. Creates a git commit (`v0.1.6`)
-3. Creates a git tag (`v0.1.6`)
-
-## Dry Run
-
-To test the publish workflow without actually releasing:
-
-1. Go to **Actions → Publish to npm & GitHub Release → Run workflow**
-2. Check "Dry run" and run
-
-## Local Docker Publish Sanity Check
-
-For the full operational checklist, see [runbook.md](./runbook.md#npm-release-docker-verification).
-
-Before publishing manually, test the exact npm tarball in a clean Node container:
-
-```bash
-npm run release:pack
-npm run release:docker:create
-npm run release:docker:copy
-npm run release:docker:install
-npm run release:docker:run
-```
-
-Or run the whole lane:
-
-```bash
-npm run release:docker:all
-```
-
-Defaults:
-- Container: `forgecad-release-check`
-- Image: `node:22-slim`
-- Browser URL: `http://localhost:4173`
-- Studio port mapping: host `4173` -> container `5173`
-- Tarball output: `dist-bundles/npm-release-check/forgecad-<version>.tgz`
-- Smoke model: `examples/api/verification-demo.forge.js`
-
-Override the model or container with environment variables:
-
-```bash
-FORGECAD_RELEASE_MODEL=/path/to/model.forge.js npm run release:docker:all
-FORGECAD_RELEASE_CONTAINER=forgecad-debug npm run release:docker:all
-```
-
-## Prerequisites
-
-- `NPM_TOKEN` must be set as a GitHub repo secret (Settings → Secrets → Actions)
-  - Create a **Granular Access Token** at npmjs.com → Account → Access Tokens
-  - Scope it to read+write on the `forgecad` package only
-
-## What Gets Published
-
-- `dist-cli/forgecad.js` — CLI binary
-- `dist/` — web app bundles
-- `dist-skill/` — AI skill documentation and context
-- `examples/` — sample models
-- `README.md`, `LICENSE`

package/dist/docs-raw/agent-native-api.md

@@ -1,27 +0,0 @@
----
-skill-group: dev-conventions
-skill-order: 3
----
-
-# Agent-Native API Design
-
-ForgeCAD assumes that much of its model code will be written by AI coding agents. That is a strength of code-first CAD: the artifact is plain source, the API is documented, and the CLI gives the agent a feedback loop. A strong agent can read domain documentation and temporarily become useful in almost any specialty.
-
-But "make the agent more specialized through documentation" is not the core problem ForgeCAD should solve. If the agent needs pages of instructions to hand-derive standard mechanical behavior, manually tune magic numbers, compute trigonometry, or reconstruct common CAD operations from primitives, the missing capability belongs in the API. Documentation can teach the vocabulary, but it should not compensate for a weak vocabulary.
-
-The goal is an API specific and powerful enough to cover most serious modeling needs directly. Instead of asking agents to become gear experts, sheet-metal experts, fixture experts, or assembly-kinematics experts from scratch on every task, ForgeCAD should give them first-class concepts with names, contracts, diagnostics, and examples. The agent should read the docs to discover `lib.spurGear()`, `SheetMetal.flange()`, connector-based assemblies, inspection bundles, and exact export workflows, then compose those concepts with confidence.
-
-Docs are leverage, not product substitute. They should explain what exists, when to use it, what guarantees it provides, what limitations remain, and how to validate the result. They should not become long recipes for reimplementing missing algorithms in user code. When a doc repeatedly explains how to work around an API gap, that is a design signal: promote the intent into the API, add diagnostics, and keep the recipe as orientation rather than obligation.
-
-This is also why API specificity matters. Generic geometry escape hatches are valuable for unusual work, but the common path should preserve domain intent. A belt drive is not just a loop of tangent lines. A countersunk hole is not just three boolean cylinders. A multi-part assembly is not just a collection of translates. When ForgeCAD encodes those concepts directly, AI agents produce code that is shorter, more inspectable, easier to repair, and closer to what a mechanical designer meant.
-
-## Design Gate
-
-When improving docs or adding API surface, ask:
-
-- Are we teaching the agent an existing ForgeCAD concept, or teaching it to reimplement a concept ForgeCAD should own?
-- Would three different agents likely write three different fragile versions of this from the same docs?
-- Does the current solution require hand-tuned constants, manual trigonometry, raw coordinate derivation, or silent fallback behavior?
-- Could a domain-specific function, builder, namespace, diagnostic, or verification primitive make the intended model obvious?
-
-If the answer points to missing vocabulary, prefer an API improvement over longer instructions. Let documentation make agents fluent in ForgeCAD; do not make documentation carry the weight of the CAD system.