forgecad 0.9.16 → 0.10.1

package/dist/docs-raw/simulation-workflow.md

@@ -0,0 +1,273 @@
+# Simulation Workflow
+
+ForgeCAD should make a robot or simulated asset runnable without making the CAD API own the control algorithm.
+
+The source `.forge.js` model owns geometry, assembly structure, physical metadata, joints, drive intent, contact hints, and the neutral simulation contract. Exported packages then generate an editable simulator lab with all names and wiring connected. Rewards, policies, perturbation tests, curriculum, and RL libraries stay in simulator-side code.
+
+## Current Path: ForgeCAD To MuJoCo
+
+1. Source-author the model as an assembly with `withSimulation(...)`.
+2. Put physical metadata on every part with `Sim.body(...)`.
+3. Put motor intent on joints with `Sim.drive.velocity(...)` or passive dynamics with `Sim.drive.passive(...)`.
+4. Add high-level controller metadata such as `Sim.controller.diffDrive(...)` when the assembly has a standard command interface.
+5. Run the offline gate:
+
+```bash
+node dist-cli/forgecad.js check simready examples/robotics/scout-cam-rover-simready/main.forge.js
+```
+
+6. Export the MuJoCo package:
+
+```bash
+node dist-cli/forgecad.js export mjcf examples/robotics/scout-cam-rover-simready/main.forge.js --output /tmp/scout-cam-rover-mjcf
+```
+
+The generated package contains:
+
+- `scene.xml`: a runnable MuJoCo scene with floor, light, and render settings.
+- `manifest.json`: ForgeCAD-to-MJCF names for links, joints, actuators, generated scripts, and suggested commands.
+- `simready-manifest.json`: neutral simulation contract and validation results.
+- `scripts/gym_env.py`: Gymnasium-compatible MuJoCo env helpers.
+- `scripts/policy_runtime.py`: shared policy loader for ForgeCAD JSON and Stable-Baselines3 zip policies.
+- `scripts/smoke_control.py`: basic actuator smoke test and GIF renderer.
+- `scripts/train_balance.py`: small editable balance trainer.
+- `scripts/play_balance.py`: policy playback with optional external force and torque pulses.
+- `scripts/train_sb3.py`: Stable-Baselines3 PPO/SAC training starter.
+- `scripts/live_policy_viewer.py`: live MuJoCo passive-viewer policy runner.
+
+## What The Generated Gym Env Does
+
+`scripts/gym_env.py` is the bridge between the exported CAD package and control code.
+
+It loads the package manifests, compiles `scene.xml`, discovers actuator IDs, identifies the simulation root body, and calibrates diff-drive signs from MuJoCo joint axes. This matters because mirrored wheel axes can make a naive same-sign left/right command spin or drift instead of moving forward.
+
+The balance environment exposes a compact observation:
+
+- tilt around the wheel axle
+- side tilt
+- angular velocity
+- uprightness
+- root height
+- longitudinal velocity
+- wheel velocities
+- previous forward command
+
+The semantic action is:
+
+- `semanticForward`
+- `semanticTurn`
+
+The env converts those semantic actions into calibrated actuator commands.
+
+## Training The Starter Balance Policy
+
+The generated trainer intentionally avoids heavy RL machinery.
+
+```bash
+cd /tmp/scout-cam-rover-mjcf
+uv run --python 3.11 --with mujoco --with numpy --with gymnasium --with pillow python scripts/train_balance.py --render-gif balance.gif --fps 10
+```
+
+It trains a linear policy:
+
+```text
+observation -> weighted sum -> tanh -> motor command
+```
+
+The optimizer is cross-entropy method:
+
+1. Try many random weight sets.
+2. Simulate each candidate.
+3. Score survival, uprightness, angular rate, and command cost.
+4. Keep the best candidates.
+5. Sample the next generation around those.
+
+This is not deep RL. It is a fast, inspectable starter controller. The right next steps for serious RL are PPO/SAC/PufferLib/MJX/Isaac Lab integrations that reuse the generated env or manifests.
+
+## Serious RL Workflow
+
+For a real reinforcement-learning run, treat the generated MJCF package as the simulator adapter and replace `train_balance.py` with the training stack you actually want. ForgeCAD's job is to produce a valid robot model, named actuators, controller metadata, and a Gymnasium-style environment scaffold; the RL project owns the policy class, reward, curriculum, vectorization, checkpointing, and evaluation harness.
+
+The usual loop is:
+
+1. Load `scene.xml` with MuJoCo.
+2. Load `manifest.json` and `simready-manifest.json` to map ForgeCAD names to MuJoCo bodies, joints, and actuators.
+3. Build observations from `mjData`, such as pose, tilt, angular velocity, wheel velocity, sensors, previous command, and task-specific state.
+4. Let the policy choose an action.
+5. Convert semantic actions, such as `[forward, turn]`, into actuator controls.
+6. Write controls into `mjData.ctrl`, then call `mj_step`.
+7. Compute reward, termination, truncation, and diagnostics.
+8. Let PPO, SAC, PufferLib, MJX, Isaac Lab, or another trainer update the policy.
+9. Save checkpoints and evaluate them with deterministic playback, randomized starts, friction/mass perturbations, and force-push tests.
+
+For the Scout Cam Rover balance example, the first serious action space should usually stay semantic:
+
+```text
+action = [semanticForward, semanticTurn]
+```
+
+That keeps the RL task independent from left/right motor sign conventions. The generated environment already calibrates mirrored wheel axes and maps semantic commands to actuator controls. If a later task needs raw motor commands, add that deliberately after the semantic baseline works.
+
+The reward should encode the actual job, not just survival. For a self-balancing rover, a practical first reward includes uprightness, low tilt rate, target velocity or position tracking, bounded control effort, and clear fall termination. Randomize initial tilt, mass, friction, and push disturbances once the baseline can solve the nominal case.
+
+## Training A Stable-Baselines3 Policy
+
+The MJCF package includes an editable SB3 starter that reuses `BalanceEnv` and the generated semantic diff-drive action mapping:
+
+```bash
+cd /tmp/scout-cam-rover-mjcf
+uv run --python 3.11 --with mujoco --with numpy --with gymnasium --with stable-baselines3 --with pillow python scripts/train_sb3.py \
+  --timesteps 50000 \
+  --output policies/sb3_balance_ppo.zip \
+  --render-gif sb3_balance.gif \
+  --fps 10
+```
+
+That command writes `policies/sb3_balance_ppo.zip` plus `policies/sb3_balance_ppo.json`. The JSON sidecar records the algorithm, observation/action shape, drive calibration, and short deterministic evaluation summary. Use `--algo sac` when you want the SAC template instead of PPO.
+
+## Pushing The Trained Policy
+
+After training, run the policy with a force pulse:
+
+```bash
+cd /tmp/scout-cam-rover-mjcf
+uv run --python 3.11 --with mujoco --with numpy --with gymnasium --with pillow python scripts/play_balance.py \
+  --policy policies/balance_linear.json \
+  --push-y 1 \
+  --push-at 2 \
+  --push-duration 0.15 \
+  --render-gif balance_push.gif \
+  --fps 10
+```
+
+`play_balance.py` applies force or torque through MuJoCo's `xfrc_applied` array on the root body. It reports the frame count, approximate GIF duration, push vector, final tilt, and survival time.
+
+Use these options to push from other directions:
+
+```bash
+--push-x 2
+--push-y -4
+--push-z 1
+--torque-x 0.1
+--torque-y -0.1
+--torque-z 0.1
+```
+
+Increase `--push-y` or `--push-x` when you want a failure/stress test instead of a recovery demo.
+
+Stable-Baselines3 zip policies use the same playback path:
+
+```bash
+cd /tmp/scout-cam-rover-mjcf
+uv run --python 3.11 --with mujoco --with numpy --with gymnasium --with stable-baselines3 --with pillow python scripts/play_balance.py \
+  --policy policies/sb3_balance_ppo.zip \
+  --push-y 1 \
+  --push-at 2 \
+  --push-duration 0.15 \
+  --render-gif sb3_balance_push.gif \
+  --fps 10
+```
+
+## MuJoCo App Vs Policy Control
+
+MuJoCo's standalone viewer and MuJoCo.app load models, not trained policies. Open `scene.xml` when you want to inspect the exported robot, geometry, joints, contacts, actuators, and passive dynamics:
+
+```bash
+uv run --python 3.11 --with mujoco python -m mujoco.viewer --mjcf=scene.xml
+```
+
+A trained policy is control code. The official MuJoCo control path is to set controls before stepping the simulator, or to install a control callback. In Python, the common interactive pattern is the passive viewer: the user script owns the loop, computes policy actions, writes `mjData.ctrl`, calls `mj_step`, and then calls `viewer.sync()`. On macOS, passive-viewer scripts should run with `mjpython`, which is installed with the `mujoco` Python package.
+
+Conceptually:
+
+```python
+model = mujoco.MjModel.from_xml_path("scene.xml")
+data = mujoco.MjData(model)
+
+with mujoco.viewer.launch_passive(model, data) as viewer:
+    while viewer.is_running():
+        action = policy(observation_from(data))
+        data.ctrl[:] = action_to_actuator_controls(action)
+        mujoco.mj_step(model, data)
+        viewer.sync()
+```
+
+`scripts/play_balance.py` is the generated scripted playback path. It loads the policy JSON, applies calibrated actuator commands, optionally applies force or torque pulses through `xfrc_applied`, and can render a diagnostic GIF. It is not the same thing as loading the policy into MuJoCo.app.
+
+To run a policy in an interactive window, use the generated passive-viewer script. On macOS, run it through `mjpython`:
+
+```bash
+cd /tmp/scout-cam-rover-mjcf
+uv run --python 3.11 --with mujoco --with numpy --with gymnasium --with stable-baselines3 mjpython scripts/live_policy_viewer.py \
+  --policy policies/sb3_balance_ppo.zip
+```
+
+## GIF Timing
+
+The generated scripts treat GIF duration as:
+
+```text
+duration ~= frame_count / fps
+```
+
+For a 6-second run at 10 FPS, expect about 60 frames. If the GIF is much shorter, the renderer is undersampling frames or the policy terminated early. The summary JSON prints both `frames` and `gifDurationSecondsApprox` for playback scripts.
+
+Keep FPS modest. A 10 FPS diagnostic GIF is usually easier to review, smaller than a 30 FPS one, and maps to a clean 100 ms GIF frame delay in common viewers.
+
+## What Belongs In ForgeCAD
+
+ForgeCAD should own:
+
+- physical metadata on parts
+- colliders and contact intent
+- joints and drive limits
+- named controller metadata
+- simulator package manifests
+- export to URDF, SDF, and MJCF; native USD/USDZ export is future work
+- generated starter envs, smoke tests, trainers, playback, and perturbation scripts
+- offline source-level readiness checks
+
+ForgeCAD should not own:
+
+- a `selfBalancingDiffDrive(...)` API
+- a single blessed RL algorithm
+- task-specific rewards
+- PufferLib-specific or IsaacLab-specific core CAD primitives
+- deployment-specific training infrastructure
+
+The durable product promise is: model once, export a working simulation lab, then swap the control stack freely.
+
+## Isaac Lab Fit
+
+Isaac Lab integration is plausible, but not turnkey in this slice.
+
+The current NVIDIA Isaac Lab docs describe custom robot training as a multi-step flow: import and tune the robot in Isaac Sim, then define the Isaac Lab interface needed to clone the robot, drive joints, and reset state. Their "Adding a New Robot" tutorial names `AssetBaseCfg` as the interface between the USD articulation and learning algorithms. Their asset configuration guide shows `ArticulationCfg` with `UsdFileCfg`, and notes that `UrdfFileCfg` can replace `UsdFileCfg` for URDF-backed articulations.
+
+Relevant docs:
+
+- https://isaac-sim.github.io/IsaacLab/main/source/tutorials/01_assets/add_new_robot.html
+- https://isaac-sim.github.io/IsaacLab/main/source/how-to/write_articulation_cfg.html
+
+ForgeCAD has the information Isaac Lab needs in pieces:
+
+- URDF export for an articulation import path
+- SimReady manifest with root part, joints, drives, materials, contacts, and controller metadata
+- SDF/MJCF packages for fast local physics iteration
+
+ForgeCAD does not currently have a native USD/USDZ export command. For Isaac workflows today, use URDF as the import artifact and carry the richer ForgeCAD simulation intent through `simready-manifest.json`.
+
+The missing ForgeCAD work for a clean Isaac Lab path is:
+
+- direct USD authoring or a generated Isaac Sim URDF import/conversion script
+- generated `ArticulationCfg` scaffold from `simready-manifest.json`
+- actuator config generation from `Sim.drive.*(...)`
+- reset/observation/action scaffolds equivalent to the MuJoCo Gym env
+- coordinate/frame audit for Isaac's stage conventions and imported URDF axes
+- Isaac Sim/Isaac Lab validation on a machine with those tools installed
+
+Until that exists, the recommended path is:
+
+1. Use MuJoCo export for fast local control-loop iteration.
+2. Export URDF for Isaac Sim and keep `simready-manifest.json` beside it.
+3. Generate or hand-write Isaac Lab `ArticulationCfg` and task code from the ForgeCAD manifests.
+4. Validate imported articulation axes, actuators, masses, colliders, and reset behavior in Isaac Lab.

package/dist/docs-raw/skills/forgecad-3d-reconstruction.md

@@ -1,3 +1,5 @@
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-3d-reconstruction/SKILL.md instead. -->
+
 # forgecad-3d-reconstruction
 
 Reconstruct a parametric ForgeCAD model from an existing 3D CAD or mesh file such as STL, OBJ, 3MF, STEP, or STP; inspect the source asset directly, author real ForgeCAD geometry, and iteratively compare the candidate with `forgecad compare 3d`.
@@ -11,132 +13,44 @@ Reconstruct a parametric ForgeCAD model from an existing 3D CAD or mesh file suc
 
 ## ForgeCAD 3D Reconstruction
 
-Use this skill when the user provides an existing 3D file and wants a ForgeCAD model that recreates it as parametric CAD.
-
-The reference asset is evidence, not the deliverable. The deliverable is a readable `.forge.js` model that runs, renders, inspects, and scores well against the source geometry.
-
-Do not solve reconstruction by returning `importMesh("reference.stl")` or `importStep("reference.step")` as the final model unless the user explicitly asks for an import wrapper. Imported source assets are for measurement, rendering, inspection, and scoring.
+The reference asset is evidence, not the deliverable. The deliverable is a readable, parametric `.forge.js` model that runs, renders, and scores well against the source. Never return `Import.mesh()`/`Import.step()` of the source as the final model unless the user explicitly asks for an import wrapper — imports are for measurement, rendering, and scoring only.
 
-### Companion Skills
+Routing: user wants to KEEP the file as a live component and design around it (bracket, enclosure, mating assembly) → `forgecad-make-a-model` (Imported Parts section), not this skill; benchmark/RL episodes → `forgecad-reconstruction-benchmark`; inspection-bundle interpretation → `forgecad-render-inspect`; independent grading after reconstruction → `forgecad-model-grader`; API and command reference → `forgecad` skill + CLI.md.
 
-- Use `forgecad` for API syntax, direct CAD CLI behavior, and validation commands.
-- Use `forgecad-reconstruction-benchmark` instead when the task is a benchmark
-  or RL episode with a fixed `submission/main.forge.js` output path.
-- Use `forgecad-make-a-model` when creating a normal user-facing `.forge.js`
-  project structure outside the benchmark harness.
-- Use `forgecad-render-inspect` when inspection bundles need interpretation.
-- Use `forgecad-model-grader` only after reconstruction, when the user asks for an independent grade.
+### Workflow
 
-### Required Workflow
-
-1. Stage the reference.
-   Put the source 3D file in a scratch folder such as `/tmp/<slug>-reconstruct/ref/` or keep the user's original path if it is already stable. Preserve the original file.
-
-2. Inspect the source directly.
-   No wrapper script is needed. Use the local checkout CLI:
+1. **Inspect the source directly** — the CLI reads CAD/mesh files as inputs, no wrapper script. Gather four evidence types: `ls --long` stats, an iso render, per-object views, sampled sections (invocations in CLI.md; when sharing a renderer server via `--port`, run renders sequentially).
+2. **3MF**: enumerate every build item before scoring — hidden multi-part structure is a common miss. Item ref syntax: `Import.mesh` docs.
+3. **Reconstruction Brief** before modeling: what must be exact vs. approximate vs. parametric; symmetry, origin, key reference planes; likely manufacturing process; scoring tolerance and alignment policy.
+4. **Blockout first.** Match bbox and main masses, then add features. Model real geometry with blueprint-first APIs — never vertex-chase a faceted copy.
+5. **Compare numerically** — the core loop:
 
    ```bash
-   node dist-cli/forgecad.js ls path/to/source.stl --quality live --long
-   node dist-cli/forgecad.js render 3d path/to/source.stl /tmp/<slug>-source.png --camera iso --edges thin --size 900
-   node dist-cli/forgecad.js inspect visual objects path/to/source.stl /tmp/<slug>-source-objects --camera iso --size 700 --force
-   node dist-cli/forgecad.js inspect sections sample path/to/source.stl /tmp/<slug>-source-sections --count 5 --size 700 --force
-   ```
-
-   For 3MF sources, `forgecad run` prints the source archive's build
-   items/resource objects with stable refs such as
-   `3mf:build:001:object:2`, automatic names, per-item bounding boxes, and
-   triangle counts. Use that item table to avoid missing hidden multi-part
-   structure before scoring the whole shape.
-
-   For STEP/STP files, the CLI auto-selects OCCT unless `--backend` is passed.
-   Run render commands sequentially; starting multiple browser renders at once can make the shared Vite renderer race and time out.
-
-3. Write a Reconstruction Brief.
-   Before modeling, record:
-   - source path and file type
-   - bounding box, volume, triangle count, and apparent units
-   - object identity and likely manufacturing process
-   - major primitive families: boxes, cylinders, plates, revolutions, lofts, sweeps, holes, fillets, ribs, threads, text, freeform surfaces
-   - symmetry, coordinate origin, and key reference planes
-   - what must be exact, what may be approximate, and what should remain parametric
-   - scoring tolerance and alignment policy
-
-4. Build the ForgeCAD candidate.
-   Model the real geometry, not a faceted copy. Start with a blockout that matches bbox and main masses, then add holes, cutouts, transitions, and details. Prefer high-level ForgeCAD APIs and blueprint-first intent over vertex chasing.
-5. Compare the candidate numerically.
-   Use the raw geometry comparison command:
-
-   ```bash
-   node dist-cli/forgecad.js compare 3d path/to/source.stl path/to/candidate.forge.js \
+   forgecad compare 3d path/to/source.stl path/to/candidate.forge.js \
      --samples 3000 --json --output /tmp/<slug>-score.json
    ```
 
-   Start with `--align none`. Use `--align center` only when the source and candidate clearly use different origins but the same scale and orientation. Use `--align center-scale` only for exploratory diagnosis because it can hide dimensional errors.
-
-6. Iterate from coarse to fine.
-   Improve in this order:
-   - bbox size and coordinate placement
-   - main volumes and silhouette
-   - major holes, bosses, ribs, shells, and cutouts
-   - edge treatments and transitions
-   - small details, labels, textures, and decorative features
-
-   Use score metrics as evidence:
-   - low coverage means missing or extra surface area
-   - high RMS means broad proportional mismatch
-   - high p95 or max means localized protrusions, holes, or outliers
-   - bounds delta means size, origin, or scale mismatch
-   - volume delta means mass, shell, cutout, or scale mismatch
-
-7. Validate the final model.
-   Minimum final checks:
-
-   ```bash
-   node dist-cli/forgecad.js run path/to/candidate.forge.js
-   node dist-cli/forgecad.js render 3d path/to/candidate.forge.js /tmp/<slug>-candidate.png --camera iso --edges thin --size 900
-   node dist-cli/forgecad.js compare 3d path/to/source.stl path/to/candidate.forge.js --samples 5000 --json --output /tmp/<slug>-final-score.json
-   node dist-cli/forgecad.js inspect compare overlay path/to/candidate.forge.js /tmp/<slug>-compare --compare-samples 5000 --force --size 700
-   ```
-
-   Add targeted evidence commands such as `inspect fit interference`, `inspect manufacture thickness`, `inspect physical components`, `inspect physical floating`, or `inspect surface zebra` when the object is multi-part, hollow, mechanical, thin-walled, or surface-sensitive.
-
-### Scoring Guidance
-
-`forgecad compare 3d` returns an overall 0-100 raw geometry score plus distance, feature, bounds, and volume metrics. Treat the score as a guide, not a license to make unmaintainable code.
-
-Suggested targets:
-
-- `95+`: excellent reconstruction for simple prismatic or revolved parts
-- `90+`: good target for ordinary mechanical parts with fillets and cutouts
-- `80+`: acceptable rough reconstruction when the source is organic, faceted, or underdetermined
-
-Always report the raw `rms`, `p95`, `max`, coverage, bounds delta, and volume delta. A high score with a large `max` distance can still hide a missing local feature.
-
-For faceted source meshes, decide whether tessellation itself is evidence. If the source is an exported primitive or low-poly mesh, exact triangle/segment matching can raise the numeric score but may reduce parametric clarity. Prefer analytic intent when the user wants a clean CAD reconstruction; match tessellation only when the faceting is part of the artifact or required by the acceptance criteria.
+6. **Iterate coarse to fine**: bbox/placement → main volumes/silhouette → holes/bosses/ribs/shells → edge treatments → small details.
 
-### Subagent Validation
+### Reading the Score
 
-When validating this skill with a subagent, give the subagent only:
+Alignment: start `--align none`. Use `--align center` only when origins clearly differ but scale and orientation match. Use `--align center-scale` only for exploratory diagnosis — it hides dimensional errors.
 
-- the reference file path
-- the desired output folder
-- this skill name
-- the command to use the local CLI: `node dist-cli/forgecad.js`
+| Signal | Diagnosis |
+|---|---|
+| Low coverage | Missing or extra surface |
+| High RMS | Broad proportional mismatch |
+| High p95/max | Localized outlier feature (protrusion, hole) |
+| Bounds delta | Size, origin, or scale mismatch |
+| Volume delta | Mass, shell, cutout, or scale mismatch |
 
-Do not provide your intended modeling strategy, hidden measurements, or expected score. The point is to test whether the skill guides a fresh agent through evidence, modeling, scoring, and iteration.
+Calibration: 95+ simple prismatic/revolved parts, 90+ ordinary mechanical parts with fillets/cutouts, 80+ acceptable for organic, faceted, or underdetermined sources. Always report raw rms, p95, max, coverage, bounds delta, and volume delta — a high overall score with a large max can hide a missing local feature.
 
-### Output Contract
+Faceted sources: decide whether tessellation itself is evidence. Matching low-poly faceting raises the score but reduces parametric clarity — prefer analytic intent unless faceting is part of the artifact or required by the acceptance criteria.
 
-When finished, report:
+### Done Criteria
 
-- source file path
-- candidate `.forge.js` path
-- Reconstruction Brief summary
-- source inspection bundle and renders
-- candidate renders and inspection bundle, if used
-- final `forgecad compare 3d` command and score JSON path
-- final score, RMS, p95, max distance, coverage, bounds delta, and volume delta
-- known mismatches and whether they are intentional simplifications or remaining work
+The final model must run, render, re-compare at `--samples 5000`, and pass an `inspect compare overlay`. Add targeted inspects (`forgecad-render-inspect`) when the object is multi-part, hollow, thin-walled, or surface-sensitive. Report: source and candidate paths, score JSON path, final metrics, and every known mismatch classified as intentional simplification or remaining work.
 
 
 ## Bundled Files

package/dist/docs-raw/skills/forgecad-blockout-model.md

@@ -1,3 +1,5 @@
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-blockout-model/SKILL.md instead. -->
+
 # forgecad-blockout-model
 
 Create rough high-level ForgeCAD concept models from simple primitives to explore layout, proportions, motion, and part relationships without production detail. Use when asked for a quick model sketch, blockout, spatial mockup, or intuitive low-detail 3D concept.
@@ -11,25 +13,7 @@ Create rough high-level ForgeCAD concept models from simple primitives to explor
 
 ## Block Out a Model
 
-Create lightweight ForgeCAD concept models. These are spatial planning artifacts: fast, legible, and intentionally approximate, but still grounded in the physical object rather than an annotated lesson diagram.
-
-### Trigger Boundary
-
-Use this skill when the user wants to answer questions like:
-
-- Roughly where do the parts go?
-- Does this mechanism idea make intuitive spatial sense?
-- What is the silhouette, footprint, or motion envelope?
-- Can we show the concept before spending time on detail?
-
-Do **not** use this skill for:
-
-- print-ready or fabrication-ready geometry
-- exact fit, tight tolerances, or detailed dimensioning
-- dense parametric modeling
-- hardware details, fillets, chamfers, or finish work unless they are essential to the concept
-
-Routing:
+A blockout is a spatial planning artifact: 3-7 simple masses that answer where parts go, whether a mechanism makes spatial sense, and what the silhouette, footprint, or motion envelope looks like. Not for print-ready geometry, exact fit, tolerances, or detail work.
 
 | Need | Skill |
 |------|-------|
@@ -37,110 +21,29 @@ Routing:
 | Written concept or architecture before CAD | `forgecad-high-level-spec` |
 | Accurate, detailed, parametric ForgeCAD model | `forgecad-make-a-model` |
 
-### File Placement
-
-All new `.forge.js` files go under the date-based directory structure:
-
-```text
-YYYY/MM/DD/file.forge.js          - single-file blockout
-YYYY/MM/DD/folder/file.forge.js   - multi-file concept project
-```
-
-Use today's date for the directory. Use the user's current ForgeCAD project when one is available; otherwise use a clearly named local model folder.
-
-#### Naming
-
-- Use kebab-case
-- Prefer names like `desk-lamp-blockout.forge.js` or `hinged-display-concept.forge.js`
-- Add `-blockout` or `-concept` unless the user already supplied a clearer name
-
-### Workflow
-
-1. **Load the `forgecad` skill first** and read the Core API and CLI docs. Only load more documentation if the concept truly needs it.
-2. **Translate the idea into 3-7 conceptual parts** before writing geometry. Think in terms of masses and zones: base, arm, payload, sweep volume, keep-out space, hand access, wheel envelope.
-3. **Choose approximate dimensions** using round numbers and obvious proportions. Favor "believably shaped" over "numerically correct".
-4. **Write the simplest geometry that communicates the idea**. Default to `box()`, `cylinder()`, `sphere()`, and very simple extrusions.
-5. **Place parts with readable transforms**. Keep coordinates easy to inspect and edit. Prefer centered primitives when that reduces mental load.
-6. **Color by meaning** so a viewer can decode the concept immediately.
-7. **Render and inspect** from a few angles. If the idea is still unclear, simplify or reposition; do not add detail as a substitute for clarity.
-8. **Stop early** once the mechanism, layout, or concept is understandable.
+### Method
 
-### Modeling Rules
+- Load the `forgecad` skill first; read its Core API and CLI docs. Load nothing else unless the concept demands it.
+- Translate the idea into 3-7 conceptual parts BEFORE writing geometry: masses and zones (base, arm, payload, sweep volume, keep-out, hand access).
+- One primitive stands in for many eventual details. A bounding box beats a fake detailed part. Never add detail as a substitute for clarity — simplify or reposition instead.
+- Use round-number dimensions; "believably shaped" beats numerically correct. Name uncertainty honestly: `armLengthGuess`, `baseWidthApprox`, `clearanceEnvelope`.
+- At most a handful of `param()` values, for comparing proportions. Do not parameterize every dimension.
+- Color by meaning; keep each conceptual part visually distinct via color or opacity. Return named shape objects so the viewer can inspect the concept part-by-part.
+- Ghost geometry: transparent volumes only for REAL physical envelopes — sweep arcs, keep-out volumes, approximate payloads, reach/access zones. Never decorative teaching overlays. Exaggerate tiny clearances when needed for readability.
+- Even a blockout represents the object in its normal assembled state: no labels, legends, cutaways, or permanently exploded layouts (full rule in the `forgecad` skill).
+- Leave out: fasteners and screw holes, wall thicknesses, fillets and blend radii, polished materials, hidden internal structure that does not affect the concept.
 
-- Use one primitive to stand in for many eventual details whenever possible.
-- A bounding box is usually better than a fake detailed part.
-- Use at most a handful of top-level `param()` values when comparing rough proportions. Do not parameterize every dimension.
-- Name uncertainty honestly: `armLengthGuess`, `baseWidthApprox`, `screenVolume`, `clearanceEnvelope`.
-- Do not add text labels, callout arrows, legends, coordinate labels, or explanatory plaques to the model. Use named return objects and a short written note outside the geometry.
-- Do not cut away a shell, remove covers, or permanently explode parts just to show hidden intent. Even a blockout should represent the object in its normal assembled state unless the user explicitly asks for a presentation view.
-- Use transparent ghost geometry for:
-  - sweep arcs
-  - keep-out volumes
-  - approximate payloads
-  - user reach or access space
-- Ghost geometry must represent a real physical envelope, clearance, motion path, or human-access zone, not decorative teaching overlays.
-- Exaggerate tiny clearances if needed to keep the concept readable.
-- Keep each conceptual part visually distinct through color or opacity.
-- Prefer arrays of named shapes in the return value so the viewer can inspect the concept part-by-part.
+### Verify
 
-### What to Leave Out
-
-Do not spend time on:
-
-- screw holes
-- exact wall thicknesses
-- blend radii
-- polished materials
-- hidden internal structure that does not affect the concept
-- mathematical precision that the concept does not justify
-
-If you notice yourself reaching for detailed constraints, pause and ask whether the blockout should instead hand off to `forgecad-make-a-model`.
-
-### Render-Verify Loop
-
-Even rough models must be rendered. The whole point is spatial intuition.
-
-#### Minimum check
-
-```bash
-forgecad run model.forge.js
-node dist-cli/forgecad.js render model.forge.js /tmp/blockout.png --camera 45:25 --camera 0:0 --camera 90:0 --size 600
-```
-
-Inspect the render and ask:
+Rendering is mandatory even for rough models. Run the script, then render from 2-3 angles with the installed `forgecad` CLI (syntax: the `forgecad` skill's CLI docs). Judge by the reader test:
 
 - Can someone unfamiliar with the idea tell what each mass represents?
-- Are the overall proportions believable enough to discuss?
+- Are proportions believable enough to discuss?
 - Is motion or interference visible where it matters?
-- Are unknowns shown honestly, rather than hidden behind fake detail?
-
-If the answer is no, simplify the model or add clearer ghost volumes.
-
-### Useful Pattern
-
-```js
-// Concept only:
-// - dimensions are approximate
-// - red transparent geometry shows motion / keep-out
-
-const base = box(160, 90, 30).placeReference('center', [0, 0, 0]).color('#4c6ef5');
-const arm = box(22, 22, 180).placeReference('center', [0, 0, 105]).color('#f08c00');
-const payload = box(120, 18, 70).placeReference('center', [0, 0, 210]).color('#2b8a3e');
-
-const sweep = cylinder(12, 110, 110, 48).placeReference('center', [0, 0, 0])
-  .rotateY(90)
-  .translate(0, 0, 120)
-  .color('#e03131')
-  .material({ opacity: 0.18 });
+- Are unknowns shown honestly, not hidden behind fake detail?
 
-return [
-  { name: 'Base', shape: base },
-  { name: 'Arm', shape: arm },
-  { name: 'Payload Volume', shape: payload },
-  { name: 'Sweep Envelope', shape: sweep },
-];
-```
+If any answer is no, simplify or add clearer ghost volumes.
 
-### Handoff Rule
+### Handoff
 
-When the blockout has answered the high-level questions, stop. If the next question is about real fit, tunable dimensions, part details, or manufacturing logic, switch to `forgecad-make-a-model` rather than refining the blockout indefinitely.
+File placement and naming follow `forgecad-make-a-model` conventions; suffix the filename `-blockout` or `-concept` unless the user supplied a clearer name. Once the high-level questions are answered, stop. If the next question is real fit, tunable dimensions, part details, or manufacturing logic, switch to `forgecad-make-a-model` instead of refining the blockout indefinitely.