trailcode · trailcode · Aug 5, 2026 · Aug 4, 2026 · Aug 5, 2026 · Aug 5, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,7 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Shape copy / paste** (<kbd>Ctrl</kbd>+<kbd>C</kbd> / <kbd>Ctrl</kbd>+<kbd>V</kbd>): in-app clipboard for selected solids, or a Shape List group subtree when the selection matches that group's descendant solids. Paste deep-copies under the current group (new ids, uniquified names, same pose) with one undo step. Survives **New** so you can copy, start a blank project, and paste. Remappable as **`edit.copy`** / **`edit.paste`**. Does not use the OS clipboard; sketch geometry is not copied.
 
-- **Align cylinders** (<kbd>J</kbd>): pick two cylindrical faces (first moves, second is fixed), coaxially align, then drag insert depth along the shared axis (or <kbd>Tab</kbd> for an exact depth). Options **Flip direction** reverses axis sense. Bakes like Move/Rotate (`Shape_geom_delta`); radius mismatch logs a warning but still places. Remappable as **`mode.cyl_align`**.
+- **Align shafts** (<kbd>J</kbd>): pick two cylindrical faces (first moves, second is fixed), coaxially align, drag axial insert depth; with Options **Clock rotation** (default off), LMB or <kbd>Shift</kbd>+<kbd>Tab</kbd> rotates about the shared axis for tooth clocking (<kbd>Enter</kbd> during depth skips clocking). <kbd>Tab</kbd> edits depth or angle by phase. Options **Flip direction** reverses axis sense. Bakes like Move/Rotate (`Shape_geom_delta`); radius mismatch logs a warning but still places. Remappable as **`mode.cyl_align`**.
 
 - **STEP Import as**: the Import dialog replaces the **Union shapes** checkbox with an **Import as** combo (**Preserve hierarchy** default, **Flat solids**, **Union shapes**). Hierarchy keeps XCAF assembly groups and product/instance names; flat adds leaf solids at the document root; union fuses into one solid.
 

diff --git a/agents/drafts/issues/active/gh-246-align-shafts-clock-rotation.md b/agents/drafts/issues/active/gh-246-align-shafts-clock-rotation.md
@@ -0,0 +1,29 @@
+---
+github_issue: 246
+github_pr: 247
+status: open
+---
+
+# Align shafts: clock rotation for tooth clocking
+
+**Suggested labels:** `enhancement`
+
+## Title (GitHub)
+
+Align shafts: clock rotation for tooth clocking
+
+## Body (GitHub)
+
+Filed: https://github.com/trailcode/EzyCad/issues/246
+
+### Summary
+
+Extend Align shafts (formerly Align cylinders) with optional Clock rotation after coaxial depth; rename user-facing tool.
+
+### Follow-ups
+
+- Deterministic Clocking pick (planar tooth flanks) — revisited later.
+
+## Related
+
+- PR: https://github.com/trailcode/EzyCad/pull/247
diff --git a/agents/drafts/prs/active/gh-247-align-shafts-clock-rotation.md b/agents/drafts/prs/active/gh-247-align-shafts-clock-rotation.md
@@ -0,0 +1,27 @@
+---
+github_issue: 246
+github_pr: 247
+status: open
+---
+
+# PR - Align shafts: clock rotation and rename
+
+## Title
+
+Align shafts: clock rotation and rename
+
+## Summary
+
+- Rename Align cylinders -> Align shafts (user-facing; `mode.cyl_align` unchanged).
+- Options Clock rotation (default off) for roll about shared axis after depth.
+- Docs + CHANGELOG.
+
+## Related
+
+- Issue: https://github.com/trailcode/EzyCad/issues/246
+- PR: https://github.com/trailcode/EzyCad/pull/247
+- Branch: `Trailcode/allign_shafts`
+
+## Test Plan
+
+- [ ] Build Release; exercise Clock rotation off/on, Flip, Tab/Shift+Tab, rename in UI/docs.
diff --git a/agents/plans/assembly-inspection-mode.md b/agents/plans/assembly-inspection-mode.md
@@ -53,7 +53,7 @@ flowchart TB
 
 Esc ladder (see [docs/usage.md](../../docs/usage.md)): sketch tool → sketch inspection → Normal.
 
-**Not first-class yet:** Parts, instances, mates, inherited parent transforms. Shape List **groups** are organizational (STEP XCAF hierarchy on import). Move / Rotate / Scale / Align cylinders **bake** into leaf BREP — one-shot geometry edits, not assembly placement. Toolbar icons named `Assembly_*.png` are FreeCAD-style assets for those shape tools, not an assembly workbench.
+**Not first-class yet:** Parts, instances, mates, inherited parent transforms. Shape List **groups** are organizational (STEP XCAF hierarchy on import). Move / Rotate / Scale / Align shafts **bake** into leaf BREP — one-shot geometry edits, not assembly placement. Toolbar icons named `Assembly_*.png` are FreeCAD-style assets for those shape tools, not an assembly workbench.
 
 Planned model: [shape-list-hierarchy-phase3.md](shape-list-hierarchy-phase3.md) (#214) — relative placement, typed nodes (Body, Group, Part, …), non-baking transforms.
 

diff --git a/docs/usage.md b/docs/usage.md
@@ -233,7 +233,7 @@ The typical modeling workflow in EzyCad follows these steps:
 
 3. **Create a Sketch from a Planar Face**: Once you have 3D shapes, use [Create sketch from planar face](usage-sketch.md#create-sketch-from-planar-face-tool) to pick a flat face on a solid. EzyCad extracts the face boundary into a new sketch aligned with that face (Origin at the face bounding-box center). Edit the sketch, then extrude again to add or cut features on the existing model.
 
-4. **Modify 3D Shapes**: Use [3D Modeling tools](#3d-modeling) to transform shapes ([move](#shape-move-tool-g), [rotate](#shape-rotate-tool-r), [scale](#shape-scale-tool-s), [align cylinders](#align-cylinders-tool-j)) or create patterns ([polar duplicate](#shape-polar-duplicate-tool)).
+4. **Modify 3D Shapes**: Use [3D Modeling tools](#3d-modeling) to transform shapes ([move](#shape-move-tool-g), [rotate](#shape-rotate-tool-r), [scale](#shape-scale-tool-s), [align shafts](#align-shafts-tool-j)) or create patterns ([polar duplicate](#shape-polar-duplicate-tool)).
 
 5. **Apply Feature Operations**: Use [boolean operations](#boolean-operations) (cut, fuse, common) or edge-based feature operations (chamfer with <kbd>C</kbd>, fillet with <kbd>F</kbd>) to refine your 3D model.
 
@@ -367,7 +367,7 @@ More detail: [Sketch snapping](usage-sketch.md#sketch-snapping) in the sketch gu
    - ![Shape Move Tool](res/icons/Assembly_AxialMove.png) [Move shapes (G)](#shape-move-tool-g)
    - ![Shape Rotate Tool](res/icons/Draft_Rotate.png) [Rotate objects (R)](#shape-rotate-tool-r)
    - ![Shape Scale Tool](res/icons/Part_Scale.png) [Scale elements (S)](#shape-scale-tool)
-   - ![Align Cylinders Tool](res/icons/Assembly_Move.png) [Align cylinders (J)](#align-cylinders-tool-j)
+   - ![Align Shafts Tool](res/icons/Assembly_Move.png) [Align shafts (J)](#align-shafts-tool-j)
    - ![Polar Duplicate Tool](res/icons/Draft_PolarArray.png) [Polar duplicate](#shape-polar-duplicate-tool)
    - ![Cross-section Tool](res/icons/Curves_ExtractSubshape.png) [Preview a local-plane cross-section](#shape-cross-section-tool)
 
@@ -477,34 +477,37 @@ The shape scale tool allows you to uniformly scale selected shapes around a comp
 - Scale works best when the view direction makes the movement relative to the center easy to see (avoid looking exactly edge-on at the objects).
 - Because the operation is undoable, you can experiment with different scale amounts and step back with <kbd>Ctrl</kbd>+<kbd>Z</kbd> if needed.
 
-#### Align Cylinders Tool (J)
+#### Align Shafts Tool (J)
 
-![Align Cylinders Tool](res/icons/Assembly_Move.png)
+![Align Shafts Tool](res/icons/Assembly_Move.png)
 
-Place a shaft into a hole (or the reverse) by aligning two cylindrical faces, then sliding along the shared axis for insert depth. This is a one-shot transform that bakes into the solid geometry (same as Move / Rotate), not a persistent assembly mate.
+Place a shaft into a hole (or the reverse) by aligning two cylindrical faces, sliding along the shared axis for insert depth, and optionally clocking rotation about that axis (splines, keyways). This is a one-shot transform that bakes into the solid geometry (same as Move / Rotate), not a persistent assembly mate.
 
 **Features:**
 
-|                         |                                                                                                      |
-| ----------------------: | ---------------------------------------------------------------------------------------------------- |
-| **Face picks**          | Click a cylindrical face on the shape to move, then a cylindrical face on the fixed shape.           |
-| **Coaxial align**       | The moving shape snaps so the two cylinder axes coincide.                                            |
-| **Axial depth drag**    | After align, drag to set how far the moving shape slides along the shared axis.                      |
-| **Flip direction**      | Options **Flip direction** reverses which way the moving axis points along the fixed axis.           |
-| **Radius mismatch**     | Placement is still allowed when radii differ (clearance / press fits); a log warning is recorded.    |
+|                      |                                                                                                    |
+| -------------------: | -------------------------------------------------------------------------------------------------- |
+| **Face picks**       | Click a cylindrical face on the shape to move, then a cylindrical face on the fixed shape.         |
+| **Coaxial align**    | The moving shape snaps so the two cylinder axes coincide.                                          |
+| **Axial depth drag** | After align, drag to set how far the moving shape slides along the shared axis.                    |
+| **Clock rotation**   | Options **Clock rotation** (default off): after depth, rotate about the shared axis to mesh teeth. |
+| **Flip direction**   | Options **Flip direction** reverses which way the moving axis points along the fixed axis.         |
+| **Radius mismatch**  | Placement is still allowed when radii differ (clearance / press fits); a log warning is recorded.  |
 
 **How to Use:**
 
 1. ![Assembly_Move](res/icons/Assembly_Move.png) **Activate:** Press <kbd>J</kbd> or click the toolbar icon.
 2. **Pick moving face:** Click a cylindrical face on the body that should move (for example the outer face of a rod).
 3. **Pick fixed face:** Click a cylindrical face on a different body (for example the inner face of a hole).
 4. **Set depth:** Drag along the axis. Optionally press <kbd>Tab</kbd> to type an exact depth.
-5. **Finalize or cancel:** <kbd>left mouse button</kbd> or <kbd>Enter</kbd> to bake; <kbd>Esc</kbd> to cancel.
+5. **Clock rotation (optional):** Enable Options **Clock rotation**. Then <kbd>left mouse button</kbd> or <kbd>Shift</kbd>+<kbd>Tab</kbd> locks depth and enters clocking; drag about the axis (or type an angle). With **Clock rotation** off, LMB finalizes after depth.
+6. **Finalize or cancel:** <kbd>left mouse button</kbd> or <kbd>Enter</kbd> to bake; <kbd>Esc</kbd> to cancel. <kbd>Enter</kbd> during the depth phase finalizes immediately without clocking.
 
 **Tips:**
 
 - The first face you pick is the body that moves. To move the hole body onto the shaft, pick the hole face first.
 - Use **Flip direction** in Options if the shaft points the wrong way after align.
+- Pick cylindrical faces (root / major diameter or smooth lands), not spline tooth flanks.
 - This tool only places solids; use [Cut](#boolean-operations) afterward if you need a boolean.
 
 ## Feature Operations
@@ -737,38 +740,38 @@ Mode, file, and edit chords in the **General Operations** and **Modeling Shortcu
 | <kbd>Shift</kbd>+<kbd>Tab</kbd>                                              | Angle input (for line edges with angle constraint)                               |
 | <kbd>Shift</kbd>+<kbd>D</kbd>, <kbd>Delete</kbd>, or <kbd>Backspace</kbd>    | Remove selected elements                                                         |
 | <kbd>Ctrl</kbd>+<kbd>C</kbd>                                                 | Copy selected shapes (or current group subtree) to the in-app clipboard          |
-| <kbd>Ctrl</kbd>+<kbd>V</kbd>                                                 | Paste clipboard shapes under the current group (same pose; undoable)               |
+| <kbd>Ctrl</kbd>+<kbd>V</kbd>                                                 | Paste clipboard shapes under the current group (same pose; undoable)             |
 
 ### Modeling Shortcuts
 
-|                                                   |                                |
-| ------------------------------------------------:| ------------------------------ |
-| <kbd>G</kbd>                                      | Move mode                      |
-| <kbd>R</kbd>                                      | Rotate mode                    |
-| <kbd>S</kbd>                                      | Scale mode                     |
-| <kbd>J</kbd>                                      | Align cylinders mode           |
-| <kbd>E</kbd>                                      | Extrude mode                   |
-| <kbd>C</kbd>                                      | Chamfer mode                   |
-| <kbd>F</kbd>                                      | Fillet mode                    |
-| <kbd>D</kbd>                                      | Dimension tool (sketch)        |
-| <kbd>I</kbd>                                      | Sketch inspection              |
-| <kbd>P</kbd>                                      | Sketch from planar face        |
-| <kbd>Shift</kbd>+<kbd>A</kbd>                     | Operation axis                 |
-| <kbd>N</kbd>                                      | Add node                       |
-| <kbd>L</kbd>                                      | Add line edge                  |
-| <kbd>Shift</kbd>+<kbd>L</kbd>                     | Add multi-line edge            |
-| <kbd>A</kbd>                                      | Add arc                        |
-| <kbd>Q</kbd>                                      | Add square                     |
-| <kbd>B</kbd>                                      | Add rectangle (two points)     |
-| <kbd>Shift</kbd>+<kbd>B</kbd>                     | Add rectangle (center)         |
-| <kbd>O</kbd>                                      | Add circle                     |
-| <kbd>Shift</kbd>+<kbd>O</kbd>                     | Add circle (three points)      |
-| <kbd>U</kbd>                                      | Add slot                       |
-| <kbd>Shift</kbd>+<kbd>P</kbd>                     | Polar duplicate                |
-| <kbd>Shift</kbd>+<kbd>X</kbd>                     | Cross-section                  |
-| <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>C</kbd>     | Shape cut                      |
-| <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>F</kbd>     | Shape fuse                     |
-| <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>M</kbd>     | Shape common                   |
+|                                               |                            |
+| --------------------------------------------: | -------------------------- |
+| <kbd>G</kbd>                                  | Move mode                  |
+| <kbd>R</kbd>                                  | Rotate mode                |
+| <kbd>S</kbd>                                  | Scale mode                 |
+| <kbd>J</kbd>                                  | Align shafts mode          |
+| <kbd>E</kbd>                                  | Extrude mode               |
+| <kbd>C</kbd>                                  | Chamfer mode               |
+| <kbd>F</kbd>                                  | Fillet mode                |
+| <kbd>D</kbd>                                  | Dimension tool (sketch)    |
+| <kbd>I</kbd>                                  | Sketch inspection          |
+| <kbd>P</kbd>                                  | Sketch from planar face    |
+| <kbd>Shift</kbd>+<kbd>A</kbd>                 | Operation axis             |
+| <kbd>N</kbd>                                  | Add node                   |
+| <kbd>L</kbd>                                  | Add line edge              |
+| <kbd>Shift</kbd>+<kbd>L</kbd>                 | Add multi-line edge        |
+| <kbd>A</kbd>                                  | Add arc                    |
+| <kbd>Q</kbd>                                  | Add square                 |
+| <kbd>B</kbd>                                  | Add rectangle (two points) |
+| <kbd>Shift</kbd>+<kbd>B</kbd>                 | Add rectangle (center)     |
+| <kbd>O</kbd>                                  | Add circle                 |
+| <kbd>Shift</kbd>+<kbd>O</kbd>                 | Add circle (three points)  |
+| <kbd>U</kbd>                                  | Add slot                   |
+| <kbd>Shift</kbd>+<kbd>P</kbd>                 | Polar duplicate            |
+| <kbd>Shift</kbd>+<kbd>X</kbd>                 | Cross-section              |
+| <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>C</kbd> | Shape cut                  |
+| <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>F</kbd> | Shape fuse                 |
+| <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>M</kbd> | Shape common               |
 
 
 ### View navigation
@@ -901,7 +904,7 @@ Contributors should follow **[ezycad_code_style.md](ezycad_code_style.md)** for
 - ![Assembly_AxialMove](res/icons/Assembly_AxialMove.png) - Shape move (<kbd>G</kbd>)
 - ![Draft_Rotate](res/icons/Draft_Rotate.png) - Shape rotate (<kbd>R</kbd>)
 - ![Part_Scale](res/icons/Part_Scale.png) - Shape scale (<kbd>S</kbd>)
-- ![Assembly_Move](res/icons/Assembly_Move.png) - Align cylinders (<kbd>J</kbd>)
+- ![Assembly_Move](res/icons/Assembly_Move.png) - Align shafts (<kbd>J</kbd>)
 
 ### Sketch Tools
 - ![Workbench_Sketcher_none](res/icons/Workbench_Sketcher_none.png) - Sketch inspection mode