feat: stabilize face attachments and closed spline workflows

docs/book/src/guide/features.md

@@ -26,13 +26,23 @@ one undo step, including downstream parameter changes. Editing a placed componen
 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; omitting the face retains the planar emboss behavior.
+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
@@ -44,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/sketching.md

@@ -25,9 +25,20 @@ error bound of 0.002 mm. Singular tangents, curvature cusps, possible self-inter
 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 offsets can be offset again, including bounded refinement after a source edit.
-A closed offset uses a natural cubic spline whose seam can have different end tangents;
-offsetting that result again is refused when the seam has no unique normal.
+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

docs/configurations.md

@@ -146,6 +146,6 @@ value lists support up to 128 expressions. These bounds are checked before saved
 decoded. Driven appearance/material rules and repeated fixed-point evaluation are outside
 the current rule scope.
 
-Designs saved with source-certified face styles use file format 10. Older designs upgrade on opening without
+Newly saved designs use file format 11, including optional durable face attachments. Older designs upgrade on opening without
 changing their existing configuration values. Older SolveCraft versions must be updated to
 open newly saved designs.

docs/face-attachments.md

@@ -0,0 +1,66 @@
+# Face-attached sketches
+
+New face-attached sketches store the selected source body, its creating feature, an exact
+face certificate, and the source and author occurrence paths. The sketch's picked origin
+and orientation are stored in the source face's canonical plane. Editing the source height
+or moving its placement therefore updates the sketch plane while preserving its local
+geometry and dimensions.
+
+Supported planar sources are exact Box faces, untapered New Body Extrude caps and straight
+sketch sides, and planar faces of immutable STEP imports. Extrude caps also identify their
+outer boundary and holes by source curve IDs. Reordering profiles cannot substitute another
+profile's cap. Curved surfaces cannot host a planar sketch through this workflow.
+Edited surfaces without retained construction provenance, ambiguous sources, and unsupported
+generators require an explicit fixed plane instead. A nearby or parallel face is never used
+to repair a new attachment automatically.
+
+## Create and repair
+
+Select a supported planar face and create a sketch. The desktop selection supplies the exact
+body and face index, including its occurrence path. Command callers can use
+`sketch.create` with `plane: {face: [x,y,z], body: "world body key", index: face_index}`;
+the point is in world coordinates. A point-only face request must find a unique supported
+source. An unsupported or ambiguous request fails with an explanation instead of creating
+an attachment with weaker identity.
+
+When a source is suppressed, deleted, replaced, or loses its certificate, the sketch reports
+a lost attachment. Its saved plane is only a visible repair guide: it does not produce a
+healthy solved sketch or let downstream features build at a substitute face.
+
+Use **Redefine Sketch Plane** to select a new supported face explicitly. The draft can be
+reviewed before applying it; cancellation leaves the existing attachment intact. Reattachment
+keeps existing sketch geometry, IDs, and dimensions. When the selected source changes, its
+previous automatically projected boundary becomes ordinary geometry on the new plane;
+it is not replaced by a newly projected boundary. Rebinding to the same certified source
+retains its live boundary. Manually created projection links retain their own sources.
+
+Choose an explicit fixed plane to detach the sketch. This preserves its current local
+geometry and dimensions and converts only its automatically projected face boundary to
+ordinary geometry. Manual projection links remain attached to their own sources. A fresh
+fixed-plane sketch has no live face auto-projection.
+
+## Occurrences, pending positions, and files
+
+The selected source occurrence and the sketch's author occurrence are separate identities.
+Repeated instances therefore cannot silently switch an attachment to the first placement.
+A missing author path also requires explicit repair. Reattachment and creation capture
+pending positions only on the involved source and author paths. Failed commands restore
+those pending positions; undo restores the previous attachment and placement state.
+
+File format 11 saves these optional attachments. Existing designs with face references
+without an attachment retain their legacy geometry and lookup behavior when opened; they
+are not silently upgraded. Redefining such a sketch onto a supported selected face creates
+the stronger attachment. Unsupported legacy geometry can instead be retained on an explicit
+fixed plane. Imported attachments also bind the exact STEP payload digest, item entity, and
+face entity: replacing the payload cannot reuse an old attachment merely because a face
+index or shape looks the same.
+
+## Profiles generated by face modelling commands
+
+Extrude, Revolve, and Press Pull can generate an internal sketch from a selected planar face. Supported
+sources use the same certified attachment and live boundary as an ordinary attached sketch.
+For modified faces without a construction certificate, these commands retain their historical
+named-face and linked-boundary behaviour through a private compatibility path. Initial capture
+uses the selected body and face index. These helper sketches do not have the stronger saved
+identity guarantee of a certified attachment. This compatibility path does not change the
+requirements for creating an ordinary face-attached sketch.

docs/occurrence-workflows.md

@@ -51,3 +51,11 @@ Create Components from Bodies and Move Bodies to Component now add ownership-tra
 Transfers preserve the body's world pose through rotated or translated parents. Pending positions on the involved source and destination paths are captured atomically with the transfer so save/reopen retains that pose; unrelated pending positions remain pending. Undo and checkpoint restoration recover the original pending positions as well as the feature history; redo restores the captured transfer. The operation requires one source and one destination placement. Shared instance definitions with several placements are rejected because a single ownership change cannot preserve several different world poses. A component that supplies transfer history outside its subtree cannot be deleted until that dependent history is removed.
 
 Older files without transfer features keep their saved assignment and offset behavior. No transfer timestamp is inferred from their final ownership map. Paste New freezes externally authored geometry after its successful entry transfer and remaps internal transfers, then replays later modifiers once. All transfer commands validate and evaluate on a scratch document before adoption.
+
+New face-attached sketches capture the selected body's producer, certified face and exact occurrence path, together with the sketch's authoring placement. A supported face follows source edits; a missing or incompatible source reports a lost attachment rather than choosing another nearby face. Opening Edit restores the saved authoring occurrence as view context without creating an undo entry. Older saved point-only face references retain their legacy behavior.
+
+`sketch.create` accepts `plane:{face:[x,y,z],body:"world body name",index:faceIndex,path:[occurrenceIDs]}`. Coordinates and custom planes are world inputs. The optional path must match the selected body. Point-only face picks must resolve uniquely to a supported exact attachment. For an unsupported planar face, explicitly add `fixed:true` to keep its current plane; this creates no live boundary projection. Curved faces cannot become planar attachments through this option.
+
+Use `sketch.redefine` with the sketch ID and a new plane to repair or convert an attachment. Its preview is disposable; Apply records one undo step. An optional `author_path` explicitly repairs a missing author placement. Rebinding a repeated owner from another active component requires that path. Changing the target or converting to a fixed plane detaches only the old automatic face borders, retaining their currently evaluated geometry and entity IDs; unrelated projection links remain live. Pending positions on the involved target and author paths are captured with the edit, while unrelated pending positions remain pending.
+
+Paste New remaps internal certified targets and authoring paths to the copied definitions. Timeline paste reports retained external face targets and refuses translating such attachments until an explicit fixed-plane conversion establishes independent geometry. Rename preserves certified body identity; another producer using the same body name cannot repair a lost attachment.