Files
make-cad/docs/skill/references
NiJingzhe 237702c7a8 feat(examples): unnumbered self-contained layout with per-example out/
- rename every numbered example (04/08/10/11/7ep scripts, 12/16/20/21 dirs)
  to clean names; each example now writes artifacts to its own out/ folder
- examples/README rewritten as a category index (part / assembly / reverse
  engineering / FEM); stale run_examples.py reference removed
- flange_plate gains the quickstart FTC part (model.py + external verify.py
  + README); u_link/ap242/flange demo builders read the new asset paths
- ap242_gmsh_volume_mesh gains render_views.py for the demo gallery

fix(artifacts): round-trip-stable geometry fingerprint bounds

AddOptimal bounds wobble by one shape-tolerance quantum between a fresh
shape and the same shape read back from BRep bytes, so definitions sitting
on a quantization cell edge failed every package re-validation. Quantize
bounds at a fixed 1e-4 mm grid, far coarser than the wobble; full suite
green (1503 passed). Stored packages captured before this change must be
recaptured.
2026-09-07 05:46:15 +08:00
..

Skill Documentation Structure

This directory is the task-routed skill layer. It sits between the SDK's generated

docs/skill/
  domains/       stable, reusable capability modules
  workflows/     goal-oriented compositions of domains
  discipline/    mechanical modeling knowledge and invariants

Layering

SKILL.md (router: load order, routing, execution discipline)
→ workflows/<scenario>.md        what to run, in what order
→ domains/<capability>.md        capability boundaries and API groups
→ discipline/<topic>.md          why: modeling reasoning and invariants
→ docs/api|stdlib|core/          exact signatures (auto-generated)

Load top-down and only what the current task triggers. No task reads the whole API index up front.

Domains

Domain Owns
requirement-refinement request → brief (dimensions, units, datums, validation targets)
part-modeling single-solid parts: primitives, profiles, features, booleans, transforms
sketch-and-features declarative constrained sketches and promotion
assembly-and-product parts, placements, connectors, constraints, @part/@assemble, cache, .scadpkg
standard-parts stdlib gears, ring gears, racks, cycloidal discs, bearings
step-inspection STEP/BREP evidence, comparison, reconstruction evaluation
export-and-translation STEP/STL/OBJ/MJCF export, FreeCAD/Fusion/SolidWorks translation

Cross-cutting capabilities — QL grounding, semantic tags, GraphSession replay, units/tolerances, incremental validation — are not routing targets; each workflow pulls them in as conditions require. Verified QL selection patterns for operation outputs (extrude-family slots, boolean seam curves, seam fillets) live in ql-playbook.md.

Workflows

Workflow Scenario
single-part-modeling one physical part from brief to validated solid — sketch tier by default, std parts first
assembly-product-build multi-part product or mechanism with connectors/constraints and package capture; stdlib gears/bearings live here
step-reconstruction editable rebuild from a target STEP with tiered acceptance
export-and-translation downstream formats from a validated package

Each workflow states: goal/scope, task decomposition (required/optional domains, artifacts, validation gates, repair routes), ordered steps with the domain/discipline/API references to load, failure routes, and deliverables. single-part-modeling is additionally role-structured: five roles (requirement confirmer → master planner → verifier planner ⇄ detail modeling planner & builder → exporter), with Roles 3 and 4 looping per stage before the next stage is allowed. Each role owns a disk artifact and an exit gate; per-harness host bindings (interactive ask, TODO/plan tool, REPL-or-script hypothesis loop, mandatory isolated image review) are declared inside the workflow file as conditional blocks compiled per target by tools/skillbuild.py (targets declared in skillproj.toml).

Discipline

Modeling reasoning and invariants, independent of any single API: mechanical-modeling (construction strategy), requirement-and-cad-brief (input precedence, drawings), datums-and-coordinate-systems, feature-ordering (operation order and boolean tool geometry), assembly-positioning (mating/motion intent), geometric-validation (validity vs volume, incremental grounding, spec-driven measurement), failure-and-repair (failure classes and the repair loop), manufacturing-boundaries (defaults and what geometry never proves).

Authoring rules

  • Domain files say what a capability owns, when to use it, when to route elsewhere, and which API pages to read — they do not restate signatures.
  • Workflow files compose domains; they never duplicate discipline content.
  • Discipline files state reasoning and invariants; they avoid CLI- or tool-specific detail that belongs in domains/workflows.
  • Every references/... path written here must exist in the packaged skill.
  • Reading an API page is an action with an output: before the first call of any API, note its signature, return type, and documented failure modes — one line each in the working notes. A method name absent from the page does not exist, however plausible it looks. Non-SDK dependencies (Gmsh, CalculiX, VTK, FreeCAD scripting) are not covered by SDK pages: check their own documentation before the first call.