### ForgeCAD CLI Quick Start

Source: https://forgecad.io/docs/cli

Install the ForgeCAD CLI globally, create a new project, run a model, and start the development server with live reload.

```bash
npm install -g forgecad
```

```bash
forgecad new cup
```

```bash
forgecad run cup.forge.js
```

```bash
forgecad dev
```

```bash
forgecad export stl cup.forge.js
```

--------------------------------

### Check Examples

Source: https://forgecad.io/docs/cli

Run the example architecture gate, with smoke and full profiles for the maintained fast lane versus the full example catalog.

```bash
check examples
```

--------------------------------

### Install ForgeCAD CLI

Source: https://forgecad.io/docs/welcome

Install the ForgeCAD command-line interface globally using npm.

```bash
npm install -g forgecad
```

--------------------------------

### Collision Detection Example

Source: https://forgecad.io/docs/cli

Example output showing a detected collision between two parts with shared volume.

```text
⚠ COLLISION: bolt ∩ base (shared vol: 42.3mm³)
```

--------------------------------

### Install ForgeCAD Skills for AI Agents

Source: https://forgecad.io/docs/cli

Install AI skills to provide ForgeCAD API knowledge to coding agents. Use `--library` to install the broader workflow library.

```bash
# Give your agent full ForgeCAD API knowledge
forgecad skill install
```

```bash
# Install the broader namespaced ForgeCAD workflow library too
forgecad skill install --library
```

--------------------------------

### Set Product Skin Rails

Source: https://forgecad.io/docs/curves

Attaches guide rails as metadata and diagnostics for the ProductSkin.

```typescript
rails(rails: Record<string, ProductRailSpec>): this
```

--------------------------------

### Product Handle Builder

Source: https://forgecad.io/docs/curves

Starts a named handle feature builder.

```APIDOC
## `handle`

### Description
Start a handle feature builder.

### Signature
`handle(name: string): ProductHandleBuilder`
```

--------------------------------

### Clone Starter Project and Start Studio

Source: https://forgecad.io/docs/welcome

Clone the 'start-here' project locally and launch the ForgeCAD studio in the current directory.

```bash
forgecad project clone start-here
cd start-here
forgecad studio .
```

--------------------------------

### Check Backend Parity

Source: https://forgecad.io/docs/cli

Compare Manifold vs OCCT backend outputs across example files.

```bash
check backend-parity
```

--------------------------------

### Install ForgeCAD AI Agent Skill

Source: https://forgecad.io/docs/welcome

Install the necessary skill for the AI coding agent to interact with ForgeCAD.

```bash
forgecad skill install
```

--------------------------------

### Install ForgeCAD CLI

Source: https://forgecad.io/docs/guides/inspection-bundles.md

Install the ForgeCAD command-line interface globally using npm. This allows you to manage your ForgeCAD projects from the terminal.

```bash
$ npm install -g forgecad
```

--------------------------------

### Basic `forgecad render` Subcommand Examples

Source: https://forgecad.io/docs/cli

Demonstrates the basic usage of different `forgecad render` subcommands to generate various outputs from Forge scene files.

```bash
forgecad render 3d examples/cup.forge.js
```

```bash
forgecad render inspect examples/api/static-assembly-connectors.forge.js
```

```bash
forgecad render wireframe examples/cup.forge.js
```

```bash
forgecad render section examples/furniture/01-table.forge.js --plane XZ
```

```bash
forgecad render hq examples/cup.forge.js --preset dramatic
```

--------------------------------

### Product Spout Builder

Source: https://forgecad.io/docs/curves

Starts a named spout or nozzle feature builder.

```APIDOC
## `spout`

### Description
Start a spout/nozzle feature builder.

### Signature
`spout(name: string): ProductSpoutBuilder`
```

--------------------------------

### RouteBuilder: Get Start Point ID

Source: https://forgecad.io/docs/viewport

Retrieves the unique identifier for the starting point of the route.

```typescript
get start(): PointId
```

--------------------------------

### RouteBuilder: Get Start Point of Segment

Source: https://forgecad.io/docs/viewport

Returns the `PointId` for the starting point of a given line or arc segment within the route.

```typescript
startOf(segId: LineId | ArcId): PointId
```

--------------------------------

### initKernel()

Source: https://forgecad.io/docs/core

Initializes the backend kernel.

```APIDOC
## initKernel()

### Description
Initializes the backend kernel.

### Signature
```
initKernel(): Promise<unknown>
```
```

--------------------------------

### Get Unit Direction Vector of Line2D

Source: https://forgecad.io/docs/sketch

Retrieves the unit direction vector from the start to the end of a Line2D object. This is useful for calculations involving line orientation.

```typescript
get direction(): [ number, number ]
```

--------------------------------

### Initialize a New ForgeCAD Project

Source: https://forgecad.io/docs/cli

Initialize a new project in the current directory and create it on the ForgeCAD server. Provide a name for your project.

```bash
forgecad project init "Spool Adapter"
```

--------------------------------

### path()

Source: https://forgecad.io/docs/sketch

Create a new PathBuilder for tracing a 2D outline point by point. PathBuilder is a fluent API for constructing 2D profiles using a mix of line segments, arcs, bezier curves, and splines. Always start with .moveTo(x, y) to set the starting point. Call .close() to get a filled Sketch, or .stroke(width) to thicken an open polyline into a solid profile. Edge labels can be assigned with .label('name') after any segment — they propagate through extrusion, revolve, loft, and sweep into named faces on the resulting Shape.

```APIDOC
## path()

### Description
Create a new `PathBuilder` for tracing a 2D outline point by point.

### Returns
`PathBuilder`
```

--------------------------------

### Get Line Segment Midpoint

Source: https://forgecad.io/docs/sketch

Get the midpoint of a `Line2D` segment.

```typescript
get midpoint(): Point2D
```

--------------------------------

### Assembly Creation and Basic Usage

Source: https://forgecad.io/docs/assembly

Demonstrates how to create a new assembly, add parts, and define joints with their properties.

```APIDOC
## Assembly Creation

### Description
Creates a new kinematic assembly with a given name.

### Method
`assembly(name: string): Assembly`

### Example
```javascript
const mech = assembly("Arm");
```

## addPart

### Description
Adds a named part to the assembly.

### Method
`addPart(partName: string, shape: Shape): Assembly`

### Example
```javascript
mech.addPart("base", box(80, 80, 20).translate(0, 0, -10));
```

## addJoint

### Description
Adds a joint between two parts, defining its type, motion limits, and frame.

### Method
`addJoint(jointName: string, type: "revolute" | "prismatic" | "fixed", parentPart: string, childPart: string, options: JointOptions): Assembly`

### Parameters
#### JointOptions
- **axis** (Array<number>) - The axis of rotation or translation.
- **min** (number) - The minimum value for the joint's motion.
- **max** (number) - The maximum value for the joint's motion.
- **default** (number) - The default value for the joint's motion.
- **frame** (Transform) - The transformation from the parent part frame to the joint's zero-state frame.

### Example
```javascript
mech.addJoint("shoulder", "revolute", "base", "link", {
  axis: [0, 1, 0],
  min: -30, max: 120, default: 25,
  frame: Transform.identity().translate(0, 0, 20),
});
```
```

--------------------------------

### Create Product Surface Reference

Source: https://forgecad.io/docs/curves

Creates an ad-hoc ProductSurfaceRef from a skin and a side/u/v query.

```APIDOC
## `ref`

### Description
Create an ad-hoc ProductSurfaceRef from a skin and side/u/v query.

### Signature
`ref(skin: ProductSkin, query: ProductSkinRefQuery): ProductSurfaceRef`
```

--------------------------------

### Get Line Segment Length

Source: https://forgecad.io/docs/sketch

Get the length of a `Line2D` segment.

```typescript
get length(): number
```

--------------------------------

### Importing and Merging Assemblies

Source: https://forgecad.io/docs/assembly

Demonstrates how to import an assembly definition from a file and merge it into a parent assembly with specified mounting options and prefixes.

```typescript
require("./arm.forge.js").mergeInto(robot, {
  prefix: "Left Arm",
  mountParent: "Chassis",
  mountJoint: "leftMount",
  mountOptions: { frame: Transform.identity().translate(-70, 0, 10) },
});
```

--------------------------------

### ProductSkinBuilder Methods

Source: https://forgecad.io/docs/curves

Methods for building and customizing a product skin.

```APIDOC
## refs()

### Description
Publish multiple named semantic surface refs on the skin.

### Method
refs(refs: Record<string, ProductSkinRefQuery>): this

### Endpoint
N/A (Method)
```

```APIDOC
## uv()

### Description
Create a side/u/v surface-ref query for use in refs(...) or Product.ref(...).

### Method
uv(side: ProductSkinSide, u?: number, v?: number): ProductSkinRefQuery

### Endpoint
N/A (Method)
```

```APIDOC
## material()

### Description
Apply a product material preset to the lowered skin.

### Method
material(material: ProductMaterial): this

### Endpoint
N/A (Method)
```

```APIDOC
## color()

### Description
Apply a simple color override to the lowered skin.

### Method
color(color: string): this

### Endpoint
N/A (Method)
```

```APIDOC
## edgeLength()

### Description
Set the sampled loft target edge length.

### Method
edgeLength(value: number): this

### Endpoint
N/A (Method)
```

```APIDOC
## wall()

### Description
Records a target wall thickness; v1 keeps exterior skin lowering sampled and reports wall as a diagnostic.

### Method
wall(thickness: number): this

### Endpoint
N/A (Method)
```

```APIDOC
## build()

### Description
Lower stations and refs into a ProductSkin body.

### Method
build(): ProductSkin

### Endpoint
N/A (Method)
```

--------------------------------

### Get Line Segment Angle

Source: https://forgecad.io/docs/sketch

Get the direction angle of a `Line2D` segment in degrees, measured counter-clockwise from the positive X-axis.

```typescript
get angle(): number
```

--------------------------------

### assemblyInstructions()

Source: https://forgecad.io/docs/sheet-metal

Generates step-by-step assembly instructions from a list of flat parts and their joints. It uses an algorithm to determine the optimal order for assembling parts.

```APIDOC
## assemblyInstructions()

### Description
Generate step-by-step assembly instructions from flat parts and joints.

### Signature
```
assemblyInstructions(parts: FlatPart[], joints: JointRecord[], options?: AssemblyInstructionsOptions): AssemblyInstructionsResult
```

### Parameters
#### Options
- **rootPart** (string) - Optional - Part to start from. Default: part with most joint connections.

### Returns
- **AssemblyInstructionsResult** - An object containing the total number of parts, a list of orphan parts, and the assembly steps.
```

--------------------------------

### Configure Scene Environment

Source: https://forgecad.io/docs/viewport

Set up the scene's background, camera, lights, fog, and post-processing effects. When lights are specified, all default lights are removed, requiring an ambient light to be included. Setting camera position overrides auto-framing.

```javascript
scene({
  background: { top: '#000814', bottom: '#001d3d' },
  camera: { position: [160, -120, 100], target: [0, 0, 50], fov: 52 },
  lights: [
    { type: 'ambient', color: '#001233', intensity: 0.08 },
    { type: 'point', position: [120, -80, 130], color: '#00f5d4', intensity: 4, distance: 400, decay: 1 },
    { type: 'point', position: [-100, 60, 20], color: '#f72585', intensity: 3, distance: 350 },
    { type: 'directional', position: [50, -30, 200], color: '#ffd60a', intensity: 1.2 },
    { type: 'hemisphere', skyColor: '#003566', groundColor: '#000814', intensity: 0.2 },
  ],
  fog: { color: '#000814', near: 100, far: 450 },
  postProcessing: {
    bloom: { intensity: param('bloom', 1.5, 0, 4), threshold: 0.5, radius: 0.7 },
    vignette: { darkness: 0.8, offset: 0.25 },
    grain: { intensity: 0.08 },
    toneMappingExposure: param('exposure', 1.5, 0.5, 4),
  },
});
```

--------------------------------

### Start a Directional Route

Source: https://forgecad.io/docs/sketch

Begin describing a path from a starting coordinate using directional commands. Each segment returns an entity ID for use in constraints.

```typescript
const r = sk.route(0, 0);
const stem = r.up(18);
r.arcLeft(8.9);
const neck = r.down();
r.done();
sk.offsetX(stem, neck, 10.8);
```

--------------------------------

### Check Compiler

Source: https://forgecad.io/docs/cli

Run compiler routing snapshots and runtime-vs-lowered invariants.

```bash
check compiler
```

--------------------------------

### getY()

Source: https://forgecad.io/docs/curves

Gets the current cursor Y position.

```APIDOC
## getY()

### Description
Current cursor Y position.

### Method
`getY(): number`
```

--------------------------------

### Wood.board()

Source: https://forgecad.io/docs/concepts

Creates a wood board with specified dimensions and optional manufacturing metadata.

```APIDOC
## Wood.board()

### Description
Creates a wood board with metadata for manufacturing. The board is a box centered on XY, with its base at Z=0. Dimensions are width along X, height along Y, and thickness along Z.

### Signature
```typescript
Wood.board(width: number, height: number, thickness: number, opts?: WoodBoardOptions): WoodBoard
```

### Parameters
#### Options (`WoodBoardOptions`)
- `species` (string, optional): Wood species (e.g., "birch", "oak", "plywood"). Defaults to "wood".
- `material` (string, optional): Material description for BOM (e.g., "birch plywood"). Defaults to the `species` value.
- `grain` (string, optional): Grain direction: "long" (along width) or "cross" (along height). Defaults to "long".
- `color` (string, optional): Color hex string for visualization. Defaults to "#d2b48c" (tan/wood).
- `autoBom` (boolean, optional): If false, skip automatic BOM registration. Defaults to true.
```

--------------------------------

### getX()

Source: https://forgecad.io/docs/curves

Gets the current cursor X position.

```APIDOC
## getX()

### Description
Current cursor X position.

### Method
`getX(): number`
```

--------------------------------

### Get Current Y Position

Source: https://forgecad.io/docs/curves

Retrieves the current Y-coordinate of the cursor.

```typescript
getY(): number
```

--------------------------------

### Create a Filleted Electronics Enclosure

Source: https://forgecad.io/docs/guides/inspection-bundles.md

This example demonstrates creating a practical engineering part with a hollow interior, screw bosses, and rounded edges using fillets. It defines parameters for width, depth, height, wall thickness, and outer fillet radius.

```javascript
// Filleted Electronics Enclosure — practical engineering part
// Demonstrates: fillet() for professional-looking product design

const width = Param.number("Width", 80, { min: 50, max: 120, unit: "mm" });
const depth = Param.number("Depth", 50, { min: 30, max: 80, unit: "mm" });
const height = Param.number("Height", 25, { min: 15, max: 40, unit: "mm" });
const wall = Param.number("Wall", 2.5, { min: 1.5, max: 4, unit: "mm" });
const outerR = Param.number("Outer Fillet", 4, { min: 1, max: 10, unit: "mm" });

// ── Outer shell with rounded vertical edges ─────────────────────────────────
const outer = box(width, depth, height);
let enclosure = fillet(outer, outerR, { parallel: [0, 0, 1], convex: true });

// ── Hollow interior ─────────────────────────────────────────────────────────
// box() is XY-centered, Z starts at 0
const cavity = box(width - wall * 2, depth - wall * 2, height - wall)
  .translate(0, 0, wall + 0.01);
enclosure = difference(enclosure, cavity);

// ── Screw bosses ────────────────────────────────────────────────────────────
const bossR = 4;
const bossH = height - wall - 1;
const inset = wall + bossR + 2;

function screwBoss(x, y) {
  const boss = cylinder(bossH, bossR, bossR, 24).translate(x, y, wall);
  const hole = cylinder(bossH + 1, 1.5, 1.5, 16).translate(x, y, wall - 0.5);
  return difference(boss, hole);
}

const hw = width / 2, hd = depth / 2;
enclosure = union(
  enclosure,
  screwBoss(-hw + inset, -hd + inset),
  screwBoss( hw - inset, -hd + inset),
  screwBoss(-hw + inset,  hd - inset),
  screwBoss( hw - inset,  hd - inset),
);

return enclosure;
```

--------------------------------

### Get Current X Position

Source: https://forgecad.io/docs/curves

Retrieves the current X-coordinate of the cursor.

```typescript
getX(): number
```

--------------------------------

### Generate Step-by-Step Assembly Instructions

Source: https://forgecad.io/docs/sheet-metal

Produces detailed, step-by-step assembly instructions for the kit. Accepts `AssemblyInstructionsOptions` to customize the output format and content.

```typescript
assemblyInstructions(options?: AssemblyInstructionsOptions): AssemblyInstructionsResult
```

--------------------------------

### Get Rectangle2D Height

Source: https://forgecad.io/docs/sketch

Retrieves the height of the Rectangle2D object. This is a computed property.

```typescript
get height(): number
```

--------------------------------

### Sculpt.look

Source: https://forgecad.io/docs/sdf

Returns a polished scene preset tuned for liquid SDF preview.

```APIDOC
## Sculpt.look

### Description
Return a polished scene preset tuned for liquid SDF preview.

### Signature
`look(preset?: SculptLookPreset): SceneOptions`
```

--------------------------------

### Get Rectangle2D Width

Source: https://forgecad.io/docs/sketch

Retrieves the width of the Rectangle2D object. This is a computed property.

```typescript
get width(): number
```

--------------------------------

### Get Circle2D Area

Source: https://forgecad.io/docs/sketch

Retrieves the area of the Circle2D object. This is a computed property.

```typescript
get area(): number
```

--------------------------------

### activateBackend()

Source: https://forgecad.io/docs/core

Sets the active backend and ensures its WASM module is initialized. Recommended for executing code.

```APIDOC
## activateBackend()

### Description
Set the active backend and ensure its WASM module is initialized. Call this instead of `setActiveBackend` when you're about to execute code — it guarantees the backend is ready, not just selected.

### Signature
```
activateBackend(backend: ActiveBackend): Promise<void>
```
```

--------------------------------

### Get Circle2D Circumference

Source: https://forgecad.io/docs/sketch

Retrieves the circumference of the Circle2D object. This is a computed property.

```typescript
get circumference(): number
```

--------------------------------

### Publish a Model

Source: https://forgecad.io/docs/cli

Publish a model to share a live reference. This command automatically syncs the project if executed within one.

```bash
forgecad publish adapter.forge.js --title "AMS Lite Adapter"
```

--------------------------------

### Get Circle2D Diameter

Source: https://forgecad.io/docs/sketch

Retrieves the diameter of the Circle2D object. This is a computed property.

```typescript
get diameter(): number
```

--------------------------------

### Create New ForgeJS File

Source: https://forgecad.io/docs/cli

Create a new .forge.js file from a template.

```bash
new
```

--------------------------------

### kind()

Source: https://forgecad.io/docs/core

Gets the kind of the resolved reference (e.g., 'face', 'edge-set', 'point').

```APIDOC
## kind()

### Description
Gets the resolved reference kind, such as `face`, `edge-set`, or `point`.

### Method
```
get kind(): ShapeReferenceKind
```
```

--------------------------------

### formatInstructions()

Source: https://forgecad.io/docs/sheet-metal

Formats the assembly instructions generated by `assemblyInstructions()` into a human-readable text document.

```APIDOC
## formatInstructions()

### Description
Format assembly instructions as a human-readable text document.

### Signature
```
formatInstructions(result: AssemblyInstructionsResult): string
```

### Parameters
- **result** (AssemblyInstructionsResult) - The result object from `assemblyInstructions()`.

### Returns
- **string** - A formatted string representing the assembly instructions.
```

--------------------------------

### Check Placement

Source: https://forgecad.io/docs/cli

Run placement reference invariants.

```bash
check placement
```

--------------------------------

### Get Circle by Index

Source: https://forgecad.io/docs/sketch

Retrieves the CircleId of a circle created at a specific insertion index.

```typescript
circleAt(index: number): CircleId
```

--------------------------------

### Check System Dependencies

Source: https://forgecad.io/docs/cli

Check system dependencies for all CLI features.

```bash
doctor
```

--------------------------------

### Get Line by Index

Source: https://forgecad.io/docs/sketch

Retrieves the LineId of a line created at a specific insertion index.

```typescript
lineAt(index: number): LineId
```

--------------------------------

### Get Point by Index

Source: https://forgecad.io/docs/sketch

Retrieves the PointId of a point created at a specific insertion index.

```typescript
pointAt(index: number): PointId
```

--------------------------------

### Build and attach panel to a surface ref

Source: https://forgecad.io/docs/curves

Use `attachTo()` on a `ProductPanelBuilder` to build and attach the panel to a specified `ProductSurfaceRef`. Options can be provided for attachment.

```typescript
attachTo(ref: ProductRefInput, options?: ProductPanelAttachOptions): Shape
```

--------------------------------

### Get Active Backend

Source: https://forgecad.io/docs/core

Use `getActiveBackend()` to retrieve the currently active backend configuration.

```typescript
getActiveBackend(): ActiveBackend
```

--------------------------------

### beltDrive(options)

Source: https://forgecad.io/docs/lib

Create a flat open-belt body around two pulley pitch circles. The belt is generated as a tangent loop in the XY plane and extruded along +Z by `beltWidth`. The result includes the solid belt, the 2D belt profile, a thin pitch-path sketch for visualization, total belt length, tangent spans, and wrap metadata for each pulley.

```APIDOC
## beltDrive(options)

### Description
Create a flat open-belt body around two pulley pitch circles. The belt is generated as a tangent loop in the XY plane and extruded along +Z by `beltWidth`. The result includes the solid belt, the 2D belt profile, a thin pitch-path sketch for visualization, total belt length, tangent spans, and wrap metadata for each pulley. For more than two pulleys, the API intentionally asks for route intent before geometry is created. Use `route: "outer"` for the future outside-envelope mode, or an ordered route for future serpentine/idler layouts.

### Parameters
#### Path Parameters
- **options** (BeltDriveOptions) - Required - Options object for configuring the belt drive.
  - **pulleys** (Array<object>) - Required - An array of pulley configurations.
    - **name** (string) - Required - The name of the pulley.
    - **center** ([number, number]) - Required - The center coordinates of the pulley in the XY plane.
    - **pitchRadius** (number) - Required - The pitch radius of the pulley.
  - **beltWidth** (number) - Required - The width of the belt.
  - **beltThickness** (number) - Required - The thickness of the belt.

### Example
```ts
const drive = lib.beltDrive({
  pulleys: [
    { name: "motor", center: [0, 0], pitchRadius: 12 },
    { name: "output", center: [80, 0], pitchRadius: 28 },
  ],
  beltWidth: 8,
  beltThickness: 2,
});

return drive.belt;
```
```

--------------------------------

### Get Renderable Shape from Product Skin

Source: https://forgecad.io/docs/curves

Retrieves the renderable shape that has been generated for a ProductSkin.

```typescript
toShape(): Shape
```

--------------------------------

### Build and place the spout on its source ref

Source: https://forgecad.io/docs/curves

Use `attach()` on a `ProductSpoutBuilder` to build and place the spout on its source reference. Optional attachment options can be provided.

```typescript
attach(options?: ProductAttachOptions): Shape
```

--------------------------------

### importStep()

Source: https://forgecad.io/docs/core

Imports a STEP file (.step, .stp) as an exact OCCT-backed Shape, preserving NURBS curves and exact topology. Requires `setActiveBackend('occt')` to be called first.

```APIDOC
## importStep()

### Description
Import a STEP file (.step, .stp) as an exact OCCT-backed Shape. Preserves NURBS curves, B-spline surfaces, and exact topology. Requires `setActiveBackend('occt')`.

### Signature
```typescript
importStep(fileName: string): Shape
```
```

--------------------------------

### Get Rectangle2D Center

Source: https://forgecad.io/docs/sketch

Retrieves the geometric center of the Rectangle2D object as a Point2D. This is a computed property.

```typescript
get center(): Point2D
```

--------------------------------

### Check BREP Export

Source: https://forgecad.io/docs/cli

Run exact BREP export invariants.

```bash
check brep
```

--------------------------------

### Initialize Backend Kernel

Source: https://forgecad.io/docs/core

Call `initKernel()` to initialize the ForgeCAD backend runtime. This is an asynchronous operation.

```typescript
initKernel(): Promise<unknown>
```

--------------------------------

### Get Connectors by Type

Source: https://forgecad.io/docs/core

Filter and retrieve all connectors of a specific type from a shape using `connectorsByType`.

```typescript
connectorsByType(type: string): Array<{ name: string; port: ConnectorDef; }>
```

--------------------------------

### ProductSkinBuilder Methods

Source: https://forgecad.io/docs/curves

Methods for constructing a ProductSkin using a builder pattern, allowing configuration of axis, stations, rails, and named references.

```APIDOC
## `axis()` — Choose the primary station axis for the skin loft.

### Description
Sets the primary axis along which the ProductSkin will be lofted, defining the direction of stations.

### Method
`axis(axis: ProductSkinAxis): this`

### Parameters
- **axis** (ProductSkinAxis) - Required - The desired axis for the skin loft.

### Response
- **this** - The `ProductSkinBuilder` instance for chaining.
```

```APIDOC
## `stations()` — Set named cross-section stations for the product skin.

### Description
Defines the cross-sectional stations along the ProductSkin's axis, which dictate its shape.

### Method
`stations(stations: Array<ProductStationBuilder | ProductStationSpec>): this`

### Parameters
- **stations** (Array<ProductStationBuilder | ProductStationSpec>) - Required - An array of station definitions.

### Response
- **this** - The `ProductSkinBuilder` instance for chaining.
```

```APIDOC
## `rails()` — Attach guide rails as ProductSkin IR metadata and diagnostics.

### Description
Attaches guide rails to the ProductSkin, which serve as metadata and can be used for diagnostics during the skin generation process.

### Method
`rails(rails: Record<string, ProductRailSpec>): this`

### Parameters
- **rails** (Record<string, ProductRailSpec>) - Required - An object mapping rail names to their specifications.

### Response
- **this** - The `ProductSkinBuilder` instance for chaining.
```

```APIDOC
## `ref()` — Publish a named semantic surface ref on the skin.

### Description
Publishes a named semantic reference point or curve on the ProductSkin, making it resolvable later via `ProductSkin.ref()`.

### Method
`ref(name: string, query: ProductSkinRefQuery): this`

### Parameters
- **name** (string) - Required - The name to assign to the surface reference.
- **query** (ProductSkinRefQuery) - Required - The query object defining the location of the surface reference.

### Response
- **this** - The `ProductSkinBuilder` instance for chaining.
```

--------------------------------

### Get Diagonals of Rectangle2D

Source: https://forgecad.io/docs/sketch

Returns an array containing the two Line2D objects representing the diagonals of the Rectangle2D.

```typescript
diagonals(): [ Line2D, Line2D ]
```

--------------------------------

### Check Constraints

Source: https://forgecad.io/docs/cli

Run constraint solver invariants and snapshot regression tests.

```bash
check constraints
```

--------------------------------

### Check CLI Status

Source: https://forgecad.io/docs/cli

Show the current user, server, and license status.

```bash
forgecad license
```

--------------------------------

### Get Point on Circle at Angle

Source: https://forgecad.io/docs/sketch

Returns a Point2D located on the circumference of the circle at a specified angle (in degrees).

```typescript
pointAtAngle(angleDeg: number): Point2D
```

--------------------------------

### Get Connector Measurements

Source: https://forgecad.io/docs/core

Retrieve measurement metadata associated with a specific connector on a shape using `connectorMeasurements`.

```typescript
connectorMeasurements(name: string): Record<string, number | string>
```

--------------------------------

### Build the ProductSkin body

Source: https://forgecad.io/docs/curves

Use `build()` on a `ProductSkinBuilder` to lower stations and references into a `ProductSkin` body.

```typescript
build(): ProductSkin
```

--------------------------------

### Capture MP4 with Animation Playback

Source: https://forgecad.io/docs/cli

Creates an MP4 by playing back a named animation clip from the model. Use `--capture animation` and `--animation` to specify the clip.

```bash
forgecad capture mp4 examples/api/runtime-joints-view.forge.js out/step.mp4 --capture animation --animation Step
```

--------------------------------

### Get Serializable Query Spec for Surface Ref

Source: https://forgecad.io/docs/curves

Returns the serializable side/u/v query that defines this ProductSurfaceRef.

```typescript
querySpec(): ProductSkinRefQuery
```

--------------------------------

### Get Point on Curve

Source: https://forgecad.io/docs/curves

Returns the position on the curve at a normalized parameter t. This is an O(1) operation with no allocations.

```typescript
pointAt(t: number): Vec3
```

--------------------------------

### Define Joints and Animations with jointsView

Source: https://forgecad.io/docs/concepts

This example demonstrates the full structure for defining joints with properties like axis, pivot, min/max, and default values, along with a named animation cycle including keyframes.

```javascript
jointsView({
  joints: [{
    name: 'Shoulder',
    child: 'Upper Arm',
    parent: 'Base',
    type: 'revolute',
    axis: [0, -1, 0],
    pivot: [0, 0, 46],
    min: -30,
    max: 110,
    default: 15,
  }],
  animations: [{
    name: 'Walk Cycle',
    duration: 1.6,
    loop: true,
    keyframes: [
      { values: { Shoulder: 20 } },
      { values: { Shoulder: -10 } },
      { values: { Shoulder: 20 } },
    ],
  }],
});
```

--------------------------------

### explain()

Source: https://forgecad.io/docs/core

Provides a human-readable explanation of how this reference was resolved.

```APIDOC
## explain()

### Description
Returns a human-readable explanation of how this reference resolved.

### Method
```
explain(): string
```
```

--------------------------------

### polygonVertices()

Source: https://forgecad.io/docs/concepts

Computes the vertex positions of a regular polygon. Options include starting angle and center coordinates.

```APIDOC
## polygonVertices() - Compute regular polygon vertices

### Description
Compute the vertex positions of a regular polygon. Default orientation places the first vertex at the top (90 degrees), matching the convention used by `ngon()`. Eliminates manual `Math.sqrt(3)` for triangles, pentagon vertex math, etc.

### Example
```typescript
// Before — manual equilateral triangle
// const v1 = [center.x - r/2, center.y + r * Math.sqrt(3)/2];
// const v2 = [center.x - r/2, center.y - r * Math.sqrt(3)/2];
// const v3 = [center.x + r, center.y];

// After — declarative
const [v1, v2, v3] = polygonVertices(3, r);
```

### Signature
```typescript
polygonVertices(sides: number, radius: number, options?: PolygonVerticesOptions): LayoutPoint[]
```

### Options
**`PolygonVerticesOptions`**
  * `startDeg?: number` — Angle of the first vertex in degrees (default: 90 = top).
  * `centerX?: number` — Center X coordinate (default: 0).
  * `centerY?: number` — Center Y coordinate (default: 0).

`LayoutPoint`: `{ x: number, y: number }`
```

--------------------------------

### Get Triangle Count

Source: https://forgecad.io/docs/core

Retrieve the total number of triangles in the mesh representation of a shape using the `numTri` method.

```typescript
numTri(): number
```

--------------------------------

### Get Number of Bodies

Source: https://forgecad.io/docs/core

Count the number of disconnected solid bodies within a shape using the `numBodies` method.

```typescript
numBodies(): number
```

--------------------------------

### scene()

Source: https://forgecad.io/docs/viewport

Configures the scene environment for the current script execution. This controls camera position, lighting, background, fog, environment maps, and post-processing effects. Multiple calls merge configurations, with later values overriding earlier ones.

```APIDOC
## `scene()` — Configure the scene environment

### Description
Controls camera position, lighting rig, background color or gradient, atmospheric fog, environment maps, post-processing effects, and capture parameters for the `forgecad capture` command. Multiple calls merge — later values override earlier ones on a per-key basis, so you can split configuration across multiple `scene()` calls.

When `lights` is specified, **all** default lights are removed. You must include your own ambient light or the scene will be fully dark.

Setting `camera.position` overrides auto-framing — the viewport will no longer auto-fit the geometry on script reload.

Post-processing effects (`bloom`, `vignette`, `grain`) work in the browser viewport only. The CLI applies camera, lights, background, fog, and `toneMappingExposure` but skips shader effects.

All numeric values accept `param()` expressions.

### Method
`scene(options: SceneOptions): void`

### Parameters
#### Options Object (`SceneOptions`)
- `capture?` (`SceneCaptureConfig`): Default capture parameters for `forgecad capture` — CLI flags override these.
- `background?` (`SceneBackgroundGradient`): Background color or gradient.
- `camera?` (`SceneCameraConfig`): Camera configuration.
- `lights?` (Array of `SceneLightConfig`): Lighting configuration. If specified, all default lights are removed.
- `environment?` (`SceneEnvironmentConfig`): Environment map configuration.
- `fog?` (`SceneFogConfig`): Fog configuration.
- `postProcessing?` (`ScenePostProcessingConfig`): Post-processing effects configuration.
- `ground?` (`SceneGroundConfig`): Ground plane configuration.

**`SceneBackgroundGradient`**
- `top`: `string` - Top color of the gradient.
- `bottom`: `string` - Bottom color of the gradient.

**`SceneCameraConfig`**
- `position?`: `[ number, number, number ]` - Camera's position in 3D space.
- `target?`: `[ number, number, number ]` - Point the camera is looking at.
- `up?`: `[ number, number, number ]` - Camera's up vector.
- `fov?`: `number` - Field of view in degrees.
- `type?`: `"perspective" | "orthographic"` - Camera projection type.

**`SceneLightConfig`**
- `type`: `string` - Type of light (e.g., 'ambient', 'point', 'directional', 'hemisphere').
- `color?`: `string` - Light color.
- `intensity?`: `number` - Light intensity.
- `position?`: `[ number, number, number ]` - Light position.
- `target?`: `[ number, number, number ]` - Target for directional/spot lights.
- `groundColor?`: `string` - Ground color for hemisphere lights.
- `skyColor?`: `string` - Sky color alias for hemisphere lights.
- `angle?`: `number` - Spot light cone angle in radians.
- `penumbra?`: `number` - Spot light penumbra (0–1).
- `decay?`: `number` - Point/spot light decay.
- `distance?`: `number` - Point/spot light distance (0 = infinite).
- `castShadow?`: `boolean` - Whether this light casts shadows.

**`SceneEnvironmentConfig`**
- `preset?`: `"studio" | "sunset" | "dawn" | "warehouse" | "forest" | "apartment" | "lobby" | "city" | "park" | "night" | "none"` - Built-in preset name or 'none' to disable.
- `intensity?`: `number` - Environment map intensity.
- `background?`: `boolean` - Use environment map as scene background.

**`SceneFogConfig`**
- `color?`: `string` - Fog color.
- `near?`: `number` - Linear fog near distance.
- `far?`: `number` - Linear fog far distance.
- `density?`: `number` - Exponential fog density (if set, uses FogExp2 instead of linear Fog).

**`ScenePostProcessingConfig`**
- `bloom?`: `SceneBloomConfig` - Bloom effect configuration.
- `vignette?`: `SceneVignetteConfig` - Vignette effect configuration.
- `grain?`: `SceneGrainConfig` - Grain effect configuration.
- `toneMappingExposure?`: `number` - Tone mapping exposure value.

**`SceneBloomConfig`**
- `intensity?`: `number` - Bloom intensity.
- `threshold?`: `number` - Bloom threshold.
- `radius?`: `number` - Bloom radius.

**`SceneVignetteConfig`**
- `darkness?`: `number` - Vignette darkness.
- `offset?`: `number` - Vignette offset.

**`SceneGrainConfig`**
- `intensity?`: `number` - Grain intensity.

**`SceneGroundConfig`**
- `visible?`: `boolean` - Show a ground plane.
- `color?`: `string` - Ground color.
- `offset?`: `number` - Offset below the model's bounding box minimum Z.
- `receiveShadow?`: `boolean` - Receive shadows on the ground.

**`SceneCaptureConfig`**
- `framesPerTurn?`: `number` - Frames for one full orbit rotation (default: 72).
- `holdFrames?`: `number` - Frozen frames before motion starts (default: 6).
- `pitchDeg?`: `number` - Orbit pitch angle in degrees (default: auto from camera).
- `fps?`: `number` - Output frame rate (default: 24).
- `size?`: `number` - Output frame size in pixels (default: 960).
- `background?`: `string` - Canvas background color for capture (default: '#252526').

### Request Example
```javascript
scene({
  background: { top: '#000814', bottom: '#001d3d' },
  camera: { position: [160, -120, 100], target: [0, 0, 50], fov: 52 },
  lights: [
    { type: 'ambient', color: '#001233', intensity: 0.08 },
    { type: 'point', position: [120, -80, 130], color: '#00f5d4', intensity: 4, distance: 400, decay: 1 },
    { type: 'point', position: [-100, 60, 20], color: '#f72585', intensity: 3, distance: 350 },
    { type: 'directional', position: [50, -30, 200], color: '#ffd60a', intensity: 1.2 },
    { type: 'hemisphere', skyColor: '#003566', groundColor: '#000814', intensity: 0.2 },
  ],
  fog: { color: '#000814', near: 100, far: 450 },
  postProcessing: {
    bloom: { intensity: param('bloom', 1.5, 0, 4), threshold: 0.5, radius: 0.7 },
    vignette: { darkness: 0.8, offset: 0.25 },
    grain: { intensity: 0.08 },
    toneMappingExposure: param('exposure', 1.5, 0.5, 4),
  },
});
```
```

--------------------------------

### describe()

Source: https://forgecad.io/docs/assembly

Returns the serializable assembly definition used by solve/inspect pipelines.

```APIDOC
## describe()

### Description
Return the serializable assembly definition used by solve/inspect pipelines.

### Method
```
describe(): AssemblyDefinition
```
```

--------------------------------

### List Face Names

Source: https://forgecad.io/docs/core

Use `.faceNames()` to get an array of all currently defined semantic face names on the shape.

```typescript
faceNames(): string[]
```

--------------------------------

### Return immutable station spec

Source: https://forgecad.io/docs/curves

Use `toSpec()` on a `ProductStationBuilder` to get the immutable station specification that is consumed by `Product.skin()`.

```typescript
toSpec(): ProductStationSpec
```

--------------------------------

### Import STEP File (`importStep`)

Source: https://forgecad.io/docs/core

Imports a STEP file (.step, .stp) as an exact OCCT-backed Shape. Requires `setActiveBackend('occt')` and preserves NURBS curves and exact topology.

```typescript
importStep(fileName: string): Shape
```

--------------------------------

### RouteBuilder: Get End Point ID

Source: https://forgecad.io/docs/viewport

Retrieves the unique identifier for the current end point (cursor) of the route.

```typescript
get end(): PointId
```

--------------------------------

### High-Quality HQ Renders via Blender Cycles

Source: https://forgecad.io/docs/cli

Exports scenes to Blender for high-quality, path-traced renders using Cycles. Requires Blender installed. Use `--preset` for different looks, `--samples` to control quality, `--size` for resolution, and `--transparent` for compositing.

```bash
forgecad render hq examples/cup.forge.js
```

```bash
forgecad render hq examples/cup.forge.js hero.png --preset dramatic --samples 1024
```

```bash
forgecad render hq examples/cup.forge.js --preset clay --size 2048
```

```bash
forgecad render hq examples/cup.forge.js --transparent --preset glass
```

--------------------------------

### route()

Source: https://forgecad.io/docs/sketch

Starts a directional route from specified coordinates. Returns a RouteBuilder to describe the path using directional methods.

```APIDOC
## route()

### Description
Start a directional route from coordinates.

Returns a `RouteBuilder` - describe the path with up/down/left/right/arcLeft/arcRight. Each method returns the entity ID (`LineId` or `ArcId`) for use in `sk.*` constraints.

### Method
```javascript
route(x: number, y: number): RouteBuilder
```

### Parameters
* `x` (number) - The starting x-coordinate.
* `y` (number) - The starting y-coordinate.
```

--------------------------------

### solve()

Source: https://forgecad.io/docs/sketch

Runs the constraint solver and returns a solved sketch. The returned ConstraintSketch can be used in 3D operations and provides access to solver status and metadata.

```APIDOC
## solve()

### Description
Run the constraint solver and return a solved sketch.

The returned `ConstraintSketch` extends `Sketch` and can be used directly in all 3D operations (`extrude`, `revolve`, etc.). It also exposes `constraintMeta` with the solver status.

### Method
```javascript
solve(options?: SolveOptions): ConstraintSketch | Sketch
```

### Parameters
* `options` (SolveOptions) - Optional configuration for the solver.
```

--------------------------------

### Product Skin Builder

Source: https://forgecad.io/docs/curves

Starts a named product skin builder. Skins define the outer surface of a product.

```APIDOC
## `skin`

### Description
Start a named product skin builder.

### Signature
`skin(name: string): ProductSkinBuilder`
```

--------------------------------

### Get Geometry Information

Source: https://forgecad.io/docs/core

Inspect the backend or representation used to produce a solid's geometry using the `geometryInfo` method.

```typescript
geometryInfo(): GeometryInfo
```

--------------------------------

### Basic SDF Operations

Source: https://forgecad.io/docs/sdf

Demonstrates creating primitive SDF shapes like spheres and boxes, and performing smooth boolean operations like union.

```APIDOC
## `sdf.sphere(radius: number): SdfShape`

### Description
Create an SDF sphere centered at the origin.

## `sdf.box(x: number, y: number, z: number): SdfShape`

### Description
Create an SDF box centered at the origin with given full dimensions (not half-extents).

## `sdf.smoothUnion(a: SdfShape, b: SdfShape, options: { radius: number; }): SdfShape`

### Description
Smooth union — blends shapes together with a smooth transition radius.

### Example Usage
```javascript
return sdf.smoothUnion(sdf.sphere(10), sdf.box(15, 15, 15), { radius: 3 }).color('#4488cc');
```
```

--------------------------------

### Activate Pro License

Source: https://forgecad.io/docs/cli

Activate the Pro license for advanced exports and rendering.

```bash
forgecad license activate
```

--------------------------------

### edge()

Source: https://forgecad.io/docs/core

Gets a named topology edge. This method is only available on shapes with tracked topology (e.g., from box, cylinder, extrude).

```APIDOC
## edge()

### Description
Get a named topology edge. Only available on shapes with tracked topology (from box/cylinder/extrude).

### Method Signature
```
edge(name: string): EdgeRef
```

### Parameters
`name` (string) - The name of the edge to retrieve.

### Request Example
```javascript
const edgeRef = shape.edge('myEdge');
```
```

--------------------------------

### mock()

Source: https://forgecad.io/docs/concepts

Registers a mock (context) object for visualization and collision checking. Mock objects appear in the viewport and spatial analysis when you run a file directly, but are excluded when the file is imported via `require()`. This lets you model the surrounding context — walls, bolts, mating parts — without polluting the module's exports.

```APIDOC
## mock()

### Description
Register a mock (context) object for visualization and collision checking. Mock objects appear in the viewport and spatial analysis when you run a file directly, but are excluded when the file is imported via `require()`. This lets you model the surrounding context — walls, bolts, mating parts — without polluting the module's exports.
The shape is returned unchanged, so you can reference it for alignment, dimensioning, and `verify` checks.
Mock objects participate in `forgecad run` collision detection and spatial analysis. Their names appear with a `(mock)` suffix in reports.
In the viewport, mock objects render at reduced opacity so they are visually distinct from real geometry.

### Method
`mock<T extends Shape>(shape: T, name?: string): T`

### Parameters
- **shape** (T) - Required - The shape to be mocked.
- **name** (string) - Optional - The name of the mock object.

### Request Example
```javascript
// bracket.forge.js
const wall = mock(box(100, 200, 5).translate(0, 0, -5), "wall");
const bolt = mock(cylinder(3, 15).translate(10, 15, 0), "bolt");

const bracket = box(20, 30, 5);
verify.notColliding("bracket vs wall", bracket, wall);

return bracket;
// When imported: only bracket is exported
// When run directly: bracket + wall + bolt all visible
```
```

--------------------------------

### Get Number of Vertices with numVert()

Source: https://forgecad.io/docs/sketch

Return the number of vertices in the polygon representation of the sketch contours using the `numVert()` method.

```typescript
numVert(): number
```

--------------------------------

### Get Diagnostics for Product Skin

Source: https://forgecad.io/docs/curves

Returns the lowering representation, station names, rail names, and any warnings associated with the ProductSkin.

```typescript
diagnostics(): ProductSkinDiagnostics
```

--------------------------------

### Check API

Source: https://forgecad.io/docs/cli

Run script API contract invariants.

```bash
check api
```