Research-Stack/5-Applications/text-to-cad/AGENTS.md

AGENTS.md

This repository is a harness for script-driven CAD generation with coding agents like Codex and Claude Code.

If you are modifying the viewer app itself, go to viewer/README.md.

Skill Routing

Use the bundled skills for workflow details:

• skills/cad/SKILL.md for STEP, STL, DXF, GLB/topology artifacts, snapshots, and @cad[...] prompt references.
• skills/urdf/SKILL.md for generated URDF files, gen_urdf(), robot links, joints, limits, and URDF mesh references.
• viewer/README.md for viewer behavior, rendering UI, prompt capture UX, and frontend development. Do not read it just to form final CAD Explorer links; use the Viewer Handoff rules below.

AGENTS.md is intentionally harness-focused. Reusable CAD and URDF workflow rules live inside the skills.

Harness Context

Project CAD files live under models/.

The CAD and URDF skill tools are file-targeted. They do not depend on this harness's models/ directory; models/ is this repo's project layout.

Project-specific context may live under models/. Keep project-local notes compact and do not copy reusable generator contracts, prompt-ref rules, validation policy, image review policy, or full CLI syntax into them; link to the CAD and URDF skill references instead.

Python Environment

The root workspace pins Python 3.11.15 in .python-version and exposes the CAD setup through root package.json scripts. From the repository root, prefer:

npm run install-python
npm run setup-cad-env
npm run verify-cad

These commands mirror the checked-in VS Code tasks in .vscode/tasks.json.

Inside this harness, prefer the repo-local CAD runtime when it exists:

./.venv/bin/python

This environment has the CAD dependencies required by the skill tools, including build123d and OCP. If .venv is missing or cannot import those modules and the root scripts are unavailable, create/install it from this harness root:

python3.11 -m venv .venv
./.venv/bin/pip install -r requirements-cad.txt

Do not commit .venv, Python caches, or local package caches. They are runtime state, not CAD source.

Source Of Truth

• Generated CAD and URDF outputs are derived artifacts.
• Package-local render, topology, component, and review-image artifacts are derived artifacts.
• Do not hand-edit generated artifacts unless explicitly instructed. Edit the owning source file or imported source file first, then regenerate explicit targets with the relevant skill tool.
• If regenerated output differs from checked-in generated files, the regenerated output is authoritative.
• Root .python-version, root package.json scripts, and root VS Code tasks are workspace setup surfaces. Update them when the preferred CAD rebuild command changes.

Compression and the Eigensolid Model

CAD files are compression targets, not just geometry. Every byte signals:

• STEP whitespace — paragraph/entity boundaries mark topological strand breaks. A newline after ENDSEC is as structural as the section itself.
• STL vertex order — triangle winding order IS the crossing matrix of the mesh braid. Reversed normals are a scar, not noise.
• Vertex count — mesh density is Sidon slack: the gap between addressable and used vertices encodes LOD capacity headroom.
• File format choice — STEP vs STL vs DXF vs GLB is a receipt dimension. The format IS the compressor selection.

The BraidEigensolid compressor applies at every level of the CAD pipeline: individual parts (strands), assemblies (braid crossings), and viewer meshes (converged eigensolid). WGSL shaders in 4-Infrastructure/gpu/wasmgpu/ handle GPU dispatch for viewer rendering; the blitter fallback handles CPU-only environments. Both produce identical geometry because Q16_16 integer arithmetic is deterministic on all substrates.

Prompt Artifacts

The viewer may provide annotated screenshots and @cad[...] references. Treat screenshots as supporting context and @cad[...] refs as stable handles. If they disagree, trust the ref and source geometry, then use the screenshot to understand intent.

Copied @cad[...] paths include the models/ directory and omit the .step or .stp suffix. For ref grammar, selector semantics, stale-ref handling, and geometry-fact workflows, read skills/cad/references/prompt-refs.md and use skills/cad/scripts/cadref.

Do not inspect viewer runtime assets to interpret prompt refs. Resolve refs from source STEP data through the CAD skill.

Viewer Handoff

After editing or regenerating any viewer-displayable .step, .stp, .stl, .dxf, or .urdf entry, make CAD Explorer available and include links for the affected entries in the final response.

Ensure the viewer server first:

npm --prefix viewer run dev:ensure

Viewer link rule: file is always relative to dir, and entry links must include file=.

• Default scan root: http://127.0.0.1:4178/?dir=models&file=<path-under-models-with-extension>
• Only use another scan root when it is intentional: http://127.0.0.1:4178/?dir=<repo-relative-scan-dir>&file=<path-relative-to-that-dir-with-extension>

For CAD prompt refs, keep the entry file= and append URL-encoded refs= parameters. Python generators are not viewer entries; link their generated outputs. If only viewer app code changed, link the base viewer URL.

Repo Policies

• Keep project CAD files under models/.
• Do not store generated review images under models/; use /tmp/....
• Use explicit generation targets. Do not run directory-wide generation.
• Let the split generation tools own viewer-consumed render assets. Do not build or edit separate viewer cache files.
• Generation tools write and overwrite current configured outputs. They do not delete stale outputs when paths change.
• Update project-local documentation only when project focus, entry roles, inventory, dependency notes, durable quirks, or preferred rebuild roots change.
• Do not create per-entry README files.

Common Harness Commands

Run from the repository root unless you intentionally want paths to resolve from another directory.

# Regenerate a CAD source
./.venv/bin/python skills/cad/scripts/gen_step_part models/path/to/source.py

# Regenerate an assembly source
./.venv/bin/python skills/cad/scripts/gen_step_assembly models/path/to/assembly.py

# Regenerate a URDF sidecar
./.venv/bin/python skills/urdf/scripts/gen_urdf models/path/to/source.py

# Inspect a CAD prompt ref
./.venv/bin/python skills/cad/scripts/cadref inspect '@cad[models/path/to/entry]' --json

# Render a quick review image
./.venv/bin/python skills/cad/scripts/snapshot models/path/to/source.py \
  --view isometric --out /tmp/cad-renders/review.png

Execution Notes

• Start with the narrowest source-only search that can identify directly affected files.
• Exclude generated artifacts, binary CAD files, caches, and build outputs from default searches unless the task explicitly targets them.
• If the first pass makes scope clear, edit the source first and validate after.
• Do not run generation tools, cadref, and snapshot in parallel against geometry that is still changing in the same edit loop. Rebuild first, then inspect, then render.
• In cloud or constrained environments, avoid full-repo hydration when affected entries are known. Fetch only the needed inputs, generated outputs, and LFS objects for the entries being edited and explicitly regenerated.

Cross-References

See root AGENTS.md for:

• Post-Interaction Workflow (mandatory 5-step session-end procedure)
• Programming Choice Flow (Lean owns decisions; Python owns I/O)
• Do Not Sweep rules (no broad git add .)
• Git Remote Hygiene