@coloopx/colocad 0.1.0-alpha.4 → 0.1.0-alpha.6

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 (34) hide show
  1. package/README.md +133 -99
  2. package/README.zh-CN.md +145 -79
  3. package/docs/README.md +7 -4
  4. package/docs/README.zh-CN.md +9 -3
  5. package/docs/agent-modeling-handbook.md +68 -0
  6. package/docs/agent-modeling-handbook.zh-CN.md +222 -0
  7. package/docs/agent-modeling-research.md +22 -0
  8. package/docs/api.md +95 -0
  9. package/docs/best-practices.md +45 -0
  10. package/docs/concepts.md +37 -0
  11. package/docs/getting-started.md +53 -0
  12. package/docs/integrations/claude-code.md +52 -0
  13. package/docs/integrations/codex.md +55 -0
  14. package/docs/integrations/overview.md +53 -0
  15. package/docs/integrations/pi.md +73 -0
  16. package/docs/integrations/verification.md +30 -0
  17. package/docs/modeling-workflow.zh-CN.md +77 -0
  18. package/docs/native-solidworks.md +12 -0
  19. package/docs/performance.md +62 -0
  20. package/docs/troubleshooting.md +25 -0
  21. package/docs/validation.md +23 -0
  22. package/examples/hiwin-kk60/README.md +1 -1
  23. package/examples/integrations/README.md +47 -0
  24. package/examples/integrations/compact-tools.mjs +27 -0
  25. package/examples/integrations/guided-workflow.mjs +31 -0
  26. package/kernel/release.json +1 -1
  27. package/package.json +5 -2
  28. package/skills/colocad/SKILL.md +17 -9
  29. package/skills/colocad/assets/product-brief.example.json +20 -0
  30. package/skills/colocad/references/materials.md +37 -0
  31. package/skills/colocad/references/modeling-loop.md +33 -0
  32. package/skills/colocad/references/prompt-patterns.md +70 -0
  33. package/skills/colocad/references/tool-contracts.md +33 -0
  34. package/skills/colocad/references/tuning.md +30 -0
package/README.md CHANGED
@@ -1,161 +1,195 @@
1
- # colocad
1
+ # Colocad
2
2
 
3
- [中文说明](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)
3
+ ![HIWIN KK60 linear actuator — actual native modeling and assembly in four views](showcase/hiwin-kk60/modeling.gif)
4
4
 
5
- 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.
5
+ **Parametric CAD for agents. Local Rust geometry, a TypeScript SDK, a CLI, and an inspectable modeling history.**
6
6
 
7
- ## Reconstruct a real industrial product and replay its modeling history
7
+ [中文](README.zh-CN.md) · [Documentation](docs/README.md) · [npm](https://www.npmjs.com/package/@coloopx/colocad) · [Releases](https://github.com/Coloopx/colocad/releases) · [Model behind the cover](examples/hiwin-kk60/README.md)
8
8
 
9
- 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.
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
- ![Actual native construction and assembly, replayed in four views](showcase/hiwin-kk60/modeling.gif)
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
- [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)
13
+ ## What you can build
14
+
15
+ - **Parts and assemblies:** parametric features, repeated part definitions, exact STEP and PNG/GLB/STL previews.
16
+ - **Agent workflows:** SDK tools and a bundled skill for interpreting dimensions, planning features, editing and checking results.
17
+ - **Human review:** persistent build attempts, source/receipt inspection, offline single-file HTML and four-view MP4/GIF replay.
18
+
19
+ 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.
20
+
21
+ ```mermaid
22
+ flowchart LR
23
+ A[Agent + skill] --> H[Existing harness]
24
+ H --> C[CLI / SDK tools]
25
+ C --> K[Local Rust kernel]
26
+ K --> F[STEP + source + receipts + meshes]
27
+ F --> V[CLI viewer / HTML / animation]
28
+ ```
29
+
30
+ ## Install
31
+
32
+ Requires **Node.js 22+** on **Linux x64, Linux arm64 or macOS arm64**.
14
33
 
15
34
  ```sh
16
- node node_modules/@coloopx/colocad/examples/hiwin-kk60/run.mjs ./actuator
17
- npx colocad view ./actuator/session
18
- npx colocad replay ./actuator/session ./actuator.html
19
- # Optional: Playwright/Chromium + FFmpeg are required for video encoding.
20
- npx colocad render ./actuator/session ./modeling.mp4
35
+ npm install @coloopx/colocad@0.1.0-alpha.6
21
36
  ```
22
37
 
23
- 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).
38
+ 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).
24
39
 
25
- ## How many tendon hands can an agent deliver in 100 seconds?
40
+ ## Quick start
26
41
 
27
- **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.
42
+ Run these commands from your Node project:
28
43
 
29
- ![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)
44
+ ```sh
45
+ # Build the packaged manifold and save its source, receipt and geometry.
46
+ npx colocad record node_modules/@coloopx/colocad/examples/manifold.json ./history \
47
+ --label "Build the manifold"
30
48
 
31
- 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).
49
+ # Launch the interactive viewer.
50
+ npx colocad view ./history
32
51
 
33
- | Same revision queue, 1 vCPU / 512 MiB | Optimized colocad | build123d |
34
- |---|---:|---:|
35
- | Complete hands delivered in 100 s | **44** | 33 |
36
- | First STEP | **2.223 s** | 3.010 s |
37
- | Median job time on the same first 33 inputs | **2.234 s** | 2.855 s |
38
- | Highest sampled cgroup memory over the 100 s window | **130.9 MiB** | 304.9 MiB |
52
+ # Export one offline HTML file, including a final STEP download.
53
+ npx colocad replay ./history ./review.html
54
+ ```
39
55
 
40
- 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)
56
+ 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).
41
57
 
42
- 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.
58
+ Prefer an API? Use the same kernel through a persistent session:
43
59
 
44
- <details>
45
- <summary>See the static comparison across four workloads</summary>
60
+ ```js
61
+ import { ModelingSession } from '@coloopx/colocad/session';
62
+
63
+ const session = await ModelingSession.create('./sdk-history');
64
+ const result = await session.build({
65
+ version: 1, units: 'mm', parameters: { length: 60 },
66
+ features: [{ id: 'stock', op: 'box', origin: [0, 0, 0],
67
+ size: [{ param: 'length' }, 30, 8] }],
68
+ output: 'stock',
69
+ });
70
+ if (!result.ok) throw new Error(JSON.stringify(result.error));
71
+ await session.edit({ length: 80 });
72
+ ```
46
73
 
47
- ![Time to STEP and peak cgroup memory across four workloads. Shorter bars are better.](docs/benchmarks/time-to-step.svg)
74
+ Use `CadClient` for direct builds without session recording. [SDK, CLI and tool API](docs/api.md).
48
75
 
49
- </details>
76
+ ## Visualize and export from the CLI
50
77
 
51
- | Deliverable | Time to STEP: colocad / build123d | Speedup¹ | Peak memory: colocad / build123d | Share of build123d peak |
52
- | :--- | ---: | ---: | ---: | ---: |
53
- | Sensor rail | 113 / 2,485 ms | **22.0×** | 20.0 / 259.3 MiB | **7.7%** |
54
- | Port manifold | 230 / 2,963 ms | **12.9×** | 20.7 / 258.7 MiB | **8.0%** |
55
- | Tendon-hand proximal link | 259 / 2,244 ms | **8.6×** | 21.4 / 260.1 MiB | **8.2%** |
56
- | Complete 43-solid hand | 3,952 / 3,293 ms | **0.83×** | 52.7 / 271.3 MiB | **19.4%** |
78
+ ![CLI modeling-history viewer showing the KK60 assembly](https://raw.githubusercontent.com/Coloopx/colocad/main/showcase/hiwin-kk60/viewer.png)
57
79
 
58
- ¹ 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.
80
+ 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`.
59
81
 
60
- [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)
82
+ | Command | Input | Result |
83
+ | --- | --- | --- |
84
+ | `colocad plan TREE.json` | `colocad/1` feature tree | Compile and inspect a native job |
85
+ | `colocad build TREE.json NEW_DIR --preview` | Feature tree | STEP, editable source and previews |
86
+ | `colocad record MODEL.json SESSION` | Feature tree or kernel JSON | Build and persist a milestone |
87
+ | `colocad view SESSION` | Saved session | Interactive local viewer |
88
+ | `colocad replay SESSION review.html` | Saved session | Self-contained offline HTML |
89
+ | `colocad render SESSION modeling.mp4` | Saved session | Four-view animation; `.gif` also supported |
61
90
 
62
- **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)
91
+ 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`.
63
92
 
64
- ## SDK, CLI or skill?
93
+ ```sh
94
+ # Optional movie dependencies; install FFmpeg on the host as well.
95
+ npm install -D playwright
96
+ npx playwright install chromium
97
+ npx colocad render ./history ./modeling.mp4 --width 1280 --height 800 --fps 15
98
+ ```
65
99
 
66
- **Start here:** [first part and edit](docs/getting-started.md) · [SDK/API reference](docs/api.md) · [modeling best practices](docs/best-practices.md).
100
+ 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).
67
101
 
68
- | Your harness | Integration guide |
69
- | --- | --- |
70
- | Pi agent core / Pi coding agent | [Typed tool adapter, extension and skill](docs/integrations/pi.md) |
71
- | Claude Code | [Project skill and local CLI](docs/integrations/claude-code.md) |
72
- | Codex | [Project skill, invocation and artifact inspection](docs/integrations/codex.md) |
73
- | Other harnesses | [Sandbox architecture, revision state and artifact lifecycle](docs/integrations/overview.md) |
102
+ ## Use with your agent
74
103
 
75
- 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).
104
+ Copy the whole skill, including its references, scripts and editable shape assets:
76
105
 
77
- Install with `npm install @coloopx/colocad@0.1.0-alpha.3`. 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.
106
+ ```sh
107
+ # Codex project skill; use .claude/skills for Claude Code.
108
+ mkdir -p .agents/skills
109
+ cp -R node_modules/@coloopx/colocad/skills/colocad .agents/skills/colocad
110
+ ```
78
111
 
79
- 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)
112
+ If that skill already exists, preserve local customizations before updating it. Then ask:
80
113
 
81
- - **In an application or harness:** call `build(tree, newDir, { preview: true })` in the SDK. Use `CadClient.build(model)` for named multi-solid assemblies.
82
- - **In a shell or agent tool call:** install `npm install @coloopx/colocad@0.1.0-alpha.3`. 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`.
83
- - **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).
114
+ > 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.
84
115
 
85
- ## What the two STEP writers produced
116
+ | Harness | Integration |
117
+ | --- | --- |
118
+ | Codex | [Project skill and CLI](docs/integrations/codex.md) |
119
+ | Claude Code | [Project skill and local tools](docs/integrations/claude-code.md) |
120
+ | Pi core / coding agent | [Typed tool adapter and extension](docs/integrations/pi.md) |
121
+ | Your own harness | [SDK schemas, state and artifact lifecycle](docs/integrations/overview.md) |
86
122
 
87
- ![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)
123
+ 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.
88
124
 
89
- 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)
125
+ ## Example: a complete linear actuator
90
126
 
91
- 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)
127
+ 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.
92
128
 
93
- ### When the agent only changes the camera
129
+ ```sh
130
+ node node_modules/@coloopx/colocad/examples/hiwin-kk60/run.mjs ./actuator
131
+ npx colocad view ./actuator/session
132
+ npx colocad render ./actuator/session ./modeling.mp4
133
+ ```
94
134
 
95
- 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:
135
+ 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.
96
136
 
97
- | Part | Rebuild part + render | Render from saved mesh | Speedup |
98
- | :--- | ---: | ---: | ---: |
99
- | Sensor rail | 108.8 ms | 19.4 ms | **5.6×** |
100
- | Port manifold | 223.8 ms | 13.3 ms | **16.8×** |
137
+ [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)
101
138
 
102
- 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)
139
+ ## Performance
103
140
 
104
- ## What ships
141
+ 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**.
105
142
 
106
- | In the [npm tarball](https://www.npmjs.com/package/@coloopx/colocad) | In the [source repository](https://github.com/Coloopx/colocad) |
107
- | :--- | :--- |
108
- | 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). |
143
+ ![10× replay: STEP deliveries and peak-so-far sampled sandbox memory](showcase/tendon-hand/window/hand-window-peak-en.gif)
109
144
 
110
- 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.
145
+ | Same revision queue, 1 vCPU / 512 MiB | Colocad | build123d |
146
+ | --- | ---: | ---: |
147
+ | Complete STEP deliveries in 100 s | **44** | 33 |
148
+ | First STEP | **2.223 s** | 3.010 s |
149
+ | Median job, same first 33 inputs | **2.234 s** | 2.855 s |
150
+ | Highest sampled cgroup memory | **130.9 MiB** | 304.9 MiB |
111
151
 
112
- **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).
152
+ 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).
113
153
 
114
- ## Run the examples
154
+ <details>
155
+ <summary>Cold-start parts and cached previews</summary>
115
156
 
116
- ```sh
117
- npm install @coloopx/colocad@alpha
118
- npx colocad build node_modules/@coloopx/colocad/examples/manifold.json ./manifold --preview
119
- npx colocad build node_modules/@coloopx/colocad/examples/sensor-rail.json ./rail
120
- ```
157
+ ![Time to STEP and peak memory on four historical workloads](docs/benchmarks/time-to-step.svg)
121
158
 
122
- 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.
159
+ 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.
123
160
 
124
- 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.
161
+ 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.
125
162
 
126
- ```js
127
- import { readFile } from 'node:fs/promises';
128
- import { build } from '@coloopx/colocad';
129
-
130
- const tree = JSON.parse(await readFile('./node_modules/@coloopx/colocad/examples/manifold.json', 'utf8'));
131
- await build(tree, './original');
132
- tree.parameters.instances = 3;
133
- const edited = await build(tree, './edited');
134
- console.log(edited.geometry.volume_mm3);
135
- ```
163
+ </details>
136
164
 
137
- 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.
165
+ [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).
138
166
 
139
- 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.
167
+ ## Support and limits
140
168
 
141
- ## Native SOLIDWORKS author (experimental)
169
+ - Native packages: Linux x64/arm64 and macOS arm64, Node.js 22+. [Release verification](docs/evidence/release-alpha.6.json).
170
+ - Editable JSON/programs and exact STEP are supported; STEP does not preserve a commercial CAD application's native feature tree.
171
+ - 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).
172
+ - CAD checks, drawing interpretation, edit preservation, fit and manufacturing readiness are separate claims. [Validation scope](docs/validation.md).
173
+ - A 512 MiB CAD test is not a memory guarantee for an entire resident agent, browser or video encoder.
142
174
 
143
- 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.
175
+ ## Documentation and help
144
176
 
145
- ```powershell
146
- colocad solidworks .\manifold\part\native-job.json .\manifold.SLDPRT
147
- ```
177
+ [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)
148
178
 
149
- 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.
179
+ 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.
150
180
 
151
- ## Build and verify from source
181
+ ## Develop and contribute
152
182
 
153
183
  ```sh
184
+ git clone https://github.com/Coloopx/colocad.git
185
+ cd colocad
186
+ npm ci
154
187
  npm run build:kernel
155
188
  npm test
156
- node bin/colocad.mjs build examples/manifold.json ./out/manifold --preview
157
189
  ```
158
190
 
159
- 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.
191
+ 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.
192
+
193
+ ## License and acknowledgments
160
194
 
161
- 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).
195
+ 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.