Simplecadapi

SimpleCAD SDK Skill

This file is the router: it owns load order, route selection, and execution discipline only. Each selected workflow owns its procedure. Classify the request, load exactly one workflow, follow its domain and discipline references, and read exact API pages for the APIs its steps use.

Mandatory load order

Paths are relative to this file's directory.

1. Read this file.
2. Select exactly one workflow from Task routing. If two rows plausibly match, ask one discriminator question that names the candidate outcomes; never pick silently between routes with different deliverables.
3. Read the selected workflow in full. From selection on, it owns the procedure; do not load another workflow's procedure.
4. Load each required domain/discipline file the workflow names before the step that uses it; optional ones only when their trigger fires.
5. Before the first call of any API, read its exact page (references/docs/api/<name>.md, references/docs/stdlib/<name>.md, references/docs/core/<type>.md). A method absent from its page does not exist, however plausible it looks.

• You MUST NOT read the full API or stdlib index up front; the workflow names every page its steps need.
• Routing questions are decided here; after selection the workflow owns execution. You MUST always follow the global rules and execution discipline below.
• Questions about an existing STEP file that change nothing enter no workflow; you MUST use references/domains/step-inspection.md for them directly.
• Creating, installing, updating, or removing a SimpleCADAPI addon (a third-party skill+tooling package around .scadpkg) enters no workflow; you MUST use references/domains/addon-development.md directly.

Task routing

Read exactly one workflow first, per the user's goal:

Do not present route-choice menus when a row already matches: profile, strategy, and tool choices inside a route belong to that workflow's own gates, not to an up-front question. A missing prerequisite — state it and stop that route; never invent an alternative route.

Routing discipline

Global rules (every task)

1. Refine the requirement into a brief before modeling (references/domains/requirement-refinement.md).
2. Use keyword arguments for every documented public API and stdlib function, except the canonical durable export call capture(result, path), whose two required arguments are positional.
3. Every model is a marimo notebook with a [tool.simplecadapi] header (references/docs/guides/notebook-runtime.md): one part per notebook; one assembly notebook per product, composing children with scad.use(...); parameters live in the notebook that consumes them; exposed tunable parameters are var()/Var declarations (optionally with unit, tolerance). Part sources follow the Feature Tree Convention (references/discipline/feature-tree-convention.md): block structure sketch → basic body op → bool → modifier, one feature per block and one block per cell, with a mandatory boundary comment # ---- feature: <slug> (<role>) ----; 2D profiles and planar paths go through the sketch API, primitives only when the shape is completely contained in the basic form.
4. Booleans (union_rsolid, cut_rsolid, intersect_rsolid) accept mixed inputs and return exactly one Solid; union defaults to glue=False with a conservative scale-relative tolerance and fails explicitly when it cannot produce one merged solid.
5. Build and validate incrementally: each major step prints small QL-derived facts; grounding uses QL wherever possible; never print whole solids or full model objects.
6. Topology enumeration is QL-only and strictly enforced: plural getters (get_edges, get_faces, get_wires, get_vertices, get_solids, get_inner_wires) accept ONLY an index — the no-argument list form raises. Enumerate, count, and measure via ql.<kind>().resolve(shape); filter with QL predicates plus take/exactly cardinality; never build selections by looping over an enumerated list and indexing it. Indexed picks (get_edges(index)) are reserved for intentional, named choices and are recorded as graph selection nodes.
7. Tags: attach with apply_tag(shape=..., tag=...) (LOCAL scope — it never propagates downward); inspect with list_tags(shape=...); keep numeric facts in metadata, never in tags.
8. The notebook file is the only source of truth; .scadpkg is generated from it for exchange and publishing (sca run product.py --out out/product.scadpkg, or capture(result, "out/product.scadpkg") in one call) and is never read back as a source. @scad.part / @scad.assemble are for reusable library parts in plain modules; they may be called inside a notebook cell.
9. simplecadapi.inspect.brep and simplecadapi.inspect.drawing are diagnostic-only and rejected inside GraphSession; obtain/export geometry first, inspect outside.
10. Standard parts first: before hand-modeling a gear, ring gear, rack, cycloidal disc, or bearing, check scad.std.gear / scad.std.bearing.
11. Read references/docs/guides/notebook-runtime.md in full before writing a notebook, composing notebooks, or reasoning about the cell cache. Run models with sca run; never enable marimo's [tool.marimo.runtime] cache_cells in the editor, and never commit the generated __marimo__/ directory.