forgecad 0.9.14 → 0.9.16

package/dist-skill/docs-dev/guides/modeling-recipes.md

@@ -1,78 +0,0 @@
----
-skill-group: recipes
-skill-order: 1
----
-
-# Modeling Recipes
-
-## Iteration Bias
-
-- Default to a buildable first pass instead of a long proposal.
-- Replace a broken model wholesale when that is faster than incremental patching.
-- Validate early with `forgecad run <file>`.
-
-## Common Patterns
-
-### Hollow Shell
-```javascript
-const innerSize = outer - 2 * wall;
-const outerBox = box(outer, outer, outer).placeReference('center', [0, 0, 0]);
-const innerBox = box(innerSize, innerSize, innerSize).placeReference('center', [0, 0, 0]);
-return outerBox.subtract(innerBox);
-```
-
-### Sketch-Based Twist
-```javascript
-const outer = ngon(sides, radius);
-const inner = ngon(sides, radius - wall);
-return outer.subtract(inner).extrude(height, { twist: 45, divisions: 32 });
-```
-
-### Rounded Profiles
-```javascript
-// All convex corners — offset trick
-const base = rect(50, 30).offset(-3, 'Round').offset(3, 'Round');
-
-// Selected corners only
-const roof = filletCorners(roofPoints, [
-  { index: 3, radius: 19 },
-  { index: 4, radius: 19 },
-  { index: 5, radius: 19 },
-]);
-```
-
-### Choosing the right sketch-rounding tool
-
-- `offset(-r).offset(+r)` — round every convex corner of a closed outline
-- `stroke(points, width, 'Round')` — centerline-based geometry (ribs, traces)
-- `filletCorners(points, ...)` — selective true-corner fillets on mixed profiles
-
-## Best Practices
-
-- All dimensions in millimeters; angles in degrees.
-- Primitives are centered on XY, base at Z=0. Use `placeReference('center', [0,0,0])` to center on all axes.
-- Prefer named intermediate values over deeply nested one-liners.
-- `union2d`, `difference2d`, `intersection2d` batch faster than chained `.add()` / `.subtract()`.
-
-## Debugging
-
-```javascript
-console.log("Volume:", shape.volume());
-```
-
-For sketch-heavy work, compare the raw profile and rounded profile side-by-side before extruding:
-
-```javascript
-return [
-  { name: "Raw", sketch: polygon(roofPoints) },
-  { name: "Rounded", sketch: filletCorners(roofPoints, [...]).translate(120, 0) },
-];
-```
-
-## Common Errors
-
-- `"Kernel not initialized"` — internal/runtime issue, reload the app
-- zero dimensions or self-intersecting sketches → invalid geometry
-- wrong variable name → `"Cannot read property of undefined"`
-
-For deeper API coverage, load the relevant generated doc group from the skill source map instead of reaching for repo examples by default.

package/dist-skill/docs-dev/guides/positioning.md

@@ -1,161 +0,0 @@
----
-skill-group: geometry
-skill-order: 3
----
-
-# Positioning Strategy
-
-## Rule 0: if parts should touch, use connectors first
-
-For any fixed assembly where parts are meant to stay in contact in the final model, start with connectors + `matchTo()`. This applies to furniture, fixtures, toys, enclosures, sleds, and any other static multi-part object, not only mechanisms.
-
-Use raw `translate()` and `rotate()` when parts are intentionally free-floating or when you are doing quick exploratory layout. Use `attachTo()` for rough bounding-box placement. But if the relationship is a real interface, make it explicit with connectors.
-
-## Primitive origin convention
-
-All 3D primitives are **centered on XY, base at Z=0**:
-
-| Primitive | X range | Y range | Z range |
-|-----------|---------|---------|---------|
-| `box(60, 40, 20)` | [-30, 30] | [-20, 20] | [0, 20] |
-| `cylinder(50, 10)` | [-10, 10] | [-10, 10] | [0, 50] |
-| `sphere(15)` | [-15, 15] | [-15, 15] | [-15, 15] |
-| `torus(20, 5)` | [-25, 25] | [-25, 25] | [-5, 5] |
-
-Sphere and torus are fully centered (symmetric in Z). Box and cylinder sit on the XY ground plane — **Z goes up from zero, never negative**.
-
-This means `box(w, d, h).translate(0, 0, -h / 2)` is the manual way to "center on Z" — it moves the box from `[0, h]` to `[-h / 2, h / 2]`. Prefer `box(w, d, h).placeReference('center', [0, 0, 0])` when you want full XYZ centering.
-
-Do not assume `center: true` or a positional `true` gives OpenSCAD-style full XYZ centering. Primitive placement is fixed unless the primitive docs explicitly say otherwise.
-
----
-
-Most positioning bugs come from manual coordinate arithmetic. Use these methods in priority order.
-
-## 1. Connectors + `matchTo()` — default for mating interfaces
-
-Define connectors on parts; `matchTo()` provides automatic 6-DOF alignment. The child translates and rotates so its connector aligns with the target's — origins coincide, axes oppose (plug-in model).
-
-```javascript
-const shelf = box(200, 120, 10).translate(0, 0, -5).withConnectors({
-  left_tab: connector.male("dovetail", { origin: [-100, 0, 0], axis: [-1, 0, 0] }),
-});
-const panel = box(12, 120, 200).translate(0, 0, -100).withConnectors({
-  shelf_0: connector.female("dovetail", { origin: [6, 0, -50], axis: [1, 0, 0] }),
-});
-const placed = shelf.matchTo(panel, "left_tab", "shelf_0");
-// Dictionary form for multiple pairs on same target:
-const placed2 = shelf.matchTo(panel, { left_tab: "shelf_0" });
-// Named group children bubble connectors via dotted paths:
-const cabinet = group({ name: "Left", shape: panel });
-shelf.matchTo(cabinet, "left_tab", "Left.shelf_0");
-```
-
-**Why connectors first:** stable (don't shift on fillet/chamfer/boolean), semantic (carry type/gender), oriented (full frame), queryable (`shape.connectorDistance('a','b')`), explode-aware.
-
-For a non-mechanism fixed-assembly example, see `examples/api/static-assembly-connectors.forge.js`.
-
-## 2. `group()` — local coordinates for multi-part assemblies
-
-The most common positioning bug: manually adding a parent's global offset to every sub-part. One wrong sign or forgotten variable and parts float into space. **Use `group()` to build parts in local coordinates (at the origin), then position the group once.**
-
-```javascript
-// BAD — every sub-part repeats the parent's global position
-const unitY = -18, unitZ = 70;
-const body = lib.roundedBox(100, 20, 32, 4).translate(0, unitY, unitZ);
-const panel = box(98, 2, 18).translate(0, unitY - 12, unitZ + 4);
-const louver = box(88, 2, 6).translate(0, unitY - 14, unitZ - 11);
-const led = sphere(1.2).translate(35, unitY - 12, unitZ + 9);
-
-// GOOD — build at local origin, group, translate once
-const body = lib.roundedBox(100, 20, 32, 4);
-const panel = box(98, 2, 18).translate(0, -12, 4);        // relative to local origin
-const louver = box(88, 2, 6).translate(0, -14, -11);      // relative to local origin
-const led = sphere(1.2).translate(35, -12, 9);             // relative to local origin
-const indoorUnit = group(
-  { name: 'Body', shape: body },
-  { name: 'Panel', shape: panel },
-  { name: 'Louver', shape: louver },
-  { name: 'LED', shape: led },
-).translate(0, -18, 70);  // ONE translate for the whole assembly
-```
-
-**Groups nest.** Build sub-assemblies as groups, then group those into larger assemblies — each level has its own local origin.
-
-```javascript
-const fan = group(hub, ...blades).translate(0, 25, 0);  // fan assembly
-const outdoorUnit = group(
-  { name: 'Body', shape: casing },
-  { name: 'Fan', shape: fan },             // already a group
-  { name: 'Grille', shape: grille },
-).translate(0, 23, -42);                    // position the whole outdoor unit
-```
-
-**When to use something else:** `group()` preserves individual shapes — you can't boolean (subtract/intersect) a group. If a sub-part needs a boolean with the parent body, do that boolean first in local coordinates, then group the result.
-
-## 3. `pointAlong()` — orient cylinders before positioning
-
-```javascript
-// BAD
-const pipe = cylinder(100, 5).rotateX(90).translate(x, y, z);
-// GOOD — reads as "pipe pointing along Y"
-const pipe = cylinder(100, 5).pointAlong([0, 1, 0]).translate(x, y, z);
-```
-
-**Always call `pointAlong()` BEFORE `matchTo()` or `translate()`** — it reorients around the origin.
-
-## 4. `attachTo()` — quick bounding-box positioning
-
-```javascript
-const column = cylinder(50, 8).attachTo(base, 'top', 'bottom');
-```
-
-`child.attachTo(parent, parentAnchor, selfAnchor, offset)`. Anchor points shift on fillet/chamfer/boolean — fragile for assembly interfaces, fine for quick prototyping.
-
-## 5. `rotateAroundTo()` — aim a point around a hinge/axis
-
-```javascript
-const aimed = arm.rotateAroundTo([0, 0, 1], [0, 0, 0], "tip", [30, 30, 20]);
-// Exact line solve:
-const lineHit = arm.rotateAroundTo([0, 0, 1], [0, 0, 0], "tip", [30, 30, 0], { mode: 'line' });
-```
-
-## 6. `moveToLocal()` — offset from another shape's min corner
-
-```javascript
-const part = box(20, 20, 30).moveToLocal(base, 10, 10, 10);
-```
-
-## 7. `translate()` — for simple offsets or bridging computed locations
-
-```javascript
-const pipeLen = bb2.min[1] - bb1.max[1];
-const pipe = cylinder(pipeLen, 5).pointAlong([0, 1, 0]).translate(40, (bb1.max[1] + bb2.min[1]) / 2, bb1.min[2] + 15);
-```
-
-## 8. `placeReference()` — align any anchor to a world coordinate
-
-Place a shape so a named anchor point lands exactly where you want it. Accepts all built-in anchors (`'bottom'`, `'center'`, `'top-front-left'`, etc.) plus custom references from `withReferences()`.
-
-```javascript
-// Ground a shape — bottom face center at Z = 0
-const grounded = shape.placeReference('bottom', [0, 0, 0])
-
-// Center at the world origin
-const centered = shape.placeReference('center', [0, 0, 0])
-
-// Align left edge to X = 10
-const aligned = shape.placeReference('left', [10, 0, 0])
-```
-
-Also works with custom placement references for cross-file parts:
-
-```javascript
-// widget.forge.js — define once
-return union(base, post).withReferences({ points: { mount: [0, -16, -4] } });
-
-// importer — consume
-const widget = require("./widget.forge.js").placeReference("mount", [120, 40, 0]);
-```
-
-For cross-file parts needing proper alignment, prefer connectors over placement references.

package/dist-skill/docs-dev/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-skill/docs-dev/internals/backend-vocabulary.md

@@ -1,35 +0,0 @@
----
-skill-group: dev-compiler
-skill-order: 0
----
-
-# Backend Vocabulary
-
-Use Forge terms first. Mention concrete backend implementations only at real implementation boundaries.
-
-## Canonical Terms
-
-- **Forge semantic intent**: the meaning of a modeling operation in Forge terms.
-- **Compile plan**: the serializable Forge IR that preserves that intent for later lowering.
-- **Backend**: a geometry engine with its own strengths, limits, and implementation details.
-- **Capability**: something a backend can or cannot do for a given flow.
-- **Route**: the centralized decision about which backend path or fallback a scene/object will use.
-- **Implementation boundary**: the narrow place where a concrete backend or adapter is named directly.
-
-## Naming Rules
-
-- In shared IR, scene routing, and contributor docs, prefer Forge terms such as `compile plan`, `backend`, `capability`, and `route`.
-- Use backend names like `manifold` or `occt` only when the code or doc is truly about that implementation boundary.
-- Use `CadQuery` only when discussing the current Python export executor or other real CadQuery-specific behavior.
-- Use `BREP` and `STEP` for file formats and interchange behavior, not as the primary architecture names for shared compiler layers.
-- Avoid `exact` as a substitute for backend identity. If the real concern is capability, say which capability is required or missing.
-
-## Practical Test
-
-When naming a shared type or document section, ask:
-
-1. Is this describing Forge's meaning?
-2. Is this describing a backend capability?
-3. Or is this describing one backend implementation detail?
-
-If the answer is 1 or 2, do not name it after a historical implementation.