simplecadapi

SimpleCAD SDK Skill

Philosophy

• This is a thin SDK reference skill: docs only.
• SDK source code is not bundled in this skill.

Working From Repo Root

• Tool calls run from the repo root.
• Use one explicit skill root: ./skills/simplecadapi/ or ./workspace/skills/simplecadapi/.
• Main doc paths:
  • <skill_root>/SKILL.md
  • <skill_root>/references/docs/api/README.md
  • <skill_root>/references/docs/api/<api_name>.md
  • <skill_root>/references/docs/stdlib/README.md
  • <skill_root>/references/docs/stdlib/<stdlib_api_name>.md
  • <skill_root>/references/docs/core/<type_name>.md
  • <skill_root>/references/SDK_OVERVIEW.md
  • <skill_root>/references/SDK_SURFACES.md
  • <skill_root>/references/MODELING_WORKFLOWS.md
  • <skill_root>/references/inspect/brep-reverse-engineering.md

MUST Requirements

1. Read SKILL.md, references/docs/api/README.md, and references/docs/stdlib/README.md before choosing APIs.
2. Read the exact API Markdown page for every API you use.
3. Read the needed core/ or exact api/ docs when an API needs Edge, Face, Wire, Solid, GraphSession, Sketch, or expression types.
4. Prefer the standard parts library for standard parts before hand-modeling with core geometry APIs.
5. Follow the documented API signatures exactly.
6. When calling any SimpleCAD public API or standard-library function, use keyword arguments for every documented parameter; do not use positional arguments.
7. Use one @model entry point for replayable tasks, @requires_session for child builders, capture_result(...) for explicit outputs, and the returned ModelResult for model/session JSON and replay.
8. Use geometry APIs for integrated parts: profiles, features, booleans, transforms, tagging, QL inspection, serialization, and exports.
9. Use tags consistently through apply_tag(shape=..., tag=...) and list_tags(shape=...); do not call shape member tag mutators.
10. Build and validate incrementally. Each step MUST include a small grounding print, and grounding MUST use QL where possible.
11. For inspection/debugging, query geometry with QL and print only the queried facts you need; do not print whole solids or full model objects.
12. Boolean operations return a single Solid.
13. Use union_rsolid(...) for boolean union.
14. For automated example/test harnesses, prefer the repo-local examples in examples/ and avoid scratch scripts in sandbox/.
15. If union cannot produce exactly one merged solid, it fails explicitly; do not silently pick one piece.
16. If a single merged solid is required and union fails, slightly adjust part placement so intended bodies overlap/embed, then recompute.
17. If a task depends on model replay or interchange, prefer ModelResult.model_json or export_model_json() output over hand-written payloads.
18. For STEP/BREP inspection or target/candidate comparison, read references/inspect/brep-reverse-engineering.md completely.
19. Use simplecadapi.inspect.brep only outside GraphSession and @model; inspection functions are diagnostic tools, not modeling operations.
20. Reverse engineering is case-by-case: the built-in inspection primitives are tools, not a pipeline — write ad hoc inspection code for the specific model when built-ins do not answer the question. Acceptance hierarchy: BREP topology identity is the best endpoint (complete reverse engineering); identical structure with minor float-level parameter drift from export is acceptable; a visually-close but structurally different result is a valid stop only when no better feature operation order/combination exists or the SDK lacks the required operation type.