forgecad 0.9.2 → 0.9.3

package/dist-skill/docs-dev/generated/viewport.md

@@ -9,7 +9,7 @@ Cut planes, exploded views, joint animations, and scene configuration.
 
 ## Contents
 
-- [Viewport & Runtime](#viewport-runtime) — `scene`, `viewConfig`, `explodeView`, `jointsView`, `cutPlane`, `mock`, `showLabels`, `highlight`
+- [Viewport & Runtime](#viewport-runtime) — `Viewport.label`, `scene`, `viewConfig`, `explodeView`, `jointsView`, `cutPlane`, `mock`, `showLabels`, `highlight`
 - [RouteBuilder](#routebuilder)
 - [route](#route)
 
@@ -17,14 +17,50 @@ Cut planes, exploded views, joint animations, and scene configuration.
 
 ### Viewport & Runtime
 
+#### `Viewport.label()` — Add a render-only viewport label at a world-space point.
+
+`Viewport.label()` is for explanatory text that helps a viewer understand the model. It does not create sketches, meshes, B-rep topology, exported text, or face labels, so it stays off the OCCT path. Use [`text2d()`](/docs/sketch#text2d) only when the letters should become manufactured geometry, such as raised lettering, engraved serial numbers, or exported nameplates.
+
+Labels are collected during script execution and rendered by the viewport as lightweight overlay annotations. They are ignored by exports and do not appear in `objects`.
+
+```js
+Viewport.label('Bearing bore', [0, 0, 18], {
+  color: '#f8fafc',
+  background: '#0f172acc',
+  offset: [0, 0, 8],
+  anchor: 'bottom',
+});
+
+return box(40, 30, 12);
+```
+
+```ts
+Viewport.label(text: string, at: [ number, number, number ], options?: RenderLabelOptions): void
+```
+
+**`RenderLabelOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `color?` | `string` | Text color as any CSS color string. |
+| `background?` | `string` | Background color as any CSS color string. Use `'transparent'` for no pill background. |
+| `size?` | `number` | Font size in CSS pixels. Defaults to 12. |
+| `offset?` | `[ number, number, number ]` | Additional world-space offset from `at`. |
+| `anchor?` | `RenderLabelAnchor` | Which point of the label box is anchored to `at`. Defaults to `'center'`. |
+| `alwaysOnTop?` | `boolean` | When false, the label is hidden when occluded by scene geometry. Defaults to true. |
+
 #### `scene()` — Configure the scene environment for the current script execution.
 
-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.
+Controls camera position, named render views, optional model journeys, 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.
 
+Named render views let scripts check in repeatable cameras next to the model code. The canonical shape is `{ camera: { position, target } }`, and a direct camera shorthand `{ position, target }` is also accepted. Use the canonical shape when you may add view metadata later. Use it from the CLI with `forgecad render 3d model.forge.js --view hero`.
+
+Model journeys let scripts check in a compact guided path through named objects. Each journey has ordered `steps`; each step can name a `focus` target by object name/tree path, provide a caption, and optionally provide an explicit camera. In the viewer, journeys are opt-in: they appear as a small Explore control and do not move the camera until the user starts them. Use `forgecad run model.forge.js --journeys` or `--journeys-json` to inspect resolved targets.
+
 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.
@@ -33,6 +69,22 @@ All numeric values accept `param()` expressions.
 scene({
   background: { top: '#000814', bottom: '#001d3d' },
   camera: { position: [160, -120, 100], target: [0, 0, 50], fov: 52 },
+  views: {
+    hero: {
+      camera: { position: [180, -140, 90], target: [0, 0, 25], up: [0, 0, 1], fov: 38 },
+    },
+    side: { position: [240, 0, 70], target: [0, 0, 25], fov: 34 },
+  },
+  journeys: {
+    grandTour: {
+      title: 'Grand Tour',
+      startsAt: 'overview',
+      steps: [
+        { id: 'overview', focus: 'Solar System', caption: 'Start with the whole model.' },
+        { id: 'earth', focus: 'Earth', caption: 'Fit and inspect Earth.' },
+      ],
+    },
+  },
   lights: [
     { type: 'ambient', color: '#001233', intensity: 0.08 },
     { type: 'point', position: [120, -80, 130], color: '#00f5d4', intensity: 4, distance: 400, decay: 1 },
@@ -59,12 +111,38 @@ scene(options: SceneOptions): void
 | Option | Type | Description |
 |--------|------|-------------|
 | `capture?` | `SceneCaptureConfig` | Default capture parameters for `forgecad capture` — CLI flags override these. |
-| `background?`, `camera?`, `lights?`, `environment?`, `fog?`, `postProcessing?`, `ground?` | | — |
+| `background?`, `camera?`, `views?`, `journeys?`, `lights?`, `environment?`, `fog?`, `postProcessing?`, `ground?` | | — |
 
 `SceneBackgroundGradient`: `{ top: string, bottom: string }`
 
 **`SceneCameraConfig`**: `position?: [ number, number, number ]`, `target?: [ number, number, number ]`, `up?: [ number, number, number ]`, `fov?: number`, `type?: "perspective" | "orthographic"`
 
+**`SceneJourneyConfig`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `title?` | `string` | Viewer-facing journey title. Defaults to the journey id. |
+| `startsAt?` | `string` | Optional starting step id. Defaults to the first step. |
+| `behavior?` | `"opt-in" \| "auto"` | Whether the viewer should offer or auto-open the journey. First slice supports opt-in. |
+| `steps` | `SceneJourneyStepConfig[]` | Ordered journey spine. Branches can be added later without changing this core contract. |
+| `valid?` | `boolean` | True unless any journey or step diagnostic has level "error". |
+| `diagnostics?` | `SceneJourneyDiagnostic[]` | Whole-journey diagnostics, including unresolved startsAt and step target diagnostics. |
+
+**`SceneJourneyStepConfig`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `id` | `string` | Stable step id used by viewer links and Next/Back state. |
+| `title?` | `string` | Viewer-facing title. Defaults to the step id. |
+| `focus?` | `string` | Object name or slash-separated tree path to focus. |
+| `caption?` | `string` | Short optional viewer caption. |
+| `camera?` | `SceneViewCameraConfig` | Optional explicit camera for this step. When omitted, the viewer fits `focus`. |
+| `resolvedFocusId?` | `string \| null` | Resolved object id after script execution, when `focus` matched exactly one object. |
+| `resolvedFocusPath?` | `string \| null` | Resolved object tree path or name after script execution. |
+| `diagnostics?` | `SceneJourneyDiagnostic[]` | Resolution diagnostics for this step. |
+
+`SceneJourneyDiagnostic`: `{ level: SceneJourneyDiagnosticLevel, message: string, stepId?: string, suggestions?: string[] }`
+
 **`SceneLightConfig`**
 
 | Option | Type | Description |

package/dist-skill/library/README.md

@@ -11,7 +11,6 @@ The installed skill names are namespaced to avoid collisions with a user's exist
 - `forgecad-api-dogfood`
 - `forgecad-blockout-model`
 - `forgecad-component-model`
-- `forgecad-deep-dive`
 - `forgecad-high-level-spec`
 - `forgecad-image-replicator`
 - `forgecad-lld`

package/dist-skill/library/forgecad-image-replicator/SKILL.md

@@ -54,7 +54,7 @@ Reference matching is a validation step after the object exists.
    - validation views and inspection channels
 
 4. Choose the modeling structure.
-   Use a multi-file `main.forge.js` project when the object has distinct parts, repeated feature families, internals, purchased hardware, variants, or meaningful manufacturing assumptions. Keep dimensions, materials, part builders, hardware ghosts, and assembly helpers in neighboring plain `.js` files.
+   Use a multi-file `main.forge.js` project when the object has distinct parts, repeated feature families, internals, purchased hardware, variants, or meaningful manufacturing assumptions. Put renderable/importable parts and sub-assemblies in neighboring `.forge.js` files; keep only pure dimensions, materials, math helpers, and lookup tables in plain `.js` files.
 
 5. Build a coarse 3D blockout.
    Model the object, not the image. Start with the large volumes, axes, symmetry, side depth, rear form, underside, and hidden continuations. Render canonical views before doing reference-camera comparison.

package/dist-skill/library/forgecad-make-a-model/SKILL.md

@@ -15,7 +15,8 @@ All new `.forge.js` files go under the date-based directory structure:
 ```
 YYYY/MM/DD/file.forge.js          — single-file model
 YYYY/MM/DD/folder/main.forge.js   — multi-file project entry point
-YYYY/MM/DD/folder/*.js            — shared helpers, constants, parts, assemblies
+YYYY/MM/DD/folder/parts/*.forge.js — standalone/importable model parts
+YYYY/MM/DD/folder/lib/*.js        — pure helpers/constants only, no geometry return
 ```
 
 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.
@@ -25,8 +26,9 @@ Use today's date for the directory. Use the user's current ForgeCAD project when
 - Use kebab-case for file and folder names: `parametric-lego.forge.js`
 - Use descriptive names that communicate what the model is
 - For any multi-file project, name the runnable ForgeCAD entry point `main.forge.js`
-- If a model needs shared helpers, put them in a subfolder as plain `.js` files (not `.forge.js`)
-- Do not create multiple `.forge.js` files in the same project folder unless they are intentionally separate runnable models
+- Put renderable/importable parts and sub-assemblies in separate `.forge.js` files when splitting is justified; each should be standalone-runnable and importable with `require('./parts/name.forge.js', params)`.
+- Use plain `.js` files only for pure constants, math helpers, tables, or formatting code that does not construct and return ForgeCAD geometry.
+- Do not create multiple `.forge.js` files merely for organization; split only for reusable parts, large self-contained components, or independent sub-assemblies.
 
 ## Workflow
 
@@ -34,12 +36,13 @@ Use today's date for the directory. Use the user's current ForgeCAD project when
 2. Create the directory — `mkdir -p YYYY/MM/DD/[folder]` as needed.
 3. Write the model — create the `.forge.js` file(s) following ForgeCAD conventions:
    - Declare `param()` / `boolParam()` for all tunable dimensions
-   - If the model is split across files, use `main.forge.js` as the only primary `.forge.js` entry point and import helpers/parts from neighboring plain `.js` modules
+   - If the model is split across files, use `main.forge.js` as the primary entry point, import renderable parts from neighboring `.forge.js` files, and keep only pure helpers/constants in plain `.js` modules
    - When there are multiple versions of the same object, expose the version as a choice parameter and render one selected version at a time
    - Use clear variable names
    - Build any implied internal structure as real geometry, even when it will be hidden in the final view
    - Make final mating geometry physically plausible: parts may touch, clear each other, or be boolean-joined, but should not unintentionally pass through each other
    - Return the final geometry (single shape, array, or named objects array)
+   - Avoid expensive global edge treatment on repeated decorative geometry: do not call `fillet(shape, r)` or `chamfer(shape, r)` on every edge of large unioned/repeated parts unless the render/run loop proves it is fast enough. Prefer simpler primitive profiles, lower segment counts, or targeted edge selectors.
 4. Validate — run `forgecad run <file>` to check for errors. For multi-file projects, always validate `main.forge.js`.
 5. Verify geometry — render the result and run `forgecad render inspect` with the relevant channels for the task (see Render-Verify Loop below). For multi-file projects, render and inspect `main.forge.js`.
 
@@ -289,6 +292,32 @@ scene({
 });
 ```
 
+### Named render views
+
+For models that need repeatable review, docs, or hero renders, declare named views inside
+`scene({ views })`. The canonical form wraps each camera in `{ camera: ... }`; direct camera
+shorthand is accepted by the runtime, but the wrapped form is the clearest prompt/example shape.
+
+```js
+scene({
+  camera: { position: [430, -540, 340], target: [0, 30, 125], fov: 38 },
+  views: {
+    hero: {
+      camera: { position: [430, -540, 340], target: [0, 30, 125], up: [0, 0, 1], fov: 38 },
+    },
+    side: {
+      camera: { position: [700, 0, 180], target: [0, 30, 100], up: [0, 0, 1], fov: 32 },
+    },
+  },
+});
+```
+
+Render one later with:
+
+```bash
+forgecad render 3d model.forge.js --view hero
+```
+
 ### Lighting principles
 
 - When `lights` is set, all defaults are replaced, so always include an ambient light or the scene goes black.

package/dist-skill/library/forgecad-prepare-prompt/SKILL.md

@@ -157,7 +157,7 @@ By the end of this skill, there should be:
    - purchased-part boundary
    - validation standard
    - variant-selection policy when multiple versions of the same object are requested
-   - file-organization policy: if the implementation needs multiple files, the runnable ForgeCAD entry point must be `main.forge.js`, with helpers/parts/constants in neighboring plain `.js` modules
+   - file-organization policy: if the implementation needs multiple files, the runnable ForgeCAD entry point must be `main.forge.js`; renderable parts/sub-assemblies belong in neighboring `.forge.js` files, while plain `.js` files are only for pure helpers/constants
    - explicit uncertainty policy
 
 8. Emit one master prompt.

package/dist-skill/library/forgecad-project/SKILL.md

@@ -8,7 +8,7 @@ forgecad-public: true
 
 ## Overview
 
-**forgecad.io** is the primary platform for ForgeCAD projects. The CLI is the main way AI agents interact with it — creating projects, managing files, publishing models, and collaborating. `forgecad studio <project-path> [project-path ...]` / `forgecad dev <project-path> [project-path ...]` run the editor locally for offline work.
+**forgecad.io** is the primary platform for ForgeCAD projects. The CLI is the main way AI agents interact with it — creating projects, managing files, publishing models, and collaborating. `forgecad studio <project-path> [project-path ...]` opens the installed local editor for users; `forgecad dev <project-path> [project-path ...]` is mainly for ForgeCAD source development.
 
 ## Authentication
 

package/dist-skill/library/forgecad-render-inspect/SKILL.md

@@ -38,7 +38,7 @@ Routing:
    Use `/tmp/<model-name>-inspect` by default so generated PNGs do not dirty the repo. Use a project output directory only when the user wants a persistent artifact.
 
 3. Pick the channel set.
-   Use the table below. Prefer small targeted channel sets; the full channel set is expensive and should be reserved for an explicit stress check.
+   Use the table below. Prefer small targeted channel sets; broad stress checks should still list explicit channels.
 
 4. Run the command.
    In the ForgeCAD repo, prefer the built CLI when you want the current checkout:

package/examples/api/conformal-product-ribbon.forge.js

@@ -0,0 +1,77 @@
+/**
+ * Conformal product ribbon: a razor-style handle with a metal insert and
+ * overmold strips that follow the product skin instead of floating as flat bars.
+ */
+
+Product.scenePreset('product');
+
+viewConfig({
+  camera: { position: [78, -180, 88], target: [0, 0, 58], fov: 31 },
+});
+
+const charcoal = Product.materials.mattePlastic('#2b3033');
+const satin = Product.materials.brushedSteel({ color: '#c6c9c9' });
+const rubber = Product.materials.softRubber({ color: '#14191b' });
+
+const handle = Product.skin('asymmetric-razor-handle-skin')
+  .axis('Z')
+  .stations([
+    Product.station('flared-butt').at([0, 0, 0]).superEllipse(18, 13, { exponent: 2.7, segments: 88 }),
+    Product.station('rear-hook').at([-1.5, 0.5, 18]).superEllipse(20, 14.5, { exponent: 3.1, segments: 96 }),
+    Product.station('palm-swell').at([1.2, -0.4, 55]).superEllipse(24, 17.5, { exponent: 3.35, segments: 104 }),
+    Product.station('pinch-waist').at([0.6, 0.2, 86]).superEllipse(16.5, 12.5, { exponent: 2.9, segments: 88 }),
+    Product.station('neck').at([0, 0, 118]).superEllipse(12.5, 9.5, { exponent: 2.5, segments: 80 }),
+  ])
+  .refs({
+    'spine-start': { side: 'bottom', u: 0.5, v: 0.08 },
+    'spine-end': { side: 'bottom', u: 0.5, v: 0.94 },
+  })
+  .material(charcoal)
+  .edgeLength(1.7)
+  .build();
+
+const metalSpine = Product.ribbon('brushed-metal-weight-spine')
+  .on(handle, [handle.ref('spine-start'), handle.ref('spine-end')])
+  .width(6.4)
+  .thickness(0.72)
+  .offset(0.22)
+  .samples(28)
+  .widthSamples(7)
+  .material(satin)
+  .build();
+
+const leftGrip = handle
+  .surface('left')
+  .ribbon('left-conformal-tpe-grip', [
+    { u: 0.3, v: 0.18 },
+    { u: 0.34, v: 0.48 },
+    { u: 0.32, v: 0.78 },
+  ])
+  .width(5.8)
+  .thickness(0.9)
+  .offset(0.75)
+  .samples(24)
+  .widthSamples(5)
+  .material(rubber)
+  .build();
+
+const rightGripFeature = Product.surface(handle, 'right')
+  .ribbon('right-conformal-tpe-grip', [
+    { u: 0.7, v: 0.18 },
+    { u: 0.66, v: 0.48 },
+    { u: 0.68, v: 0.78 },
+  ])
+  .width(5.8)
+  .thickness(0.9)
+  .offset(0.75)
+  .samples(24)
+  .widthSamples(5)
+  .material(rubber)
+  .buildWithDiagnostics();
+
+return group(
+  { name: 'handle-skin', shape: handle.toShape() },
+  { name: 'metal-spine', shape: metalSpine },
+  { name: 'left-grip', shape: leftGrip },
+  { name: 'right-grip', shape: rightGripFeature.shape },
+);

package/examples/api/render-labels.forge.js

@@ -0,0 +1,33 @@
+/**
+ * Viewport.label — viewport-only annotations.
+ *
+ * Use Viewport.label() for explanatory text that should help the viewer understand
+ * the model but should not become manufactured geometry. Use text2d() only for
+ * raised, engraved, cut, or exported text.
+ */
+
+const base = box(70, 40, 6).color('#64748b');
+const tower = cylinder(34, 8).translate(0, 0, 6).color('#38bdf8');
+const arm = box(50, 8, 8).translate(0, 0, 44).color('#f59e0b');
+
+Viewport.label('base plate', [-28, -16, 9], {
+  color: '#f8fafc',
+  background: '#0f172acc',
+  anchor: 'bottom-left',
+});
+
+Viewport.label('non-exported viewport label', [0, 0, 47], {
+  color: '#fde68a',
+  background: '#1f2937dd',
+  size: 14,
+  anchor: 'bottom',
+  offset: [0, 0, 6],
+});
+
+Viewport.label('geometry stays simple', [27, 0, 44], {
+  color: '#d1fae5',
+  background: '#064e3bcc',
+  anchor: 'left',
+});
+
+return { base, tower, arm };

package/examples/api/text2d-basics.forge.js

@@ -1,14 +1,17 @@
 /**
  * text2d — first-class text geometry examples.
  *
- * Demonstrates extruded labels, engraved text, centred text, and combining
- * text with other geometry.
+ * Demonstrates text that becomes real geometry: raised labels, engraved text,
+ * centred badges, and combining text with other solids.
+ *
+ * For explanatory viewport-only labels, use Viewport.label() instead. text2d()
+ * creates sketch geometry and can slow exact/OCCT workflows.
  */
 
 // 1. Simple extruded nameplate ─────────────────────────────────────────────
 const nameplate = text2d('FORGE CAD', { size: 8 }).extrude(1.5);
 
-// 2. Centred label (useful for annotations, badges, etc.) ──────────────────
+// 2. Centred badge text as physical geometry ────────────────────────────────
 const badge = text2d('V 2.0', {
   size: 5,
   align: 'center',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgecad",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "Code-first parametric CAD for JavaScript/TypeScript, in the browser and CLI.",
   "license": "BUSL-1.1",
   "type": "module",

package/dist-skill/library/forgecad-deep-dive/SKILL.md

@@ -1,120 +0,0 @@
----
-name: forgecad-deep-dive
-description: Create a linked folder of concept one-pagers that deconstruct a ForgeCAD idea, architecture area, scientific concept, competitor capability, or future feature into a recursive concept tree. Use when the user wants a deep dive, concept book, walkthrough folder, architecture explainer, state-of-the-art analysis, or future-facing capability teardown saved under docs/temporary/projects/ or in Obsidian.
-forgecad-public: true
-forgecad-docs: false
----
-
-# ForgeCAD Deep Dive
-
-Create a durable deep-dive folder that helps a reader internalize one idea by walking from the thesis down to its irreducible concepts.
-
-This skill is for understanding, not for shipping code directly. The deliverable is a linked set of notes that makes one concept feel obvious after reading, especially when the topic spans architecture, geometry, science, manufacturing, or competitor workflows.
-
-## Distinct Intent
-
-- Use this skill when the user wants a multi-page concept tree, not a single page.
-- If the user only wants one short narrative memo, use `concept-one-pager` instead.
-- If the user wants implementation design without the teaching artifact, use `forgecad-high-level-spec` or `design-doc`.
-- If the user wants brainstorming or pushback before writing, use `nonaction` or `discuss`.
-
-## Output Contract
-
-1. Choose the artifact location.
-   Default to `docs/temporary/projects/YYYY/MM/DD/<slug>/`.
-   Only write into Obsidian when the user explicitly asks for it or provides a vault path.
-2. Create `INDEX.md`.
-   Start with a short thesis paragraph, then show the concept tree and suggested reading order.
-3. Create a linked set of concept notes.
-   The usual range is 5-12 notes.
-   Each note should cover one pure concept and link to its parent and children.
-4. Keep each note narrative-first.
-   The main body should read like a concept one-pager.
-   Put examples, sources, code references, and neighboring-note links in an appendix.
-5. Add `appendix/sources.md`.
-   Use primary sources whenever possible.
-   If a claim is inferred from public evidence rather than explicitly stated, label it as an inference.
-6. When the topic touches ForgeCAD, add `appendix/forgecad-code-map.md` or an equivalent file that maps the concept back to concrete repo files, current limitations, and leverage points.
-
-Before drafting, read [references/output-shape.md](references/output-shape.md).
-
-## Workflow
-
-1. Frame the root question.
-   State what the user is actually trying to understand and why it matters.
-2. Find the central thesis.
-   The entire folder should orbit one claim, not a bag of notes.
-3. Decompose the thesis into a concept tree.
-   Start with 3-6 first-order concepts.
-   Recurse only where a child concept is still too impure or overloaded.
-4. Gather evidence from both sides of the problem.
-   For ForgeCAD topics, read the relevant local code and docs.
-   For competitor or industry topics, verify temporally unstable claims on the internet and prefer official docs, product pages, release notes, standards, or research papers.
-5. Draft the notes from top to bottom.
-   Write the root thesis first, then the foundational notes, then the downstream implications.
-6. Link the notes.
-   The reader should always know what concept a note depends on and where to go next.
-7. Close with implications.
-   If the topic is external or competitive, end with what ForgeCAD should learn, copy, reject, or build.
-
-## Writing Rules
-
-- One concept per note.
-- The main body should be mostly paragraphs, not bullets.
-- Explain the plain-language version before introducing specialized vocabulary.
-- Keep the note short enough that a motivated reader can finish it in one sitting.
-- Avoid changelog language. The goal is understanding, not event reporting.
-- If you include comparisons, separate direct evidence from your inference.
-- Be explicit about uncertainty when public material is incomplete.
-
-## Quality Bar
-
-A good deep dive leaves the reader with:
-
-- a clear root thesis,
-- a believable decomposition into smaller ideas,
-- a sense of what is proven versus inferred,
-- a practical bridge back to ForgeCAD,
-- and a folder they can revisit later without needing the original conversation.
-
-If the folder reads like notes from a research sprint instead of a teachable walkthrough, rewrite it.
-
-## Common Patterns
-
-- Competitor teardown:
-  Explain the public model, the likely internal architecture, the user-visible constraints, and the implications for ForgeCAD.
-- Future feature deep dive:
-  Explain what the feature is, what abstractions it needs, what the hard parts really are, and what a staged roadmap should look like.
-- Science concept deep dive:
-  Isolate the math or geometry concepts until each note has one job.
-- Repo architecture deep dive:
-  Tie every major concept back to the current codebase and make the missing abstractions obvious.
-
-## Deliverable Shape
-
-Use a shape like this unless the topic strongly suggests a different tree:
-
-```text
-<slug>/
-├── INDEX.md
-├── 00-thesis.md
-├── 10-<cluster>/
-│   ├── 11-<concept>.md
-│   └── 12-<concept>.md
-├── 20-<cluster>/
-│   └── ...
-└── appendix/
-    ├── sources.md
-    └── forgecad-code-map.md
-```
-
-Use numbered prefixes so the notes are readable both as a graph and as a linear path.
-
-## Final Check
-
-Ask these questions before you stop:
-
-- Would a new teammate understand the idea from the folder alone?
-- Did I split overloaded notes into purer concepts?
-- Are the most important public claims verified and dated where needed?
-- Does the folder make a concrete difference to ForgeCAD, not just summarize a competitor?

package/dist-skill/library/forgecad-deep-dive/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "ForgeCAD Deep Dive"
-  short_description: "Build linked concept deep dives"
-  default_prompt: "Use $forgecad-deep-dive to create a linked folder of one-pagers that deconstruct a ForgeCAD concept, architecture area, or future capability."

package/dist-skill/library/forgecad-deep-dive/references/output-shape.md

@@ -1,64 +0,0 @@
-# Output Shape
-
-Use this reference before drafting the deep-dive folder.
-
-## Folder skeleton
-
-```text
-docs/temporary/projects/YYYY/MM/DD/<slug>/
-├── INDEX.md
-├── 00-thesis.md
-├── 10-<cluster>/
-│   ├── 11-<concept>.md
-│   └── 12-<concept>.md
-├── 20-<cluster>/
-│   └── ...
-└── appendix/
-    ├── sources.md
-    └── forgecad-code-map.md
-```
-
-## INDEX.md
-
-`INDEX.md` is the navigation surface, not just a title page.
-
-Include:
-
-- one short thesis paragraph,
-- the concept tree,
-- one or two recommended reading paths,
-- links to the appendix files,
-- a short note on source posture if the topic mixes verified facts and inference.
-
-## Concept note template
-
-Use this template for each concept page:
-
-```markdown
-# <Concept Title>
-
-<A few clean paragraphs that explain one concept from first principles.>
-
-## Appendix
-
-- Parent: <link or none>
-- Children: <links>
-- ForgeCAD anchors: <repo files, docs, or APIs>
-- Primary sources: <URLs or local artifacts>
-- Inference notes: <what was inferred rather than directly stated>
-```
-
-## Writing standard
-
-- Keep the main body narrative-first.
-- Do not let the appendix become larger than the explanation.
-- Prefer a few high-signal sources over a noisy dump.
-- Use concrete product or code examples only when they clarify the concept.
-- End external analyses with a concrete implication for ForgeCAD.
-
-## What to avoid
-
-- Changelog summaries.
-- A giant report pasted into one file.
-- Notes that each cover three or four ideas at once.
-- Hiding uncertainty. If a conclusion is inferred, say so.