Merge remote-tracking branch 'origin/main' into feat/sketch-tools-return-ids

# Conflicts:
#	crates/engine/src/cmd/mod.rs
#	crates/engine/src/cmd/sketch.rs
#	crates/engine/src/cmd/sketch_create.rs
#	crates/engine/src/cmd/sketch_modify.rs
#	crates/engine/src/lib.rs
#	docs/book/src/guide/sketching.md

docs/book/src/guide/assemblies.md

@@ -11,6 +11,13 @@ component, and **Paste New** creates an independent copy. Move an occurrence wit
 triad, then **Capture Position** to keep it or **Revert** to put it back. SolveCraft asks before
 the next command if a move wasn't captured. **Ground** fixes an occurrence in place.
 
+Paste New copies nested component definitions, sketches, feature histories and generated
+dimension parameters. Repeated child instances remain shared within the new copy. Materials,
+appearances and wholly internal joints/motion records receive copied references. Design-wide
+user parameters remain shared; retained external links and omitted cross-boundary motion
+records are reported. Unsupported destructive links refuse the entire copy. See
+[individual-instance and copy details](https://github.com/bherbruck/solvecraft/blob/main/docs/occurrence-workflows.md).
+
 **Joints** (`joint.create`, J) connect two components by joint origins that snap to faces, edges,
 circles and vertices: rigid, revolute, slider, cylindrical, pin-slot, planar and ball, with
 offsets, flip and limits. **As-built Joint** keeps the current position, **Rigid Group** locks
@@ -20,3 +27,12 @@ couples two joints. Contact sets stop motion where bodies would pass through eac
 volumes in red.
 
 STEP export writes the component tree as an assembly.
+
+Right-click a component in the Browser and choose **Properties** to inspect
+material-aware mass, volume, surface area, centre of mass and world bounds. Descendants and
+repeated instances contribute to assembly totals; pending moves are included. A component
+uses its first placement; `occurrence.properties` selects a specific instance. Root Properties
+measures the complete assembly. Volumes are summed, including overlapping bodies, rather than
+measuring their union. The same workflow is available through `component.properties` and
+`occurrence.properties`; see
+[placement and measurement details](https://github.com/bherbruck/solvecraft/blob/main/docs/assembly-properties.md).

docs/book/src/guide/features.md

@@ -18,6 +18,32 @@ Extruding into existing material selects **Cut**. In an empty component it selec
 choose **New Body** explicitly to keep an addition separate. Changing the default does not alter
 operations already saved in a design.
 
+Editing an extrusion retains its signed distances, From/To Object inputs, taper expressions
+and explicit body targets. Revolve edits retain world, sketch and explicit-line axes, both
+angle expressions and To Object targets. An unchanged **All profiles** selection continues
+to include profiles added later. Cancel restores the complete timeline; a successful edit is
+one undo step, including downstream parameter changes. Editing a placed component previews the
+edited feature before its downstream history. Cylindrical Emboss profile guides follow the
+sketch's chosen occurrence frame.
+
+New symmetric revolves split the entered angle evenly around the sketch profile, regardless
+of which way the selected axis points. Two Sides measures the second angle backward and the
+first angle forward along the sketch-normal sweep direction. Profiles on opposite sides of
+an axis each use their own sweep direction. Designs saved before format 11 keep their original
+angular placement when opened, edited or copied; creating another revolve uses the new behavior.
+To Object follows that same direction for each selected profile, including curved target faces.
+Pick a target away from the axis so its angular position is defined.
+
+For cylindrical **Emboss**, select a supported exterior cylinder face and a tangent sketch
+profile. **Deboss** cuts radially into the wall. Orthogonal line profiles, including holes and
+concave outlines, wrap with exact radial walls; the profile must stay clear of seams and ends.
+Complete cylinders and coaxial sleeves are supported. Capture pending component positions
+before applying. The feature stores the selected target and author occurrence paths, so edits
+and reopening retain the chosen instances. Other curved surfaces and free-form profiles remain
+unsupported. A new Emboss without an explicit face infers a unique eligible supported cylinder;
+select the face when the target is ambiguous. Older saved features without a face retain their
+planar placement.
+
 Fillets and chamfers handle straight edges between planar faces, whole smooth loops, runs of
 neighbouring edges with mitred or spherical corners, and closed chains of curved edges (a rolling
 ball). See the roadmap's known limitations for the rest.
@@ -28,3 +54,7 @@ be found, the feature warns instead of silently picking another face.
 
 Press **Delete** on anything selected (bodies, faces, sketches, features, planes, components,
 canvases). It runs as one undoable step and lists the features that would go with it or fail.
+
+Face Extrude, face Revolve, and Press Pull retain linked generated profiles. When a modified planar face has no construction certificate, these internal profiles use the legacy named-face attachment and projection behavior so upstream edits still update the plane and outline. This compatibility path is private to those modeling tools: newly attached user sketches require a certified face or an explicitly fixed plane. Legacy internal attachments can follow the nearest matching face after topology changes; inspect their result after major upstream edits. Activate the intended occurrence before generating a face profile from a repeated component; capture a separately moved source position before creating a legacy profile across components.
+
+A negative Press Pull across a planar face containing a round through-hole can still fail when the Boolean cutter has coincident curved faces. This operation reports an error and preserves the design atomically; positive face extrusion and Press Pull retain the hole and remain linked.

docs/book/src/guide/files.md

@@ -17,3 +17,12 @@ Saves are atomic: a crash at any moment leaves either the old file or the new on
 replaced version is kept as `<file>.bak`. Unsaved changes are autosaved to a recovery folder,
 and the next launch offers to recover them. Older design files are upgraded on open, and files
 from a newer version are refused with a message.
+
+Current designs use format 10 for recorded body transfers, explicit 3D curve coordinate
+spaces and certified face bindings, alongside semantic configuration styles, associative
+free-form offsets and cylindrical emboss selections. Older ownership maps, geometry and
+expressions retain their saved meaning. Legacy 3D curves with retained associations receive
+their producer's coordinate-space marker without changing any saved points; detached curves
+retain world coordinates. A lost cross-component association refreshed by an older build may
+need an explicit relink or refresh when its source returns. Loading never guesses a numerical
+correction. Association records, coordinate arrays and placements are bounded and checked.

docs/book/src/guide/parameters.md

@@ -18,4 +18,8 @@ existing geometry.
 
 Parameters export to and import from CSV or JSON (`parameters.export`, `parameters.import`).
 **Configurations** (`config.*`) keep a table of rows, each with its own parameter values and
-suppressed features, switched with `config.activate`.
+suppressed features, physical materials and body appearances, switched with `config.activate`.
+The table's Library picker selects material or appearance values. Choose **Follow material**
+to clear an appearance override. Custom looks retain their colour and opacity across
+activation, undo and save/reopen. See
+[configuration commands and examples](https://github.com/bherbruck/solvecraft/blob/main/docs/configurations.md).

docs/book/src/guide/sheet-metal.md

@@ -9,7 +9,47 @@ The SHEET METAL tab builds parts from a sheet of constant thickness under a **sh
 - **Unfold / Refold** (`sheet.unfold`, `sheet.refold`) for working on the flat part.
 - **Convert** (`sheet.convert`) turns a solid of constant thickness into sheet metal.
 - **Create Flat Pattern** (`sheet.flat_pattern`) shows the flat part with its bend lines and a
-  bend table, and exports it as DXF.
+  bend table, and exports it as DXF or a bend-table CSV through the save picker.
 
 Bends follow the rule's K-factor, so flat lengths match what a press brake will make. The
 oracle checks these against parts built in Fusion.
+
+For a shop drawing or spreadsheet, `sheet.export_bend_table` returns CSV by default; choose
+`format: "json"` for structured data. It includes the sheet rule, thickness, bend angles,
+radii, allowances and flat centre-line coordinates. Lengths use millimetres and angles use
+degrees. Supply `path` to save it, or omit `path` to receive the content through the command
+response. `body` defaults to the last sheet body. Exporting does not add a timeline entry or
+consume an undo step.
+
+```json
+{"command":"sheet.export_bend_table","params":{"format":"csv","path":"bracket-bends.csv"}}
+{"command":"sheet.export_dxf","params":{"path":"bracket-flat.dxf"}}
+```
+
+DXF cutout geometry preserves lines, circles and circular arcs; other curves are sampled
+adaptively. The `OUTLINE`, `BEND_UP` and `BEND_DOWN` layers separate cuts from bend centres.
+
+Base-flange profiles keep their interior holes. Through cuts that cross a sheet edge become
+notches in the flat outline; overlapping and repeated cuts remove their combined area once.
+The flat preview, DXF and unfolded solid use the same material boundaries. Lines and circular
+arcs remain exact; other profile curves use a 0.001 mm chord tolerance.
+
+Cuts can leave separate material pieces, including the centre of a ring cut. These pieces
+remain one logical sheet group through Unfold / Refold and export as separate flat outlines.
+Large profiles that exceed the geometry processing budget report an error instead of
+exporting a partial outline.
+
+Parallel, untapered extrude cuts also preserve shallow pockets through Unfold / Refold.
+The pocket floor and side walls remain solid geometry; overlapping cuts from opposite sides
+become a through hole wherever they remove the whole thickness. Flat-pattern JSON lists
+`pockets` with their side, depth and bottom/top thickness coordinates in millimetres.
+DXF pocket boundaries use `POCKET_BOTTOM_Z…_TO_…_MM`, `POCKET_TOP_Z…_TO_…_MM`, or
+`POCKET_INTERNAL_Z…_TO_…_MM` layers. These are machining operations, so do not treat every
+pocket layer as a through-cut contour when importing the drawing into a CAM tool.
+
+Extrude Intersect on a straight base or an unfolded sheet retains the exact planar material,
+including interior holes and detached islands. A completely empty intersection removes the
+sheet and its metadata together. Pocket profiles can move with planar panels when forming,
+but a pocket crossing a bend zone cannot yet be refolded. Machining folded bend material,
+tapered sheet cuts and other unsupported 3D sheet Cut/Intersect operations report an error before changing
+the design; they cannot silently restore removed material during a later sheet rebuild.

docs/book/src/guide/sketching.md

@@ -20,6 +20,43 @@ ids of what it added (`created: {points, curves, constraints, dimensions}`). Ids
 never reused within a sketch, even after a delete, so a script can dimension or constrain the new
 geometry right away.
 
+Extend finds intersections with exact ellipses, rational conics and spline spans. It keeps the
+original line or circular support and extends only beyond the selected endpoint; conflicting
+constraints or an ambiguous overlap leave the sketch unchanged.
+
+Offsets of smooth ellipses, conics and splines follow their source after dimension changes,
+dragging and reopening a design. Their stored cubic spline has a whole-span normal-distance
+error bound of 0.002 mm. Singular tangents, curvature cusps, possible self-intersections and
+excessive subdivisions are refused. Offset these curves individually: mixed chain junctions
+currently require separate geometry. `sketch.offset.break` releases an offset for independent
+editing, and undo restores its association. Older independently sampled offsets remain independent.
+Smooth open and newly created smooth closed offsets can be offset again, including bounded
+refinement after a source edit. New closed outputs use a periodic cubic fit with continuous
+tangent and curvature at the seam. Break Offset Association preserves that interpolation,
+and its closing point remains joined when dragged. Deleting an output also removes its
+unused private fit points; deleting a source with a retained dependent is refused.
+
+For explicit closed fit splines, `sketch.spline.fit_point` accepts `periodic: true` and at
+least three distinct cyclic samples. It closes the loop automatically. Existing calls and
+older saved closed splines retain natural interpolation; older associative closed offsets
+also retain their saved natural fit. A legacy seam without a unique normal still refuses
+another offset. Periodic intent is stored on each curve and survives save, reopen and Break.
+While drawing a fit spline, click its starting point after three distinct samples to close
+it smoothly. Right-click finishes an ordinary natural fit. Offset accepts both ellipse
+handles and dense fitted curves; the second click sets the side and distance from the curve.
+
+Enable **3D Sketch** in the Sketch Palette to draw lines, fit splines and points off the plane.
+New 3D geometry follows its sketch's component placement, including the selected occurrence
+and pending position changes. Click a drawn fit point to show its move triad; its arrows move
+along world X, Y and Z. Scripts also supply world coordinates to `sketch.line3d`,
+`sketch.spline3d`, `sketch.point3d` and `sketch.move3d`. Activate the desired occurrence before
+editing an explicit sketch belonging to a component with multiple placements.
+
+Older drawn or detached 3D wires keep their saved world positions. Included and surface-linked
+wires with an explicit component marker keep that meaning after the link is broken. Old files
+whose links became lost after an incorrectly scoped cross-component refresh may require a
+fresh link once the source is available; their stored point values are preserved on opening.
+
 ## Constraints and dimensions
 
 The solver is SolveCraft's own (damped Gauss–Newton with degree-of-freedom analysis). Constraints: