@coloopx/colocad 0.1.0-alpha.5 → 0.1.0-alpha.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/CHANGELOG.md +44 -0
  2. package/README.md +115 -172
  3. package/README.zh-CN.md +118 -125
  4. package/bin/colocad.mjs +17 -9
  5. package/docs/README.md +10 -3
  6. package/docs/README.zh-CN.md +11 -2
  7. package/docs/agent-modeling-handbook.md +1 -1
  8. package/docs/agent-modeling-handbook.zh-CN.md +2 -2
  9. package/docs/api.md +9 -6
  10. package/docs/engineering-queries.md +122 -0
  11. package/docs/engineering-queries.zh-CN.md +74 -0
  12. package/docs/getting-started.md +1 -1
  13. package/docs/integrations/claude-code.md +1 -1
  14. package/docs/integrations/codex.md +1 -1
  15. package/docs/integrations/pi.md +17 -4
  16. package/docs/integrations/verification.md +7 -1
  17. package/docs/native-solidworks.md +12 -0
  18. package/docs/performance.md +62 -0
  19. package/examples/integrations/README.md +11 -2
  20. package/examples/integrations/compact-tools.mjs +1 -1
  21. package/kernel/dist/client.d.ts +5 -2
  22. package/kernel/dist/client.js +35 -7
  23. package/kernel/dist/generated.d.ts +297 -4
  24. package/kernel/dist/process.d.ts +1 -1
  25. package/kernel/dist/process.js +3 -3
  26. package/kernel/dist/query-generated.d.ts +181 -0
  27. package/kernel/dist/query-generated.js +1 -0
  28. package/kernel/dist/tools.d.ts +35 -0
  29. package/kernel/dist/tools.js +11 -2
  30. package/kernel/dist/types.d.ts +9 -0
  31. package/kernel/native/darwin-arm64/agent-cad +2 -2
  32. package/kernel/native/darwin-arm64/manifest.json +2 -2
  33. package/kernel/native/linux-arm64/agent-cad +2 -2
  34. package/kernel/native/linux-arm64/manifest.json +2 -2
  35. package/kernel/native/linux-x64/agent-cad +2 -2
  36. package/kernel/native/linux-x64/manifest.json +2 -2
  37. package/kernel/release.json +4 -4
  38. package/kernel/schemas/model.schema.json +1752 -135
  39. package/kernel/schemas/query.schema.json +1150 -0
  40. package/package.json +5 -2
  41. package/skills/colocad/references/tool-contracts.md +14 -2
  42. package/src/build.mjs +3 -2
  43. package/src/index.d.mts +2 -1
  44. package/src/session.d.mts +5 -3
  45. package/src/session.mjs +26 -10
  46. package/viewer/dist/index.js +179 -179
  47. package/viewer/dist/standalone.js +179 -179
  48. package/viewer/index.d.ts +2 -1
package/CHANGELOG.md ADDED
@@ -0,0 +1,44 @@
1
+ # Changelog
2
+
3
+ Notable user-facing changes are recorded here. Colocad remains alpha software; supported geometry and measured workloads define each release's scope.
4
+
5
+ ## [0.1.0-alpha.7](https://github.com/Coloopx/colocad/releases/tag/v0.1.0-alpha.7) — 2026-11-09
6
+
7
+ ### Added
8
+
9
+ - Exact, revision-bound B-rep queries through `CadClient.query`, `ModelingSession.query`, `cad_query` and `colocad query`. Reopened or relocated snapshots preserve identity; edits invalidate old observations.
10
+ - Bounded composable topology selection, trim-aware face evaluation, primitive named datums and datum-driven assembly mates with explicit direction and physical residuals.
11
+ - Analytic through/blind/counterbored hole recognition, plane-scoped hole groups, declared/recognized `planar_hole_mount/v1` interfaces, all-hole compatibility checks and geometry-driven external STEP replacement.
12
+ - Explicit part-pair separation, contact, overlap and containment measurements, plus required checks at bounded pose samples. Read-only queries perform no geometry rebuild, STEP export or tessellation.
13
+ - Geometry-reference highlights in recorded CLI/offline review, revision-aware compact agent feedback, capability-gated Pi query tools and updated English/Chinese modeling guidance.
14
+
15
+ ### Fixed
16
+
17
+ - Required disjoint or tangent cuts now fail with `NO_MATERIAL_REMOVED` instead of silently returning unchanged stock.
18
+ - Selection tolerance is validated separately from minimum feature size, permitting the specified `1e-5 mm` query precision.
19
+ - Checkpoint reuse requires a source/compiler/target execution fingerprint, preventing an unchanged development version from restoring geometry made under old feature semantics.
20
+ - The process-interruption regression now resolves the packaged native when no development override is set.
21
+
22
+ ### Verification
23
+
24
+ - G1–G3 accepted in their declared domains: 127 Rust tests, 41 Node tests, six deterministic integration tests, offline browser checks, and all 24 frozen geometry cases (18 positives, six correct rejections).
25
+ - Independent OCCT readback validates significant exact deliveries, including the 82-solid KK60/accessory reconstruction and geometry-driven foreign replacements.
26
+ - Two actual Pi inference tasks run with agent, harness, SDK and native in the same Linux arm64 1 vCPU / 512 MiB cgroup. The product task edits an existing sourced assembly; it does not reconstruct that product from images. Its measured peak is 370.57 MiB with no OOM.
27
+ - Fresh archive installations verify the SDK, CLI, packaged native, query/edit/reopen behavior and foreign mounting replacements on macOS arm64, Linux arm64 and Linux x64. Linux checks run offline at 1 vCPU / 512 MiB; x64 uses emulation.
28
+
29
+ See [G1 evidence](specs/experiments/0004/README.md), [G2/G3 evidence and failures](specs/experiments/0005/README.md), [release archive evidence](docs/evidence/release-alpha.7.json) and the [query guide](docs/engineering-queries.md).
30
+
31
+ ### Compatibility and limits
32
+
33
+ - This is Colocad's JSON/TypeScript API, not a CadQuery Python or API compatibility layer. Existing modeling entry points remain available.
34
+ - Conical, intersecting, side-open and spline-based bore recognition can be partial. Certified allowed contact is bounded to supported opposing planar polyhedral faces; curved-contact certification and region-restricted measurement remain unsupported.
35
+ - Semantic intent is re-evaluated after edits. Missing or ambiguous references fail explicitly; arbitrary topology changes do not guarantee one-to-one identity.
36
+ - Resource figures apply to the recorded workloads. G4 has not started, and this release establishes no new speed/memory ratio against build123d. Native editable SOLIDWORKS acceptance is unchanged.
37
+
38
+ ## [0.1.0-alpha.6](https://github.com/Coloopx/colocad/releases/tag/v0.1.0-alpha.6) — 2026-11-07
39
+
40
+ - Documented the SDK → CLI/tools → skill workflow, agent integration examples, CLI visualization and source-backed HIWIN KK60 showcase.
41
+ - Improved release verification and publishing integrity checks. Native geometry binaries were unchanged from alpha.4.
42
+ - Exact engineering queries and mounting-interface APIs were not included in this version.
43
+
44
+ Earlier release notes remain in [GitHub Releases](https://github.com/Coloopx/colocad/releases).
package/README.md CHANGED
@@ -2,257 +2,200 @@
2
2
 
3
3
  ![HIWIN KK60 linear actuator — actual native modeling and assembly in four views](showcase/hiwin-kk60/modeling.gif)
4
4
 
5
- **HIWIN KK60 linear actuator** · [Modeling example](examples/hiwin-kk60/README.md) · [Watch MP4](showcase/hiwin-kk60/modeling.mp4) · [Independent checks](showcase/hiwin-kk60/verification.json)
5
+ **Parametric CAD for agents. Local Rust geometry, a TypeScript SDK, a CLI, and an inspectable modeling history.**
6
6
 
7
- [中文说明](README.zh-CN.md) · [Developer docs](docs/README.md) · [npm package](https://www.npmjs.com/package/@coloopx/colocad) · [Download the offline comparison](https://github.com/Coloopx/colocad/raw/refs/heads/main/docs/benchmarks/comparison.html)
7
+ [中文](README.zh-CN.md) · [Documentation](docs/README.md) · [npm](https://www.npmjs.com/package/@coloopx/colocad) · [Changelog](CHANGELOG.md) · [Releases](https://github.com/Coloopx/colocad/releases) · [Model behind the cover](examples/hiwin-kk60/README.md)
8
8
 
9
- Generate a mechanical part from a JSON feature tree, export an exact STEP solid, and give an agent a PNG or 3D preview to inspect. **The npm package ships the compiled Rust CAD kernel.** The agent and harness call it locally in the same sandbox through the Node CLI or TypeScript API. No Python, Rust toolchain, network or separate service is required to build a part after installation.
9
+ Colocad turns explicit modeling instructions into editable source, exact STEP geometry and visual review artifacts. It runs alongside the agent and its harness **inside the same sandbox**. The npm package includes the compiled Rust kernel; installed modeling needs no Python, Rust toolchain, network or separate CAD service.
10
10
 
11
- ## Start here: SDK + CLI + skill
11
+ **Alpha software:** useful for supported mechanical parts and assemblies, with measured performance and reproducible examples. It is not a complete replacement for build123d or a manufacturing-certified CAD system. See [support and limits](#support-and-limits).
12
12
 
13
- [End-to-end agent modeling handbook](docs/agent-modeling-handbook.md) · [Research and evidence](docs/agent-modeling-research.md)
13
+ ## What you can build
14
14
 
15
- The **SDK is the modeling foundation**. The CLI exposes it to a shell-based harness; the skill supplies modeling instructions, editable starter shapes and verification guidance. The agent, harness and CAD executable run inside the same sandbox. A recorded session provides the human-facing view of that work.
15
+ - **Parts and assemblies:** parametric features, repeated part definitions, exact STEP and PNG/GLB/STL previews.
16
+ - **Engineering queries (alpha.7):** exact topology, composable selection, datums, holes/groups, mounting interfaces and measured assembly relationships. [Supported domains](docs/engineering-queries.md).
17
+ - **Agent workflows:** SDK tools and a bundled skill for interpreting dimensions, planning features, editing and checking results.
18
+ - **Human review:** persistent build attempts, source/receipt inspection, offline single-file HTML and four-view MP4/GIF replay.
19
+
20
+ The SDK is the foundation; the CLI and tool adapters expose it to your harness; the skill guides modeling decisions. Images and drawings are evidence the agent interprets. Colocad executes explicit geometry instructions.
16
21
 
17
22
  ```mermaid
18
23
  flowchart LR
19
- A[Agent + colocad skill] --> H[Harness]
20
- H --> C[colocad CLI]
21
- H --> S[TypeScript SDK]
22
- C --> S
23
- S --> K[Local Rust B-rep kernel]
24
- K --> F[STEP + model + receipts + meshes]
25
- F --> V[CLI viewer / HTML / MP4 / GIF]
24
+ A[Agent + skill] --> H[Existing harness]
25
+ H --> C[CLI / SDK tools]
26
+ C --> K[Local Rust kernel]
27
+ K --> F[STEP + source + receipts + meshes]
28
+ F --> V[CLI viewer / HTML / animation]
26
29
  ```
27
30
 
28
- ### CLI: build, inspect and keep the modeling process
29
-
30
- ```sh
31
- npm install @coloopx/colocad@0.1.0-alpha.5
31
+ ## Install
32
32
 
33
- # Build the packaged example and persist an inspectable native revision.
34
- npx colocad record node_modules/@coloopx/colocad/examples/manifold.json ./history \
35
- --label "Build the manifold"
33
+ Requires **Node.js 22+** on **Linux x64, Linux arm64 or macOS arm64**.
36
34
 
37
- # Launch the viewer and open the browser.
38
- npx colocad view ./history
39
-
40
- # Export one self-contained HTML file, including the final STEP download.
41
- npx colocad replay ./history ./review.html
35
+ ```sh
36
+ npm install @coloopx/colocad@0.1.0-alpha.7
42
37
  ```
43
38
 
44
- Record the next edited JSON into the **same** history directory to append a revision. Every attempted build retains its source and receipt; failures remain visible. `view` serves a snapshot, so reopen it after adding revisions. In a headless sandbox, use `colocad view ./history --no-open --port 8787` and the harness's existing port forwarding. The listener binds to `127.0.0.1`.
39
+ The package ships JS/TS APIs, the CLI, native executables, viewer and complete skill. Rust source is in [crates/agent-cad](crates/agent-cad); the npm tarball contains compiled binaries. [Package and model formats](docs/concepts.md).
45
40
 
46
- | CLI command | Input | Output / purpose |
47
- | --- | --- | --- |
48
- | `colocad plan TREE.json` | `colocad/1` feature tree | Compile a native modeling job without building geometry |
49
- | `colocad build TREE.json NEW_DIR --preview` | `colocad/1` feature tree | STEP, editable tree, report and previews |
50
- | `colocad record MODEL.json SESSION --label TEXT` | Feature tree **or** kernel model JSON | Build and append a persistent modeling milestone |
51
- | `colocad view SESSION` | Recorded session | Local interactive viewer; optional `--export review.html` |
52
- | `colocad replay SESSION review.html` | Recorded session | Single offline HTML, no listening process |
53
- | `colocad render SESSION modeling.mp4` | Recorded session | Four-view animation, timing/hash manifest and poster; `.gif` also supported |
41
+ ## Quick start
54
42
 
55
- ### Visualization and animation are launched from the CLI
43
+ Run these commands from your Node project:
56
44
 
57
- ![CLI-launched modeling-history viewer with the real KK60 assembly](https://raw.githubusercontent.com/Coloopx/colocad/main/showcase/hiwin-kk60/viewer.png)
45
+ ```sh
46
+ # Build the packaged manifold and save its source, receipt and geometry.
47
+ npx colocad record node_modules/@coloopx/colocad/examples/manifold.json ./history \
48
+ --label "Build the manifold"
58
49
 
59
- The viewer includes a step timeline, source/feature/receipt inspector, part selection and visibility, four camera presets, display cutaway/explosion, and downloads of the current model and final STEP. The HTML embeds its rendering code and geometry; it works offline. The browser component is also available as `@coloopx/colocad/viewer` for a host application.
50
+ # Launch the interactive viewer.
51
+ npx colocad view ./history
60
52
 
61
- ```sh
62
- # Optional dependencies for movie encoding only:
63
- npm install -D playwright
64
- npx playwright install chromium
65
- # Install FFmpeg on your host, then export from the same persisted session:
66
- npx colocad render ./history ./modeling.mp4 --width 1280 --height 800 --fps 15
67
- npx colocad render ./history ./modeling.gif --width 960 --height 600 --fps 10
53
+ # Export one offline HTML file, including a final STEP download.
54
+ npx colocad replay ./history ./review.html
68
55
  ```
69
56
 
70
- Movies replay **actual saved CAD revisions** with four synchronized views and measured call times. Playback pacing and exploded placement are presentation controls; film duration is not CAD build time. Geometry builds and offline HTML export do not need Chromium or FFmpeg. [Complete CLI / recorder / renderer guide](docs/modeling-history.md).
57
+ The manifold includes an extrusion, blind cut, fillet, linear pattern and pocket. Record an edited JSON into the same history directory to append a revision; failed attempts remain visible. `view` serves a snapshot, so reopen it after adding revisions. [First part and parameter edit](docs/getting-started.md).
71
58
 
72
- ### SDK: call the same kernel from your harness
59
+ Prefer an API? Use the same kernel through a persistent session:
73
60
 
74
61
  ```js
75
62
  import { ModelingSession } from '@coloopx/colocad/session';
76
63
 
77
- const session = await ModelingSession.create('./history', { title: 'Agent modeling' });
78
- const model = {
64
+ const session = await ModelingSession.create('./sdk-history');
65
+ const result = await session.build({
79
66
  version: 1, units: 'mm', parameters: { length: 60 },
80
67
  features: [{ id: 'stock', op: 'box', origin: [0, 0, 0],
81
68
  size: [{ param: 'length' }, 30, 8] }],
82
69
  output: 'stock',
83
- };
84
- const result = await session.build(model, { label: 'Extrude the stock' });
70
+ });
85
71
  if (!result.ok) throw new Error(JSON.stringify(result.error));
86
- await session.edit({ length: 80 }, { label: 'Lengthen the stock' });
72
+ await session.edit({ length: 80 });
87
73
  ```
88
74
 
89
- Use `CadClient` for direct builds, edits and cached observation without a session; use `ModelingSession` when the modeling process must be persisted. `createCadTools` and `createSessionTools` expose tool schemas/executors for a harness adapter. [Runnable integrations](examples/integrations/README.md) cover Pi core/extension and the Codex/Claude local skill paths; scripted integration tests are distinguished from live model reasoning.
90
-
91
- ### Skill: give the agent the complete modeling guide
75
+ Use `CadClient` for direct builds without session recording. [SDK, CLI and tool API](docs/api.md).
92
76
 
93
- Copy the **whole** bundled skill directory, including scripts, references and editable shape assets:
94
-
95
- ```sh
96
- # Codex project skill
97
- mkdir -p .agents/skills
98
- cp -R node_modules/@coloopx/colocad/skills/colocad .agents/skills/colocad
99
-
100
- # For Claude Code, use .claude/skills/colocad instead.
101
- ```
77
+ ## Visualize and export from the CLI
102
78
 
103
- Then ask the agent to use the colocad skill, specify the product/dimensions and require a recorded session, exact STEP and CLI-exported review. For other harnesses, load `skills/colocad/SKILL.md` and register the SDK tools. The skill guides interpretation and verification; colocad executes explicit geometry instructions. [Codex](docs/integrations/codex.md) · [Claude Code](docs/integrations/claude-code.md) · [Pi](docs/integrations/pi.md) · [Actual drawing-to-model workflow](docs/modeling-workflow.zh-CN.md).
79
+ ![CLI modeling-history viewer showing the KK60 assembly](https://raw.githubusercontent.com/Coloopx/colocad/main/showcase/hiwin-kk60/viewer.png)
104
80
 
105
- ## Reconstruct a real industrial product and replay its modeling history
106
-
107
- The [HIWIN KK60 actuator example](examples/hiwin-kk60/README.md) reconstructs a specific manufacturer catalog configuration: 300 mm rail, 5 mm lead, 210 mm travel. Its **52 native features, 81 named occurrences and 16 persisted milestones** include a physically cut helical screw groove, guide tracks, mounting holes, bearings, carriage and coupling.
81
+ Inspect the timeline, source, features, receipts and selected parts. Switch cameras, show display sections or explosion, and download artifacts. The offline HTML embeds its rendering code and geometry. Hosts can also embed `@coloopx/colocad/viewer`.
108
82
 
83
+ | Command | Input | Result |
84
+ | --- | --- | --- |
85
+ | `colocad plan TREE.json` | `colocad/1` feature tree | Compile and inspect a native job |
86
+ | `colocad build TREE.json NEW_DIR --preview` | Feature tree | STEP, editable source and previews |
87
+ | `colocad record MODEL.json SESSION` | Feature tree or kernel JSON | Build and persist a milestone |
88
+ | `colocad view SESSION` | Saved session | Interactive local viewer |
89
+ | `colocad replay SESSION review.html` | Saved session | Self-contained offline HTML |
90
+ | `colocad render SESSION modeling.mp4` | Saved session | Four-view animation; `.gif` also supported |
109
91
 
110
- [Watch the MP4](showcase/hiwin-kk60/modeling.mp4) · [Edit the model](showcase/hiwin-kk60/model.json) · [Read the independent checks](showcase/hiwin-kk60/verification.json) · [Dimensions and assumptions](examples/hiwin-kk60/sources.json)
92
+ In a headless sandbox, use `colocad view ./history --no-open --port 8787` with the harness's port forwarding; the listener binds to `127.0.0.1`.
111
93
 
112
94
  ```sh
113
- node node_modules/@coloopx/colocad/examples/hiwin-kk60/run.mjs ./actuator
114
- npx colocad view ./actuator/session
115
- npx colocad replay ./actuator/session ./actuator.html
116
- # Optional: Playwright/Chromium + FFmpeg are required for video encoding.
117
- npx colocad render ./actuator/session ./modeling.mp4
95
+ # Optional movie dependencies; install FFmpeg on the host as well.
96
+ npm install -D playwright
97
+ npx playwright install chromium
98
+ npx colocad render ./history ./modeling.mp4 --width 1280 --height 800 --fps 15
118
99
  ```
119
100
 
120
- This is a catalog-based product reconstruction, with explicitly approximated internal races/bearings and no manufacturing certification. The animation reads actual saved CAD revisions; measured call times appear separately from edited playback. It is not a performance comparison. See [CLI history/rendering](docs/modeling-history.md) and the [actual agent modeling workflow](docs/modeling-workflow.zh-CN.md).
101
+ Movies replay **actual saved revisions**. Recorded call times and edited playback duration are separate. Building geometry and exporting HTML do not need Chromium or FFmpeg. [History, viewer and rendering guide](docs/modeling-history.md).
121
102
 
122
- ## How many tendon hands can an agent deliver in 100 seconds?
103
+ ## Use with your agent
123
104
 
124
- **colocad delivered 44 complete revisions to build123d’s 33 (+33.3%), with 57.1% lower peak sampled sandbox memory.** Both tools rebuilt and assembled the same 43-solid hand at each revision. Each tick marks a complete STEP handed off to storage.
105
+ Copy the whole skill, including its references, scripts and editable shape assets:
125
106
 
126
- ![10× replay of tendon-hand modeling and assembly: 44 vs. 33 STEP deliveries; sampled sandbox memory peaks at 130.9 vs. 304.9 MiB.](showcase/tendon-hand/window/hand-window-peak-en.gif)
127
-
128
- The GIF shows the **highest memory sampled so far** for each tool on the same 0–512 MiB scale. For actual usage between builds, see the [instantaneous-memory replay (MP4)](https://github.com/Coloopx/colocad/raw/refs/heads/main/showcase/tendon-hand/window/hand-window-en.mp4) or the [timestamped samples](showcase/tendon-hand/evidence/window-optimized.json).
129
-
130
- | Same revision queue, 1 vCPU / 512 MiB | Optimized colocad | build123d |
131
- |---|---:|---:|
132
- | Complete hands delivered in 100 s | **44** | 33 |
133
- | First STEP | **2.223 s** | 3.010 s |
134
- | Median job time on the same first 33 inputs | **2.234 s** | 2.855 s |
135
- | Highest sampled cgroup memory over the 100 s window | **130.9 MiB** | 304.9 MiB |
136
-
137
- One measured window per backend, with a new CAD process for each revision. The original run used the alpha.2 SDK and the optimized Linux arm64 kernel now bundled in alpha.3. Memory samples taken about every 25 ms include subprocesses, tmpfs and charged file cache. Every counted STEP reopened successfully. [Measurement method](showcase/tendon-hand/window/README.md) · [Detailed build and single-call replay](showcase/tendon-hand/assembly-performance.md)
138
-
139
- The static scorecard below uses the **published alpha.2 binary**. With fresh tool processes the sensor rail and manifold reached STEP 22.0× and 12.9× faster than build123d, using 7.7% and 8.0% of its peak memory.
140
-
141
- <details>
142
- <summary>See the static comparison across four workloads</summary>
143
-
144
- ![Time to STEP and peak cgroup memory across four workloads. Shorter bars are better.](docs/benchmarks/time-to-step.svg)
145
-
146
- </details>
147
-
148
- | Deliverable | Time to STEP: colocad / build123d | Speedup¹ | Peak memory: colocad / build123d | Share of build123d peak |
149
- | :--- | ---: | ---: | ---: | ---: |
150
- | Sensor rail | 113 / 2,485 ms | **22.0×** | 20.0 / 259.3 MiB | **7.7%** |
151
- | Port manifold | 230 / 2,963 ms | **12.9×** | 20.7 / 258.7 MiB | **8.0%** |
152
- | Tendon-hand proximal link | 259 / 2,244 ms | **8.6×** | 21.4 / 260.1 MiB | **8.2%** |
153
- | Complete 43-solid hand | 3,952 / 3,293 ms | **0.83×** | 52.7 / 271.3 MiB | **19.4%** |
154
-
155
- ¹ build123d time divided by colocad time from unrounded observations. Same Linux arm64 image, 1 vCPU, 512 MiB. Five fresh processes and cgroups per part and backend after warm-up. Time is the median wall clock including startup, imports, modeling, backend checks and STEP export. Memory is the maximum measured cgroup peak; charged pages, temporary outputs and tool descendants count. Installation, container startup, previews, inference and a resident agent are excluded.
156
-
157
- [Rail/manifold samples](docs/benchmarks/runs.json) · [Finger/hand samples](showcase/tendon-hand/evidence/scope.json) · [Four-view hand study and CAD downloads](showcase/tendon-hand/README.md) · [Offline scorecard](https://github.com/Coloopx/colocad/raw/refs/heads/main/docs/benchmarks/time-to-step.html)
158
-
159
- **Historical alpha.2 result.** in a separate 100-second sweep of complete hand revisions, colocad delivered 24 STEPs to build123d’s 30. Every counted file reopened as a valid 43-solid assembly. [Timestamped outputs and paired geometry checks](showcase/tendon-hand/evidence/window.json)
107
+ ```sh
108
+ # Codex project skill; use .claude/skills for Claude Code.
109
+ mkdir -p .agents/skills
110
+ cp -R node_modules/@coloopx/colocad/skills/colocad .agents/skills/colocad
111
+ ```
160
112
 
161
- ## SDK, CLI or skill?
113
+ If that skill already exists, preserve local customizations before updating it. Then ask:
162
114
 
163
- **Start here:** [first part and edit](docs/getting-started.md) · [SDK/API reference](docs/api.md) · [modeling best practices](docs/best-practices.md).
115
+ > Use the colocad skill to build a 100 × 50 × 6 mm plate with a centered 3 × 2 grid of Ø6 through-holes on 32 × 30 mm pitches. Keep editable source and modeling history, verify the dimensions, and export STEP and an offline HTML review through the CLI.
164
116
 
165
- | Your harness | Integration guide |
117
+ | Harness | Integration |
166
118
  | --- | --- |
167
- | Pi agent core / Pi coding agent | [Typed tool adapter, extension and skill](docs/integrations/pi.md) |
168
- | Claude Code | [Project skill and local CLI](docs/integrations/claude-code.md) |
169
- | Codex | [Project skill, invocation and artifact inspection](docs/integrations/codex.md) |
170
- | Other harnesses | [Sandbox architecture, revision state and artifact lifecycle](docs/integrations/overview.md) |
171
-
172
- The [runnable examples](examples/integrations/README.md) exercise the published package, real native builds and Pi tool-loop error recovery. See [what was verified](docs/integrations/verification.md) and [how to contribute](CONTRIBUTING.md).
173
-
174
- Install with `npm install @coloopx/colocad@0.1.0-alpha.5`. This version bundles the optimized assembly kernel and the complete agent skill. The skill lives at `node_modules/@coloopx/colocad/skills/colocad/`. Point your harness at its `SKILL.md` or copy the whole directory into your agent’s skill collection.
119
+ | Codex | [Project skill and CLI](docs/integrations/codex.md) |
120
+ | Claude Code | [Project skill and local tools](docs/integrations/claude-code.md) |
121
+ | Pi core / coding agent | [Typed tool adapter and extension](docs/integrations/pi.md) |
122
+ | Your own harness | [SDK schemas, state and artifact lifecycle](docs/integrations/overview.md) |
175
123
 
176
- For a dimensioned part, try “Make a 100 × 50 × 6 mm plate with a centered 3 × 2 grid of Ø6 through-holes on 32 × 30 mm pitches.” The skill includes editable stock, hole grids, sleeves, brackets and open housings. [Quick-build commands and examples](skills/colocad/references/quick-build.md)
124
+ The [end-to-end handbook](docs/agent-modeling-handbook.md) covers source preparation, dimension uncertainty, tool abstraction, prompts, modeling loops, validation and tuning. A [runnable guided workflow](examples/integrations/README.md) demonstrates real builds, quantitative edits and recovery; its decisions are scripted, not a live-LLM benchmark.
177
125
 
178
- - **In an application or harness:** call `build(tree, newDir, { preview: true })` in the SDK. Use `CadClient.build(model)` for named multi-solid assemblies.
179
- - **In a shell or agent tool call:** install `npm install @coloopx/colocad@0.1.0-alpha.5`. Run `./node_modules/.bin/colocad plan tree.json`, then `./node_modules/.bin/colocad build tree.json ./new-part --preview`. Open `new-part/part/model.step`.
180
- - **From drawings with an agent:** install the [colocad skill](skills/colocad/SKILL.md). Start the next turn with “Use `$colocad` to reconstruct these four views, export STEP, and flag any internal details you inferred.” [Installation and assembly replay](showcase/tendon-hand/README.md#try-it-with-your-agent).
126
+ ## Example: a complete linear actuator
181
127
 
182
- ## What the two STEP writers produced
128
+ The cover reconstructs a **HIWIN KK60, 300 mm rail, 5 mm lead, 210 mm travel** from manufacturer drawings: **52 final features, 81 named solid occurrences and 16 modeling milestones**. It includes a physically cut helical screw groove, rail tracks, mounting holes, carriage, bearings and coupling.
183
129
 
184
- ![Two independently modeled STEP pairs. Top: a sensor rail with three through-slots. Bottom: a manifold with four blind bores and a rectangular pocket. Colocad on the left; build123d on the right.](docs/benchmarks/step-comparison.png)
130
+ ```sh
131
+ node node_modules/@coloopx/colocad/examples/hiwin-kk60/run.mjs ./actuator
132
+ npx colocad view ./actuator/session
133
+ npx colocad render ./actuator/session ./modeling.mp4
134
+ ```
185
135
 
186
- Each backend modeled the part from the same parameters. The images use the exported STEPs, the same mesher and camera. OCCT reopened each file as **one valid solid**. Both rail exports had 22 faces and 56 edges; both manifold exports had 27 faces and 54 edges. The two directional boolean differences measured **0 mm³** in both cases (boolean tolerance: 0.000001 mm). [Geometry checks](docs/benchmarks/step-checks.json)
136
+ Independent OCCT checks cover all 16 STEP revisions, 64 material probes and selected rail/carriage clearances. Proprietary internals are explicitly approximated or omitted; this is a catalog reconstruction, not a production drawing package. The animation is not a speed benchmark.
187
137
 
188
- On the manifold, build123d’s modeling phase alone was **43.8 ms** to colocad’s **53.7 ms**, while build123d import alone took **2.45 s**. The table measures a fresh tool call, not the speed of an isolated boolean operation. [Stage timings and reproduction](benchmarks/readme/README.md)
138
+ [MP4](showcase/hiwin-kk60/modeling.mp4) · [Editable model](showcase/hiwin-kk60/model.json) · [Checks](showcase/hiwin-kk60/verification.json) · [Dimensions and assumptions](examples/hiwin-kk60/sources.json) · [Full offline delivery](https://github.com/Coloopx/colocad/releases/download/v0.1.0-alpha.4/hiwin-kk60-delivery.zip)
189
139
 
190
- ### When the agent only changes the camera
140
+ ## Performance
191
141
 
192
- The first preview saves a display mesh. For a second view of unchanged geometry, the kernel SDK can load that mesh instead of rebuilding the solid or triangulating it again. Here are five-run medians for the same **top view**, comparing two paths inside colocad:
142
+ Performance depends on geometry and execution mode. In a measured 100-second queue of the same **43-solid tendon hand**, Colocad delivered **44 complete STEP revisions versus build123d's 33**, with **57.1% lower highest sampled sandbox memory**.
193
143
 
194
- | Part | Rebuild part + render | Render from saved mesh | Speedup |
195
- | :--- | ---: | ---: | ---: |
196
- | Sensor rail | 108.8 ms | 19.4 ms | **5.6×** |
197
- | Port manifold | 223.8 ms | 13.3 ms | **16.8×** |
144
+ ![10× replay: STEP deliveries and peak-so-far sampled sandbox memory](showcase/tendon-hand/window/hand-window-peak-en.gif)
198
145
 
199
- The PNG, GLB and STL from both paths matched byte for byte on every pair. This test starts with the SDK already loaded and includes native process startup and display output. A geometry edit needs a new revision. [Preview measurements and hashes](docs/benchmarks/preview-runs.json)
146
+ | Same revision queue, 1 vCPU / 512 MiB | Colocad | build123d |
147
+ | --- | ---: | ---: |
148
+ | Complete STEP deliveries in 100 s | **44** | 33 |
149
+ | First STEP | **2.223 s** | 3.010 s |
150
+ | Median job, same first 33 inputs | **2.234 s** | 2.855 s |
151
+ | Highest sampled cgroup memory | **130.9 MiB** | 304.9 MiB |
200
152
 
201
- ## What ships
153
+ One window per backend; a fresh CAD process per revision; approximately 25 ms memory sampling includes subprocesses, temporary files and charged file cache. Every counted STEP reopened successfully. This run used the alpha.2 SDK and the optimized kernel first bundled in alpha.3; it is not a new alpha.6 measurement. The GIF plots the highest sample so far, not instantaneous usage. [Method and samples](showcase/tendon-hand/window/README.md).
202
154
 
203
- | In the [npm tarball](https://www.npmjs.com/package/@coloopx/colocad) | In the [source repository](https://github.com/Coloopx/colocad) |
204
- | :--- | :--- |
205
- | Agent skill, CLI, JavaScript API, TypeScript declarations and precompiled Rust executables for **Linux x64, Linux arm64 and macOS arm64**. Node.js 22+. | [Rust CAD source](crates/agent-cad/src), [TypeScript kernel SDK](kernel/src), [feature compiler](src/tree.mjs), tests and [pinned SolidCore dependency](third_party/solidcore.lock.json). |
155
+ <details>
156
+ <summary>Cold-start parts and cached previews</summary>
206
157
 
207
- For example, on Linux arm64 the CLI launches `node_modules/@coloopx/colocad/kernel/native/linux-arm64/agent-cad`. The tarball contains the executable; the Rust `.rs` files are in the repository.
158
+ ![Time to STEP and peak memory on four historical workloads](docs/benchmarks/time-to-step.svg)
208
159
 
209
- **Alpha status.** Linux supports parametric edits, STEP and PNG/GLB/STL export. Direct generation of a complex, editable SOLIDWORKS part on Linux is still experimental. The optional Windows author compiles against the SOLIDWORKS 2024 interop API; a licensed native rebuild has not been verified. See the [native author](#native-solidworks-author-experimental) and [validation notes](docs/validation.md).
160
+ The published alpha.2 kernel reached STEP **22.0× faster** for a sensor rail and **12.9× faster** for a manifold, using **7.7% and 8.0%** of build123d's peak memory. Five fresh processes/cgroups per part and backend after warm-up; Linux arm64, 1 vCPU / 512 MiB. Startup/imports, modeling, checks and export count; installation, previews, inference and a resident agent do not. These gains do not apply to every operation: manifold geometry alone took 53.7 ms versus build123d's 43.8 ms, and the old complete-hand result was slower.
210
161
 
211
- ## Run the examples
162
+ For unchanged geometry, saved-mesh observation was 5.6×–16.8× faster than Colocad's own rebuild-and-render path on two parts. This is an internal cache comparison, not a build123d result.
212
163
 
213
- ```sh
214
- npm install @coloopx/colocad@alpha
215
- npx colocad build node_modules/@coloopx/colocad/examples/manifold.json ./manifold --preview
216
- npx colocad build node_modules/@coloopx/colocad/examples/sensor-rail.json ./rail
217
- ```
164
+ </details>
218
165
 
219
- The manifold contains a six-sided extrusion, a blind circular cut, an upper-rim fillet, a four-instance pattern referencing the earlier cut, and a rectangular pocket. The sensor rail uses a different sketch, feature order and pattern direction. Both run through the same compiler. The pattern count includes the seed.
166
+ [Full performance evidence and limitations](docs/performance.md) · [Offline comparison with STEP downloads](https://github.com/Coloopx/colocad/raw/refs/heads/main/docs/benchmarks/comparison.html).
220
167
 
221
- Each call requires a new output directory. The `part/` subdirectory holds `model.step`, `feature-tree.json`, a kernel report, and `native-job.json`. With `--preview` it also contains PNG, STL and GLB files. The native job stores the ordered feature definitions, resolved inputs and reference geometry measurements.
168
+ ## Support and limits
222
169
 
223
- ```js
224
- import { readFile } from 'node:fs/promises';
225
- import { build } from '@coloopx/colocad';
226
-
227
- const tree = JSON.parse(await readFile('./node_modules/@coloopx/colocad/examples/manifold.json', 'utf8'));
228
- await build(tree, './original');
229
- tree.parameters.instances = 3;
230
- const edited = await build(tree, './edited');
231
- console.log(edited.geometry.volume_mm3);
232
- ```
170
+ - Native packages: Linux x64/arm64 and macOS arm64, Node.js 22+. [Release verification](docs/evidence/release-alpha.7.json).
171
+ - Editable JSON/programs and exact STEP are supported; STEP does not preserve a commercial CAD application's native feature tree.
172
+ - General editable SOLIDWORKS output on Linux remains incomplete. The experimental Windows author requires licensed SOLIDWORKS, and a native rebuild pass is still unverified. [Native author status](docs/native-solidworks.md).
173
+ - CAD checks, drawing interpretation, edit preservation, fit and manufacturing readiness are separate claims. [Validation scope](docs/validation.md).
174
+ - A 512 MiB CAD test is not a memory guarantee for an entire resident agent, browser or video encoder.
233
175
 
234
- All coordinates and lengths are in mm. The first extrusion creates a solid. Further extrusions add material and cuts remove material along +Z from a sketch at `startZ` (default 0). Profiles can be rectangles, circles or polygons. Fillets select edges on a specified Z plane and require the declared match count. A linear pattern refers to an earlier extrusion or cut by ID, with X/Y direction, positive pitch and instance count. IDs are unique, case-insensitively. A scalar is a finite number or a reference such as `{"param":"thickness"}`. The public TypeScript declaration defines the full input.
176
+ ## Documentation and help
235
177
 
236
- The kernel API at `@coloopx/colocad/kernel` also exposes the lower-level geometry operations, STEP import, incremental revisions and preview cache. The npm tarball includes Linux arm64/x64 and macOS arm64 executables and dependency licenses. The checked-in sources build the kernel on supported toolchains.
178
+ Available in alpha.7: [exact queries and geometry-backed assembly](docs/engineering-queries.md), with a [runnable external STEP example](examples/engineering-queries/README.md). The [four ordered goals](specs/0005-capability-reliability-and-optimization.md) track functional coverage, geometry reliability, engineering usability, then benchmark-driven optimization. The SDK, CLI, tool schema and all three native targets ship together; this is a Colocad API, not CadQuery Python/API compatibility.
237
179
 
238
- ## Native SOLIDWORKS author (experimental)
180
+ G1–G3 are accepted for the [declared workloads](specs/experiments/0005/README.md): 24/24 geometry cases independently verified, 127 Rust / 41 Node tests, and two live Pi tasks in Linux arm64 **1 vCPU / 512 MiB**. Peak cgroup memory was **256 MiB** for the corpus with a minimal supervisor and **371 MiB** for resident Pi/harness plus the 82-solid actuator edit and preview; zero OOM. This is resource/correctness acceptance, not a new build123d speed comparison or full industry-wide parity. G4 has not started.
239
181
 
240
- The Windows entry point consumes the same job. It starts a blank part using the application's configured default, builds sketches with native lines and circles, calls extrusion/cut/fillet/pattern APIs and names the resulting features. The fillet uses body edges and the native pattern selects the original seed feature. There are no part-specific model files. Running it requires local Windows, .NET 8 and a licensed SOLIDWORKS installation with a valid default blank part configuration.
241
182
 
242
- ```powershell
243
- colocad solidworks .\manifold\part\native-job.json .\manifold.SLDPRT
244
- ```
183
+ [Getting started](docs/getting-started.md) · [API](docs/api.md) · [Agent handbook](docs/agent-modeling-handbook.md) · [Skill](skills/colocad/SKILL.md) · [Troubleshooting](docs/troubleshooting.md) · [All documentation](docs/README.md)
245
184
 
246
- Use `COLOCAD_SW_INTEROP` for an alternate directory containing the local SOLIDWORKS interop DLLs. The completion check is designed to save a temporary part, reopen it, verify native types, radius, pattern seed, count, pitch and reference volume, then edit a driving extrusion dimension, rebuild, restore and check it. Only a successful check publishes the output. The current release has **no native runtime pass** for either complex part. The package includes no four-hole template and does not route jobs to another machine.
185
+ For a bug or feature request, [open an issue](https://github.com/Coloopx/colocad/issues) with the package version, platform, minimal model and relevant receipt. Remove credentials and private source material.
247
186
 
248
- ## Build and verify from source
187
+ ## Develop and contribute
249
188
 
250
189
  ```sh
190
+ git clone https://github.com/Coloopx/colocad.git
191
+ cd colocad
192
+ npm ci
251
193
  npm run build:kernel
252
194
  npm test
253
- node bin/colocad.mjs build examples/manifold.json ./out/manifold --preview
254
195
  ```
255
196
 
256
- The first command fetches the pinned SolidCore archive, checks its SHA-256 and builds the local Rust executable. The plain Node tests use the local executable or `AGENT_CAD_BINARY`. The repository includes the TypeScript kernel SDK source and its compiled distribution. To rebuild the .NET author, build `solidworks/Colocad.SolidWorks.csproj` with a .NET 8 SDK and `-p:SWInteropDir=<directory containing the two SOLIDWORKS interop DLLs>`. Copy only Colocad.SolidWorks.dll, its deps.json and runtimeconfig.json to solidworks/managed.
197
+ Building from source requires the Rust toolchain and fetches the pinned SolidCore dependency. Viewer/render and Pi integration checks have additional dependencies; see [CONTRIBUTING.md](CONTRIBUTING.md) for setup, tests and release instructions. Contributions are welcome as issues and pull requests.
198
+
199
+ ## License and acknowledgments
257
200
 
258
- Independent OCCT validation is in `test/validation/geometry.py`. It reopens the STEP and checks both volume and whether selected points lie inside the plate, the holes, the recess or the fillet. The measured results and the limits of the native experiment are in [the validation notes](docs/validation.md).
201
+ Colocad application code is [MIT licensed](LICENSE). The kernel builds on [SolidCore](https://github.com/tangency-labs/solidcore), including work derived from NVIDIA USD BRep / SMLib; the viewer uses Three.js. Dependency licenses and attribution are in [NOTICE.md](NOTICE.md) and [kernel/licenses](kernel/licenses). The industrial example is not affiliated with or endorsed by HIWIN.