simplecadapi 2.1.1__tar.gz → 2.1.3b1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simplecadapi
-Version: 2.1.1
+Version: 2.1.3b1
 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
@@ -388,18 +388,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 +425,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.3b1`.
 
 ## What It Provides
 
@@ -785,6 +786,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:

{simplecadapi-2.1.1 → simplecadapi-2.1.3b1}/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.3b1`.
 
 ## What It Provides
 
@@ -531,6 +532,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:

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

@@ -4,9 +4,9 @@ description: Build, assemble, inspect, reconstruct, and export parametric CAD mo
 license: Apache-2.0
 metadata:
   project: simplecadapi
-  version: 2.1.1
+  version: 2.1.3b1
   package-name: simplecadapi
-  package-version: 2.1.1
+  package-version: 2.1.3b1
 ---
 
 # 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
 
@@ -175,12 +179,15 @@ print(len(rebuilt))
 
 - `references/README.md` — skill layer structure
 - `references/workflows/` — six goal-oriented workflows
-- `references/domains/` — eight capability domains
+- `references/domains/` — nine capability domains
 - `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.3b1}/docs/skill/references/README.md

@@ -34,12 +34,15 @@ whole API index up front.
 | `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 |
+| `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
 

{simplecadapi-2.1.1 → simplecadapi-2.1.3b1}/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.3b1/docs/skill/references/domains/addon-development.md

@@ -0,0 +1,175 @@
+# Task Domain: Addon Development
+
+Author, install, and manage SimpleCADAPI addons: third-party packages that
+add non-modeling capabilities — simulation, analysis, downstream tooling —
+by consuming `.scadpkg` product packages.
+
+## Use when
+
+- Creating or publishing an addon (a repository with `sca-addon.toml` and
+  a skill directory).
+- Installing, updating, or removing an addon with the `sca` CLI.
+- Deciding whether a capability belongs in an addon or in the SDK.
+
+## Boundary: addon vs SDK contribution
+
+| Capability | Belongs in |
+| --- | --- |
+| Geometry modeling, domain modeling operations, anything that must build BRep inside a session | SimpleCADAPI core (optionally as an extra, e.g. `simplecadapi[fem]`) |
+| Verification, analysis, simulation, rendering, export to foreign ecosystems, anything that *consumes* finished geometry | An addon |
+
+An addon has two legal integration modes with the SDK.
+
+**Recommended default — process boundary.** The addon consumes
+`.scadpkg` files (members, tags channel, occurrence graph, scene
+projection; units are millimeters) and whatever host tooling it needs,
+in any language. Dependency conflicts are structurally impossible and
+non-Python addons are first-class.
+
+**Allowed — in-process SDK use.** A Python addon may install
+`simplecadapi` inside its own environment and import it: the builtin
+exporters (STEP/STL/OBJ/MJCF, gmsh meshing) and the package readers
+(`read_product_package`, `load_product_package`) exist for exactly this
+kind of downstream consumer. The descriptor's `[compat] sca` range
+governs which SDK releases that dependency may resolve to — declare
+the SDK as a dependency of the addon environment and keep the range
+honest.
+
+What holds in both modes: the addon runs in its own environment and is
+not installed into the environment that models the geometry — mixing
+plugin dependencies into the modeling SDK environment is what the
+separation exists to prevent.
+
+## Repository layout
+
+```text
+<repo root>/
+  sca-addon.toml      descriptor: machine-checked facts only, no prose
+  skill/
+    SKILL.md          everything an agent reads; installed as sca-<name>
+    <supporting assets: scripts, references, templates...>
+  <runtime code, binaries, docs — addon-owned>
+```
+
+One document per audience: the descriptor is read by the `sca` CLI, the
+SKILL.md is read by agents. Never duplicate prose into the descriptor.
+
+## Descriptor reference (`sca-addon.toml`)
+
+Validation is strict: unknown tables and keys are rejected, every
+failure names the field and file.
+
+| Field | Rule |
+| --- | --- |
+| `[addon] name` | lowercase slug `[a-z0-9][a-z0-9-]{0,63}`; becomes the install directory and skill prefix |
+| `[addon] version` | dotted numeric with optional pre-release suffix (e.g. `0.3.1`, `2.0.4b2`) |
+| `[addon] license` | non-empty; must be accurate — addons are redistributed |
+| `[addon] skill_path` | relative POSIX-style directory containing `SKILL.md` |
+| `[compat] sca` | version range, comma-separated clauses with `== != >= <= > <`; a bare version means exact match. Ranges, never pins: SDK releases within a range must not break addons. Pre-release suffixes sort before their release (`2.0.4b2 < 2.0.4`); missing trailing components pad with zero (`2.1` == `2.1.0`) |
+| `[runtime] kind` | `binary` \| `python-env` \| `docker` \| `none` |
+| `[runtime] platforms` | non-empty list, required for `binary`/`python-env`, forbidden for `none`/`docker` |
+| `[runtime] check_cmd` | required for `binary`/`python-env`, optional for `docker`, forbidden for `none` |
+| `[runtime.check_overrides]` | optional per-platform command overrides; keys must be declared platforms |
+
+Closed platform enum (additive across spec versions):
+
+```text
+macos-arm64 | macos-x86_64 | linux-x86_64 | linux-aarch64
+| windows-x86_64 | windows-arm64
+```
+
+## `check_cmd` contract
+
+A runtime probe must be fast but meaningful:
+
+1. Exit code `0` means usable; any other exit or a missing command means
+   not usable.
+2. Execution shell is pinned by the spec: `sh -c` on Unix, `cmd /c` on
+   Windows — write the command accordingly.
+3. Completes in about two seconds; no network access, no license
+   checkout, no GUI launch.
+4. A failing probe warns loudly at install time but never blocks the
+   install — the runtime can be installed afterwards. Re-run it before
+   first use.
+
+## Addon SKILL.md requirements
+
+The skill is the addon's single agent-facing document:
+
+- **Frontmatter `description` is the routing card.** Hosts surface it to
+  agents verbatim; state the trigger condition, what the addon consumes
+  from `.scadpkg` (which members, which tag patterns such as
+  `interface.*`), and what it produces.
+- **Pre-check the runtime.** Run the probe (the descriptor's
+  `check_cmd`) before first use; on failure, name the missing runtime
+  and stop — never silently skip the analysis.
+- **Declare the consumption contract.** Units are millimeters; state
+  coordinate-system assumptions and required tags explicitly.
+- **Never modify geometry.** An addon analyzes, verifies, or transforms
+  finished packages; when a task needs geometry changes, return to the
+  SimpleCADAPI modeling workflows and re-capture.
+- **Reference the main skill.** Describe the pipeline end to end:
+  model with SimpleCADAPI → `capture` a `.scadpkg` → this addon
+  consumes it.
+
+## Reading a `.scadpkg`
+
+The complete consumer-facing format spec — member layout, manifest
+fields, the `interface.*` tag channel, and two verified minimal
+readers (in-process SDK and pure ZIP+JSON for any language) — lives in
+`references/scadpkg-format.md`. Point your addon's agent at that page:
+it is written so that an agent given the document alone can produce a
+correct parser or exporter for the inputs your addon declares. Mirror
+this pointer in your addon's SKILL.md (the page ships inside the
+SimpleCADAPI skill; the normative JSON Schemas also ship inside the
+`simplecadapi` wheel at `simplecadapi/contracts/` for environments
+without the skill).
+
+Consumer rules that hold regardless of path:
+
+- resolve members through the manifest by `sha256`, never by guessing
+  names or extensions;
+- treat missing `interface.*` names as loud failures naming the exact
+  name — never approximate by geometry;
+- verify `schema_version` major before parsing anything else.
+
+## Installing and managing addons
+
+```bash
+sca addon init                     # once per machine: home + registry + config
+sca addon add owner/repo           # install from GitHub (default branch)
+sca addon add owner/repo@v1.2.0    # pin a tag or commit for reproducibility
+sca addon add ./my-addon           # install a local checkout (test before publishing)
+sca addon update [name]            # re-fetch one addon or all
+sca addon remove name
+sca addon list                     # registry contents + on-disk drift
+```
+
+- Locations resolve as flag > environment variable (`SCA_ADDON_HOME`,
+  `SCA_SKILLS_DIR`) > `~/.sca/config.toml` > defaults
+  (`~/.sca/addons`, `~/.agents/skills`). The CLI never writes shell
+  profiles; env vars are user-side overrides.
+- Skills install as `sca-<name>` inside the skills directory — copied,
+  never symlinked. A non-registry directory of that name is never
+  overwritten.
+- GitHub sources fetch as tarballs (no git binary needed, byte-exact
+  files); `--method clone` is the escape hatch for private
+  repositories.
+
+### Hard failures vs warnings
+
+| Outcome | Behavior |
+| --- | --- |
+| Descriptor invalid, `[compat] sca` mismatch, platform unsupported, name collision, foreign skill directory | install aborts, naming the exact cause |
+| `check_cmd` fails, update downgrades | loud warning; install/update proceeds |
+| Registry vs disk drift (missing directories) | surfaced by `sca addon list` as `DRIFT` lines |
+
+## Publishing checklist
+
+1. `sca addon add ./repo` from a local checkout; confirm the summary
+   and that the skill lands under `sca-<name>`.
+2. `sca addon list` shows no drift; the runtime probe passes on every
+   declared platform you can test.
+3. Tag the release; users pin with `owner/repo@<tag>`.
+4. Bump `[addon] version` for every published change; widen
+   `[compat] sca` only after testing against the new SDK release.

simplecadapi-2.1.3b1/docs/skill/references/scadpkg-format.md

@@ -0,0 +1,152 @@
+# `.scadpkg` Package Format
+
+The durable product archive written by `capture`. This page is a
+consumer's spec: read it once, and you can parse any package and locate
+what an addon needs — geometry, tags, assemblies, scene assets — in any
+language. The normative sources are the JSON Schemas shipped inside the
+`simplecadapi` wheel (`simplecadapi/contracts/`); when prose and schema
+disagree, the schema wins.
+
+Authoring and installing addons that consume packages:
+`references/domains/addon-development.md`.
+
+## What a package is
+
+A ZIP archive. Everything inside is content-addressed and
+integrity-checked; the manifest (`package.json`) is the only map —
+never guess members by name or extension, always resolve through it.
+Packages are validated against Draft 2020-12 JSON Schemas both when
+written and when read; a tampered member produces a named rejection,
+not a silent fallback. Units are millimeters throughout.
+
+## Member layout
+
+| Member | Content | Schema |
+| --- | --- | --- |
+| `package.json` | manifest — the map to every other member | `product-package-3.schema.json` |
+| `definitions/part/<hash>.json` | one part definition (units, generator, caches, topology ref, connectors, material) | `part-definition-2.schema.json` |
+| `definitions/assembly/<hash>.json` | one assembly definition (instances, relations, solved snapshot, public connectors) | `assembly-definition-2.schema.json` |
+| `occurrences/root.json` | occurrence graph (which definitions occur where) | manifest member record |
+| `projections/scene/scene.json` | scene projection for rendering (present when captured with scene) | scene contracts |
+| `blobs/<sha256>` | content-addressed payloads (BREP cache, topology snapshots, glTF assets, feature graphs) | — |
+
+## Manifest (`package.json`) fields
+
+All top-level fields are required: `schema_version` (`"3.0"`),
+`artifact_kind` (`"product_package"`), `root` (path/definition_kind/
+definition_id/revision/content_hash), `definitions[]` (one record per
+definition: path, definition_kind, definition_id, revision,
+content_hash, sha256, byte_length), `blobs[]` (sha256, byte_length,
+`media_type`, `storage: {kind: "member", path}`), `occurrence_graph`
+(member record), `projections` (scene member record), and `content_hash`
+covering the manifest body.
+
+## Resolving references: sha256 is the key, not the path
+
+Every reference into a payload carries
+`{path, sha256, byte_length, media_type}`. The `path` is a **logical
+name** (`topology/<hash>.json`) — it is not necessarily a ZIP member
+path. The payload is stored under `blobs/<sha256-without-prefix>`, and
+the manifest's `blobs[]` entry gives the real `storage.path`. Resolve
+by `sha256`, always:
+
+```python
+def member_bytes(package, ref):
+    """ref: a BlobRef (attribute access) or its dict form (subscript)."""
+    sha = getattr(ref, "sha256", None) or ref["sha256"]
+    digest = str(sha).removeprefix("sha256:")
+    for blob in package.manifest["blobs"]:
+        if str(blob["sha256"]).removeprefix("sha256:") == digest:
+            return package.objects[str(blob["storage"]["path"])]
+    raise KeyError(f"member for {digest} not in manifest blobs")
+```
+
+`storage.kind` is `"member"` for single payloads; `"archive"` entries
+are composites (feature-graph manifests with source snapshots) whose
+inner files are themselves `member` blobs — resolving any single file
+by its own sha256 through the map above works uniformly.
+`media_type` on the record tells you what the payload is
+(`application/vnd.simplecad.entities+json` topology snapshots,
+`application/vnd.simplecad.feature-graph+zip` feature graphs,
+`model/gltf-binary` scene assets) — do not infer from extensions.
+
+## Definitions
+
+Part definitions carry: `units` (`"mm"`), `generator`
+(`{ocp_version}`), `solid_cache` (body reference — the BREP payload for
+in-process rebuild), `topology_snapshot_ref` (the tag channel, below),
+`connectors`, `material_ref`, `metadata`, `profile`, `revision`.
+Assembly definitions carry `definition_refs`, `instances`,
+`relations`, `public_connectors`, `solved_snapshot`,
+`grounded_instance_ids`, `feature_graph_ref`. Identity is
+(`definition_id`, `revision`, `content_hash`).
+
+## The tag channel: `interface.*` only
+
+Only tags in the `interface.*` namespace cross the package boundary;
+every other tag stays in the session. The chain:
+
+1. Take a **part** definition's `topology_snapshot_ref` (assemblies
+   carry `feature_graph_ref` instead).
+2. Resolve it by sha256 (above) into the snapshot JSON
+   (`{schema_version, entities[], entity_count, name_index,
+   topology_hash, geometry_hash}`).
+3. Read `name_index`: `{"interface.<name>": [{"kind", "topo_id",
+   "geometry_hash"}, ...]}` — one public name may reference several
+   entities of a single kind (a pattern of holes is one name over many
+   faces), in deterministic order.
+4. `entities[]` entries carry `kind` (`FACE` / `EDGE` / ...),
+   `topo_id`, `geometry_hash`, the full `tags` list, and
+   `feature_output` provenance (which graph node produced them).
+
+Consumer contract: if an `interface.*` name your tool requires is
+absent from `name_index`, fail loudly and name it — never guess by
+geometry. Model authors create these names with
+`apply_tag(shape=..., tag="interface.xxx")` during modeling; consuming
+them requires nothing from the modeling side afterwards.
+
+## Minimal readers
+
+### Path A — in-process SDK (Python addon with its own environment)
+
+```python
+import json
+
+from simplecadapi import read_product_package
+
+package = read_product_package(data="bracket.scadpkg")
+root = package.root_definition
+snapshot = json.loads(member_bytes(package, root.topology_snapshot_ref))
+faces_by_name = snapshot["name_index"]  # {"interface.load_surface": [...], ...}
+```
+
+`read_product_package` validates the full package (integrity + schema)
+before returning; `load_product_package(data=...)` returns the root
+definition directly. Builtin exporters
+(`export_product_package_to_step/stl/obj/mjcf`) start from the same
+validated package.
+
+### Path B — language-agnostic (pure ZIP + JSON)
+
+The same five steps in any language:
+
+1. Open the ZIP; read `package.json`.
+2. Check `schema_version` major is `3`; abort loudly otherwise.
+3. Walk `manifest["definitions"]`, reading each record's `path`
+   (these paths ARE real member paths).
+4. Build a sha→path map over `manifest["blobs"]` entries with
+   `storage.kind == "member"`; resolve every payload reference's
+   `sha256` through it, then read that member.
+5. Parse the topology snapshot and read `name_index`.
+
+In Python this is `zipfile` + `json` only — no SDK import, no OCP;
+this is the path for non-Python addons and for plugins that must not
+share an environment with the SDK.
+
+## Integrity rules
+
+Every member is covered by a sha256 recorded in the manifest; the
+manifest body is covered by `content_hash` over canonical JSON
+(RFC 8785). Consumers should verify the digest of anything they load;
+the SDK read path already does. Hand-editing members is unsupported —
+rebuild the package from source instead.

simplecadapi-2.1.3b1/docs/updates/2.1.2.md

@@ -0,0 +1,54 @@
+# 2.1.2 Update Notes
+
+> **Release notice:** Validate generated definitions, assembly constraints, and
+> manufacturing geometry before production use.
+
+## Script-anchored part cache (SDK behavior change)
+
+The `@scad.part` / `@scad.assemble` anchor is now the directory containing the
+builder's source file. The content-addressed part cache and the part interface
+state land at `<script dir>/.simplecad/` by default:
+
+- A standalone script runs from anywhere — no `pyproject.toml` is required up
+  the tree, and a missing project root no longer fails at decoration time.
+- Copying or deleting a script directory carries or clears its cache with it.
+- `file_input()` paths resolve relative to the anchor; scripts typically
+  declare their inputs next to themselves (`scad.file_input("model.py")`).
+- Pass `project_root=...` explicitly to anchor at a larger project — the
+  project-level cache and the `[tool.simplecadapi.cache]` table follow the
+  explicit anchor. Environment overrides (`SIMPLECAD_CACHE_DIR`,
+  `SIMPLECAD_CACHE_MODE`, …) are unchanged.
+
+## Keyword-form translator corpus
+
+All sketch-family calls emitted by the HistCAD→FTC translator are now
+keyword-form (`scad.add_circle_rsketch(sketch=s, entity_id=..., center=...,
+radius=...)`, `scad.constrain_distance_x_rsketch(sketch=s, a=..., b=...,
+value=...)`). Translated sources are training corpus: the parameter names
+carry the meaning in the source itself. The same pin already guarded the
+CadQuery translator; both suites now reject positional sketch-family calls
+(boolean `*solids` varargs stay positional by signature).
+
+## Explicit cache anchor in emitted sources
+
+Both translators (histjson, cadqueryftc) emit
+`project_root=Path(__file__).parent` on `@scad.part` explicitly, so a
+delivered `.ftc.py` states where its cache lands instead of relying on
+implicit resolution. The three `examples/histcad_demo` sources were
+regenerated; STEP volume reconciliation is unchanged (1.63e-16 / 8.18e-05).
+
+## FTC convention: `@scad.part` parameters and the cache
+
+`docs/skill/references/discipline/feature-tree-convention.md` gains a section
+documenting the decorator's keyword parameters (`id`, `revision`, `inputs`,
+`cache`, `project_root`, `tolerance_profile`), where the cache and interface
+state land, the override chain (decorator > environment > project config >
+defaults), and the cache key composition.
+
+## Compatibility notes
+
+- Builders relying on the old implicit project-root walk-up (shared
+  `<repo>/.simplecad`) now get a script-local cache instead; pass
+  `project_root=...` explicitly to keep the old anchoring.
+- In-repo examples that declared repo-root-relative `file_input` paths were
+  rewritten to script-relative paths in this release.

simplecadapi-2.1.3b1/docs/updates/2.1.2.zh-CN.md

@@ -0,0 +1,47 @@
+# 2.1.2 更新说明
+
+> **发布说明：** 用于生产前，请验证生成的定义、装配约束和制造几何。
+
+## @part 缓存锚定到脚本目录（SDK 行为变更）
+
+`@scad.part` / `@scad.assemble` 的锚点改为 builder 源文件所在目录，内容寻址
+part 缓存与 interface 状态默认落在 `<脚本目录>/.simplecad/`：
+
+- 独立脚本在任何位置都能运行——不再要求向上存在 `pyproject.toml`，
+  缺少工程根不会再在装饰阶段报错。
+- 拷贝或删除脚本目录，缓存随之带走或清空。
+- `file_input()` 路径相对锚点解析；脚本通常声明自己旁边的文件
+  （`scad.file_input("model.py")`）。
+- 需要工程级缓存时显式传 `project_root=...`——工程级缓存与
+  `[tool.simplecadapi.cache]` 配置表跟随显式锚点。环境变量覆盖
+  （`SIMPLECAD_CACHE_DIR`、`SIMPLECAD_CACHE_MODE` 等）不变。
+
+## 翻译语料 keyword 参数化
+
+HistCAD→FTC 翻译器发射的全部草图族调用改为 keyword 形式
+（`scad.add_circle_rsketch(sketch=s, entity_id=..., center=..., radius=...)`、
+`scad.constrain_distance_x_rsketch(sketch=s, a=..., b=..., value=...)`）。
+翻译产物是训练语料：参数名让语义直接从源码可读。CadQuery 翻译器此前已有
+同一钉子；现在两套测试套件都拒绝位置形式的草图族调用（布尔 `*solids`
+变参按签名豁免）。
+
+## 发射源显式声明缓存锚点
+
+两个翻译器（histjson、cadqueryftc）都在 `@scad.part` 上显式发射
+`project_root=Path(__file__).parent`——交付的 `.ftc.py` 自己声明缓存落点，
+不依赖隐式解析。`examples/histcad_demo` 三个产物已重生成；STEP 体积对账
+不变（1.63e-16 / 8.18e-05）。
+
+## FTC 规范：@part 参数与缓存契约
+
+`docs/skill/references/discipline/feature-tree-convention.md` 新增一节，
+写明装饰器的 keyword 参数（`id`、`revision`、`inputs`、`cache`、
+`project_root`、`tolerance_profile`）、缓存与 interface 状态的落点、
+覆盖链（装饰器 > 环境变量 > 工程配置 > 默认值）与缓存键构成。
+
+## 兼容性说明
+
+- 依赖旧的隐式工程根向上查找（共享 `<repo>/.simplecad`）的 builder，
+  现在默认得到脚本局部缓存；显式传 `project_root=...` 可保留旧锚定。
+- 仓库内以工程根相对路径声明 `file_input` 的示例，本版本已改写为
+  脚本相对路径。