simplecadapi 2.1.1__tar.gz → 2.1.3__tar.gz

{simplecadapi-2.1.1 → simplecadapi-2.1.3}/.gitignore

@@ -53,6 +53,7 @@ examples/histcad/
 # Research tool scan outputs (generated by tools/research scripts)
 tools/research/out/
 tools/research/histjson/out/
+tools/research/whucad/out/
 tools/research/cadqueryftc/out/
 .venv-cq/
 

{simplecadapi-2.1.1 → simplecadapi-2.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simplecadapi
-Version: 2.1.1
+Version: 2.1.3
 Summary: A simplified OCP-native CAD modeling Python API
 Project-URL: Homepage, https://github.com/NiJingzhe/SimpleCADAPI
 Project-URL: Repository, https://github.com/NiJingzhe/SimpleCADAPI
@@ -250,6 +250,8 @@ Provides-Extra: gmsh
 Requires-Dist: gmsh<5,>=4.15; extra == 'gmsh'
 Provides-Extra: inspect
 Requires-Dist: matplotlib>=3.7.0; extra == 'inspect'
+Provides-Extra: whucad
+Requires-Dist: h5py>=3.8; extra == 'whucad'
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -388,18 +390,19 @@ the full crank cycle sweeps clean in the same sim ·
 
 ---
 
-## Update Notes (2.1.1)
+## Update Notes (2.1.3b1)
 
-> **Release notice:** Validate generated definitions, assembly constraints, and
-> manufacturing geometry before production use.
+> **Release notice:** Pre-release (beta). Validate generated definitions,
+> assembly constraints, and manufacturing geometry before production use.
 
-SimpleCADAPI 2.1.1 is a tooling patch (SDK API unchanged): a CadQuery→FTC
-translator toolset with snapshot constraint recovery under
-`tools/research/cadqueryftc`, aligned with the histjson four-stage research
-pattern. See the [full English update notes](docs/updates/2.1.1.md) for the
-tracer/translator/validator split, the recovery axioms, and verification
-coverage; the 2.1.0 agent-first feature set is described in
-[docs/updates/2.1.0.md](docs/updates/2.1.0.md).
+SimpleCADAPI 2.1.3b1 ships the addon ecosystem: a `sca` CLI that installs
+third-party skill+tooling repositories (`sca addon init/add/update/remove/list`),
+a strict `sca-addon.toml` descriptor with platform and `[compat] sca` gates, and
+a consumer-facing `.scadpkg` format spec written so an agent given the document
+alone can produce a correct parser or exporter. See the
+[full English update notes](docs/updates/2.1.3b1.md) for the CLI contract, the
+two legal integration modes, and the tag channel; 2.1.2's script-anchored part
+cache is described in [docs/updates/2.1.2.md](docs/updates/2.1.2.md).
 
 All formal single-script examples emit a synchronized `.scadpkg`, AP242
 `.step`, and editable `.FCStd` from the same product package. The
@@ -424,7 +427,7 @@ in a compact public API for creating solids, applying features, tagging semantic
 intent, querying topology, exporting manufacturing files, and translating recorded
 models into FreeCAD workflows.
 
-Current release: `simplecadapi==2.1.1`.
+Current release: `simplecadapi==2.1.3`.
 
 ## What It Provides
 
@@ -467,6 +470,29 @@ For local development from this repository:
 uv sync --group dev
 ```
 
+### Agent Skill
+
+After installing with pip above, install the bundled skill for your agent
+harness:
+
+```bash
+sca skill targets
+# Default location (~/.agents/skills), or select ZCode's explicitly:
+sca skill install --target zcode --skills-dir ~/.zcode/skills
+```
+
+`targets` lists the available harness targets. `install` compiles the bundled
+source and writes it to `<skills-dir>/simplecadapi`; without `--skills-dir`,
+it uses the existing addon configuration/environment resolution, falling back
+to `~/.agents/skills`; `sca init` is not required. The wheel includes the
+uncompiled `docs/skill/` source tree and `skillproj.toml` as package
+resources — compilation happens on install, no repository checkout needed.
+With `uv`, prefix these commands with `uv run`.
+
+`install` fails if the destination already exists. Add `--force` to replace it
+only if it is a directory whose `SKILL.md` declares the matching skill name
+(`simplecadapi`); unrelated directories cannot be overwritten.
+
 ## Quick Start
 
 ```python
@@ -576,9 +602,9 @@ print(cold.cache_report.hit, warm.cache_report.hit)
 Inspect or maintain the cache with stable JSON output:
 
 ```bash
-simplecad-cache status
-simplecad-cache verify
-simplecad-cache prune
+sca cache status
+sca cache verify
+sca cache prune
 ```
 
 See the [persistent cache and product build workflow](docs/skill/references/docs/guides/cache-build-workflow.md)
@@ -607,7 +633,7 @@ Export the standard delivery set (AP242 STEP, binary STL, and OBJ) from a
 validated product package with no wrapper script:
 
 ```bash
-uv run simplecad-export out/mounting_plate.scadpkg --output-dir out/exports
+uv run sca export out/mounting_plate.scadpkg --output-dir out/exports
 ```
 
 Request additional targets explicitly.  FCStd requires `FreeCADCmd` (or an
@@ -615,9 +641,9 @@ explicit `--freecad-cmd` path); `--check` validates the package, output paths,
 and selected target prerequisites without writing files.
 
 ```bash
-uv run simplecad-export out/mounting_plate.scadpkg \
+uv run sca export out/mounting_plate.scadpkg \
   --format fcstd --format mjcf --output-dir out/exports --check
-uv run simplecad-export out/mounting_plate.scadpkg \
+uv run sca export out/mounting_plate.scadpkg \
   --format fcstd --freecad-cmd /path/to/FreeCADCmd --output-dir out/exports
 ```
 STL and OBJ share one direct OpenCASCADE tessellation of the evaluated BREP.
@@ -785,6 +811,8 @@ against a target STEP (see `examples/bowl_connector/`).
 
 ## Documentation
 
+- 2.1.3b1 update notes: [`docs/updates/2.1.3b1.md`](docs/updates/2.1.3b1.md)
+- 2.1.2 update notes: [`docs/updates/2.1.2.md`](docs/updates/2.1.2.md)
 - 2.1.1 update notes: [`docs/updates/2.1.1.md`](docs/updates/2.1.1.md)
 - 2.1.0 update notes: [`docs/updates/2.1.0.md`](docs/updates/2.1.0.md)
 - Reconstruction Agent test specification:
@@ -808,11 +836,14 @@ against a target STEP (see `examples/bowl_connector/`).
 ## Releasing the Agent Skill
 
 The skill source tree lives under `docs/skill/` and stays harness-neutral.
-`tools/skillbuild.py` compiles it per harness target (targets and output
-directories are configured in `skillproj.toml`; the outputs under
-`skills/simplecadapi-*/` are regenerable build artifacts and are not
+`tools/skillbuild.py` wraps the same compiler the `sca skill` CLI uses, for
+maintainer builds in this repository: it compiles per harness target (targets
+and default output directories are configured in `skillproj.toml`; the outputs
+under `skills/simplecadapi-*/` are regenerable build artifacts and are not
 committed). Harness-specific text, when it is ever needed, is marked with
-`<!-- skill:if ... -->` conditional blocks that compile per target.
+`<!-- skill:if ... -->` conditional blocks that compile per target. The wheel
+itself never contains precompiled targets — end users install from the
+bundled source with `sca skill install`.
 
 From a clean checkout, update the project version and documentation, then
 build and validate the release artifacts:
@@ -835,7 +866,8 @@ tar -tzf skills/simplecadapi.tar.gz | head
 ```
 
 Commit only the `docs/skill/` source tree; the release workflow builds the
-harness outputs and uploads the archive to the GitHub release.
+harness outputs and uploads the archive to the GitHub release. Prefer
+`sca skill` for installation from a pip-installed package.
 
 ## Development
 
@@ -856,3 +888,13 @@ The group chat currently has too many members for direct QR-code joining. Scan t
 <p align="center">
   <img src="img/dp个人账号.png.jpg" alt="Teacher Du Peng's personal WeChat QR code" width="420">
 </p>
+
+## Star History
+
+<a href="https://www.star-history.com/?repos=nijingzhe%2Fsimplecadapi&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=nijingzhe/simplecadapi&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=nijingzhe/simplecadapi&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=nijingzhe/simplecadapi&type=date&legend=top-left" />
+ </picture>
+</a>

{simplecadapi-2.1.1 → simplecadapi-2.1.3}/README.md

@@ -134,18 +134,19 @@ the full crank cycle sweeps clean in the same sim ·
 
 ---
 
-## Update Notes (2.1.1)
+## Update Notes (2.1.3b1)
 
-> **Release notice:** Validate generated definitions, assembly constraints, and
-> manufacturing geometry before production use.
+> **Release notice:** Pre-release (beta). Validate generated definitions,
+> assembly constraints, and manufacturing geometry before production use.
 
-SimpleCADAPI 2.1.1 is a tooling patch (SDK API unchanged): a CadQuery→FTC
-translator toolset with snapshot constraint recovery under
-`tools/research/cadqueryftc`, aligned with the histjson four-stage research
-pattern. See the [full English update notes](docs/updates/2.1.1.md) for the
-tracer/translator/validator split, the recovery axioms, and verification
-coverage; the 2.1.0 agent-first feature set is described in
-[docs/updates/2.1.0.md](docs/updates/2.1.0.md).
+SimpleCADAPI 2.1.3b1 ships the addon ecosystem: a `sca` CLI that installs
+third-party skill+tooling repositories (`sca addon init/add/update/remove/list`),
+a strict `sca-addon.toml` descriptor with platform and `[compat] sca` gates, and
+a consumer-facing `.scadpkg` format spec written so an agent given the document
+alone can produce a correct parser or exporter. See the
+[full English update notes](docs/updates/2.1.3b1.md) for the CLI contract, the
+two legal integration modes, and the tag channel; 2.1.2's script-anchored part
+cache is described in [docs/updates/2.1.2.md](docs/updates/2.1.2.md).
 
 All formal single-script examples emit a synchronized `.scadpkg`, AP242
 `.step`, and editable `.FCStd` from the same product package. The
@@ -170,7 +171,7 @@ in a compact public API for creating solids, applying features, tagging semantic
 intent, querying topology, exporting manufacturing files, and translating recorded
 models into FreeCAD workflows.
 
-Current release: `simplecadapi==2.1.1`.
+Current release: `simplecadapi==2.1.3`.
 
 ## What It Provides
 
@@ -213,6 +214,29 @@ For local development from this repository:
 uv sync --group dev
 ```
 
+### Agent Skill
+
+After installing with pip above, install the bundled skill for your agent
+harness:
+
+```bash
+sca skill targets
+# Default location (~/.agents/skills), or select ZCode's explicitly:
+sca skill install --target zcode --skills-dir ~/.zcode/skills
+```
+
+`targets` lists the available harness targets. `install` compiles the bundled
+source and writes it to `<skills-dir>/simplecadapi`; without `--skills-dir`,
+it uses the existing addon configuration/environment resolution, falling back
+to `~/.agents/skills`; `sca init` is not required. The wheel includes the
+uncompiled `docs/skill/` source tree and `skillproj.toml` as package
+resources — compilation happens on install, no repository checkout needed.
+With `uv`, prefix these commands with `uv run`.
+
+`install` fails if the destination already exists. Add `--force` to replace it
+only if it is a directory whose `SKILL.md` declares the matching skill name
+(`simplecadapi`); unrelated directories cannot be overwritten.
+
 ## Quick Start
 
 ```python
@@ -322,9 +346,9 @@ print(cold.cache_report.hit, warm.cache_report.hit)
 Inspect or maintain the cache with stable JSON output:
 
 ```bash
-simplecad-cache status
-simplecad-cache verify
-simplecad-cache prune
+sca cache status
+sca cache verify
+sca cache prune
 ```
 
 See the [persistent cache and product build workflow](docs/skill/references/docs/guides/cache-build-workflow.md)
@@ -353,7 +377,7 @@ Export the standard delivery set (AP242 STEP, binary STL, and OBJ) from a
 validated product package with no wrapper script:
 
 ```bash
-uv run simplecad-export out/mounting_plate.scadpkg --output-dir out/exports
+uv run sca export out/mounting_plate.scadpkg --output-dir out/exports
 ```
 
 Request additional targets explicitly.  FCStd requires `FreeCADCmd` (or an
@@ -361,9 +385,9 @@ explicit `--freecad-cmd` path); `--check` validates the package, output paths,
 and selected target prerequisites without writing files.
 
 ```bash
-uv run simplecad-export out/mounting_plate.scadpkg \
+uv run sca export out/mounting_plate.scadpkg \
   --format fcstd --format mjcf --output-dir out/exports --check
-uv run simplecad-export out/mounting_plate.scadpkg \
+uv run sca export out/mounting_plate.scadpkg \
   --format fcstd --freecad-cmd /path/to/FreeCADCmd --output-dir out/exports
 ```
 STL and OBJ share one direct OpenCASCADE tessellation of the evaluated BREP.
@@ -531,6 +555,8 @@ against a target STEP (see `examples/bowl_connector/`).
 
 ## Documentation
 
+- 2.1.3b1 update notes: [`docs/updates/2.1.3b1.md`](docs/updates/2.1.3b1.md)
+- 2.1.2 update notes: [`docs/updates/2.1.2.md`](docs/updates/2.1.2.md)
 - 2.1.1 update notes: [`docs/updates/2.1.1.md`](docs/updates/2.1.1.md)
 - 2.1.0 update notes: [`docs/updates/2.1.0.md`](docs/updates/2.1.0.md)
 - Reconstruction Agent test specification:
@@ -554,11 +580,14 @@ against a target STEP (see `examples/bowl_connector/`).
 ## Releasing the Agent Skill
 
 The skill source tree lives under `docs/skill/` and stays harness-neutral.
-`tools/skillbuild.py` compiles it per harness target (targets and output
-directories are configured in `skillproj.toml`; the outputs under
-`skills/simplecadapi-*/` are regenerable build artifacts and are not
+`tools/skillbuild.py` wraps the same compiler the `sca skill` CLI uses, for
+maintainer builds in this repository: it compiles per harness target (targets
+and default output directories are configured in `skillproj.toml`; the outputs
+under `skills/simplecadapi-*/` are regenerable build artifacts and are not
 committed). Harness-specific text, when it is ever needed, is marked with
-`<!-- skill:if ... -->` conditional blocks that compile per target.
+`<!-- skill:if ... -->` conditional blocks that compile per target. The wheel
+itself never contains precompiled targets — end users install from the
+bundled source with `sca skill install`.
 
 From a clean checkout, update the project version and documentation, then
 build and validate the release artifacts:
@@ -581,7 +610,8 @@ tar -tzf skills/simplecadapi.tar.gz | head
 ```
 
 Commit only the `docs/skill/` source tree; the release workflow builds the
-harness outputs and uploads the archive to the GitHub release.
+harness outputs and uploads the archive to the GitHub release. Prefer
+`sca skill` for installation from a pip-installed package.
 
 ## Development
 
@@ -602,3 +632,13 @@ The group chat currently has too many members for direct QR-code joining. Scan t
 <p align="center">
   <img src="img/dp个人账号.png.jpg" alt="Teacher Du Peng's personal WeChat QR code" width="420">
 </p>
+
+## Star History
+
+<a href="https://www.star-history.com/?repos=nijingzhe%2Fsimplecadapi&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=nijingzhe/simplecadapi&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=nijingzhe/simplecadapi&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=nijingzhe/simplecadapi&type=date&legend=top-left" />
+ </picture>
+</a>

{simplecadapi-2.1.1 → simplecadapi-2.1.3}/docs/skill/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: simplecadapi
-description: Build, assemble, inspect, reconstruct, and export parametric CAD models with the SimpleCADAPI Python SDK. Use for SimpleCAD geometry modeling, constrained sketches, parts and assemblies, standard gears and bearings, STEP/BREP inspection and reconstruction, durable product packages, model JSON replay, and CAD backend translation.
+description: Build, assemble, inspect, reconstruct, and export parametric CAD models with the SimpleCADAPI Python SDK. Use for SimpleCAD geometry modeling, constrained sketches, parts and assemblies, standard gears and bearings, STEP/BREP inspection and reconstruction, vector-PDF drawing reconstruction, durable product packages, model JSON replay, and CAD backend translation.
 license: Apache-2.0
 metadata:
   project: simplecadapi
-  version: 2.1.1
+  version: 2.1.3
   package-name: simplecadapi
-  package-version: 2.1.1
+  package-version: 2.1.3
 ---
 
 # SimpleCAD SDK Skill
@@ -44,6 +44,10 @@ Paths are relative to this file's directory.
 - 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
 
@@ -56,6 +60,7 @@ Read exactly one workflow first, per the user's goal:
 | Rebuild an editable model from a STEP file | `references/workflows/step-reconstruction.md` |
 | Export/translate a validated package | `references/workflows/export-and-translation.md` |
 | Produce a GB engineering drawing (DXF) from validated geometry | `references/workflows/engineering-drawing.md` |
+| Rebuild a 3D model from a vector-PDF engineering drawing | `references/workflows/drawing-reconstruction.md` |
 
 Do not present route-choice menus when a row already matches: profile,
 strategy, and tool choices inside a route belong to that workflow's
@@ -115,9 +120,9 @@ it and stop that route; never invent an alternative route.
    `@scad.assemble` for assemblies with explicit definitions.
    Neither nests inside an active `GraphSession`. Durable delivery
    is `capture(result, "out/product.scadpkg")` in one call.
-9. `simplecadapi.inspect.brep` is diagnostic-only and rejected
-   inside `GraphSession`; obtain/export geometry first, inspect
-   outside.
+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`.
@@ -174,13 +179,16 @@ print(len(rebuilt))
 ## References
 
 - `references/README.md` — skill layer structure
-- `references/workflows/` — six goal-oriented workflows
-- `references/domains/` — eight capability domains
+- `references/workflows/` — goal-oriented workflows, including drawing reconstruction
+- `references/domains/` — capability domains, including drawing inspection
 - `references/discipline/` — modeling knowledge and invariants
 - `references/SDK_OVERVIEW.md` — package-level map
 - `references/inspect/brep-reverse-engineering.md`
+- `references/domains/addon-development.md` — `sca` addon CLI and authoring guide
 - `references/docs/guides/reconstruction-agent-test-prompt.md`
 - `references/docs/guides/reconstruction-agent-strategy.md`
 - `references/docs/guides/cache-build-workflow.md`
 - `references/ql-playbook.md`
+- `references/scadpkg-format.md` — `.scadpkg` consumer spec: member
+  layout, tag channel, minimal readers (addon exporters read this)
 - `references/docs/api/`, `references/docs/stdlib/`, `references/docs/core/`

{simplecadapi-2.1.1 → simplecadapi-2.1.3}/docs/skill/references/README.md

@@ -33,13 +33,17 @@ whole API index up front.
 | `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 |
+| `drawing-inspection` | vector-PDF coordinates and dimensions, model-section measurements, independent evidence validation |
 | `export-and-translation` | STEP/STL/OBJ/MJCF export, FreeCAD/Fusion/SolidWorks translation |
+| `addon-development` | third-party addon authoring and management: `sca` CLI, `sca-addon.toml` descriptor, runtime probes, addon SKILL.md requirements |
 
 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`.
+fillets) live in `ql-playbook.md`. The `.scadpkg` consumer-facing format
+spec (member layout, `interface.*` tag channel, minimal readers for addon
+exporters) lives in `scadpkg-format.md`.
 
 ## Workflows
 
@@ -48,6 +52,7 @@ fillets) live in `ql-playbook.md`.
 | `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 |
+| `drawing-reconstruction` | editable rebuild from vector-PDF dimensions with stage checks and independent drawing/model/output acceptance |
 | `export-and-translation` | downstream formats from a validated package |
 
 Each workflow states: goal/scope, task decomposition (required/optional

{simplecadapi-2.1.1 → simplecadapi-2.1.3}/docs/skill/references/discipline/feature-tree-convention.md

@@ -101,6 +101,44 @@ design parameters) stay in the source; geometric verification never does
 — it lives in the external verification scripts per
 `geometric-validation.md`.
 
+## The `@scad.part` decorator and its cache
+
+`@scad.part` accepts keyword parameters only; emitted corpus sources state
+them explicitly so the meaning is legible from the source itself:
+
+- `id` — logical part identity (defaults to the function name); part of the
+  cache key.
+- `revision` — `'1.0.0'` by default; bump it to force rebuilds; part of the
+  cache key.
+- `inputs` — sequence of `file_input()` declarations; the referenced files'
+  content snapshots enter the cache key.
+- `cache` — cache policy: `"auto"` (read/write), `"off"`, `"read_only"`,
+  `"read_write"`, `"refresh"`, or a policy dict / `CachePolicy`.
+- `project_root` — anchor for the part cache, file inputs, and project
+  config. Default: the directory containing the builder's source file —
+  a script is its own project, runs from anywhere, and its cache lands
+  beside it. Pass it explicitly only to anchor at a larger project
+  (project-level cache or `[tool.simplecadapi.cache]` config).
+- `tolerance_profile` — kernel tolerance fingerprint (default
+  `'simplecad-default'`); part of the cache key.
+
+**Where the cache lands.** The cache root is `<anchor>/.simplecad/cache`
+(`records/`, `objects/`, `locks/`, `quarantine/`); part interface state
+lives beside it at `<anchor>/.simplecad/state/latest-parts.json` and
+follows the cache root. Overrides resolve as decorator `cache=` >
+environment (`SIMPLECAD_CACHE_DIR`, `SIMPLECAD_CACHE_MODE`, …) >
+`[tool.simplecadapi.cache]` in the `pyproject.toml` at the anchor >
+defaults. The cache key covers `id`, `revision`, `tolerance_profile`,
+normalized call arguments, the whole-file source fingerprint, file-input
+snapshots, and the generator profile (SDK/OCC versions) — any source edit
+invalidates.
+
+**Delivered sources state the anchor explicitly.** A translator-emitted
+or standalone `.ftc.py` passes `project_root=Path(__file__).parent`
+explicitly so the cache location is legible from the source itself —
+even though it matches the default, the corpus states it rather than
+relying on implicit resolution.
+
 ## Reference shape of a compliant source
 
 ```python
@@ -111,7 +149,8 @@ PLATE_T = scad.var("plate_t", 6.0, unit="mm")
 def _pocket_tools(p):
     ...  # block-local, geometry tier when tools are pure primitives
 
-@scad.part(id="motor-mount", revision="1.0.0", ...)
+@scad.part(id="motor-mount", revision="1.0.0",
+           project_root=Path(__file__).parent)
 def build_motor_mount() -> scad.Part:
     # ---- feature: base-plate (build, profile=sketch) ----
     s = scad.make_sketch_rsketch(name="base", plane="XY")

{simplecadapi-2.1.1 → simplecadapi-2.1.3}/docs/skill/references/docs/api/CacheLockTimeout.md

@@ -15,3 +15,5 @@ class CacheLockTimeout
 ## Description
 
 Raised when a cache key remains locked past policy timeout.
+
+Stays catchable as TimeoutError for lock-handling callers.

simplecadapi-2.1.3/docs/skill/references/docs/api/DrawingCalibration.md

@@ -0,0 +1,22 @@
+# DrawingCalibration
+
+## Class Definition
+
+```python
+class DrawingCalibration(pair_count: int, scale_mm_per_pt: float, scales_per_pair: list[float], max_relative_deviation: float, relative_tolerance: float, min_pairs: int, accepted: bool)
+```
+
+*Source: inspect/drawing/calibrate.py*
+
+## Import Surface
+
+- drawing-inspection namespace: `from simplecadapi.inspect import drawing` then `drawing.DrawingCalibration(...)`; unavailable inside GraphSession
+
+## Description
+
+Consensus mm-per-pt scale fitted from independent known dimensions.
+
+``accepted`` requires at least ``min_pairs`` pairs and all per-pair
+scales agreeing within ``relative_tolerance``. A calibration that failed
+must never be used to produce derived numbers: fix the anchor selection
+or the measurement instead.

simplecadapi-2.1.3/docs/skill/references/docs/api/DrawingMeasurements.md

@@ -0,0 +1,22 @@
+# DrawingMeasurements
+
+## Class Definition
+
+```python
+class DrawingMeasurements(measurement_count: int, scale_mm_per_pt: float | None, measurements: list[dict[str, Any]])
+```
+
+*Source: inspect/drawing/calibrate.py*
+
+## Import Surface
+
+- drawing-inspection namespace: `from simplecadapi.inspect import drawing` then `drawing.DrawingMeasurements(...)`; unavailable inside GraphSession
+
+## Description
+
+Point-pair and stroke-length measurements with optional mm conversion.
+
+Every entry keeps its native ``length_pt``; ``length_mm`` is populated
+only when a calibration is supplied. Millimetre values derived here are
+〔推算〕-grade claims: they must be cross-checked against annotated
+dimensions before they harden into facts.

simplecadapi-2.1.3/docs/skill/references/docs/api/DrawingSectionDimensions.md

@@ -0,0 +1,27 @@
+# DrawingSectionDimensions
+
+## Class Definition
+
+```python
+class DrawingSectionDimensions(source: str, plane: dict[str, Any], closed_contour_count: int, open_contour_count: int, measurements: list[dict[str, Any]], metadata: dict[str, Any] = field(default_factory=dict), configuration: dict[str, Any] = field(default_factory=dict), section_validation: dict[str, Any] = field(default_factory=dict), circle_diagnostics: list[dict[str, Any]] = field(default_factory=list))
+```
+
+*Source: inspect/drawing/section.py*
+
+## Import Surface
+
+- drawing-inspection namespace: `from simplecadapi.inspect import drawing` then `drawing.DrawingSectionDimensions(...)`; unavailable inside GraphSession
+
+## Description
+
+Candidate dimensions measured from one model section.
+
+Entries are candidates, not verdicts: the caller picks the ones that
+correspond to ledger rows and passes them back to
+:func:`render_model_section_rpath` with ``dim_id`` / ``nominal`` filled
+in. ``thickness`` candidates arise only from nested contour pairs; wall
+thickness of side-by-side strips shows up as a contour ``extent``.
+``section_validation`` separately reports closure, material topology and
+solid/section/display point checks; ``circle_diagnostics`` includes open
+contours and rejected fits. Neither output turns an uncertain value into
+a verified dimension.

simplecadapi-2.1.3/docs/skill/references/docs/api/DrawingStrokes.md

@@ -0,0 +1,25 @@
+# DrawingStrokes
+
+## Class Definition
+
+```python
+class DrawingStrokes(source: str, page: int, rotation: int, width_pt: float, height_pt: float, total_primitives: int, matched: int, strokes: list[dict[str, Any]], stroke_color_census: dict[str, int], fill_color_census: dict[str, int], metadata: dict[str, Any] = field(default_factory=dict))
+```
+
+*Source: inspect/drawing/geometry.py*
+
+## Import Surface
+
+- drawing-inspection namespace: `from simplecadapi.inspect import drawing` then `drawing.DrawingStrokes(...)`; unavailable inside GraphSession
+
+## Description
+
+Normalized path primitives of one page in display space.
+
+``strokes`` are flattened one entry per path item: ``line`` carries two
+endpoints, ``bezier`` carries all four control points (first and last are
+on-curve), ``quad`` carries the four corners in perimeter order, ``rect``
+carries four corners in perimeter order. ``total_primitives`` counts every item on
+the page; ``matched`` counts the entries that survived the filters. Only
+verified vector coordinates support calibrated measurements; coordinate
+preflight and feature-association checks are still required.

simplecadapi-2.1.3/docs/skill/references/docs/api/DrawingSummary.md

@@ -0,0 +1,23 @@
+# DrawingSummary
+
+## Class Definition
+
+```python
+class DrawingSummary(source: str, page_count: int, route: str, metadata: dict[str, Any], fonts: list[str], pages: list[dict[str, Any]])
+```
+
+*Source: inspect/drawing/summary.py*
+
+## Import Surface
+
+- drawing-inspection namespace: `from simplecadapi.inspect import drawing` then `drawing.DrawingSummary(...)`; unavailable inside GraphSession
+
+## Description
+
+Facts-only health report for one PDF drawing document.
+
+``route`` recommends how the downstream analysis should treat the file:
+``vector`` (mine the text and vector layers), ``raster`` (render-only
+reading), ``mixed`` (both layers present), ``text_only`` (no graphics at
+all), or ``empty`` (nothing extractable). The verdict is counted from
+per-page facts; no geometric or semantic interpretation happens here.

simplecadapi-2.1.3/docs/skill/references/docs/api/DrawingText.md

@@ -0,0 +1,23 @@
+# DrawingText
+
+## Class Definition
+
+```python
+class DrawingText(source: str, page: int, rotation: int, width_pt: float, height_pt: float, words: list[dict[str, Any]], clusters: list[dict[str, Any]], metadata: dict[str, Any] = field(default_factory=dict))
+```
+
+*Source: inspect/drawing/text.py*
+
+## Import Surface
+
+- drawing-inspection namespace: `from simplecadapi.inspect import drawing` then `drawing.DrawingText(...)`; unavailable inside GraphSession
+
+## Description
+
+All text objects of one page plus proximity clusters.
+
+Word and cluster boxes are in display space (matching ``page.rect`` and
+the image after the explicit pt-to-px transform). Clusters are proximity
+combination candidates, not verified tolerance stacks or feature mappings.
+Original word objects and display-space directions are preserved. Metadata
+supplies source hash, zero-based page, rotation, page boxes, units and version.