@coloopx/colocad 0.1.0-alpha.3 → 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.
Files changed (53) hide show
  1. package/NOTICE.md +2 -0
  2. package/README.md +130 -4
  3. package/README.zh-CN.md +111 -4
  4. package/bin/colocad.mjs +28 -4
  5. package/docs/README.md +28 -0
  6. package/docs/README.zh-CN.md +85 -0
  7. package/docs/agent-modeling-handbook.md +68 -0
  8. package/docs/agent-modeling-handbook.zh-CN.md +222 -0
  9. package/docs/agent-modeling-research.md +22 -0
  10. package/docs/api.md +95 -0
  11. package/docs/best-practices.md +45 -0
  12. package/docs/concepts.md +37 -0
  13. package/docs/getting-started.md +53 -0
  14. package/docs/integrations/claude-code.md +52 -0
  15. package/docs/integrations/codex.md +55 -0
  16. package/docs/integrations/overview.md +53 -0
  17. package/docs/integrations/pi.md +73 -0
  18. package/docs/integrations/verification.md +30 -0
  19. package/docs/modeling-history.md +60 -0
  20. package/docs/modeling-workflow.zh-CN.md +77 -0
  21. package/docs/troubleshooting.md +25 -0
  22. package/docs/validation.md +23 -0
  23. package/examples/hiwin-kk60/README.md +55 -0
  24. package/examples/hiwin-kk60/model.mjs +94 -0
  25. package/examples/hiwin-kk60/run.mjs +14 -0
  26. package/examples/hiwin-kk60/sources.json +88 -0
  27. package/examples/integrations/README.md +47 -0
  28. package/examples/integrations/compact-tools.mjs +27 -0
  29. package/examples/integrations/guided-workflow.mjs +31 -0
  30. package/kernel/native/darwin-arm64/agent-cad +1 -1
  31. package/kernel/native/darwin-arm64/manifest.json +1 -2
  32. package/kernel/native/linux-arm64/agent-cad +1 -1
  33. package/kernel/native/linux-arm64/manifest.json +1 -2
  34. package/kernel/native/linux-x64/agent-cad +2 -2
  35. package/kernel/native/linux-x64/manifest.json +2 -3
  36. package/kernel/release.json +4 -4
  37. package/package.json +40 -4
  38. package/skills/colocad/SKILL.md +18 -8
  39. package/skills/colocad/assets/product-brief.example.json +20 -0
  40. package/skills/colocad/references/history.md +19 -0
  41. package/skills/colocad/references/materials.md +37 -0
  42. package/skills/colocad/references/modeling-loop.md +33 -0
  43. package/skills/colocad/references/prompt-patterns.md +70 -0
  44. package/skills/colocad/references/tool-contracts.md +33 -0
  45. package/skills/colocad/references/tuning.md +30 -0
  46. package/src/render.mjs +72 -0
  47. package/src/session.d.mts +34 -0
  48. package/src/session.mjs +140 -0
  49. package/src/view-server.mjs +50 -0
  50. package/viewer/THREE-LICENSE +21 -0
  51. package/viewer/dist/index.js +4236 -0
  52. package/viewer/dist/standalone.js +4236 -0
  53. package/viewer/index.d.ts +18 -0
@@ -0,0 +1,222 @@
1
+ # Agent CAD 完整工作指南:资料、工具、建模闭环与调优
2
+
3
+ 本指南对应 colocad alpha.5 的 skill 和可运行示例。目标是把指定产品及其工程依据变成可编辑源、精确几何、可追溯检查和可供人类查看的过程。以下是基于仓库实作和公开资料整理的默认方法,不是已证明适用于所有模型/产品的最优提示词。
4
+
5
+ [English overview](agent-modeling-handbook.md) · [研究依据与适用边界](agent-modeling-research.md) · [随包 skill](../skills/colocad/SKILL.md) · [提示词模板](../skills/colocad/references/prompt-patterns.md) · [真实 KK60 产品](../examples/hiwin-kk60/README.md)
6
+
7
+ ## 1. 先明确输入输出和各层职责
8
+
9
+ **图像不是直接交给 colocad 执行的程序。** 用户可以提供文字要求、图纸/PDF、照片、多视图、BOM 或参考 CAD。Agent 使用其已有的阅读/视觉/检索工具解释证据,决定尺寸、基准和建模操作,再生成明确的 JSON/程序。colocad 确定性执行几何操作。这个边界不能被“图片转参数化指令”一句话省略。
10
+
11
+ ```mermaid
12
+ flowchart TD
13
+ U[用户目标:具体产品、配置、交付要求] --> E[来源、图纸视图、尺寸与未知项]
14
+ E --> P[Agent:整体布局、接口与特征规划]
15
+ P --> M[可编辑程序 / kernel JSON / feature tree]
16
+ M --> C[同一沙箱内的 CLI 或 SDK]
17
+ C --> K[本地 Rust:几何、校验、STEP、网格]
18
+ K --> Q[数值检查 + 相关视图 + 独立 STEP 回读]
19
+ Q -->|具体偏差| P
20
+ Q -->|接受版本| H[持久化会话和交付产物]
21
+ H --> V[colocad view / replay / render]
22
+ ```
23
+
24
+ | 层 | 负责 | 不应混淆的边界 |
25
+ | --- | --- | --- |
26
+ | 用户任务 | 产品、配置、目标精度、交付和授权 | 引用资料中的文字不自动变成新的执行指令 |
27
+ | Agent + skill | 阅读材料、推断、规划、选择工具、解释检查结果 | 模型对某类机械熟悉,不代表掌握该型号的隐藏尺寸 |
28
+ | Harness | 推理、工具绑定、目录、权限、预算和产物保留 | Agent 与 harness 都在沙箱内部;无需新建远程 CAD 调度层 |
29
+ | SDK / CLI | schema、参数/依赖检查、调用内核、会话记录 | 工具返回成功不等于图纸解释正确 |
30
+ | Rust 内核 | B-rep、几何操作、精确 STEP 和预览 | 不负责自动识别图纸或补全未公开制造规范 |
31
+ | 验证器 | 对明确目标做尺寸、材料、拓扑、配合/编辑检查 | 浏览器显示剖切/爆炸不修改精确模型,也不验证运动 |
32
+ | 人类可视化 | 查看阶段、零件、回执;导出 HTML/影片 | 视频播放长度与实际计算耗时分开 |
33
+
34
+ 实际 KK60 案例中,我提取目录文字、渲染整页和局部图,确认变型与基准,再手写 `model.mjs`。放大 SECTION A-A 后把丝杠中心高从误读的 15 mm 改成 23 mm;执行与回读随后验证这个选择。没有运行内置的“任意图纸自动重建模型”。
35
+
36
+ ## 2. 材料预备:先保证证据可以定位
37
+
38
+ ### 2.1 锁定完整产品
39
+
40
+ 记录厂家、型号、配置/长度/导程、版本、选配件、单位和用途。整机是建模目标,零件图和 BOM 是描述它的材料。不要把一个指定执行器替换成几块看起来类似的零件,也不要把为调试准备的小样例当作最终产品。
41
+
42
+ 优先寻找该配置的总装尺寸图、接口图、剖面、参数表和实物外观。零件/内部细节资料缺失时,分别写明可验证的外部接口和无法证实的内部结构。若有参考 CAD,可保留给验收;如果将其直接导入,应明确这是导入或复用,不宣称重新建模。
43
+
44
+ ### 2.2 为图像提供上下文
45
+
46
+ 保留原文件和 URL、日期/图纸版本、页码、文件哈希。先看完整页面确定单位、投影/剖视和表格对应,再裁出当前接口的可读细节,标明它来自哪里。不要只给一个没有基准和尺寸延长线的数字裁图。
47
+
48
+ ```sh
49
+ pdftotext -layout catalog.pdf catalog.txt
50
+ pdftoppm -f 25 -singlefile -scale-to 2400 -png catalog.pdf page-25
51
+ ```
52
+
53
+ 文字提取用来查找数值;图像用于判断数值属于哪个尺寸、视图或零件。照片可辅助外形和装配关系,未经标定的透视图片不能直接给出精确尺寸。多视图有助于消歧,但不能揭示所有隐藏通道或公差。
54
+
55
+ ### 2.3 建立尺寸与接口证据表
56
+
57
+ | 状态 | 保存什么 | 本次案例 |
58
+ | --- | --- | --- |
59
+ | 图纸给定 specified | 数值、单位、页/视图/标注位置 | 丝杠中心高 23 mm、滑台高 33 mm |
60
+ | 关系推导 derived | 表达式、依赖尺寸和基准 | 安装孔站位由 G、孔距和导轨端点推导 |
61
+ | 暂时假设 assumed | 数值/范围、理由、影响的结论 | 未公开轴承滚道尺寸 |
62
+ | 未知 unknown | 缺失内容和不能验证的事项 | 螺母回珠通道 |
63
+
64
+ 定义一个整机坐标系,另为每个零件定义局部 frame。检查直径/半径、通孔/盲孔、深度起点、正常/特殊滑块、角度方向和尺寸表行列。把“重建验收误差”与厂家制造公差分开;自己选择的 0.01 mm 检查阈值不能被写成厂家公差。
65
+
66
+ 需要保证的接口仍有关键未知时,指出缺失的具体值及影响,继续独立部分。不要为每一个非关键假设都停下来要求确认,也不要把未知静默改成确定值。[详细材料规则](../skills/colocad/references/materials.md) · [填好的产品 brief 示例](../skills/colocad/assets/product-brief.example.json)。
67
+
68
+ 推荐任务目录:
69
+
70
+ ```text
71
+ sources/ 原始来源索引、图纸页、必要局部图
72
+ product-brief.json 产品配置、尺寸状态、接口、验收范围(任务数据)
73
+ model.mjs 可编辑生成程序(需要程序化重复结构时)
74
+ model.json 实际送入内核的几何指令
75
+ session/ 每次输入、回执、STEP、网格和失败记录
76
+ verification.json 执行过的检查、数值、来源和未覆盖项
77
+ review.html CLI 导出的单文件查看器
78
+ modeling.mp4 可选;CLI 导出的实际阶段回放
79
+ ```
80
+
81
+ `product-brief.json` 是本指南的资料约定,不是内核接受的新 schema。不要把溯源字段随意塞进 `additionalProperties: false` 的 kernel JSON。
82
+
83
+ ## 3. 工具抽象:从下一步决策设计接口
84
+
85
+ 保留 SDK 的完整 schema 和引用定义,工具层选择少量明确的动作。不要给每个库函数都生成一个远程工具,也不要把所有工作藏在一个没有可检查结果的“生成产品”调用里。
86
+
87
+ | 实际可用入口 | 什么时候用 | Agent 应读取什么 |
88
+ | --- | --- | --- |
89
+ | `cad_capabilities` | 会话开始、选择不熟悉操作时 | 版本、操作、预算、明确不支持项 |
90
+ | `cad_validate` | 开始昂贵构建前 | 参数、依赖和预算错误;它不执行几何验证 |
91
+ | `cad_build` | 一个有意义的特征/接口阶段 | `ok`、几何、失败特征、时间、产物及降级 |
92
+ | `cad_preview` | 观察新的几何或换相关视角 | 实际图像;是否复用网格、源几何目录 |
93
+ | `cad_edit` | 修改已有命名参数 | 新版本尺寸、依赖是否跟随、接受的源 |
94
+ | `cad_solve_sketch` | 确实需要草图约束时 | 局部 DOF、约束残差与冲突 |
95
+ | `cad_inspect_step` | 需要检查/复用已登记 STEP 时 | 产品树、共享定义和变换、导入限制 |
96
+
97
+ 默认可先注册前五项,按任务加入后两项。`CadClient.inspect` 读取保存的报告,不是任意几何查询器;当前工具集也没有自动图纸尺寸识别工具。材料阅读使用现有 harness 的文件/图像工具,独立精确检查使用明确的几何验证程序。
98
+
99
+ 直接 `createCadTools(client)` 的 `cad_edit` 参数是 `{model, parameters}`;`createSessionTools(session)` 的参数是 `{parameters}`,由会话读取最后成功的源。接入时保留这个区别,避免失败后从错误或过时的模型开始改参。
100
+
101
+ ### 3.1 工具返回摘要,不丢失证据
102
+
103
+ 模型通常需要:错误码/feature ID、版本与产物路径、实体数、尺寸/体积、当前相关测量、时间、缓存命中和全部降级项。完整 feature trace、模型和网格保存在文件里,必要时按引用读取。不要每轮把 STEP 文本、大网格和全部历史图片塞回上下文。
104
+
105
+ [compact-tools.mjs](../examples/integrations/compact-tools.mjs) 是实际可运行的无传输层适配器:保持工具 schema/执行语义,压缩成功回执,保留失败/降级与完整回执路径。宿主负责把 `ok:false` 映射为其工具错误格式,并按需要附上 PNG。它是示例适配器,不是额外的 CAD 后台服务。
106
+
107
+ ### 3.2 执行一个完整工具闭环
108
+
109
+ ```sh
110
+ # 源码 checkout
111
+ node examples/integrations/guided-workflow.mjs ./out/guided-workflow
112
+ # 或安装包内的同一示例
113
+ node node_modules/@coloopx/colocad/examples/integrations/guided-workflow.mjs ./guided-workflow
114
+ ```
115
+
116
+ 这个例子实际执行能力查询、校验、建模、孔径修改、体积核对、失败改参、恢复接受的源、缓存观察、长度修改,最后通过 CLI 输出 HTML。检查孔径变化应移除的材料体积和最终长度。它证明工具契约和闭环实现可运行;决策序列是脚本化的,不宣称某个 LLM 在未知图纸上自主完成了这些步骤。
117
+
118
+ ## 4. 典型建模环节与信息流
119
+
120
+ | 环节 | 输入上下文 | Agent 的操作 | 输出和验收 |
121
+ | --- | --- | --- | --- |
122
+ | 目标定义 | 用户目标、产品配置 | 确定整体交付和必须保持的接口 | 产品 brief、成功条件 |
123
+ | 解释材料 | 当前接口的总图/剖面/表格 | 对应视图、建立尺寸证据和基准 | 带来源和不确定性的尺寸表 |
124
+ | 布局与特征规划 | 尺寸、接口、已有参数源 | 唯一零件定义、实例、依赖和局部 frame | 特征计划与具体检查 |
125
+ | 构建 | 当前明确 JSON | validate 后执行 build/record | 新版本、回执、精确几何 |
126
+ | 定向检查 | 变化特征及目标值 | 相关投影/剖面、数值/材料/配合检查 | 偏差和证据;接受或修复 |
127
+ | 改参验证 | 被接受的源和目标变更 | 改主参数、重建、复查依赖接口 | 可编辑性证据,保留失败 |
128
+ | 整机与交付 | 所有部件、必要姿态 | 组合检查、独立 STEP 回读 | 整机 STEP、会话、结果报告 |
129
+ | 人类审阅 | 已保存的真实结果 | CLI view/replay/render | 查看器、单文件 HTML、动画 |
130
+
131
+ 简单零件可合并这些环节。长任务在有工程意义的节点保存里程碑:截面/毛坯、关键孔腔、相配接口、子总成、整机。只记录零件放置不能解释建模过程;每一条微小操作都单独启动一轮模型推理也不经济。
132
+
133
+ ### 4.1 参数和特征设计
134
+
135
+ 从控制外形的截面开始。板/轴/球/锥可用单特征;套筒用带孔截面;壳体用壁厚/底厚和开口关系;重复孔用原生孔阵列;重复零件只建一个定义再实例化。优先复用[快速搭建资产](../skills/colocad/references/quick-build.md),替换实际参数和必要特征,避免从任意网格逼近规则结构。
136
+
137
+ 把中心对称、共轴、厚度、孔距和运动关系写为参数表达式。使用稳定的语义 feature ID、零件 ID 和明确局部坐标。几何引用和约束需要在编辑后仍表达设计意图,不能只让原始形状看起来对。[DIP-CAD 的研究](https://arxiv.org/abs/2609.22688v4)也将引用、局部坐标和编辑后依赖保持作为独立问题;其结果不等于本库已经获得相同成功率。
138
+
139
+ ### 4.2 失败恢复
140
+
141
+ 先分辨是读图错误、frame/单位、参数依赖、几何操作、预算、预览,还是工具传输失败。查看具体 feature ID、操作数和错误,缩小到能复现问题的子模型;不要同时改一批无关尺寸。
142
+
143
+ 保留失败输入和回执,从最后接受的源修复。不要靠删掉必需的孔、螺旋槽、圆角来换一个成功状态。用户明确允许的可选省略才可以降低对应交付范围,并保留降级说明。新证据应更新来源/假设记录,而非只改模型里的一个数值。
144
+
145
+ KK60 的真实螺旋槽让总装触发内部 STEP 实体数限制,最终修复的是内部序列化预算,同时维持外部导入限制;没有减少 56 圈螺纹来绕过问题。四视图镜头裁切则通过正交取景和包络测试修复,没有缩短精确模型。
146
+
147
+ ## 5. 提示词和 skill 怎么组织
148
+
149
+ `SKILL.md` 保留能力范围、入口选择和关键判断;材料处理、完整产品循环、工具契约、提示词、调优、可视化分别在按需读取的 references 中。基础形状和产品 brief 放 assets,确定性执行放 scripts/examples。不要把整份工程手册和所有例外都常驻系统提示。这与 [Anthropic 的 skill 编写建议](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)关于简洁、按需披露和按任务脆弱程度约束行为的原则一致。
150
+
151
+ 可以直接使用的任务提示:
152
+
153
+ ```text
154
+ 使用 colocad skill,依据提供的厂家/型号/配置材料重建完整产品。
155
+ 交付可编辑源、整机 STEP、建模会话,以及由 CLI 导出的离线 HTML 和指定动画。
156
+ 先确定单位、整体基准和关键接口;区分给定、推导、假设、未知尺寸。
157
+ 图像作为证据,由你解释并生成明确建模指令,不把未知隐藏结构写成确定制造尺寸。
158
+ 在有意义的几何/装配里程碑执行构建,检查相关视图和具体数值偏差。
159
+ 失败保留输入与回执,针对原因修复,不能省略必需几何来宣称成功。
160
+ 按目标做改参/配合/STEP 回读检查,列出实际通过与未覆盖的内容。
161
+ ```
162
+
163
+ 后续轮次只提供当前子系统所需的材料、接口、接受源和检查结果。修复提示写出错误/偏差和稳定 ID;检查提示写明目标值、误差和对应主张。长任务交接保留产品、基准、源文件/哈希、已通过检查、失败、未知项和下一项检查。[分阶段提示词](../skills/colocad/references/prompt-patterns.md)可按任务直接调整。
164
+
165
+ 这不是要求模型输出隐含推理链。需要的是可检查的尺寸表、设计决策、程序、执行结果和结论依据。
166
+
167
+ ## 6. 质量验收:把结论拆开
168
+
169
+ | 结论 | 需要的证据 | 单独不足以证明它的结果 |
170
+ | --- | --- | --- |
171
+ | 几何有效 | 实体/壳体有效性、体积、STEP 回读 | 进程退出 0 |
172
+ | 符合尺寸 | 有来源的关键尺寸和定位检查 | 单张漂亮渲染 |
173
+ | 内部孔腔正确 | 孔轴/直径/深度、内外材料点和剖面 | 外轮廓或总体积相似 |
174
+ | 可编辑 | 实际改变主参数,复查关联几何/接口 | JSON 里有 parameters 字段 |
175
+ | 能装配/运动 | 所需姿态和相关零件对的干涉/间隙、耦合关系 | 爆炸视图和插值动画 |
176
+ | 制造可用 | 必需公差、材料、工艺、功能/强度等相应验证 | 目录接口复建 |
177
+
178
+ [Parametric CAD Bench v3](https://arxiv.org/abs/2611.02659v1)把几何、规格和建模历史纳入评估,并区分创建、改参和工程图重建;它评的是完整 agent 系统。这里借用这种分开验收的思路,不把外部榜单成绩转写为 colocad 的成绩。
179
+
180
+ 本仓库的实证是:KK60 16 个阶段独立 STEP 回读、64 个材料探针、三个位置的特定导轨/滑块检查,以及工具/查看器/CLI 集成回归。未公开回珠通道、全部零件对干涉、载荷/寿命和制造公差仍不在通过项中。
181
+
182
+ ## 7. 调优:对准测量到的瓶颈
183
+
184
+ ### 7.1 理解与建模质量
185
+
186
+ - 尺寸错:先核对标注归属、单位、直径/半径、视图与局部 frame;增加清晰局部证据,不先加大推理长度。
187
+ - 编辑破坏关系:减少重复常量,绑定共用参数/基准;增加有意义的参数扰动检查。
188
+ - 工具选择反复:消除语义重叠,保留少量明确工具;按需载入 schema/reference,返回足够定位的错误。
189
+ - 上下文过大:保存详细工件,用路径/哈希引用;每轮加载相关图和摘要,避免重复发送全部网格/日志。
190
+
191
+ [工具设计建议](https://www.anthropic.com/research/writing-tools-for-agents)强调清晰职责、可操作反馈和有针对性的评估;[上下文工程建议](https://www.anthropic.com/research/effective-context-engineering-for-ai-agents)强调按需检索与保存关键状态。本指南的具体工具选择、回执字段和材料结构来自 colocad 的实际接口,不是直接套用外部产品的 API。
192
+
193
+ ### 7.2 执行性能与资源
194
+
195
+ 分开计时:资料读取/推理、进程启动、几何、校验、STEP、三角化、视图渲染、视频编码。先看 per-feature/native timings,再决定优化算法、共享定义、参数重算、缓存或显示精度。
196
+
197
+ 同一任务顺序复用 client/session。重复零件复用定义;只换镜头时复用已校验网格。预览可选择适合观察的精度,但比较时要固定参数。影片编码另外需要浏览器与 FFmpeg,不包含在纯几何运行的资源结论中。
198
+
199
+ 与 build123d 比较时固定输入几何、实例、精度、交付工件、环境和冷/热启动模式;先验证两边几何等价。报告重复次数、分布、失败和测量范围。内存明确 RSS/进程和/cgroup、采样频率、瞬时值还是截至当前峰值。保留原始采样;用峰值曲线展示时不能称为瞬时内存。
200
+
201
+ 本次 KK60 单次 Linux arm64、1 vCPU/512 MiB、禁网、含预览的原生总耗时为 24.192 秒;未测该次内存峰值,也未做同模型 build123d 对照。这个结果不能推导整个 resident agent/harness 或 Chromium 也只需要 512 MiB。[证据](../showcase/hiwin-kk60/evidence.json)。
202
+
203
+ ### 7.3 如何证明 skill/提示词真的更好
204
+
205
+ 固定资料包、目标产品、模型/provider 版本、工具、预算和随机设置,对比旧 skill 与单项改动。覆盖明确尺寸件、需要剖视解释的零件、编辑后仍须配合的装配和有歧义的材料;留出未参与调优的任务。测关键尺寸/特征、编辑保持、接口检查、无依据结论、修改次数、推理成本和端到端时间。
206
+
207
+ 先运行确定性契约回归,再做使用真实模型的对照评估。不能把工具脚本测试、一次成功案例或引用论文直接说成提示词优化成功率。当前新增指南经过链接/skill 校验、实际工具流程和打包回归;没有宣称完成跨模型盲测。
208
+
209
+ ## 8. 运行、审阅与交付
210
+
211
+ ```sh
212
+ npm install @coloopx/colocad@0.1.0-alpha.5
213
+ node node_modules/@coloopx/colocad/examples/hiwin-kk60/run.mjs ./actuator
214
+ npx colocad view ./actuator/session
215
+ npx colocad replay ./actuator/session ./actuator.html
216
+ # 已安装可选 Chromium / FFmpeg 时:
217
+ npx colocad render ./actuator/session ./modeling.mp4
218
+ ```
219
+
220
+ 完整会话应随 sandbox 产物保留。单文件 HTML 带模型、回执、网格和最终 STEP;需要所有中间 STEP 时交付完整 session 目录。给出具体文件、检查数值和限制,保留可重新执行的源,不只交一张图或一句“成功”。
221
+
222
+ [接入 Pi / Claude Code / Codex](integrations/overview.md) · [SDK/CLI API](api.md) · [历史与动画](modeling-history.md) · [故障排查](troubleshooting.md)
@@ -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).