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

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.
@@ -0,0 +1,22 @@
1
+ # Research basis and evidence boundaries
2
+
3
+ Reviewed 2026-11-07. These are primary sources and implementation observations used to design the guide. External results are not Colocad benchmark results. The guide's detailed workflows, tool fields and tradeoffs are project recommendations to test, not copied universal rules.
4
+
5
+ | Source | What it supports | Colocad design decision |
6
+ | --- | --- | --- |
7
+ | [Normal: CAD Arena](https://normal.ai/research/cadarena) | Engineering drawings to editable CAD parts as an evaluation target | Test the requested geometry and editability; do not equate a preview with a reconstructed product. The static page did not expose its results table during this review, so no ranking is quoted. |
8
+ | [DIP-CAD, arXiv 2609.22688v4](https://arxiv.org/abs/2609.22688v4) | References, sketch placement and dependencies affect design intent under edits | Use explicit datums/semantic references and verify a real parameter change, separately from initial shape validity. This does not claim this kernel implements DIP-CAD or inherits its reported gains. |
9
+ | [Parametric CAD Bench v3, arXiv 2611.02659v1](https://arxiv.org/abs/2611.02659v1) | Geometry, specification and modeling history require separate evaluation; scores describe complete agent systems | Separate creation, edit preservation and drawing reconstruction; retain inspectable artifacts. No leaderboard score is attributed to Colocad. |
10
+ | [Anthropic: Writing effective tools for agents](https://www.anthropic.com/research/writing-tools-for-agents) | Tool boundaries, informative responses and realistic evaluations matter | Keep semantic operations, preserve schemas/errors, and provide a compact receipt with paths to full evidence. The adapter is tested against actual local native calls. |
11
+ | [Anthropic: Effective context engineering](https://www.anthropic.com/research/effective-context-engineering-for-ai-agents) | Relevant context can be loaded on demand and task state kept outside the immediate prompt | Load selected views/references; persist source IDs, accepted revision, unknowns and the next check. Do not repeat complete meshes or traces in every turn. |
12
+ | [Claude Platform: Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) | Concision, progressive disclosure, appropriate freedom and usage-based validation | A short skill entry point routes to task-specific references, executable helpers and filled assets. Prompt examples are adaptable, not mandatory approvals. |
13
+ | [HIWIN: KK-series catalog](https://hiwin.com/wp-content/uploads/2026/08/HIWIN-Ballscrew-Driven-Stages-Catalog-1.pdf) | Dimensions/configurations for the selected real product | Source interfaces to the catalog and explicitly label approximate internals. The file hash/pages and assumptions are in the example's sources.json. |
14
+
15
+ ## What was actually executed
16
+
17
+ - KK60: native construction and assembly across 16 milestones, 52 final features and 81 named solids; independent OCCT STEP checks, material probes and selected rail/carriage clearance checks. [Evidence](../showcase/hiwin-kk60/verification.json).
18
+ - A complete KK60 build in Linux arm64, 1 vCPU / 512 MiB, network disabled, with preview. One run; no peak-memory sampling or equivalent build123d run for this product. [Execution scope](../showcase/hiwin-kk60/evidence.json).
19
+ - SDK/session/error recovery, Pi integration, offline viewer controls/framing, CLI MP4 export, and installed-package checks. The new compact tool adapter and guided workflow execute real native geometry and quantitative edits; their decisions are scripted.
20
+ - The skill's structure/references and packaged examples are validated. No cross-model blind reconstruction study or skill-prompt ablation is claimed.
21
+
22
+ A native geometry pass, a harness integration pass, a successful agent run and a controlled skill improvement are distinct kinds of evidence. The handbook keeps those distinctions explicit.
package/docs/api.md ADDED
@@ -0,0 +1,95 @@
1
+ # SDK, CLI and tool reference
2
+
3
+ Targets `@coloopx/colocad@0.1.0-alpha.5`. The [public declarations](../src/index.d.mts) and [kernel declarations](../kernel/src/types.ts) are the complete type contracts.
4
+
5
+ ## Feature-tree SDK and CLI
6
+
7
+ ```js
8
+ import { build, compileTree, kernelModel } from '@coloopx/colocad';
9
+ const resolvedFeatures = compileTree(tree);
10
+ const model = kernelModel(tree);
11
+ const result = await build(tree, './new-part', { preview: true });
12
+ // result: { directory, step, nativeJob, geometry }
13
+ ```
14
+
15
+ `build` accepts `preview?: boolean` and `binary?: string`. It rejects an existing destination and throws on failure. The directory contains a `part/` subdirectory. `compileTree` validates/resolves the feature instructions without building a solid.
16
+
17
+ ```text
18
+ colocad plan TREE.json
19
+ colocad build TREE.json NEW_DIRECTORY [--preview]
20
+ colocad solidworks NATIVE-JOB.json NEW_FILE.SLDPRT
21
+ ```
22
+
23
+ CLI success prints JSON to stdout. Failure prints an error to stderr and exits nonzero. Feature-tree CLI input is limited to 2 MiB. The third command is the [experimental Windows author](../README.md#native-solidworks-author-experimental).
24
+
25
+ ## Kernel SDK
26
+
27
+ ```js
28
+ import { CadClient, createCadTools } from '@coloopx/colocad';
29
+ const cad = new CadClient({ outputRoot: '/workspace/cad-output', wallMs: 30000 });
30
+ const receipt = await cad.build(model);
31
+ if (!receipt.ok) throw new Error(JSON.stringify(receipt.error));
32
+ console.log(receipt.data.artifact_directory, receipt.data.geometry);
33
+ ```
34
+
35
+ The host chooses `outputRoot`, a local directory for generated revisions, and optionally `binary`, an executable override. `wallMs` defaults to 30,000 and accepts 1–120,000 ms per native invocation. The directory is created as needed. A call runs a local Rust child process in the same sandbox. The SDK does not provision CPU or memory limits; the surrounding sandbox does that.
36
+
37
+ | Method | Meaning |
38
+ | --- | --- |
39
+ | `capabilities()` | Native version, supported operations, budgets and declared limitations |
40
+ | `schema()` | Complete kernel model JSON Schema |
41
+ | `validate(model)` | Cheap input/dependency/budget preflight; no geometric validity guarantee |
42
+ | `build(model, previousRevision?)` | Build/check exact geometry and export a new revision; optional checkpoint source |
43
+ | `edit(model, parameters)` | Change existing numeric parameters, then build; input remains unchanged |
44
+ | `preview(model, options?)` | Build or reuse a matching display mesh and render it |
45
+ | `observeArtifact(directory, options?)` | Render from a trusted saved mesh with integrity checks |
46
+ | `inspect(artifactDirectory)` | Read `report.json`; returns a record and can throw on I/O failure |
47
+ | `solveSketch(sketch, parameters?)` | Solve constraints and report degrees of freedom/residuals |
48
+ | `inspectStep(model, assetId)` | Inspect registered STEP and return a model template; reuse `model.assets` when building it |
49
+
50
+ Apart from `inspect`, these methods return a discriminated receipt:
51
+
52
+ ```ts
53
+ { ok: true, data: Record<string, unknown> }
54
+ // or
55
+ { ok: false, error: { code: string, message: string, feature_id?: string } }
56
+ ```
57
+
58
+ Build receipts include `artifact_directory`, `geometry`, `validation`, feature reports, `timing_ms` and `artifact_sha256`. Available fields vary by operation; a validate/capabilities/observation result is not a build result. Keep the full receipt for diagnostics; send the model a compact summary and any requested PNG.
59
+
60
+ Preview options include `view: "iso" | "top" | "bottom" | "front" | "back" | "left" | "right"`, image size, `chord_mm` and section settings. Use the schema for exact fields and limits. A different camera can reuse geometry; changing mesh precision or geometry can require new work.
61
+
62
+ The kernel SDK limits serialized input to 32 MiB. Query capabilities for native feature, assembly and mesh budgets. The SDK has no in-flight `AbortSignal` contract in alpha.5: the Pi example checks cancellation before dispatch, while an already-running native call is bounded by `wallMs`.
63
+
64
+ ## Agent tools
65
+
66
+ `await createCadTools(cad)` returns definitions with `{ name, description, inputSchema, execute }`. Register them using your harness's tool interface:
67
+
68
+ | Tool | Arguments |
69
+ | --- | --- |
70
+ | `cad_capabilities` | `{}` |
71
+ | `cad_validate` | `{ model }` |
72
+ | `cad_build` | `{ model }` |
73
+ | `cad_preview` | `{ model, options? }` |
74
+ | `cad_edit` | `{ model, parameters }` |
75
+ | `cad_solve_sketch` | `{ sketch, parameters? }` |
76
+ | `cad_inspect_step` | `{ model, asset }` |
77
+
78
+ Preserve the complete `inputSchema`, including root `$defs`. Do not wrap it without rewriting `$ref` locations. These definitions are transport-neutral; the package does not launch an MCP server. If a provider rejects the union-heavy schema, use the skill with shell tools or build a provider-specific schema adapter and test its validation behavior.
79
+
80
+ The Pi example exposes the first five tools for a smaller modeling surface. It converts failed receipts into failed tool results and includes PNG bytes in image content when a preview is at most 4 MiB. The full model/source is in the artifact directory, not in a fabricated project ID.
81
+
82
+ For STEP imports, use `attachStep(model, assetId, stepText)` from `@coloopx/colocad/kernel`. The host registers text under an opaque ID; the model need not choose arbitrary filesystem paths. The returned model is a copy. [Integration policy and lifecycle](integrations/overview.md).
83
+
84
+ ## Persistent sessions and CLI visualization (alpha.4+)
85
+
86
+ Import `ModelingSession`, `createSessionTools`, `readSessionBundle` and `exportSessionHtml` from `@coloopx/colocad/session`. A recorded edit takes `{parameters}` and uses the accepted source; it does not take the plain tool's `{model, parameters}` input. The browser component is exported at `@coloopx/colocad/viewer`.
87
+
88
+ ```sh
89
+ colocad record MODEL.json SESSION --label "Milestone"
90
+ colocad view SESSION --no-open --port 8787
91
+ colocad replay SESSION review.html
92
+ colocad render SESSION modeling.mp4 --width 1280 --height 800 --fps 15
93
+ ```
94
+
95
+ `record` accepts feature trees or kernel JSON. The viewer serves a local snapshot. `replay` creates a self-contained HTML file. `render` uses optional Playwright/Chromium and FFmpeg to encode actual saved meshes; it writes a movie, poster and manifest. See [modeling history](modeling-history.md) for lifecycle, all options and artifact semantics.
@@ -0,0 +1,45 @@
1
+ # Modeling and integration best practices
2
+
3
+ For the complete material preparation, tool/skill/prompt design, workflow and tuning guide, see the [agent modeling handbook](agent-modeling-handbook.md).
4
+
5
+
6
+ ## Start from the structure that controls the part
7
+
8
+ Use a parameterized asset when it matches the requested geometry. A plate with a hole grid should begin with stock dimensions and grid parameters; a sleeve should begin with outer diameter, bore and length. The [quick-build guide](../skills/colocad/references/quick-build.md) gives datums and checks for eight structures. Adapt the feature program when the part differs; an asset is a starting point, not a replacement for reading the drawing.
9
+
10
+ For an unfamiliar part, write a short dimension table: overall envelope, datum, wall thickness, hole diameters/pitches/depths, symmetry and interfaces. Separate measured dimensions from assumptions. If four views disagree, identify the conflict before treating one as ground truth. Occluded bores and tendon routing need explicit assumptions or sectional evidence.
11
+
12
+ Use stable named parameters for interface dimensions. Preserve feature IDs across revisions. Build stock and main cuts first, inspect them, then add small rounds and secondary details. A failed fillet is easier to diagnose on a correct base shape.
13
+
14
+ ## Choose the cheapest operation that answers the question
15
+
16
+ | Change | Action |
17
+ | --- | --- |
18
+ | Camera or image size only | Reuse `preview()` on the same client, or `observeArtifact()` on a saved mesh |
19
+ | Parameter dimension | `edit()` against the latest accepted source; save the new source |
20
+ | Repeated identical components | Define the part once; place named assembly occurrences |
21
+ | Repeated face bores | Use a hole-grid/pattern operation where it represents the design |
22
+ | Coarse clearance exploration | Use an explicit envelope/simplification, then check the final exact model |
23
+ | New exact geometry | Build a new revision and inspect the affected region |
24
+
25
+ Do not rebuild exact B-rep merely to orbit the view. Conversely, do not use a display mesh to prove hole depth, watertight solid validity or manufacturing tolerances. Export the exact STEP for independent checking.
26
+
27
+ ## Give the agent a small, useful tool surface
28
+
29
+ For routine parts, capabilities, validate, build, preview and edit are enough to start. Add STEP inspection and sketch solving when the task requires them. Supply the skill for workflow guidance and assets; keep the full schema accessible instead of pasting it into every system prompt.
30
+
31
+ Keep model-facing results concise: success/failure, the failing feature if any, solid count, dimensions/volume, validation summary, artifact paths and a preview image. Store the detailed feature trace and timings for diagnostics. Never send a full STEP, mesh JSON or base64 PNG as ordinary text in the conversation when the harness supports image/file attachments.
32
+
33
+ Use a bounded correction loop: locate the failed feature, inspect its inputs and dependencies, change the cause, rebuild, then recheck earlier requirements. Preserve the previous accepted revision until the new one passes. Do not silently drop a failing cut to make a model appear complete.
34
+
35
+ ## Acceptance beyond a screenshot
36
+
37
+ Check solid count, envelope, material volume and critical internal regions. For assemblies, check named occurrences, placements, repeated-part consistency and required clearances. A visually plausible rendering can hide fused fingers, solid-filled holes or inverted placements.
38
+
39
+ Keep a reproducible record: input model, relevant source views and assumptions, package/native version, full receipt, exact STEP and chosen preview settings. For high-value geometry, reopen the STEP using an independent kernel. [Existing OCCT checks](../test/validation/geometry.py) illustrate volume and material probes; they are not a universal verifier for arbitrary parts.
40
+
41
+ ## Measure the workflow you actually deploy
42
+
43
+ Separate fresh-process time to STEP, resident-session edits, preview-only views and full agent turnaround. Record whether startup/import, STEP export, independent validation and inference are included. Measure memory for the sandbox/process tree, not just the parent Node process. Compare matched accepted geometry, not only successful exit codes.
44
+
45
+ The [100-second hand study](../showcase/tendon-hand/window/README.md) compares a fixed revision queue and explicitly excludes live-model inference. Its throughput and memory gains are workload-specific. A sequential primitive benchmark does not establish that all booleans or all complex assemblies are faster.
@@ -0,0 +1,37 @@
1
+ # Models, revisions and artifacts
2
+
3
+ ## Two input formats
4
+
5
+ | | Feature tree | Kernel model |
6
+ | --- | --- | --- |
7
+ | Discriminator | `format: "colocad/1"` | `version: 1` |
8
+ | Units | `mm` | `mm` |
9
+ | Entry point | `build(tree, newDirectory)` / `colocad build` | `CadClient` / skill `scripts/build.mjs` |
10
+ | Operations | Extrude, cut, Z-plane fillet, X/Y linear pattern | Wider native feature set, sketches, imported STEP, assemblies and previews |
11
+ | Output selection | Ordered part history | Explicit `output` feature or named `assembly` occurrences |
12
+ | Parametric source | `feature-tree.json` | `model.json` |
13
+ | Contract | [Type declarations](../src/index.d.mts) | [JSON Schema](../kernel/schemas/model.schema.json), `cad.schema()`, `cad.capabilities()` |
14
+
15
+ Do not send a kernel model to `colocad build`, or wrap a feature tree as the `model` argument of `cad_build`. Use `kernelModel(tree)` to compile the feature tree to a kernel model when moving to the richer SDK.
16
+
17
+ The two profile syntaxes also differ: a feature-tree rectangle uses `center` and `size`; kernel sketch profiles follow the kernel schema. Feature-tree scalars are numbers or `{ "param": "thickness" }`. Kernel scalars additionally support arithmetic expressions such as `{ "op": "div", "a": { "param": "diameter" }, "b": 2 }`.
18
+
19
+ ## Coordinates and identity
20
+
21
+ The feature tree extrudes or cuts along +Z from `startZ` (default 0). Kernel boxes use a lower-corner origin; cylinders start at their base center along +Z. Other sketch planes and frames must be explicit. Choose a datum and units before translating a drawing.
22
+
23
+ Feature IDs identify dependencies and checkpoints. Keep them stable when changing a dimension. In an assembly, define a repeated part once and create named occurrences with placements. Keep moving links separate; union only material that forms one physical solid. The [hand example](../showcase/tendon-hand/README.md) demonstrates this distinction.
24
+
25
+ ## Revision ownership
26
+
27
+ A successful `CadClient.build` returns a new `artifact_directory`. One sequential `CadClient` remembers its previous successful revision for checkpoint reuse. A new client can use `build(model, previousRevisionDirectory)`. The harness owns the accepted source and artifact record; the client is not a persistent project database.
28
+
29
+ `edit(model, patch)` returns a new revision and does **not** mutate `model`. After acceptance, save the returned `model.json` or apply the patch to your owned source. Otherwise a later edit can accidentally revert an earlier change. Retain the source, its receipt, tool version and artifact hashes together.
30
+
31
+ For an unchanged model, `preview()` can reuse a saved mesh. `observeArtifact(directory, options)` also works across SDK processes with a trusted saved preview directory. An observation directory contains display output; its `source_artifact_directory` points to the geometry revision. Keep that source when handing off STEP or pruning old files.
32
+
33
+ ## What editable means
34
+
35
+ JSON parameters and feature definitions can be edited and rebuilt. Exact STEP contains boundary geometry, not the original driving feature history. GLB/STL/PNG are previews. Imported STEP is usable geometry; import does not reconstruct its original CAD history.
36
+
37
+ Generic editable SOLIDWORKS output is a separate experimental Windows author. It requires the installed application and a license, and licensed native rebuild verification is still outstanding. Linux STEP success is not evidence of native `.SLDPRT` feature-tree fidelity. See [validation](validation.md).
@@ -0,0 +1,53 @@
1
+ # Getting started
2
+
3
+ Use Node.js 22+ on Linux x64/arm64 or macOS arm64. Installation downloads the npm package; subsequent CAD calls run locally without Python or a Rust compiler.
4
+
5
+ ## Create and edit a mechanical part
6
+
7
+ Run in a new project directory:
8
+
9
+ ```sh
10
+ mkdir my-cad-project
11
+ cd my-cad-project
12
+ npm init -y
13
+ npm install --save-exact @coloopx/colocad@0.1.0-alpha.5
14
+ cp node_modules/@coloopx/colocad/examples/manifold.json manifold.json
15
+ ./node_modules/.bin/colocad plan manifold.json
16
+ ./node_modules/.bin/colocad build manifold.json ./manifold-v1 --preview
17
+ ```
18
+
19
+ `plan` checks and resolves the feature instructions. `build` creates the geometry. Each `colocad build` destination must be new. Read the returned JSON rather than guessing where files were written.
20
+
21
+ Open `manifold-v1/part/preview.png`. The deliverables are `part/model.step`, the editable `part/feature-tree.json` and `part/report.json`; GLB/STL are display representations. The manifold exercises extrusion, a blind cut, a fillet and a linear pattern.
22
+
23
+ Create `edit.mjs`:
24
+
25
+ ```js
26
+ import { readFile } from 'node:fs/promises';
27
+ import { build } from '@coloopx/colocad';
28
+
29
+ const tree = JSON.parse(await readFile('./manifold.json', 'utf8'));
30
+ tree.parameters.instances = 3;
31
+ const result = await build(tree, './manifold-v2', { preview: true });
32
+ console.log(result.step, result.geometry);
33
+ ```
34
+
35
+ ```sh
36
+ node edit.mjs
37
+ ```
38
+
39
+ This version has three bores instead of four. Keep both revision directories and the accepted source. Editing is regeneration from parameters; STEP does not contain the original feature program.
40
+
41
+ ## Use a quick structure or assembly
42
+
43
+ The skill assets use the more expressive **kernel model** format. They are run by the skill helper rather than the feature-tree CLI:
44
+
45
+ ```sh
46
+ node node_modules/@coloopx/colocad/skills/colocad/scripts/build.mjs \
47
+ node_modules/@coloopx/colocad/skills/colocad/assets/plate-grid.json \
48
+ ./plate-v1 --set length=100 --set xCount=3 --set xPitch=32 --preview
49
+ ```
50
+
51
+ The command prints a `directory` containing `model.json`, `model.step`, `report.json` and preview files. Run it from the project with the installed dependency so the copied skill resolves the correct SDK version. [Eight starting shapes and structures](../skills/colocad/references/quick-build.md) cover stock, pins, balls, tapers, hole grids, sleeves, brackets and housings.
52
+
53
+ For a full SDK cycle with mesh reuse, see [sdk.mjs](../examples/integrations/sdk.mjs) and its [run instructions](../examples/integrations/README.md). For an agent, follow [Codex](integrations/codex.md), [Claude Code](integrations/claude-code.md) or [Pi](integrations/pi.md).
@@ -0,0 +1,52 @@
1
+ # Claude Code
2
+
3
+ Use a project skill with Claude Code's existing Bash and file/image tools. Install colocad **where Claude Code runs**. A local installation is not automatically present in a remote/container session.
4
+
5
+ ## Install in the project
6
+
7
+ From your project's root (with a `package.json`; create one with `npm init -y` if needed):
8
+
9
+ ```sh
10
+ npm install --save-exact @coloopx/colocad@0.1.0-alpha.5
11
+ mkdir -p .claude/skills
12
+ test ! -e .claude/skills/colocad && \
13
+ cp -R node_modules/@coloopx/colocad/skills/colocad .claude/skills/colocad
14
+ ```
15
+
16
+ The command deliberately stops copying if the skill already exists. For an upgrade, review/back up your local changes and replace the whole folder from the newly pinned package. Do not copy only `SKILL.md`.
17
+
18
+ ## Build a part
19
+
20
+ Start Claude Code in the project. Invoke:
21
+
22
+ ```text
23
+ /colocad Make a 100 × 50 × 6 mm mounting plate, with a centered 3 × 2
24
+ array of Ø6 through-holes on 32 × 30 mm pitches. Keep the parameters
25
+ editable, export STEP, inspect top and iso views, and report the output paths.
26
+ ```
27
+
28
+ Claude Code can load a matching skill automatically; explicit `/colocad` makes this first run easy to diagnose. For a shell-only smoke check before inference:
29
+
30
+ ```sh
31
+ node .claude/skills/colocad/scripts/build.mjs \
32
+ .claude/skills/colocad/assets/plate-grid.json ./plate-v1 \
33
+ --set length=100 --set xCount=3 --set xPitch=32 --preview
34
+ ```
35
+
36
+ The command prints the effective artifact directory. Ask Claude Code to read its `report.json` and open `preview.png` with its image-capable file tool. A successful command alone does not establish visual correctness.
37
+
38
+ ## Add a project convention
39
+
40
+ If you want CAD behavior on later tasks, merge this short guidance into your existing `CLAUDE.md`:
41
+
42
+ ```text
43
+ Use the colocad skill for mechanical CAD. Work in mm and keep the parametric
44
+ JSON source with each accepted STEP. Use a new output directory for each build.
45
+ Inspect report.json and the required views; identify inferred dimensions.
46
+ After edits, persist the accepted model rather than reusing stale parameters.
47
+ Return source, STEP and preview paths. Report failed or degraded features.
48
+ ```
49
+
50
+ Keep the installed skill's detailed workflow in the skill instead of duplicating it into every prompt. Existing shell/filesystem permissions still apply. The package does not ship a Claude-specific plugin or an MCP server.
51
+
52
+ Checked against [Claude Code's official skills documentation](https://code.claude.com/docs/en/skills) on 2026-11-07. The copied skill/helper was exercised locally; a Claude Code live-model session was not run in this verification. [Verification scope](verification.md).
@@ -0,0 +1,55 @@
1
+ # Codex
2
+
3
+ Install a project skill and let Codex use its existing terminal and image tools. The agent, harness and native CAD process run in the same sandbox. Install the npm dependency in that environment, including for a remote Codex task.
4
+
5
+ ## Install in the project
6
+
7
+ From the root of a Node project:
8
+
9
+ ```sh
10
+ npm install --save-exact @coloopx/colocad@0.1.0-alpha.5
11
+ mkdir -p .agents/skills
12
+ test ! -e .agents/skills/colocad && \
13
+ cp -R node_modules/@coloopx/colocad/skills/colocad .agents/skills/colocad
14
+ ```
15
+
16
+ Use the whole folder, including `assets`, `scripts` and `references`. Codex discovers repository skills from `.agents/skills`; the current official guide also documents user-level `~/.agents/skills`. This guide uses the project location so installation and versioning are visible to collaborators.
17
+
18
+ If the target exists, review/back up local skill edits before replacing it with the newly installed version. Do not install a second copy in multiple discovery locations unless you intend to manage that duplication.
19
+
20
+ ## Invoke and inspect
21
+
22
+ In Codex CLI, use `/skills` to check discovery, or mention `$colocad` explicitly:
23
+
24
+ ```text
25
+ Use $colocad to make a 100 × 50 × 6 mm plate with a centered 3 × 2
26
+ array of Ø6 through-holes, pitches 32 × 30 mm. Export editable JSON and
27
+ STEP, inspect top and iso views, and report artifact paths and assumptions.
28
+ ```
29
+
30
+ Attach drawings using your Codex client's normal attachment mechanism. For four views, include a known dimension or scale and state which dimensions may be inferred. If the skill does not appear after a filesystem change, restart the session in the project directory.
31
+
32
+ Before involving a model, verify the local execution path:
33
+
34
+ ```sh
35
+ node .agents/skills/colocad/scripts/build.mjs \
36
+ .agents/skills/colocad/assets/plate-grid.json ./plate-v1 \
37
+ --set length=100 --set xCount=3 --set xPitch=32 --preview
38
+ ```
39
+
40
+ The printed `directory` contains the model, STEP, receipt and preview. Codex should inspect the PNG using an available image tool and read the receipt; a file path alone does not show the rendered shape.
41
+
42
+ ## Project instructions
43
+
44
+ Merge this into your existing `AGENTS.md` if CAD is a recurring task:
45
+
46
+ ```text
47
+ For mechanical CAD, use the colocad skill and the project's pinned npm SDK.
48
+ Keep units, datums and inferred dimensions explicit. Save editable model JSON,
49
+ STEP and the receipt together. Use new revision directories. Check geometry
50
+ and relevant views before accepting an edit. Return exact artifact paths.
51
+ ```
52
+
53
+ The skill does not change Codex permissions. Use the workspace and sandbox policy already configured by your harness; no blanket permission escalation is needed for this integration.
54
+
55
+ Skill discovery paths and invocation were checked against [OpenAI's official skill guide](https://developers.openai.com/codex/skills/) on 2026-11-07, after inspecting the local Codex CLI. The helper commands were run locally. This is not a claim of autonomous reconstruction accuracy across unseen drawings. [Verification scope](verification.md).
@@ -0,0 +1,53 @@
1
+ # Integrate with an existing harness
2
+
3
+ Keep the agent, harness, SDK and native CAD process in the **same sandbox**. Install colocad in the sandbox image or project dependency layer. Bind it to the harness's existing tool execution and artifact storage.
4
+
5
+ ```mermaid
6
+ flowchart LR
7
+ subgraph Sandbox[One sandbox]
8
+ A[Agent + existing harness] --> B[Skill + shell tools]
9
+ A --> C[Typed CAD tools]
10
+ B --> D[Local SDK]
11
+ C --> D
12
+ D --> E[Rust child process]
13
+ E --> F[Revision files]
14
+ F --> A
15
+ end
16
+ ```
17
+
18
+ | Harness | Recommended first route | Optional route |
19
+ | --- | --- | --- |
20
+ | Codex | Project skill + existing shell/image tools | Host-provided tool bridge |
21
+ | Claude Code | Project skill + existing Bash/Read tools | Host-provided MCP adapter |
22
+ | Pi coding agent | Project skill or explicit `--skill` | Local extension registering CAD tools |
23
+ | Pi agent core / custom TypeScript harness | `createCadTools` through a thin adapter | Existing shell tool + loaded skill instructions |
24
+
25
+ An MCP transport is optional integration code, not a shipped colocad server. A skill supplies workflow guidance; it does not grant filesystem access, install Node, or register typed tools by itself.
26
+
27
+ ## Session lifecycle
28
+
29
+ 1. Allocate a session output root from trusted harness state. Load the pinned package and skill once; record package and native versions.
30
+ 2. Parse the task into dimensions, datum, constraints and explicit assumptions. Pick a kernel model or a feature tree deliberately.
31
+ 3. Preflight the source, then build a geometry revision. Return failures with their feature ID so the agent can correct the relevant feature.
32
+ 4. Inspect the result: geometry counts/bounds/volume, requested views and any internal regions. Persist the accepted source and receipt before moving to the next edit.
33
+ 5. Return artifact references through the harness's existing attachment system. Upload or copy the source, STEP, receipt and useful previews before the sandbox is destroyed.
34
+
35
+ With typed tools, allocate one `CadClient` for each sequential modeling session. Do not share its mutable revision/cache state across unrelated concurrent sessions. Schedule independent jobs with separate clients and output roots, and cap concurrency according to actual sandbox memory. The Pi sample deliberately serializes modeling calls.
36
+
37
+ With shell tools, use argument arrays in a process API rather than interpolating model text into shell commands. Store JSON in a file. Agent-controlled dimensions belong in model input; executable paths, output roots and credentials belong to harness configuration. Keep normal harness permissions in force.
38
+
39
+ ## Results and failures
40
+
41
+ A useful tool result includes the artifact directory, counts/bounds/volume, validation summary and timings. Keep detailed feature diagnostics in the full receipt and attach a PNG for visual inspection. A path in text is not itself an image input to a remote vision model. The [Pi adapter](../../examples/integrations/pi-tools.mjs) shows text/image content and full `details` together.
42
+
43
+ `cad_validate` success is only preflight. A nonzero child exit, a failed receipt or an explicit degraded feature must remain visible. Do not turn a failed build into a success containing an empty output path. Do not retry the same invalid geometry indefinitely; change the failing feature or report the unresolved constraint.
44
+
45
+ The `on_fail` record policy is an explicit degraded-model choice, not a general recovery default. Its object includes `kind: "record"`, a reason, omitted details and affected requirements. Check recorded degradations before accepting a revision; the Pi adapter includes these in model-visible text. Preserve the original exact model when using a simplified display/envelope representation.
46
+
47
+ ## Resource and storage policy
48
+
49
+ Start with the default 30-second call budget and one active native operation. Increase the budget for a measured workload; do not infer a universal 512 MiB allowance from one benchmark. Account for agent runtime, Node, native descendants, previews and file cache in a real sandbox measurement.
50
+
51
+ For multiple camera angles, use the same client or `observeArtifact`. For repeated parts, reuse a part definition and place occurrences. Keep cache/source revisions while referenced; artifact cleanup is a host policy and must not delete a live observation's source STEP.
52
+
53
+ Use [Pi](pi.md), [Claude Code](claude-code.md) or [Codex](codex.md) for concrete setup. [Best practices](../best-practices.md) covers modeling and performance choices.
@@ -0,0 +1,73 @@
1
+ # Pi agent core and Pi coding agent
2
+
3
+ The adapter is tested with `@earendil-works/pi-agent-core@1.5.0` and `@earendil-works/pi-coding-agent@1.5.0`. Pi APIs have changed across releases: pin the versions in your harness and run the adapter tests before upgrading. Older harnesses can use the skill/CLI route without replacing their agent core.
4
+
5
+ ## Pi agent core: register local tools
6
+
7
+ Clone the example project and install its lockfile:
8
+
9
+ ```sh
10
+ git clone https://github.com/Coloopx/colocad.git
11
+ cd colocad/examples/integrations
12
+ npm ci --ignore-scripts
13
+ npm test
14
+ ```
15
+
16
+ [pi-tools.mjs](../../examples/integrations/pi-tools.mjs) adapts colocad's JSON Schemas and receipts to Pi `AgentTool`s. [pi-core.mjs](../../examples/integrations/pi-core.mjs) constructs an agent with these tools. Your harness supplies its existing model, stream function and authentication:
17
+
18
+ ```js
19
+ import { createCadAgent } from './pi-core.mjs';
20
+
21
+ // model, streamFn and getApiKey come from your existing harness configuration.
22
+ const agent = await createCadAgent({
23
+ model, streamFn, getApiKey,
24
+ outputRoot: '/workspace/cad-output/session-001',
25
+ });
26
+ await agent.prompt('Build an 80 × 50 × 6 mm mounting plate with four Ø6 holes. '
27
+ + 'Use a centered 2 × 2 grid at 50 × 30 mm pitch. Export STEP and inspect a preview.');
28
+ ```
29
+
30
+ This is a host wiring fragment, not a standalone provider login script. Pi core 1.5 requires a `streamFn`. For an existing agent, merge the returned tools into its tools array while idle, retaining your existing tools and context policies:
31
+
32
+ ```js
33
+ import { createPiCadTools } from './pi-tools.mjs';
34
+ const cadTools = await createPiCadTools({ outputRoot: '/workspace/cad-output/session-001' });
35
+ agent.state.tools = [...agent.state.tools, ...cadTools]; // register once; names must be unique
36
+ ```
37
+
38
+ The adapter preserves schema `$defs`, serializes CAD operations, throws on failed receipts, and attaches preview PNG content. It does not add a database or copy artifacts outside the sandbox. The harness still owns accepted model state, attachments, token budget and session persistence.
39
+
40
+ ## Pi coding agent: use the extension
41
+
42
+ From the example project after `npm ci`:
43
+
44
+ ```sh
45
+ ./node_modules/.bin/pi --extension ./pi-extension.mjs
46
+ ```
47
+
48
+ The extension registers five `cad_*` tools. Output defaults to `./cad-output`; set `COLOCAD_OUTPUT_DIR` in the shell launching Pi to choose a trusted absolute destination. Start it from the intended project directory and restart/rebind when changing projects. Use Pi's existing model/auth configuration.
49
+
50
+ For the modeling workflow as well, load the bundled skill:
51
+
52
+ ```sh
53
+ ./node_modules/.bin/pi --extension ./pi-extension.mjs \
54
+ --skill ./node_modules/@coloopx/colocad/skills/colocad
55
+ ```
56
+
57
+ Use `/skill:colocad` with the part description. The skill may use the shell helper for its starting assets; the extension adds direct typed tools. You can use either route independently.
58
+
59
+ ## Skill-only integration
60
+
61
+ In a project where colocad and Pi are already installed:
62
+
63
+ ```sh
64
+ mkdir -p .agents/skills
65
+ test ! -e .agents/skills/colocad && \
66
+ cp -R node_modules/@coloopx/colocad/skills/colocad .agents/skills/colocad
67
+ ```
68
+
69
+ Start Pi in that project and invoke `/skill:colocad`. Keep the complete folder: its instructions reference scripts, assets and supporting guides. Review the project skill under Pi's normal project trust flow. No global install or permissions bypass is required.
70
+
71
+ The example tests execute the actual Pi core loop with deterministic model responses, the actual extension loader, and the published Rust binary. They do not call a live model provider. See [verification scope](verification.md).
72
+
73
+ References checked 2026-11-07: [Pi core](https://github.com/earendil-works/pi/tree/main/packages/agent), [extensions](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md), [skills](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md). The installed 1.5.0 declarations and CLI help were also checked.
@@ -0,0 +1,30 @@
1
+ # Integration verification
2
+
3
+ Verified on **2026-11-07**, Node.js **22.23.3**, **macOS arm64**, using the public npm package **@coloopx/colocad@0.1.0-alpha.3** and its bundled Rust binary. Pi core, Pi AI and Pi coding agent are pinned to **1.5.0** in the example lockfile.
4
+
5
+ | Check | Result | What it establishes |
6
+ | --- | --- | --- |
7
+ | SDK validate → preview → camera change → parameter edit | Pass | Real geometry, cached observation, expected removed volume and persisted source |
8
+ | Pi adapter schemas, preview image, failure mapping and cancellation before dispatch | Pass | Complete `$defs`, valid PNG content, error results and no dispatch after pre-cancellation |
9
+ | Explicit degraded feature | Pass | The omitted fillet and native error remain in model-visible tool text |
10
+ | Pi core tool loop with a failed edit then corrected build | Pass | Actual agent loop propagates failure and resumes to a successful STEP export |
11
+ | Pi coding agent extension loader and skill discovery | Pass | Five executable CAD tools register; the complete skill is discoverable |
12
+ | Existing root Node regression suite | 5 passed | Feature compiler, edits, output collision handling and native-output refusal |
13
+ | Documented CLI and copied skill commands | Pass | Feature-tree planning/build/edit and kernel-model helpers execute from a consuming project |
14
+ | Independent OCCT STEP readback | 4 passed | Two manifold revisions and two copied-skill plates are valid single solids with checked material regions |
15
+
16
+ [Machine-readable results, volumes, probes and STEP hashes](../evidence/harness-integrations.json).
17
+
18
+ Reproduce the integration tests from the repository root:
19
+
20
+ ```sh
21
+ npm ci --prefix examples/integrations --ignore-scripts
22
+ npm test --prefix examples/integrations
23
+ node examples/integrations/sdk.mjs ./out/sdk-example
24
+ ```
25
+
26
+ The five integration tests run native CAD operations and actual Pi library code. The model response stream is deliberately scripted: no provider API key, inference request or autonomous model decision is involved. Thus the result verifies execution contracts and recovery, not unseen-drawing success rate or a model's ability to choose the correct CAD features.
27
+
28
+ Codex skill paths/invocation and Claude Code skill paths/invocation were checked against their official documentation. The bundled helper was run from both `.agents/skills/colocad` and `.claude/skills/colocad`. No Claude Code live session was run, and this test run did not evaluate a live Codex model reconstructing a drawing. The Pi live-provider schema negotiation remains dependent on the provider you configure.
29
+
30
+ This verification adds no new performance claims. Cross-platform npm release checks are recorded separately in [release-alpha.3.json](../evidence/release-alpha.3.json); the new adapter regression itself was run on macOS arm64. Native SOLIDWORKS acceptance remains subject to the [existing limitations](../validation.md).
@@ -0,0 +1,77 @@
1
+ # 实际建模操作、数据流与完整产品的验收
2
+
3
+ [完整方案:材料、工具、skill/提示词、调优](agent-modeling-handbook.zh-CN.md)在本次操作记录基础上给出可复用方法。
4
+
5
+ 本说明区分已执行的操作与下一阶段拟采用的方法。熟悉某类机械的原理,有助于拆解设计;具体型号的尺寸、公差和内部结构仍需资料与测量支持。
6
+
7
+ ## 当前实际执行了什么
8
+
9
+ 本次实际完成的是 [HIWIN KK60 完整执行器复建](../examples/hiwin-kk60/README.md),配置为 300 mm 导轨、5 mm 导程、单滑块、无选配电机与罩壳。此前的涡扇仍只是合成几何测试件。
10
+
11
+ | 阶段 | 实际输入与操作 | 实际输出 |
12
+ | --- | --- | --- |
13
+ | 查资料与读图 | 厂家目录 PDF;提取尺寸文字,渲染第 25 页,再放大检查剖视图 | 指定型号/配置,尺寸来源、坐标基准与假设清单 |
14
+ | 纠正读图 | 放大 SECTION A-A,把误读的 15 mm 丝杠中心高纠正为 23 mm | 更新共轴零件与接口尺寸 |
15
+ | 编写几何程序 | 助手依据图纸、数值和接口编写 `model.mjs` | 52 个特征及 81 个命名实例的生成器;运行时开放行程参数 |
16
+ | 实际执行 | 生成明确的 kernel JSON,调用 `ModelingSession.build` | 16 个阶段的源文件、回执、精确 STEP、预览网格 |
17
+ | 处理失败 | 总装触发内部 STEP 的 10 万实体限制 | 修复内部序列化预算、增加 Rust 回归;保留原失败会话 |
18
+ | 独立检查 | 用 OCCT 读回 STEP,检查实体、体积、孔/槽材料点与行程端点 | 可复现的验证脚本与 JSON 结果 |
19
+ | 人类查看与交付 | `colocad view / replay / render` | 本地查看器、单文件 HTML、四视图 MP4/GIF、整机 STEP |
20
+
21
+ **图像转参数化指令是本次助手读图与编程产生的中间结果,不是要求用户预先提供的输入,也不是 colocad 内置的自动图像转换能力。** 我先读取文字/图像并形成尺寸判断,再编写程序,colocad 执行明确指令。当前没有经过盲测的“任意图纸一键工业级复建”结论。
22
+
23
+ 资料不足的内部结构仍标为假设:螺旋槽是有几何实体的近似,螺母回珠通道未还原,不能将验证通过解释为制造精度认证。动画也没有隐藏这些范围说明。
24
+
25
+ ## 更适合真实产品任务的输入
26
+
27
+ 先确定唯一的产品目标:厂家、型号、变型、行程或尺寸配置、版本。目标交付是该配置的完整产品,零件图和 BOM 是输入资料。优先取得总装尺寸、剖面、零件图、接口图和实物照片;若有参考 CAD,可单独留给验收使用。
28
+
29
+ 输入不必全是图片。矢量 PDF 的尺寸文字、厂家参数表、图纸图像、剖视图和必要的局部裁图各有作用。图像提供视图对应和空间结构;准确数值优先取尺寸标注/表格;清晰度不足或互相矛盾的标注不能靠视觉印象补成精确值。照片通常用于核对形态,不作为未经标定的尺寸来源。
30
+
31
+ ## 从本次操作整理的工作方法:尚非盲测通过的通用能力
32
+
33
+ 1. **固定完整产品的规格。** 建立单位、坐标系、投影法、型号配置和验收范围,先确定总装包络、主要轴线、运动方向与安装接口。
34
+ 2. **建立可追溯的尺寸记录。** 每个关键参数记录原文件、页码、标注区域、数值和单位。分清图纸给定、由关系推导、暂时假设、尚未知四种状态。关键未知项应体现在完成度中。
35
+ 3. **先规划总装约束。** 建立零件定义、实例、父子关系、基准与配合接口。不要先随意画一批零件,再靠移动拼成看起来相似的产品。
36
+ 4. **生成小步的建模程序。** 助手按工程含义选择旋转、拉伸、切除、扫掠、放样、阵列等操作,使用稳定 ID、命名尺寸和关系式。先实现安装与运动接口,再处理次要外观细节。重复件复用定义。
37
+ 5. **执行并读取反馈。** 每个有意义的里程碑由 CLI/SDK 实际构建,保存输入和回执。失败后根据 feature ID 和几何反馈修改,保留失败记录。不能用略去关键结构来换取成功状态。
38
+ 6. **定向检查,再接受版本。** 内核有效性、图纸尺寸、装配关系分别验证。生成与原图一致的投影视角/剖面检查轮廓和孔位;独立回读 STEP 检查实体、体积及内部区域。调整参数后复查受影响的接口和整机包络。
39
+
40
+ 建议中间数据与内核输入分开保存:
41
+
42
+ ```text
43
+ product.json 型号、配置、单位、坐标与整机验收要求
44
+ sources/ 原始资料、页码与局部裁图
45
+ measurements.json 尺寸、来源、推导关系与未知项
46
+ interfaces.json 零件间接口、装配基准和运动关系
47
+ model.mjs 必要时使用的可编辑参数生成程序
48
+ model.json 给 colocad 的明确几何指令
49
+ history/ 每次实际执行的输入、回执、STEP 和预览
50
+ ```
51
+
52
+ 其中前四项是建议的任务数据约定,当前不是 colocad 内核 schema 的新增字段,也还没有自动提取器。不能把这些任意字段塞入 kernel model。
53
+
54
+ ## 给助手的有效任务约束
55
+
56
+ 比“照图做一个工业级模型”更明确的提示应包含:
57
+
58
+ ```text
59
+ 目标:还原指定厂家、型号、配置的完整产品。
60
+ 依据:列出图纸/手册文件及其版本,指定优先来源。
61
+ 单位与基准:确认投影法、总装坐标、主要轴线。
62
+ 精度目标:列出应核对的尺寸、公差、配合和行程。
63
+ 未知项:不得默默替换为确定尺寸;单独记录假设与影响。
64
+ 执行:先列整体布局和接口,再分阶段建模;保留失败与修改。
65
+ 验收:给出整机、关键接口、内部结构的测量与对应视图。
66
+ 交付:可编辑源、整机 STEP、建模会话、CLI 导出的离线回放。
67
+ ```
68
+
69
+ 不要只靠一个很长的提示。每轮仅给当前子系统所需的清晰视图、相关尺寸和接口约束,并保留共享整机基准。让校验返回具体数值与误差,而非只有“看着不对”。这套方法是否提高成功率,应通过实际任务记录证明。
70
+
71
+ ## 如何判断效果真的提升
72
+
73
+ 在相同型号、资料、模型版本和预算下,比较尺寸识别正确率、关键特征遗漏、独立几何检查、装配接口误差、未知项数量与人工修改次数。推理时间/费用、CAD 执行、预览分别计量。执行器更快,不直接等于读图更准;实体数更多也不等于完整产品更准确。
74
+
75
+ 对于滚珠丝杠执行器,完整产品验收应覆盖所选配置的轨道/壳体、滑台、丝杠螺母、支承与连接,以及实际公开资料能确定的内部结构;还包括轴线关系、安装孔位、行程端点和旋转—平移关系。仅有外形 CAD 时,不能据此声称滚道、滚珠回流和制造公差均已还原。
76
+
77
+ [CLI 查看与导出](modeling-history.md) · [本次真实产品实例](../examples/hiwin-kk60/README.md)