feat: integrate SimpleCADAPI 2.0.2 CAD workflows

SimpleCADAPI/docs/api/Dimension.md

@@ -0,0 +1,17 @@
+# Dimension
+
+## Class Definition
+
+```python
+class Dimension(length: int = 0, angle: int = 0)
+```
+
+*Source: units.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import Dimension`
+
+## Description
+
+Physical dimension represented by integer length and angle exponents.

SimpleCADAPI/docs/api/DimensionTolerance.md

@@ -0,0 +1,20 @@
+# DimensionTolerance
+
+## Class Definition
+
+```python
+class DimensionTolerance(lower_deviation: float, upper_deviation: float)
+```
+
+*Source: expr.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import DimensionTolerance`
+
+## Description
+
+Permitted lower and upper deviations from a nominal dimension.
+
+Deviations are signed: the lower deviation must be less than or equal to
+zero and the upper deviation must be greater than or equal to zero.

SimpleCADAPI/docs/api/FreeCADScriptTranslator.md

@@ -21,6 +21,7 @@ Current design goals:
 - Translate only from the canonical low-level `graph` IR
 - Preserve node metadata and graph lineage as FreeCAD custom properties
 - Preserve `expression_graph` as explicit translator metadata
+- Preserve dimension tolerances and tolerance-chain requirements as metadata
 - Preserve exported assembly constraints as document metadata objects
 - Keep assembly metadata from the full model payload alongside the IR-driven
 geometry translation

SimpleCADAPI/docs/api/GraphSession.md

@@ -16,16 +16,15 @@ class GraphSession(graph_id: Optional[str] = None)
 
 Context manager that records CAD operations into a DAG.
 
-with GraphSession() as session:
-n1 = record_operation(
-"make_line_redge", {"start": (0, 0, 0), "end": (1, 0, 0)}
-)
-n2 = record_operation(
-"make_line_redge", {"start": (1, 0, 0), "end": (1, 1, 0)}
-)
-record_operation(
-"make_wire_from_edges_rwire", {"edge_count": 2}, inputs=[n1, n2]
-)
+For new replayable model entry points, prefer `@scad.model`, which owns the
+session and returns a `ModelResult`. Use `GraphSession` directly when composing
+or testing lower-level graph workflows. `result_node_ids` reports the graph
+nodes selected by `capture_result`:
 
-# Access the graph after the session
-print(session.graph.topological_order())
+```python
+with GraphSession(graph_id="demo") as session:
+    body = make_box_rsolid(width=10.0, height=6.0, depth=2.0)
+    session.capture_result(value=body)
+
+print(session.result_node_ids)
+```

SimpleCADAPI/docs/api/ModelResult.md

@@ -0,0 +1,64 @@
+# ModelResult
+
+## Class Definition
+
+```python
+@dataclass(frozen=True)
+class ModelResult:
+    value: Any
+    session: GraphSession
+    result_node_ids: Tuple[str, ...]
+    model_json: str
+    session_json: str
+    artifact_paths: Mapping[str, Path] = field(default_factory=dict)
+```
+
+*Source: graph.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import ModelResult`
+
+## Description
+
+Immutable result returned by a function decorated with `@scad.model`.
+It keeps the ordinary Python return value together with the owned session and
+the durable graph artifacts produced for that model invocation.
+
+## Attributes
+
+- `value`: The value returned by the model function. It may be a shape, a
+  product assembly, or a tuple containing application-level reports and a
+  captured preview.
+- `session`: The completed `GraphSession` that recorded the model.
+- `result_node_ids`: Explicitly captured graph node ids used as model outputs.
+- `model_json`: Canonical low-level operation graph JSON containing the captured
+  result leaves.
+- `session_json`: Session JSON containing the complete session state.
+- `artifact_paths`: Files written by automatic export. It contains the `scene`
+  key when captured geometry or product values produced a Scene ZIP.
+
+## Artifact Export
+
+```python
+result = build_model()
+exported = result.export_artifacts(output_dir="examples/out/bracket")
+print(exported.artifact_paths["scene"])
+```
+
+The same export runs automatically when `@scad.model(export_dir=...)` is used.
+Only values explicitly passed to `capture_result(...)` are considered final
+geometry/product outputs. Automatic export writes one self-contained
+`<graph_id>.scene.zip` containing the model JSON, mapped Python sources, and
+render/selection assets; it does not write adjacent model/session JSON, STEP,
+STL, or FCStd files. Without an export directory, no files are written.
+
+## Replay
+
+```python
+result = build_model()
+rebuilt = result.replay()
+```
+
+`replay()` is equivalent to replaying `result.model_json`. Pass
+`strict=False` only when intentionally relaxing replay validation.

SimpleCADAPI/docs/api/README.md

@@ -65,14 +65,38 @@ This index includes generated docs for the public SimpleCAD API surface, includi
 - [loft_rsolid](loft_rsolid.md) *(from operations.py)* `top-level`
 - [revolve_rsolid](revolve_rsolid.md) *(from operations.py)* `top-level`
 - [sweep_rsolid](sweep_rsolid.md) *(from operations.py)* `top-level`
+- [twisted_sweep_rsolid](twisted_sweep_rsolid.md) *(from operations.py)* `top-level`
 
 ## Tagging and Selection
 
 - [apply_tag](apply_tag.md) *(from operations.py)* `top-level`
+- [apply_tag_rselection](apply_tag_rselection.md) *(from operations.py)* `top-level`
+- [explain_tag](explain_tag.md) *(from operations.py)* `top-level`
 - [list_tags](list_tags.md) *(from operations.py)* `top-level`
 - [select_edges_by_tag](select_edges_by_tag.md) *(from operations.py)* `top-level`
 - [select_faces_by_tag](select_faces_by_tag.md) *(from operations.py)* `top-level`
 
+Creation-time topology-identity tags are supported by profile constructors and
+native feature primitives through `tag_prefix`. QL selectors also support `shared_boundary(...)`,
+`intersection(...)`, `incident_to(...)`, `incident_face_count(...)`, and
+`solids()` for relation-aware Edge selection.
+
+## Unified Tag Contract
+
+Topology identity and user semantics share one public tag model. Every binding
+is inspected with `list_tags(...)` and `explain_tag(...)` and queried with
+`ql.tag(...)`; one topology object may carry several tags for different uses.
+
+`tag_prefix="housing"` creates topology-identity tags such as
+`housing.face.top` and `housing.solid`. These bindings carry `topology_name`
+evidence and project only when kernel history proves exact correspondence.
+
+Role parameters such as `top_face_tag`, `side_faces_tag`, and
+`generated_faces_tag`, plus `result_tag`, create tags whose evidence identifies
+the kernel-proven role or result. Their tag text alone does not establish
+topology identity. There is one public tag parameter per target role, not a
+generic role-to-tag mapping.
+
 ## Boolean Operations
 
 - [cut_rsolid](cut_rsolid.md) *(from operations.py)* `top-level`
@@ -98,6 +122,10 @@ This index includes generated docs for the public SimpleCAD API surface, includi
 ## Modeling Graph and Replay
 
 - [GraphSession](GraphSession.md) *(from graph.py)* `top-level`
+- [ModelResult](ModelResult.md) *(from graph.py)* `top-level`
+- [capture_result](capture_result.md) *(from graph.py)* `top-level`
+- [model](model.md) *(from graph.py)* `top-level`
+- [requires_session](requires_session.md) *(from graph.py)* `top-level`
 - [export_graph_json](export_graph_json.md) *(from serializer.py)* `top-level`
 - [export_model_json](export_model_json.md) *(from serializer.py)* `top-level`
 - [export_session_json](export_session_json.md) *(from serializer.py)* `top-level`
@@ -111,12 +139,34 @@ This index includes generated docs for the public SimpleCAD API surface, includi
 ## Expressions and Parameters
 
 - [Const](Const.md) *(from expr.py)* `top-level`
+- [DimensionTolerance](DimensionTolerance.md) *(from expr.py)* `top-level`
 - [Expr](Expr.md) *(from expr.py)* `top-level`
 - [ExpressionGraph](ExpressionGraph.md) *(from expr.py)* `top-level`
+- [ToleranceAnalysis](ToleranceAnalysis.md) *(from tolerance.py)* `top-level`
+- [ToleranceAnalysisError](ToleranceAnalysisError.md) *(from tolerance.py)* `top-level`
+- [ToleranceCheck](ToleranceCheck.md) *(from tolerance.py)* `top-level`
+- [ToleranceContribution](ToleranceContribution.md) *(from tolerance.py)* `top-level`
+- [ToleranceGraph](ToleranceGraph.md) *(from tolerance.py)* `top-level`
+- [ToleranceReport](ToleranceReport.md) *(from tolerance.py)* `top-level`
+- [ToleranceRequirement](ToleranceRequirement.md) *(from tolerance.py)* `top-level`
+- [ToleranceValidationError](ToleranceValidationError.md) *(from tolerance.py)* `top-level`
 - [Var](Var.md) *(from expr.py)* `top-level`
+- [analyze_tolerance](analyze_tolerance.md) *(from tolerance.py)* `top-level`
+- [check_tolerance](check_tolerance.md) *(from tolerance.py)* `top-level`
 - [const](const_function.md) *(from expr.py)* `top-level`
 - [var](var_function.md) *(from expr.py)* `top-level`
 
+## Physical Units
+
+- [Dimension](Dimension.md) *(from units.py)* `top-level`
+- [Unit](Unit.md) *(from units.py)* `top-level`
+- [UnitValidationError](UnitValidationError.md) *(from units.py)* `top-level`
+- [canonical_unit_for_dimension](canonical_unit_for_dimension.md) *(from units.py)* `top-level`
+- [convert_value](convert_value.md) *(from units.py)* `top-level`
+- [expression_uses_units](expression_uses_units.md) *(from units.py)* `top-level`
+- [get_unit](get_unit.md) *(from units.py)* `top-level`
+- [infer_dimension](infer_dimension.md) *(from units.py)* `top-level`
+
 ## Types and Errors
 
 - [SimpleCADError](SimpleCADError.md) *(from errors.py)* `top-level`
@@ -207,11 +257,15 @@ This index includes generated docs for the public SimpleCAD API surface, includi
 - [meta](meta.md) *(from ql.py)* `submodule:ql`
 - [not_](not_.md) *(from ql.py)* `submodule:ql`
 - [or_](or_.md) *(from ql.py)* `submodule:ql`
+- [output_role](output_role.md) *(from ql.py)* `submodule:ql`
 - [place_component_rassembly](place_component_rassembly.md) *(from operations.py)* `top-level`
 - [radial_pattern_rsolidlist](radial_pattern_rsolidlist.md) *(from operations.py)* `top-level`
 - [render_screenshot_rpath](render_screenshot_rpath.md) *(from operations.py)* `top-level`
 - [select](select.md) *(from ql.py)* `submodule:ql`
+- [solids](solids.md) *(from ql.py)* `submodule:ql`
 - [solve_assembly_constraints_rassembly](solve_assembly_constraints_rassembly.md) *(from operations.py)* `top-level`
+- [source_binding](source_binding.md) *(from ql.py)* `submodule:ql`
+- [source_topology](source_topology.md) *(from ql.py)* `submodule:ql`
 - [tag](tag.md) *(from ql.py)* `submodule:ql`
 - [unground_component_rassembly](unground_component_rassembly.md) *(from operations.py)* `top-level`
 - [value](value.md) *(from ql.py)* `submodule:ql`

SimpleCADAPI/docs/api/Sketch.md

@@ -22,3 +22,12 @@ Use `make_sketch_rsketch(...)`, `add_point_rsketch(...)`,
 profiles. Public sketch construction APIs are functional and return an
 updated `Sketch` document. The legacy `curves` constructor remains only for
 reading already-built wire/edge containers.
+
+Entity IDs are creation-time local identifiers, not geometry guesses. During
+`make_wire_from_sketch_rwire(...)` or `make_face_from_sketch_rface(...)`, the
+promotion map binds each ordered profile entity to exactly one generated Edge.
+The canonical topology-identity tags are
+`sketch.<sketch-name>.entity.<entity-id>` and
+`sketch.<sketch-name>.profile.<profile-id>`, with `topology_name` evidence.
+Downstream features can project those tags only when their kernel history
+proves one-source/one-target correspondence.

SimpleCADAPI/docs/api/ToleranceAnalysis.md

@@ -0,0 +1,17 @@
+# ToleranceAnalysis
+
+## Class Definition
+
+```python
+class ToleranceAnalysis(target_expr_id: str, method: ToleranceMethod, nominal: float, lower_bound: float, upper_bound: float, lower_deviation: float, upper_deviation: float, dimension: Dimension | None = None, unit: Unit | None = None, contributions: Tuple[ToleranceContribution, ...] = ())
+```
+
+*Source: tolerance.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import ToleranceAnalysis`
+
+## Description
+
+Nominal value and propagated limits for an expression.

SimpleCADAPI/docs/api/ToleranceAnalysisError.md

@@ -0,0 +1,17 @@
+# ToleranceAnalysisError
+
+## Class Definition
+
+```python
+class ToleranceAnalysisError
+```
+
+*Source: tolerance.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import ToleranceAnalysisError`
+
+## Description
+
+Raised when a tolerance chain cannot be propagated safely.

SimpleCADAPI/docs/api/ToleranceCheck.md

@@ -0,0 +1,17 @@
+# ToleranceCheck
+
+## Class Definition
+
+```python
+class ToleranceCheck(requirement: ToleranceRequirement, analysis: ToleranceAnalysis, passed: bool, lower_margin: float, upper_margin: float)
+```
+
+*Source: tolerance.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import ToleranceCheck`
+
+## Description
+
+Validation result for one tolerance requirement.

SimpleCADAPI/docs/api/ToleranceContribution.md

@@ -0,0 +1,17 @@
+# ToleranceContribution
+
+## Class Definition
+
+```python
+class ToleranceContribution(variable_expr_id: str, variable_name: str, nominal: float, source_tolerance: DimensionTolerance, sensitivity: float | None, lower_deviation: float, upper_deviation: float, source_unit: Unit | None = None)
+```
+
+*Source: tolerance.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import ToleranceContribution`
+
+## Description
+
+One source dimension's propagated contribution to a result.

SimpleCADAPI/docs/api/ToleranceGraph.md

@@ -0,0 +1,17 @@
+# ToleranceGraph
+
+## Class Definition
+
+```python
+class ToleranceGraph(expression_graph: ExpressionGraph)
+```
+
+*Source: tolerance.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import ToleranceGraph`
+
+## Description
+
+Tolerance requirements attached to one expression graph.

SimpleCADAPI/docs/api/ToleranceReport.md

@@ -0,0 +1,17 @@
+# ToleranceReport
+
+## Class Definition
+
+```python
+class ToleranceReport(checks: Tuple[ToleranceCheck, ...] = ())
+```
+
+*Source: tolerance.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import ToleranceReport`
+
+## Description
+
+Validation report for every requirement in a tolerance graph.

SimpleCADAPI/docs/api/ToleranceRequirement.md

@@ -0,0 +1,17 @@
+# ToleranceRequirement
+
+## Class Definition
+
+```python
+class ToleranceRequirement(requirement_id: str, target_expr_id: str, tolerance: DimensionTolerance, method: ToleranceMethod = 'worst_case', name: str = '', tolerance_unit: Unit | None = None, target_dimension: Dimension | None = None)
+```
+
+*Source: tolerance.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import ToleranceRequirement`
+
+## Description
+
+Permitted result deviations for one derived dimension.

SimpleCADAPI/docs/api/ToleranceValidationError.md

@@ -0,0 +1,17 @@
+# ToleranceValidationError
+
+## Class Definition
+
+```python
+class ToleranceValidationError(report: 'ToleranceReport')
+```
+
+*Source: tolerance.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import ToleranceValidationError`
+
+## Description
+
+Raised when one or more declared tolerance requirements fail.

SimpleCADAPI/docs/api/Unit.md

@@ -0,0 +1,20 @@
+# Unit
+
+## Class Definition
+
+```python
+class Unit(symbol: str, dimension: Dimension, scale_to_canonical: float)
+```
+
+*Source: units.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import Unit`
+
+## Description
+
+Named unit with a scale to SimpleCAD's canonical numeric units.
+
+Custom units are supported and serialize their symbol, dimension, and scale.
+Registered built-in units serialize as compact symbols.

SimpleCADAPI/docs/api/UnitValidationError.md

@@ -0,0 +1,17 @@
+# UnitValidationError
+
+## Class Definition
+
+```python
+class UnitValidationError
+```
+
+*Source: units.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import UnitValidationError`
+
+## Description
+
+Raised when units or expression dimensions are physically inconsistent.

SimpleCADAPI/docs/api/Var.md

@@ -3,7 +3,7 @@
 ## Class Definition
 
 ```python
-class Var(name: str, default: float, comment: str | None = None, expr_id: str = field(default_factory=lambda : _make_expr_id('var')))
+class Var(name: str, default: float, comment: str | None = None, expr_id: str = field(default_factory=lambda : _make_expr_id('var')), tolerance: DimensionTolerance | None = None, unit: Unit | None = None, tolerance_unit: Unit | None = None)
 ```
 
 *Source: expr.py*
@@ -14,4 +14,8 @@ class Var(name: str, default: float, comment: str | None = None, expr_id: str =
 
 ## Description
 
-Named scalar parameter with a default fallback value.
+Named scalar parameter with optional physical-unit and tolerance intent.
+
+``default`` and ``tolerance`` remain in their declared units. Evaluation,
+geometry parameters, and tolerance propagation convert them to SimpleCAD's
+canonical CAD units: millimeters for length and degrees for angle.

SimpleCADAPI/docs/api/add_line_rsketch.md

@@ -14,4 +14,6 @@ def add_line_rsketch(sketch: Sketch, entity_id: str, start: Union[SketchRef, str
 
 ## Description
 
-Add a named line entity and return an updated sketch document.
+Add an identified line entity and return an updated sketch document. During
+profile promotion, `entity_id` becomes the local segment of the canonical
+topology-identity tag for the corresponding profile Edge.

SimpleCADAPI/docs/api/analyze_tolerance.md

@@ -0,0 +1,27 @@
+# analyze_tolerance
+
+## API Definition
+
+```python
+def analyze_tolerance(value: ScalarLike, *, method: ToleranceMethod = 'worst_case') -> ToleranceAnalysis
+```
+
+*Source: tolerance.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import analyze_tolerance`
+
+## Description
+
+Propagate source manufacturing tolerances through a scalar expression.
+
+``worst_case`` returns guaranteed interval bounds. Affine chains are
+dependency-aware, so repeated variables such as ``x - x`` cancel exactly;
+nonlinear chains use conservative interval arithmetic. ``rss`` performs a
+first-order root-sum-square calculation using analytic sensitivities.
+
+Unit-aware variables are converted to canonical CAD units before
+propagation. The returned analysis reports the inferred physical dimension
+and canonical result unit. Every variable in the expression must declare a
+source tolerance.

SimpleCADAPI/docs/api/apply_tag.md

@@ -14,10 +14,13 @@ def apply_tag(shape: AnyShape, tag: str) -> AnyShape
 
 ## Description
 
-Attach a normalized tag to a shape using the standard propagation policy.
+Attach a normalized local user tag to a shape.
 
 Tags must already be normalized lowercase tokens such as
-``role.mounting_surface`` or ``group.fasteners``. Propagation is intentionally
-not configurable from the public API; the default tag policy propagates
-semantic role/anchor/group tags downward and keeps topology-specific tags
-local.
+`role.mounting_surface` or `group.fasteners`. The default topology policy is
+`local` for every tag; token prefixes do not imply downward propagation.
+Lineage visibility is limited to proven continuation and fragment witnesses.
+
+`apply_tag(...)` preserves its historical in-place wrapper behavior. Use
+`apply_tag_rselection(...)` when you need an independent semantic shape view,
+explicit topology propagation, or a replayable multi-entity assignment.

SimpleCADAPI/docs/api/apply_tag_rselection.md

@@ -0,0 +1,36 @@
+# apply_tag_rselection
+
+## API Definition
+
+```python
+def apply_tag_rselection(
+    scope: AnyShape,
+    targets: Union[ShapeSelector, Sequence[AnyShape]],
+    tag: str,
+    topology_propagation: str | TopologyPropagation = TopologyPropagation.LOCAL,
+    lineage_policy: str | LineagePolicy = LineagePolicy.CONTINUATION_FRAGMENT,
+) -> AnyShape
+```
+
+*Source: operations.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import apply_tag_rselection`
+
+## Description
+
+Return an independent semantic view over the same geometry with one canonical
+`TagBinding` attached to the selected entities. `targets` may be a serializable
+QL `ShapeSelector` or a non-empty sequence of topology objects belonging to
+`scope`.
+
+Topology propagation defaults to `local`. Set `topology_propagation="downward"`
+only when descendants should inherit the binding. Lineage defaults to proven
+continuation and fragment derivations; it never makes lineage part of the
+`effective` scope.
+
+Inside `GraphSession`, the operation records the complete binding, target intent,
+and selected-reference evidence. Replay re-resolves the target and checks that
+the evidence has not drifted. The semantic node does not replace geometry-owned
+topology references.

SimpleCADAPI/docs/api/canonical_unit_for_dimension.md

@@ -0,0 +1,19 @@
+# canonical_unit_for_dimension
+
+## API Definition
+
+```python
+def canonical_unit_for_dimension(dimension: Dimension) -> Unit
+```
+
+*Source: units.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import canonical_unit_for_dimension`
+
+## Description
+
+Return the canonical unit used by CAD and tolerance calculations.
+
+Length, area, volume, and angle use ``mm``, ``mm^2``, ``mm^3``, and ``deg``.

SimpleCADAPI/docs/api/capture_result.md

@@ -0,0 +1,34 @@
+# capture_result
+
+## API Definition
+
+```python
+def capture_result(*, value: Any) -> Any
+```
+
+*Source: graph.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import capture_result`
+
+## Description
+
+Mark the graph nodes represented by `value` as the explicit final outputs of the
+active model session. The value is returned unchanged, so it can be used inline
+or assigned back to a local variable.
+
+```python
+@scad.model(graph_id="multi_output_demo")
+def build_model():
+    primary = scad.make_box_rsolid(width=10.0, height=4.0, depth=2.0)
+    secondary = scad.make_cylinder_rsolid(radius=2.0, height=5.0)
+    return scad.capture_result(value=(primary, secondary))
+```
+
+Explicit capture prevents unrelated intermediate graph leaves from becoming
+model outputs. When the enclosing `@model` uses `export_dir=...`, captured
+geometry and product values become roots in the single self-contained Scene ZIP.
+The package embeds model JSON and mapped Python sources; automatic export does
+not create adjacent model/session JSON, STEP, STL, or FCStd files. It must be
+called inside `@model` or another active `GraphSession`.

SimpleCADAPI/docs/api/chamfer_rsolid.md

@@ -3,7 +3,14 @@
 ## API Definition
 
 ```python
-def chamfer_rsolid(solid: Solid, edges: Union[Sequence[Edge], ShapeSelector], distance: ScalarLike) -> Solid
+def chamfer_rsolid(
+    solid: Solid,
+    edges: Union[Sequence[Edge], ShapeSelector],
+    distance: ScalarLike,
+    *,
+    result_tag: Optional[str] = None,
+    generated_faces_tag: Optional[str] = None,
+) -> Solid
 ```
 
 *Source: operations.py*
@@ -14,4 +21,10 @@ def chamfer_rsolid(solid: Solid, edges: Union[Sequence[Edge], ShapeSelector], di
 
 ## Description
 
-Apply chamfers to selected solid edges.
+Apply chamfers to selected solid edges. `generated_faces_tag` targets every face
+with the kernel-proven `chamfer.patch` role. OCC contour expansion is included
+rather than treating only the seed edge as the feature boundary.
+
+The operation fails if a requested patch role has no proven result. `result_tag`
+tags the resulting solid, and graph recording lowers assignments to replayable
+semantic nodes.

SimpleCADAPI/docs/api/check_tolerance.md

@@ -0,0 +1,22 @@
+# check_tolerance
+
+## API Definition
+
+```python
+def check_tolerance(value: ScalarLike, tolerance: ToleranceLike, *, method: ToleranceMethod = 'worst_case', name: str | None = None, tolerance_unit: UnitLike | None = None) -> ToleranceCheck
+```
+
+*Source: tolerance.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import check_tolerance`
+
+## Description
+
+Propagate and verify one Length or Angle requirement.
+
+``tolerance_unit`` defaults to the target dimension's canonical unit. When
+provided, it must be dimensionally compatible and is converted before the
+comparison. Legacy unitless requirements remain supported when no unit is
+supplied.

SimpleCADAPI/docs/api/convert_value.md

@@ -0,0 +1,17 @@
+# convert_value
+
+## API Definition
+
+```python
+def convert_value(value: int | float, from_unit: UnitLike, to_unit: UnitLike) -> float
+```
+
+*Source: units.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import convert_value`
+
+## Description
+
+Convert a finite numeric value between dimensionally compatible units.

SimpleCADAPI/docs/api/cut_rsolid.md

@@ -3,7 +3,11 @@
 ## API Definition
 
 ```python
-def cut_rsolid(*solids: Union[Solid, Sequence[Solid]], skip_non_intersecting: bool = True) -> Solid
+def cut_rsolid(
+    *solids: Union[Solid, Sequence[Solid]],
+    skip_non_intersecting: bool = True,
+    tracking_policy: TrackingPolicy | str = TrackingPolicy.FULL,
+) -> Solid
 ```
 
 *Source: operations.py*
@@ -29,6 +33,10 @@ sequences, and returns a single `Solid`.
 
 - **Description**: When True, tools with no meaningful intersection are ignored for interactive convenience. Graph replay records this flag and should use False for strict diagnostic workflows.
 
+### tracking_policy
+
+- **Description**: `TrackingPolicy.FULL` computes topology history and lineage. `TrackingPolicy.GRAPH` preserves the canonical cut node, parameters, inputs, result topology references, and replay while omitting `TopoDelta` and history-derived topology lineage. Intersection validation and `skip_non_intersecting` behavior are unchanged.
+
 ## Returns
 
 Solid: The cut result solid.

SimpleCADAPI/docs/api/explain_tag.md

@@ -0,0 +1,27 @@
+# explain_tag
+
+## API Definition
+
+```python
+def explain_tag(
+    shape: AnyShape,
+    tag: str,
+    scope: str | TagScope = TagScope.EFFECTIVE,
+) -> List[Dict[str, Any]]
+```
+
+*Source: operations.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import explain_tag`
+
+## Description
+
+Return every visible canonical binding that produces `tag` in the requested
+scope. Explanations preserve binding identity, producer, attachment, evidence,
+and policy-allowed lineage witnesses, so equal tag tokens from different
+producers remain distinguishable.
+
+As with `list_tags(...)`, `effective` excludes lineage. A lineage explanation
+requires complete topology-history coverage.

SimpleCADAPI/docs/api/export_model_json.md

@@ -3,7 +3,12 @@
 ## API Definition
 
 ```python
-def export_model_json(session: 'GraphSession', indent: int = 2) -> str
+def export_model_json(
+    session: 'GraphSession',
+    indent: int = 2,
+    *,
+    result_node_ids: Optional[Sequence[str]] = None,
+) -> str
 ```
 
 *Source: serializer.py*
@@ -20,3 +25,8 @@ Current Phase 1 scope uses the active session as the container of:
 - operation graph
 - expression graph
 - capabilities/schema metadata
+
+When `result_node_ids` is omitted, explicitly captured session results are used
+when available; otherwise export falls back to graph leaves. New top-level model
+code normally reads `ModelResult.model_json` instead of calling this function
+directly.

SimpleCADAPI/docs/api/expression_uses_units.md

@@ -0,0 +1,17 @@
+# expression_uses_units
+
+## API Definition
+
+```python
+def expression_uses_units(value: 'ScalarLike') -> bool
+```
+
+*Source: units.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import expression_uses_units`
+
+## Description
+
+Return whether an expression contains an explicit unit declaration.

SimpleCADAPI/docs/api/extrude_rsolid.md

@@ -3,7 +3,17 @@
 ## API Definition
 
 ```python
-def extrude_rsolid(profile: Union[Wire, Face], direction: Tuple[float, float, float], distance: ScalarLike) -> Solid
+def extrude_rsolid(
+    profile: Union[Wire, Face],
+    direction: Tuple[float, float, float],
+    distance: ScalarLike,
+    *,
+    tag_prefix: Optional[str] = None,
+    result_tag: Optional[str] = None,
+    start_face_tag: Optional[str] = None,
+    end_face_tag: Optional[str] = None,
+    side_faces_tag: Optional[str] = None,
+) -> Solid
 ```
 
 *Source: operations.py*
@@ -14,4 +24,27 @@ def extrude_rsolid(profile: Union[Wire, Face], direction: Tuple[float, float, fl
 
 ## Description
 
-Create a solid by extruding a profile.
+Create a solid by extruding a profile. Kernel history assigns the output roles
+`extrusion.start`, `extrusion.end`, and `extrusion.side`. Use the semantic role
+tag arguments to attach user tags to those exact role sets.
+
+When `tag_prefix` is supplied, profile Edge tags are recommended at creation
+time through the profile API (`edge_tags` and `tag_prefix`). The feature
+produces `<tag_prefix>.face.start`, `<tag_prefix>.face.end`, and one
+`<tag_prefix>.face.side.<profile_edge_tag>` for each kernel-proven profile Edge.
+The cap Face tags are inherited by their boundary Edges, so an exact Edge
+can be selected from two tagged neighboring Faces with QL `incident_to` or
+`shared_boundary` rather than an enumeration index.
+
+Start and end roles require exactly one proven face. The side role requires one
+or more proven faces and tags all of them. Missing, ambiguous, or unsupported
+roles fail the whole operation instead of returning an untagged result.
+
+`result_tag` attaches a local tag to the resulting solid. In a `GraphSession`,
+all requested tags lower to replayable `apply_tag_rselection` semantic nodes;
+they are not stored as geometry parameters.
+
+Topology tags produced by `tag_prefix` remain directly queryable after
+booleans when OCC provides a complete preserved or modified Face history. The
+result binding retains the original semantic binding ID and source topology ID;
+new boundary faces do not inherit the topology tag.

SimpleCADAPI/docs/api/fillet_rsolid.md

@@ -3,7 +3,14 @@
 ## API Definition
 
 ```python
-def fillet_rsolid(solid: Solid, edges: Union[Sequence[Edge], ShapeSelector], radius: ScalarLike) -> Solid
+def fillet_rsolid(
+    solid: Solid,
+    edges: Union[Sequence[Edge], ShapeSelector],
+    radius: ScalarLike,
+    *,
+    result_tag: Optional[str] = None,
+    generated_faces_tag: Optional[str] = None,
+) -> Solid
 ```
 
 *Source: operations.py*
@@ -14,4 +21,10 @@ def fillet_rsolid(solid: Solid, edges: Union[Sequence[Edge], ShapeSelector], rad
 
 ## Description
 
-Apply fillets to selected solid edges.
+Apply fillets to selected solid edges. `generated_faces_tag` targets every face
+with the kernel-proven `fillet.patch` role. OCC contour expansion is included,
+so the role is not limited to the original seed edge.
+
+The operation fails if a requested patch role has no proven result. `result_tag`
+tags the resulting solid. In a `GraphSession`, assignments are separate replayable
+semantic nodes with asserted user provenance.

SimpleCADAPI/docs/api/get_unit.md

@@ -0,0 +1,17 @@
+# get_unit
+
+## API Definition
+
+```python
+def get_unit(value: UnitLike) -> Unit
+```
+
+*Source: units.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import get_unit`
+
+## Description
+
+Resolve a built-in unit name/alias or return an existing ``Unit``.

SimpleCADAPI/docs/api/infer_dimension.md

@@ -0,0 +1,21 @@
+# infer_dimension
+
+## API Definition
+
+```python
+def infer_dimension(value: 'ScalarLike') -> Dimension | None
+```
+
+*Source: units.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import infer_dimension`
+
+## Description
+
+Infer and validate an expression's result dimension.
+
+``None`` means the expression uses only legacy variables without unit
+declarations. Expressions that contain explicit units are validated
+strictly and cannot mix in legacy variables.

SimpleCADAPI/docs/api/list_tags.md

@@ -3,7 +3,10 @@
 ## API Definition
 
 ```python
-def list_tags(shape: AnyShape) -> List[str]
+def list_tags(
+    shape: AnyShape,
+    scope: str | TagScope = TagScope.EFFECTIVE,
+) -> List[str]
 ```
 
 *Source: operations.py*
@@ -14,4 +17,12 @@ def list_tags(shape: AnyShape) -> List[str]
 
 ## Description
 
-Return shape tags in deterministic sorted order.
+Return shape tags in deterministic sorted order for one semantic scope.
+
+- `local`: bindings attached directly to the entity.
+- `inherited`: bindings visible through explicit downward topology propagation.
+- `effective`: local plus inherited bindings. Lineage is not included.
+- `lineage`: bindings visible through complete, policy-allowed topology history.
+
+Lineage queries fail with a semantic capability error when complete topology
+history is unavailable; they do not guess from geometry or enumeration order.

SimpleCADAPI/docs/api/loft_rsolid.md

@@ -3,7 +3,17 @@
 ## API Definition
 
 ```python
-def loft_rsolid(profiles: List[Wire], ruled: bool = False) -> Solid
+def loft_rsolid(
+    profiles: List[Wire],
+    ruled: bool = False,
+    *,
+    tracking_policy: TrackingPolicy | str = TrackingPolicy.FULL,
+    tag_prefix: Optional[str] = None,
+    result_tag: Optional[str] = None,
+    start_face_tag: Optional[str] = None,
+    end_face_tag: Optional[str] = None,
+    side_faces_tag: Optional[str] = None,
+) -> Solid
 ```
 
 *Source: operations.py*
@@ -14,4 +24,13 @@ def loft_rsolid(profiles: List[Wire], ruled: bool = False) -> Solid
 
 ## Description
 
-Create a solid by lofting multiple profiles.
+Create a solid by lofting multiple profiles. Kernel history assigns
+`loft.start`, `loft.end`, and `loft.side` roles. Start and end tags require one
+proven face each; side tags apply to all proven side faces. `result_tag` targets
+the solid. Recorded assignments are replayable semantic nodes.
+
+`TrackingPolicy.FULL` is the default and preserves complete kernel topology
+history. `TrackingPolicy.GRAPH` skips topology-history queries while still
+recording and replaying the `make_loft_rsolid` graph node. In `GRAPH` mode,
+`result_tag` remains available, but face-role tags and `tag_prefix` require
+`FULL` tracking.

SimpleCADAPI/docs/api/make_box_rsolid.md

@@ -3,7 +3,21 @@
 ## API Definition
 
 ```python
-def make_box_rsolid(width: ScalarLike, height: ScalarLike, depth: ScalarLike, bottom_face_center: Tuple[float, float, float] = (0, 0, 0)) -> Solid
+def make_box_rsolid(
+    width: ScalarLike,
+    height: ScalarLike,
+    depth: ScalarLike,
+    bottom_face_center: Tuple[float, float, float] = (0, 0, 0),
+    *,
+    tag_prefix: Optional[str] = None,
+    result_tag: Optional[str] = None,
+    bottom_face_tag: Optional[str] = None,
+    top_face_tag: Optional[str] = None,
+    front_face_tag: Optional[str] = None,
+    back_face_tag: Optional[str] = None,
+    left_face_tag: Optional[str] = None,
+    right_face_tag: Optional[str] = None,
+) -> Solid
 ```
 
 *Source: operations.py*
@@ -14,4 +28,19 @@ def make_box_rsolid(width: ScalarLike, height: ScalarLike, depth: ScalarLike, bo
 
 ## Description
 
-Create a box solid.
+Create a native box solid. The exact kernel-backed Face roles are `box.bottom`,
+`box.top`, `box.front`, `box.back`, `box.left`, and `box.right`. Each role has
+exactly one Face.
+
+The face tag arguments attach tags to those roles. `result_tag` targets the
+result Solid. `tag_prefix="housing"` creates the topology tags
+`housing.solid`, `housing.face.bottom`,
+`housing.face.top`, `housing.face.front`, `housing.face.back`,
+`housing.face.left`, and `housing.face.right`.
+
+The roles and topology tags come directly from OCC Box Face witnesses, not Face
+enumeration or geometric classification. The current OCP Box builder does not
+expose equivalent direct Edge witnesses, so Box Edge output roles are
+unsupported. Select an exact Edge from two tagged incident Faces with
+`Q.edges().incident_to(face_a, face_b, distinct=True)` or
+`face_a.shared_boundary(face_b)`.

SimpleCADAPI/docs/api/make_circle_redge.md

@@ -3,7 +3,13 @@
 ## API Definition
 
 ```python
-def make_circle_redge(center: Tuple[float, float, float], radius: ScalarLike, normal: Tuple[float, float, float] = (0, 0, 1)) -> Edge
+def make_circle_redge(
+    center: Tuple[float, float, float],
+    radius: ScalarLike,
+    normal: Tuple[float, float, float] = (0, 0, 1),
+    *,
+    tag_prefix: Optional[str] = None,
+) -> Edge
 ```
 
 *Source: operations.py*
@@ -14,4 +20,5 @@ def make_circle_redge(center: Tuple[float, float, float], radius: ScalarLike, no
 
 ## Description
 
-Create a circular edge.
+Create a circular edge. `tag_prefix` optionally creates the topology tag
+`<tag_prefix>.edge`.

SimpleCADAPI/docs/api/make_circle_rface.md

@@ -3,7 +3,14 @@
 ## API Definition
 
 ```python
-def make_circle_rface(center: Tuple[float, float, float], radius: ScalarLike, normal: Tuple[float, float, float] = (0, 0, 1)) -> Face
+def make_circle_rface(
+    center: Tuple[float, float, float],
+    radius: ScalarLike,
+    normal: Tuple[float, float, float] = (0, 0, 1),
+    *,
+    tag_prefix: Optional[str] = None,
+    edge_tag: Optional[str] = None,
+) -> Face
 ```
 
 *Source: operations.py*
@@ -14,4 +21,8 @@ def make_circle_rface(center: Tuple[float, float, float], radius: ScalarLike, no
 
 ## Description
 
-Create a circular face.
+Create a circular face. `tag_prefix` creates `<tag_prefix>.face`, while
+`edge_tag` supplies the final segment of `<tag_prefix>.edge.<edge_tag>` for its
+boundary Edge, or the complete Edge tag when `tag_prefix` is omitted. The Face
+topology tag is visible to effective boundary-Edge QL queries without copying
+arbitrary local Face tags to every Edge.

SimpleCADAPI/docs/api/make_circle_rwire.md

@@ -3,7 +3,14 @@
 ## API Definition
 
 ```python
-def make_circle_rwire(center: Tuple[float, float, float], radius: ScalarLike, normal: Tuple[float, float, float] = (0, 0, 1)) -> Wire
+def make_circle_rwire(
+    center: Tuple[float, float, float],
+    radius: ScalarLike,
+    normal: Tuple[float, float, float] = (0, 0, 1),
+    *,
+    tag_prefix: Optional[str] = None,
+    edge_tag: Optional[str] = None,
+) -> Wire
 ```
 
 *Source: operations.py*
@@ -14,4 +21,8 @@ def make_circle_rwire(center: Tuple[float, float, float], radius: ScalarLike, no
 
 ## Description
 
-Create a circular wire.
+Create a circular wire. `tag_prefix` creates `<tag_prefix>.wire`, while
+`edge_tag` supplies the final segment of `<tag_prefix>.edge.<edge_tag>` for its
+single circular Edge, or the complete Edge tag when `tag_prefix` is omitted.
+These topology tags are preserved only where a downstream operation has
+complete, kernel-proven correspondence.

SimpleCADAPI/docs/api/make_cone_rsolid.md

@@ -3,7 +3,22 @@
 ## API Definition
 
 ```python
-def make_cone_rsolid(bottom_radius: ScalarLike, height: ScalarLike, top_radius: ScalarLike = 0.0, bottom_face_center: Tuple[float, float, float] = (0, 0, 0), axis: Tuple[float, float, float] = (0, 0, 1)) -> Solid
+def make_cone_rsolid(
+    bottom_radius: ScalarLike,
+    height: ScalarLike,
+    top_radius: ScalarLike = 0.0,
+    bottom_face_center: Tuple[float, float, float] = (0, 0, 0),
+    axis: Tuple[float, float, float] = (0, 0, 1),
+    *,
+    tag_prefix: Optional[str] = None,
+    result_tag: Optional[str] = None,
+    start_face_tag: Optional[str] = None,
+    end_face_tag: Optional[str] = None,
+    side_face_tag: Optional[str] = None,
+    start_edge_tag: Optional[str] = None,
+    end_edge_tag: Optional[str] = None,
+    seam_edge_tag: Optional[str] = None,
+) -> Solid
 ```
 
 *Source: operations.py*
@@ -14,4 +29,19 @@ def make_cone_rsolid(bottom_radius: ScalarLike, height: ScalarLike, top_radius:
 
 ## Description
 
-Create a cone or truncated cone solid.
+Create a native cone or frustum. The kernel-backed Face roles are `cone.start`,
+`cone.end`, and `cone.side`. The Edge roles are `cone.start_boundary`,
+`cone.end_boundary`, and `cone.seam`.
+
+For a pointed cone (`top_radius=0`), no top cap exists, so `cone.end` is absent
+and requesting `end_face_tag` fails. `cone.end_boundary` remains available as
+the kernel's degenerate apex Edge. A frustum (`top_radius>0`) has all six roles.
+
+The role tag arguments attach tags to exact roles. `result_tag` targets the
+Solid. `tag_prefix="adapter"` creates `adapter.solid`, the
+Face tags `adapter.face.start`, `adapter.face.end` when present, and
+`adapter.face.side`, plus `adapter.edge.start`, `adapter.edge.end`, and
+`adapter.edge.seam`.
+
+All roles and topology tags use direct OCC Cone witnesses. They are not inferred from
+topology enumeration, size, normal, or position.

SimpleCADAPI/docs/api/make_cylinder_rsolid.md

@@ -3,7 +3,21 @@
 ## API Definition
 
 ```python
-def make_cylinder_rsolid(radius: ScalarLike, height: ScalarLike, bottom_face_center: Tuple[float, float, float] = (0, 0, 0), axis: Tuple[float, float, float] = (0, 0, 1)) -> Solid
+def make_cylinder_rsolid(
+    radius: ScalarLike,
+    height: ScalarLike,
+    bottom_face_center: Tuple[float, float, float] = (0, 0, 0),
+    axis: Tuple[float, float, float] = (0, 0, 1),
+    *,
+    tag_prefix: Optional[str] = None,
+    result_tag: Optional[str] = None,
+    start_face_tag: Optional[str] = None,
+    end_face_tag: Optional[str] = None,
+    side_face_tag: Optional[str] = None,
+    start_edge_tag: Optional[str] = None,
+    end_edge_tag: Optional[str] = None,
+    seam_edge_tag: Optional[str] = None,
+) -> Solid
 ```
 
 *Source: operations.py*
@@ -14,4 +28,21 @@ def make_cylinder_rsolid(radius: ScalarLike, height: ScalarLike, bottom_face_cen
 
 ## Description
 
-Create a cylinder solid.
+Create a native cylinder solid. The kernel-backed output roles are:
+
+- `cylinder.start`, `cylinder.end`, and `cylinder.side` for Faces.
+- `cylinder.start_boundary`, `cylinder.end_boundary`, and `cylinder.seam` for Edges.
+
+The role tag arguments attach tags to those exact roles.
+`tag_prefix="shaft"` creates the topology tag prefix `shaft`: the cap and
+lateral Faces receive `shaft.face.start`, `shaft.face.end`, and
+`shaft.face.side`; their boundary Edges inherit the corresponding Face tags.
+The three native Edge roles additionally receive `shaft.edge.start`,
+`shaft.edge.end`, and `shaft.edge.seam`.
+
+Topology tag prefixes must be supplied while creating the profile or feature. The implementation
+uses OCC primitive witnesses and exact incident topology, not face or edge
+enumeration, area, normal, or position heuristics. Use QL relation/set queries
+to disambiguate an Edge shared by two tagged Faces, for example
+`Q.edges().incident_to(face_a, face_b, distinct=True)` or
+`face_a.shared_boundary(face_b)`.

SimpleCADAPI/docs/api/make_face_from_sketch_rface.md

@@ -14,4 +14,12 @@ def make_face_from_sketch_rface(sketch: Sketch, profile: int | str = 0, *, requi
 
 ## Description
 
-Promote a sketch profile to a concrete face, solving internally.
+Promote a sketch profile to a concrete face, solving internally. The promoted
+Face receives the canonical profile topology-identity tag and each boundary
+Edge receives the exact Sketch entity tag from the promotion map. For example,
+a Sketch with `name="rect"` and profile `bottom` produces `sketch.rect.profile.bottom` and
+`sketch.rect.entity.bottom`.
+
+These are creation-time tags with `topology_name` evidence backed by the solved Sketch
+promotion map. They replay from the Sketch payload and promotion parameters;
+ordinary compatibility tags such as `sketch_entity.bottom` remain separate.

SimpleCADAPI/docs/api/make_face_from_wire_rface.md

@@ -3,7 +3,12 @@
 ## API Definition
 
 ```python
-def make_face_from_wire_rface(wire: Wire, normal: Tuple[float, float, float] = (0, 0, 1)) -> Face
+def make_face_from_wire_rface(
+    wire: Wire,
+    normal: Tuple[float, float, float] = (0, 0, 1),
+    *,
+    tag_prefix: Optional[str] = None,
+) -> Face
 ```
 
 *Source: operations.py*
@@ -14,4 +19,6 @@ def make_face_from_wire_rface(wire: Wire, normal: Tuple[float, float, float] = (
 
 ## Description
 
-Create a face from a closed wire.
+Create a face from a closed wire. Existing proven Edge topology tags on the
+wire are copied to corresponding Face boundary Edges. `tag_prefix` optionally
+adds the Face tag `<tag_prefix>.face`.

SimpleCADAPI/docs/api/make_line_redge.md

@@ -3,7 +3,12 @@
 ## API Definition
 
 ```python
-def make_line_redge(start: Tuple[ScalarLike, ScalarLike, ScalarLike], end: Tuple[ScalarLike, ScalarLike, ScalarLike]) -> Edge
+def make_line_redge(
+    start: Tuple[ScalarLike, ScalarLike, ScalarLike],
+    end: Tuple[ScalarLike, ScalarLike, ScalarLike],
+    *,
+    tag_prefix: Optional[str] = None,
+) -> Edge
 ```
 
 *Source: operations.py*
@@ -14,4 +19,7 @@ def make_line_redge(start: Tuple[ScalarLike, ScalarLike, ScalarLike], end: Tuple
 
 ## Description
 
-Create a straight edge between two points.
+Create a straight edge between two points. When `tag_prefix` is provided, the
+edge receives the topology tag `<tag_prefix>.edge`. Downstream profile and
+feature operations may preserve that tag when kernel history proves the
+correspondence.

SimpleCADAPI/docs/api/make_rectangle_rface.md

@@ -3,7 +3,15 @@
 ## API Definition
 
 ```python
-def make_rectangle_rface(width: ScalarLike, height: ScalarLike, center: Tuple[ScalarLike, ScalarLike, ScalarLike] = (0, 0, 0), normal: Tuple[ScalarLike, ScalarLike, ScalarLike] = (0, 0, 1)) -> Face
+def make_rectangle_rface(
+    width: ScalarLike,
+    height: ScalarLike,
+    center: Tuple[ScalarLike, ScalarLike, ScalarLike] = (0, 0, 0),
+    normal: Tuple[ScalarLike, ScalarLike, ScalarLike] = (0, 0, 1),
+    *,
+    tag_prefix: Optional[str] = None,
+    edge_tags: Optional[Sequence[str]] = None,
+) -> Face
 ```
 
 *Source: operations.py*
@@ -14,4 +22,9 @@ def make_rectangle_rface(width: ScalarLike, height: ScalarLike, center: Tuple[Sc
 
 ## Description
 
-Create a rectangular face.
+Create a rectangular face. `tag_prefix` creates `<tag_prefix>.face`, and
+`edge_tags` supplies one tag for each of its four boundary Edges. With
+`tag_prefix`, each is a local segment under `<tag_prefix>.edge`; without it,
+each is a complete Edge tag. These topology tags can be projected to proven
+feature Faces and queried with the same `list_tags(...)` and `ql.tag(...)`
+surfaces as other tags.

SimpleCADAPI/docs/api/make_rectangle_rwire.md

@@ -3,7 +3,15 @@
 ## API Definition
 
 ```python
-def make_rectangle_rwire(width: ScalarLike, height: ScalarLike, center: Tuple[ScalarLike, ScalarLike, ScalarLike] = (0, 0, 0), normal: Tuple[ScalarLike, ScalarLike, ScalarLike] = (0, 0, 1)) -> Wire
+def make_rectangle_rwire(
+    width: ScalarLike,
+    height: ScalarLike,
+    center: Tuple[ScalarLike, ScalarLike, ScalarLike] = (0, 0, 0),
+    normal: Tuple[ScalarLike, ScalarLike, ScalarLike] = (0, 0, 1),
+    *,
+    tag_prefix: Optional[str] = None,
+    edge_tags: Optional[Sequence[str]] = None,
+) -> Wire
 ```
 
 *Source: operations.py*
@@ -14,4 +22,9 @@ def make_rectangle_rwire(width: ScalarLike, height: ScalarLike, center: Tuple[Sc
 
 ## Description
 
-Create a rectangular wire.
+Create a rectangular wire. `tag_prefix` creates `<tag_prefix>.wire`.
+`edge_tags` must contain one tag for each generated profile Edge, in kernel
+construction order. With `tag_prefix`, each value is the local segment of
+`<tag_prefix>.edge.<edge_tag>`; without it, each value is the complete Edge tag.
+These topology tags are stable anchors for operations such as `extrude_rsolid`
+when correspondence is proven.

SimpleCADAPI/docs/api/make_sketch_rsketch.md

@@ -17,4 +17,5 @@ def make_sketch_rsketch(name: Optional[str] = None, *, plane: Any = 'XY', sketch
 Create an empty declarative sketch document.
 
 Use this API, not concrete edge/wire constructors, when the intent is to
-build a sketch profile with constraints.
+build a sketch profile with constraints. The sketch name and explicit entity
+IDs are stable local identifiers used by constrained profile promotion.

SimpleCADAPI/docs/api/make_wire_from_edges_rwire.md

@@ -3,7 +3,7 @@
 ## API Definition
 
 ```python
-def make_wire_from_edges_rwire(edges: List[Edge]) -> Wire
+def make_wire_from_edges_rwire(edges: List[Edge], *, tag_prefix: Optional[str] = None) -> Wire
 ```
 
 *Source: operations.py*
@@ -14,4 +14,6 @@ def make_wire_from_edges_rwire(edges: List[Edge]) -> Wire
 
 ## Description
 
-Create a wire from a list of connected edges.
+Create a wire from a list of connected edges. Existing proven Edge topology
+tags are preserved by exact topology identity; `tag_prefix` optionally adds
+`<tag_prefix>.wire` to the resulting wire.

SimpleCADAPI/docs/api/make_wire_from_sketch_rwire.md

@@ -14,4 +14,11 @@ def make_wire_from_sketch_rwire(sketch: Sketch, profile: int | str = 0, *, requi
 
 ## Description
 
-Promote a sketch profile to a concrete wire, solving internally.
+Promote a sketch profile to a concrete wire, solving internally. The promotion
+map preserves the exact ordered `entity_id` to Edge correspondence. A Sketch
+with `name="rect"` and profile `bottom` produces the tag
+`sketch.rect.profile.bottom`; entity ID `right` produces
+`sketch.rect.entity.right` with `topology_name` evidence.
+
+Promotion fails if the kernel returns a different Edge count, because the SDK
+does not guess correspondence from Edge order, geometry, or measurements.

SimpleCADAPI/docs/api/model.md

@@ -0,0 +1,50 @@
+# model
+
+## API Definition
+
+```python
+def model(
+    func=None,
+    *,
+    graph_id: Optional[str] = None,
+    export_dir: Optional[str | Path] = None,
+) -> Callable
+```
+
+*Source: graph.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import model`
+
+## Description
+
+Decorate the single top-level entry point of a replayable model. Each invocation
+creates and owns exactly one `GraphSession`, activates it while the function
+runs, captures model/session JSON in memory, and returns a `ModelResult`. When
+`export_dir` is provided, explicitly captured geometry/product values produce
+one `<graph_id>.scene.zip` in that directory. The package embeds
+`model/model.json`, mapped project-relative Python source files under
+`sources/`, and the GLB/entity assets required for rendering and selection. It
+does not create adjacent model/session JSON, STEP, STL, or FCStd files.
+
+```python
+import simplecadapi as scad
+
+@scad.model(graph_id="bracket")
+def build_bracket():
+    body = scad.make_box_rsolid(width=20.0, height=10.0, depth=3.0)
+    scad.capture_result(value=body)
+    return body
+
+result = build_bracket()
+print(result.result_node_ids)
+```
+
+Use `result.artifact_paths["scene"]` to locate the package, or call
+`result.export_artifacts(output_dir=...)` after a model has run without an
+export directory. The explicit `export_dir` opt-in avoids unexpected filesystem
+writes for library callers and tests.
+
+Do not nest `@model` functions or create another `GraphSession` inside a model
+function. Use `@requires_session` for child builders.

SimpleCADAPI/docs/api/output_role.md

@@ -0,0 +1,23 @@
+# output_role
+
+## API Definition
+
+```python
+def output_role(role_name: str) -> SerializablePredicate
+```
+
+*Source: ql.py*
+
+## Import Surface
+
+- submodule: `from simplecadapi import ql`
+
+## Description
+
+Return a serializable predicate matching a kernel-proven operation output role
+in `metadata["track"]`. Role matching never falls back to face order, geometry,
+or flat tags. Use it with a typed selector, for example:
+
+```python
+end = ql.faces().where(ql.output_role(role_name="extrusion.end")).exactly(1)
+```

SimpleCADAPI/docs/api/render_screenshot_rpath.md

@@ -3,7 +3,7 @@
 ## API Definition
 
 ```python
-def render_screenshot_rpath(shapes: Union[Solid, Sequence[Solid]], output_path: str, highlight_tags: Optional[Sequence[str]] = None, tag_labels: Optional[Dict[str, str]] = None, image_size: Tuple[int, int] = (1400, 900), view: Union[Tuple[float, float], str] = 'auto', show_axes: bool = True, show_legend: bool = True, zoom: float = 4.0) -> str
+def render_screenshot_rpath(shapes: Union[Solid, Sequence[Solid]], output_path: str, highlight_tags: Optional[Sequence[str]] = None, tag_labels: Optional[Dict[str, str]] = None, image_size: Tuple[int, int] = (1400, 900), view: Union[Tuple[float, float], str] = 'auto', show_axes: bool = True, show_legend: bool = True, zoom: float = 4.0, show_callouts: bool = True) -> str
 ```
 
 *Source: operations.py*
@@ -14,4 +14,6 @@ def render_screenshot_rpath(shapes: Union[Solid, Sequence[Solid]], output_path:
 
 ## Description
 
-Render a screenshot of shapes and save it to a file.
+Render a screenshot of shapes and save it to a file. Set `show_callouts=False`
+to retain highlighted material colors and the legend without placing tag labels
+over the model.

SimpleCADAPI/docs/api/requires_session.md

@@ -0,0 +1,28 @@
+# requires_session
+
+## API Definition
+
+```python
+def requires_session(func=None) -> Callable
+```
+
+*Source: graph.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import requires_session`
+
+## Description
+
+Decorate a reusable graph-producing builder that must run inside the caller's
+active `GraphSession`. The decorator reuses the session owned by the enclosing
+`@model` function and validates that returned graph values belong to it.
+
+```python
+@scad.requires_session
+def make_bracket_body():
+    return scad.make_box_rsolid(width=20.0, height=10.0, depth=3.0)
+```
+
+Calling a `@requires_session` builder without an active session raises
+`RuntimeError`. Builders must not create their own `GraphSession`.

SimpleCADAPI/docs/api/revolve_rsolid.md

@@ -3,7 +3,18 @@
 ## API Definition
 
 ```python
-def revolve_rsolid(profile: Union[Wire, Face], axis: Tuple[float, float, float] = (0, 0, 1), angle: ScalarLike = 360, origin: Tuple[float, float, float] = (0, 0, 0)) -> Solid
+def revolve_rsolid(
+    profile: Union[Wire, Face],
+    axis: Tuple[float, float, float] = (0, 0, 1),
+    angle: ScalarLike = 360,
+    origin: Tuple[float, float, float] = (0, 0, 0),
+    *,
+    tag_prefix: Optional[str] = None,
+    result_tag: Optional[str] = None,
+    start_face_tag: Optional[str] = None,
+    end_face_tag: Optional[str] = None,
+    side_faces_tag: Optional[str] = None,
+) -> Solid
 ```
 
 *Source: operations.py*
@@ -14,4 +25,12 @@ def revolve_rsolid(profile: Union[Wire, Face], axis: Tuple[float, float, float]
 
 ## Description
 
-Create a solid by revolving a profile around an axis.
+Create a solid by revolving a profile around an axis. Kernel history assigns
+`revolution.start`, `revolution.end`, and `revolution.side` output roles.
+
+Start and end roles require exactly one proven face; side tags apply to every
+proven side face. A full 360-degree revolve normally has no separate start or end
+face, so requesting either cap tag raises a capability error rather than guessing.
+The semantic role tag arguments attach tags to the proven cap or side Faces.
+`result_tag` tags the resulting Solid. These assignments are replayable
+semantic nodes.

SimpleCADAPI/docs/api/select.md

@@ -15,3 +15,15 @@ def select(items: Iterable[Any]) -> Query
 ## Description
 
 Start a QL query over a shape collection or selector scope.
+
+For topology-aware selection, use `ql.faces()`, `ql.edges()`, `ql.wires()`,
+`ql.vertices()`, or `ql.solids()`. `ShapeSelector.intersection(other)` forms a
+serializable set intersection. `selector.shared_boundary(other,
+to_kind="edge")` intersects the boundaries of two selectors. Edge selectors
+also support `incident_to(face_selector, ..., distinct=True)` and
+`incident_face_count(exactly=2)` to select edges by exact incident Face
+witnesses and reject open or non-manifold edges.
+
+These selectors resolve by topology identity, not enumeration order, area,
+normal, or position heuristics. Their `to_dict()` payloads can be restored with
+`ql.selector_from_dict(...)`.

SimpleCADAPI/docs/api/select_edges_by_tag.md

@@ -3,7 +3,11 @@
 ## API Definition
 
 ```python
-def select_edges_by_tag(shape: Union[Face, Solid], tag: str) -> List[Edge]
+def select_edges_by_tag(
+    shape: Union[Face, Solid],
+    tag: str,
+    scope: str | TagScope = TagScope.EFFECTIVE,
+) -> List[Edge]
 ```
 
 *Source: operations.py*
@@ -14,4 +18,6 @@ def select_edges_by_tag(shape: Union[Face, Solid], tag: str) -> List[Edge]
 
 ## Description
 
-Select edges by tag.
+Select edges by an exact normalized tag in the requested semantic scope.
+`effective` does not include lineage; request `scope="lineage"` explicitly when
+selection depends on complete topology-history evidence.

SimpleCADAPI/docs/api/select_faces_by_tag.md

@@ -3,7 +3,11 @@
 ## API Definition
 
 ```python
-def select_faces_by_tag(solid: Solid, tag: str) -> List[Face]
+def select_faces_by_tag(
+    solid: Solid,
+    tag: str,
+    scope: str | TagScope = TagScope.EFFECTIVE,
+) -> List[Face]
 ```
 
 *Source: operations.py*
@@ -14,4 +18,6 @@ def select_faces_by_tag(solid: Solid, tag: str) -> List[Face]
 
 ## Description
 
-Select faces by tag.
+Select faces by an exact normalized tag in the requested semantic scope.
+`effective` does not include lineage; request `scope="lineage"` explicitly when
+selection depends on complete topology-history evidence.

SimpleCADAPI/docs/api/shell_rsolid.md

@@ -3,7 +3,17 @@
 ## API Definition
 
 ```python
-def shell_rsolid(solid: Solid, faces_to_remove: Union[Sequence[Face], ShapeSelector], thickness: ScalarLike) -> Solid
+def shell_rsolid(
+    solid: Solid,
+    faces_to_remove: Union[Sequence[Face], ShapeSelector],
+    thickness: ScalarLike,
+    *,
+    result_tag: Optional[str] = None,
+    body_faces_tag: Optional[str] = None,
+    offset_faces_tag: Optional[str] = None,
+    closing_faces_tag: Optional[str] = None,
+    wall_edges_tag: Optional[str] = None,
+) -> Solid
 ```
 
 *Source: operations.py*
@@ -14,4 +24,16 @@ def shell_rsolid(solid: Solid, faces_to_remove: Union[Sequence[Face], ShapeSelec
 
 ## Description
 
-Shell a solid to create a hollow part.
+Shell a solid to create a hollow part. The operation can expose these exact
+kernel roles:
+
+- `shell.body_face`: surviving or modified source body faces.
+- `shell.offset_face`: generated offset faces.
+- `shell.closing_descendant`: descendants of removed closing faces.
+- `shell.wall`: generated closing-boundary edges.
+
+The named arguments map directly to those roles. A role is available only when
+OCC provides a complete witness;
+requesting an unavailable role fails instead of deriving one from enumeration or
+geometry. `result_tag` tags the resulting solid. Recorded assignments replay as
+semantic nodes and preserve face versus edge target kinds.

SimpleCADAPI/docs/api/solids.md

@@ -0,0 +1,19 @@
+# solids
+
+## API Definition
+
+```python
+def solids() -> ShapeSelector
+```
+
+*Source: ql.py*
+
+## Import Surface
+
+- submodule: `from simplecadapi import ql`
+
+## Description
+
+Create a serializable selector over Solid topology. Solid selectors can be
+traversed to boundary Edges and combined with `intersection(...)` or
+`shared_boundary(...)` to find topology common to two named Solid selectors.

SimpleCADAPI/docs/api/source_binding.md

@@ -0,0 +1,19 @@
+# source_binding
+
+## API Definition
+
+```python
+def source_binding(binding_id: str) -> SerializablePredicate
+```
+
+*Source: ql.py*
+
+## Import Surface
+
+- submodule: `from simplecadapi import ql`
+
+## Description
+
+Match a local projected `TagBinding` whose topology-change evidence preserves the
+exact source `binding_id`. Objects without canonical local binding evidence raise
+an unsupported-query capability error instead of consulting flat tags.

SimpleCADAPI/docs/api/source_topology.md

@@ -0,0 +1,19 @@
+# source_topology
+
+## API Definition
+
+```python
+def source_topology(topo_id: str) -> SerializablePredicate
+```
+
+*Source: ql.py*
+
+## Import Surface
+
+- submodule: `from simplecadapi import ql`
+
+## Description
+
+Match a local projected `TagBinding` by the exact source topology identity stored
+in its kernel-history evidence. This predicate queries source-preserving evidence;
+it does not infer ancestry from geometry.

SimpleCADAPI/docs/api/sweep_rsolid.md

@@ -3,7 +3,17 @@
 ## API Definition
 
 ```python
-def sweep_rsolid(profile: Face, path: Wire, is_frenet: bool = False) -> Solid
+def sweep_rsolid(
+    profile: Face,
+    path: Wire,
+    is_frenet: bool = False,
+    *,
+    tag_prefix: Optional[str] = None,
+    result_tag: Optional[str] = None,
+    start_face_tag: Optional[str] = None,
+    end_face_tag: Optional[str] = None,
+    side_faces_tag: Optional[str] = None,
+) -> Solid
 ```
 
 *Source: operations.py*
@@ -14,4 +24,10 @@ def sweep_rsolid(profile: Face, path: Wire, is_frenet: bool = False) -> Solid
 
 ## Description
 
-Create a solid by sweeping a profile along a path.
+Create a solid by sweeping a profile along a path. Kernel history assigns
+`sweep.start`, `sweep.end`, and `sweep.side` roles. Start and end tags require one
+proven face each; side tags apply to all proven side faces. `result_tag` targets
+the solid, and recorded assignments are replayable semantic nodes.
+
+Profiles with inner wires are rejected because the current PipeShell operation
+receives only the outer wire; silently dropping profile holes is not allowed.

SimpleCADAPI/docs/api/twisted_sweep_rsolid.md

@@ -0,0 +1,46 @@
+# twisted_sweep_rsolid
+
+## API Definition
+
+```python
+def twisted_sweep_rsolid(
+    profile: Face,
+    distance: ScalarLike,
+    twist_angle: ScalarLike,
+    axis: Tuple[float, float, float] = (0.0, 0.0, 1.0),
+    origin: Tuple[float, float, float] = (0.0, 0.0, 0.0),
+    *,
+    guide_radius: ScalarLike = 1.0,
+    tag_prefix: Optional[str] = None,
+    result_tag: Optional[str] = None,
+    start_face_tag: Optional[str] = None,
+    end_face_tag: Optional[str] = None,
+    side_faces_tag: Optional[str] = None,
+) -> Solid
+```
+
+*Source: operations.py*
+
+## Import Surface
+
+- top-level: `from simplecadapi import twisted_sweep_rsolid`
+
+## Description
+
+Sweep a planar profile along a straight axis while rotating it linearly by the
+signed total `twist_angle` in degrees. The profile must lie at the sweep start,
+be planar, and be normal to `axis`.
+
+The OCP implementation uses a one-edge straight spine and a one-edge
+cylindrical auxiliary spine. This normally creates one continuous side face per
+profile edge rather than splitting every side at intermediate loft sections.
+Profiles with inner wires are rejected.
+
+Kernel history assigns `twisted_sweep.start`, `twisted_sweep.end`, and
+`twisted_sweep.side` roles. The operation records one canonical
+`make_twisted_sweep_rsolid` graph node containing `axis`, `origin`, `distance`,
+`twist_angle`, and `guide_radius`; strict replay invokes the same public
+operation with the recorded parameters.
+
+`guide_radius` controls only the auxiliary orientation guide and must be a
+positive finite value. It does not set the swept profile radius.

SimpleCADAPI/docs/api/union_rsolid.md

@@ -3,7 +3,13 @@
 ## API Definition
 
 ```python
-def union_rsolid(*solids: Union[Solid, Sequence[Solid]], clean: bool = True, glue: bool = _DEFAULT_UNION_GLUE, tol: Optional[float] = None) -> Solid
+def union_rsolid(
+    *solids: Union[Solid, Sequence[Solid]],
+    clean: bool = True,
+    glue: bool = _DEFAULT_UNION_GLUE,
+    tol: Optional[float] = None,
+    tracking_policy: TrackingPolicy | str = TrackingPolicy.FULL,
+) -> Solid
 ```
 
 *Source: operations.py*
@@ -40,6 +46,10 @@ returning multiple pieces.
 - **Type**: `Optional fuzzy-boolean tolerance used by the OCC union kernel. When`
 - **Description**: omitted, SimpleCAD chooses a conservative scale-aware tolerance.
 
+### tracking_policy
+
+- **Description**: `TrackingPolicy.FULL` computes topology history and lineage. `TrackingPolicy.GRAPH` preserves the canonical union node, parameters, inputs, result topology references, and replay while omitting `TopoDelta` and history-derived topology lineage. Geometry options `clean`, `glue`, and `tol` are unchanged.
+
 ## Returns
 
 Solid: The merged union result.

SimpleCADAPI/docs/api/var_function.md

@@ -3,7 +3,7 @@
 ## API Definition
 
 ```python
-def var(name: str, default: int | float, comment: str | None = None) -> Var
+def var(name: str, default: int | float, comment: str | None = None, tolerance: ToleranceLike | None = None, *, unit: UnitLike | None = None, tolerance_unit: UnitLike | None = None) -> Var
 ```
 
 *Source: expr.py*
@@ -14,4 +14,13 @@ def var(name: str, default: int | float, comment: str | None = None) -> Var
 
 ## Description
 
-Create a named variable node for v2 expression-driven parameters.
+Create a physical or legacy scalar variable.
+
+``tolerance=0.1`` declares a symmetric ``+/-0.1`` tolerance. Use a
+``(lower_deviation, upper_deviation)`` pair for an asymmetric tolerance.
+``tolerance_unit`` defaults to ``unit`` when a nominal unit is declared.
+Values are converted to canonical CAD units only when evaluated, so the
+declaration and serialized expression node preserve the user's units.
+
+Variables without ``unit`` retain legacy unitless behavior. A unit-aware
+expression cannot mix declared-unit variables with legacy variables.