trailcode · trailcode · Aug 1, 2026 · Aug 1, 2026 · Aug 1, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **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`**.
+
 - **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.
 
 - **STEP import progress**: on **Import into project**, an **Importing...** modal appears while transferring. Desktop shows stage/progress and Cancel (OCCT transfer on a background thread). Web shows a simple wait dialog (no Cancel; transfer runs on the main thread after the dialog paints). The Import dialog no longer shows a file metadata summary (opens immediately after file pick).

diff --git a/docs/usage.md b/docs/usage.md
@@ -232,7 +232,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)) 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 cylinders](#align-cylinders-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.
 
@@ -366,6 +366,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)
    - ![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)
 
@@ -475,6 +476,36 @@ 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 Cylinders 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.
+
+**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.    |
+
+**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.
+
+**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.
+- This tool only places solids; use [Cut](#boolean-operations) afterward if you need a boolean.
+
 ## Feature Operations
 
 ### Extrude Sketch Face Tool (E)
@@ -712,6 +743,7 @@ Mode, file, and edit chords in the **General Operations** and **Modeling Shortcu
 | <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                    |
@@ -866,6 +898,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>)
 
 ### Sketch Tools
 - ![Workbench_Sketcher_none](res/icons/Workbench_Sketcher_none.png) - Sketch inspection mode

diff --git a/res/ezycad_settings.json b/res/ezycad_settings.json
@@ -55,6 +55,7 @@
       "mode.add_slot": "U",
       "mode.polar_duplicate": "Shift+P",
       "mode.cross_section": "Shift+X",
+      "mode.cyl_align": "J",
       "cmd.shape_cut": "Ctrl+Shift+C",
       "cmd.shape_fuse": "Ctrl+Shift+F",
       "cmd.shape_common": "Ctrl+Shift+M",

diff --git a/src/doc/gui.md b/src/doc/gui.md
@@ -162,8 +162,9 @@ Remappable chords live in `Gui_hotkeys` (`gui_hotkeys.h` / `.cpp`), owned by `GU
 | Remappable chord                  | `m_hotkeys` hit     | `dispatch_hotkey_action_` (`Gui_action`: sketch/shape modes, booleans, delete, file, undo/redo)       |
 | Move-mode keys                    | `Mode::Move`        | `on_key_move_mode_` (axis constraints X/Y/Z); hardcoded                                               |
 | Rotate-mode keys                  | `Mode::Rotate`      | `on_key_rotate_mode_` (axis pick, Tab angle); hardcoded                                               |
+| Cyl-align keys                    | `Mode::Shape_cyl_align` | `on_key_cyl_align_mode_` (Tab depth, Enter finalize); hardcoded                                   |
 
-Default remappable chords include G/R/S/E/C/F/D shape tools; sketch tools N/L/A/Q/B/O/U/I/P and Shift variants; Shift+P polar, Shift+X cross-section; Ctrl+Shift+C/F/M booleans; Shift+D delete; Ctrl+N/O/S; Ctrl+Z / Ctrl+Y. Unmodified X/Y/Z are reserved for Move/Rotate axis toggles (`is_reserved_chord`); Shift+X remains free for cross-section. Remappable keys must pass `is_bindable_key` (letters, digits, Space, and named keys that round-trip in settings JSON); punctuation such as `,` / `.` and numpad keys are rejected. Settings **Keyboard shortcuts** has a `?` to `doc_urls::k_hotkeys` ([usage-settings.md#keyboard-shortcuts](../../docs/usage-settings.md#keyboard-shortcuts)).
+Default remappable chords include G/R/S/J/E/C/F/D shape tools; sketch tools N/L/A/Q/B/O/U/I/P and Shift variants; Shift+P polar, Shift+X cross-section; Ctrl+Shift+C/F/M booleans; Shift+D delete; Ctrl+N/O/S; Ctrl+Z / Ctrl+Y. Unmodified X/Y/Z are reserved for Move/Rotate axis toggles (`is_reserved_chord`); Shift+X remains free for cross-section. Remappable keys must pass `is_bindable_key` (letters, digits, Space, and named keys that round-trip in settings JSON); punctuation such as `,` / `.` and numpad keys are rejected. Settings **Keyboard shortcuts** has a `?` to `doc_urls::k_hotkeys` ([usage-settings.md#keyboard-shortcuts](../../docs/usage-settings.md#keyboard-shortcuts)).
 
 See also [`src/doc/sketch.md`](sketch.md) and [`src/doc/shape.md`](shape.md) for per-mode mouse routing after `GUI` delegates to `Occt_view`.
 
@@ -174,6 +175,7 @@ See also [`src/doc/sketch.md`](sketch.md) and [`src/doc/shape.md`](shape.md) for
 | `Move`                                              | `shp_move().move_selected`       |
 | `Rotate`                                            | `shp_rotate().rotate_selected`   |
 | `Scale`                                             | `shp_scale().scale_selected`     |
+| `Shape_cyl_align`                                   | `shp_cyl_align().drag_depth`     |
 | `Shape_polar_duplicate`                             | `shp_polar_dup().move_point`     |
 | Sketch tool modes (line, arc, rect, dim, axis, ...) | `curr_sketch().sketch_pt_move`   |
 | `Sketch_face_extrude`                               | `sketch_face_extrude(..., true)` |
@@ -187,7 +189,7 @@ Always calls `m_view->on_mouse_move(screen_coords)` first.
 | LMB (underlay calib active) | `try_underlay_calib_click_` (early return)                                                                           |
 | LMB                         | `m_view->on_mouse_button` then `on_left_click_` (skipped when extrude LMB already advanced/finalized the session)    |
 | RMB press                   | `finalize_elm` for line / multi-line sketch modes                                                                    |
-| LMB in `on_left_click_`     | Mode-specific: transform finalize, sketch `add_sketch_pt`, fillet/chamfer click, polar dup `add_point`, extrude pick |
+| LMB in `on_left_click_`     | Mode-specific: transform finalize, cyl-align face pick / finalize, sketch `add_sketch_pt`, fillet/chamfer click, polar dup `add_point`, extrude pick |
 
 Tests use `sketch_left_click` to simulate sketch LMB without ImGui mouse position.
 
@@ -206,6 +208,7 @@ Tests use `sketch_left_click` to simulate sketch LMB without ImGui mouse positio
 | -------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
 | `Normal`                         | `options_normal_mode_` (selection filter, orthographic)                                                             |
 | `Move` / `Rotate` / `Scale`      | `options_*_mode_` (constraints, axis, material)                                                                     |
+| `Shape_cyl_align`                | Flip direction; short pick/drag help                                                                                |
 | `Shape_chamfer` / `Shape_fillet` | mode + radius/distance                                                                                              |
 | `Shape_polar_duplicate`          | angle, count, rotate/combine, **Dup** button                                                                        |
 | `Shape_cross_section`            | local XY/XZ/YZ, invert normal, hide back side, show section outline, bbox-ranged offset, Clip, Cross section sketch |