* feat(skill): replace skill-pack with per-harness conditional compiler
skillbuild compiles the skill tree into per-target harness builds:
- <!-- skill:if omp,!claude --> blocks include text only for matching
targets; name-list conditions only, no else/nesting, fail-loud on
unknown targets and unpaired/nested directives
- fence-aware: directive-looking lines inside code fences are literal
- layout is the filesystem; tree root configured in skillproj.toml
- post-build assertion: zero directive residue, SKILL.md frontmatter
name check
Migration to the new model:
- docs/skill/ becomes the self-contained source root (SKILL.md,
references/, generated api/stdlib/core/guides now under
references/docs/; SDK_OVERVIEW/LICENSE/inspect are ordinary tree
files)
- auto_docs_gen output redirected into the tree (docs/api ->
docs/skill/references/docs/api, likewise stdlib)
- skills/simplecadapi/ is now the compiled omp target output;
dist/generic/simplecadapi the generic target
- dropped skill-pack entry point (plus dangling evolve/make-export
entries and their orphaned test), release workflow builds via
skillbuild + tar; README updated
First real conditional block: harness reading paths in SKILL.md
(skill:// mount on omp vs disk-relative on generic).
Verified: 59 tests pass (skillbuild 31, auto_docs_gen 19, persistence
regression 9); both targets build; outputs residue-clean; full suite
collects (1376 tests).
* refactor(tools): auto_docs_gen moves out of the installed package
tools/ scripts are repo-checkout dev scripts, not packaged CLIs:
- auto_docs_gen.py now lives in tools/ beside the other generators;
auto_tools/ package removed entirely
- path resolution simplifies: repo root = parent of tools/, fail-loud
if pyproject.toml missing; site-packages/cwd fallback branches were
dead code once the script stopped shipping in the wheel
- auto-docs-gen console script dropped from [project.scripts];
release.yml and README invoke python tools/auto_docs_gen.py
- MANIFEST.in stale src/auto_tools include removed; CadQuery-free
runtime scan no longer needs the auto_tools filter
- run_examples.py retired (user removal): README example-runner text
updated to direct examples/ scripts; dangling runner-contract test
(runpy.run_path into the deleted script) removed
Verified: 53 tests pass (auto_docs_gen + skill_build + ocp runtime
scan) and test_example_model_contract passes; regeneration from
tools/ is byte-identical (zero docs drift).
* refactor(skill): strip harness and build-tool content from the skill tree
The skill is plain harness-neutral content again:
- SKILL.md 'Reading skill files' section removed (the omp skill://
mount block and its !omp complement were the only conditional
blocks; the tree compiles identically for every target now)
- references/README.md: build-tool meta removed ('per-harness
conditional compilation', skillbuild packaging/validation claims —
link validation was never implemented, so the claim was false)
- live test now asserts the tree stays harness-neutral (zero blocks)
- skillproj.toml targets aligned with the user's output table
(omp -> skills/simplecadapi-omp, opencode -> skills/simplecadapi-opencode;
leftover 'generic' entry had no output and failed the build)
- compiled outputs are regenerable artifacts: skills/simplecadapi/
untracked from git, skills/simplecadapi-*/ gitignored, release.yml
and README build via skillbuild and tar the omp output directly
(bsdtar has no --transform; inner dir keeps its suffixed name)
Verified: 49 tests pass; both targets build 372 files with zero
conditional blocks; no omp/conditional/directive residue in the tree
or outputs.
* chore(docs): drop stale architecture review and design notes
2.9 KiB
Discipline: Datums and Coordinate Systems
Choosing origins, planes, and axes from function before the first primitive. The coordinate and unit statements below are SDK facts where labeled; origin choices and part-type defaults are modeling guidance.
Core rule
The part-local coordinate system is chosen from the functional datum, and the SDK evaluates lengths in millimeters and angles in degrees (declared units are preserved in model JSON). Declaring the convention in the brief is not optional bookkeeping: every downstream measurement, connector frame, and placement reads against it.
Modeling guidance: origin defaults by part type
- Symmetric standalone parts: origin at the body center.
- Plates / mounting plates: origin at footprint center; thickness along the up axis.
- Enclosures: origin at footprint center; base/lid mating surfaces controlled by named height parameters.
- Shafts, knobs, axisymmetric parts: origin on the rotational axis.
- Adapter / mating plates: origin on the primary mounting datum or the bolt-pattern center.
When nothing better applies, center of the main part or assembly.
Convention skeleton
Declare in the brief:
Origin: center | base datum | mounting interface | functional axis
Base plane: which model plane carries the main profile
Up / feature direction: which axis, which sign
Named dimensions: offsets, spacings, clearances
Datum features: mating faces, screw axes, centerlines, locating features
SimpleWorkplane (a context manager for modeling in a local frame) and
CoordinateSystem exist for local contexts; use them when a feature is
naturally authored in a local frame, and say so in the source.
Placement semantics
- Part-local coordinates equal the wrapped solid's modeling coordinates. If a
different part origin is wanted, build the solid in that frame before
wrapping it as a
Part. - A component placement maps child-local coordinates into parent coordinates; nested placements compose. Moving a part inside an assembly changes only the placement — never the part's internal solid.
- A numeric placement should correspond to a stated datum, offset, clearance, axis, or contact relationship. An untraceable transform constant is the same defect as a magic number.
Imported and factory geometry
Geometry you did not author — stdlib factory output, imported STEP — carries
no assumed origin or orientation. Measure it (QL queries on faces, axes,
bounds; inspect.brep for STEP) and derive connector frames from measured
geometry. Bevel gears are the classic trap: measure the output axes before
constraining.
Validation
- Frame checks: expected axes aligned with model axes; repeated parts share orientation; mating frames land where the brief says.
- After assembly: verify flush faces measure flush, axes measure coaxial, and
offsets measure as specified — see
geometric-validation.md.