Document the Alignment Tool wizard and automatic compass orientation detection

docs/03-getting-started/04-accel-calibration.mdx

@@ -49,7 +49,9 @@ There is no need to place the model perfectly aligned, the algorithm does not ca
 
 ### Board Orientation and Level Calibration
 
-If the FC board is rotated in any way that differs from its default orientation markings, the board alignment settings must be changed to match (_see the "Alignment Tool" tab in the INAV configurator_). 
+If the FC board is rotated in any way that differs from its default orientation markings, the board alignment settings must be changed to match (_see the [Alignment Tool Tab](../04-inav-configurator/alignment-tool-tab.mdx) in the INAV configurator_).
+That tab's wizard can determine the correct board alignment (and, if you have a compass fitted, its alignment too) for you automatically — see [Which Path Applies to Your Board?](../04-inav-configurator/alignment-tool-tab.mdx#which-path-applies-to-your-board).
+
 
 You can verify the correct board orientation by banking your aircraft left and right, forward and back and rotate left and right. 
 In all examples the 3D model image in configurator **must** move accordingly.

docs/04-inav-configurator/alignment-tool-tab.mdx

@@ -3,9 +3,83 @@ title: Alignment Tool Tab
 sidebar_position: 16
 ---
 
-This tab lets you change the angle that you FC and compass are mounted on your aircraft. 
-This is critical to setting up INAV.
-You may have mounted the FC upside-down or backwards and this is where you can save this new orientation.
-When you go back to the Setup Tab, you should see the 3D Graphic move the same as your actual aircraft.
+This tab lets you set the mounting orientation of your flight controller and, if fitted, your compass.
+Getting this right is critical: INAV uses these settings to translate raw sensor readings into the aircraft's real-world attitude and heading.
 
-![Alignment Tool Tab](/img/app/alignment-tool-tab.png)
+You may have mounted the FC upside-down, backwards, or at an angle, and this is where you tell INAV about it.
+Once set correctly, going to the [Status Tab](./status-tab.mdx) and moving the aircraft by hand should show the 3D model move the same way, on every axis.
+
+![Alignment Tool Tab](/img/app/alignment-tool-tab.png)
+
+## Which Path Applies to Your Board?
+
+INAV also ships an **Experimental: Auto Alignment Wizard** on this tab that determines both the board's and, if fitted, the compass's mounting orientation automatically — from a few accelerometer and compass readings — rather than you working them out and entering them by hand.
+The wizard runs the same way on every board; the only thing that changes is whether a compass is fitted:
+
+- [**No magnetometer**](#no-magnetometer): board alignment only — there's no compass step to do.
+- [**With a magnetometer**](#with-a-magnetometer): board alignment, then one more step (face east) to determine the compass's mounting orientation too.
+
+:::info
+**Order matters.** The wizard's compass step needs a compass that's already calibrated (offsets and gains) — calibrate the compass on the [Calibration Tab](./calibration-tab.mdx) first, then run this wizard.
+Calibration itself doesn't depend on board alignment being set yet, so it's fine to calibrate before the wizard sets that.
+:::
+
+:::tip
+Boards with plenty of spare RAM (F745/H7-class and similar) can also have INAV detect the compass's mounting orientation automatically, as part of the Calibration tab's own magnetometer-calibration spin — see [Automatic Compass Orientation Detection](../05-core-features/compass.mdx#automatic-compass-orientation-detection).
+That's an alternative to this wizard's east-facing step, not a requirement — the wizard works the same way regardless of your board's RAM class.
+:::
+
+## Using the Wizard
+
+Click **Launch Wizard** to begin.
+The steps are the same up through board alignment regardless of which path your board takes:
+
+1. **Start**: place the aircraft flat and pointing north, then confirm.
+
+   ![Alignment Wizard: place flat and pointing north](/img/app/alignment-wizard-step1-north.png)
+1. **Nose up ~45°**: tilt the nose up by about 45 degrees from the first position, keeping the aircraft otherwise still, then confirm.
+   INAV uses the two readings together to work out which of the 16 standard mounts (upright or inverted, in 45° yaw steps) your board is in.
+
+   ![Alignment Wizard: tilt nose up 45 degrees](/img/app/alignment-wizard-step2-tilt.png)
+
+From here, the wizard finishes right away if no magnetometer is fitted, or continues with one more step if one is.
+
+### No magnetometer
+
+The wizard finishes right after the nose-up step — there's no third step, and nothing to calibrate or align beyond the board itself.
+Click **Save** to save the board alignment and reboot.
+
+![Alignment Wizard: finished, no magnetometer detected](/img/app/alignment-wizard-nomag-done.png)
+
+### With a magnetometer
+
+The wizard continues with one more step before finishing:
+
+3. **Face east**: turn the aircraft (keeping it flat) so the nose points east, then confirm.
+
+   ![Alignment Wizard: face east step](/img/app/alignment-wizard-compass-east.png)
+
+The wizard uses the heading change between the first and third readings to work out the compass's mounting orientation relative to the flight controller, and reports both the board alignment and the compass alignment it's about to save.
+Click **Save** to save both and reboot.
+
+![Alignment Wizard: board and compass alignment finished](/img/app/alignment-wizard-mag-done.png)
+
+:::info
+The compass must already be calibrated (via **Calibrate Magnetometer** on the Calibration tab) before this step will work — the wizard checks for this up front and tells you to calibrate first if it isn't.
+:::
+
+## Troubleshooting
+
+The wizard validates each reading and will stop with an explanation if something doesn't look right:
+
+- **"Readings did not match a supported mount"**: the two accelerometer readings didn't match any of the 16 supported mounts.
+  This can happen if the flight controller is mounted on its edge, if the board moved between readings, or if the nose wasn't raised close enough to 45 degrees.
+  Use a flat or upside-down mount and try again, or set the board alignment manually on this tab.
+- **"The second reading looks too similar to the first"**: the nose-up tilt wasn't big enough for the wizard to distinguish it from the flat reading.
+  Make sure the nose is raised by about 45 degrees, then try again.
+- **"The compass must be calibrated before its alignment can be determined"**: calibrate the magnetometer on the Calibration tab first, then re-run the wizard.
+
+## Manual Alignment
+
+The rest of this tab lets you set board and compass alignment directly, without the wizard — useful for mounts the wizard can't resolve (e.g. tilted at a non-45° angle), or if you'd simply rather set the values by hand.
+See [Manual Compass Orientation and Placement](../05-core-features/compass.mdx#manual-compass-orientation-and-placement) for that procedure.

docs/04-inav-configurator/calibration-tab.mdx

@@ -42,7 +42,9 @@ There is no need to place the model perfectly aligned, the algorithm does not ca
 
 ## Board Orientation and Level Calibration
 
-If you have your board rotated in any way, change board alignment to match (_see the "Alignment Tool" tab in the INAV configurator_). 
+If you have your board rotated in any way, change board alignment to match (_see the [Alignment Tool Tab](./alignment-tool-tab.mdx) in the INAV configurator_).
+That tab also has a wizard that can determine your board's (and, if you have one fitted, your compass's) mounting orientation automatically — see [Which Path Applies to Your Board?](./alignment-tool-tab.mdx#which-path-applies-to-your-board) for whether to use it before or after the compass calibration below.
+
 
 You can verify the correct board orientation by banking your aircraft left and right, forward and back and rotate left and right.
 In all examples the 3D model image in configurator **must** move accordingly.

docs/05-core-features/compass.mdx

@@ -200,6 +200,26 @@ Calibrate with flight battery powering up the aircraft.
 1. Within 30 seconds, hold the aircraft in the air and rotate it so that each side (front, back, left, right, top and bottom) points down towards the earth.
    The algorithm is smart enough to calculate the proper calibration values even if each side does not see a complete rotation after pressing the "Calibrate Magnetometer" button.
 
+### Automatic Compass Orientation Detection
+
+INAV can automatically detect and set the compass's mounting orientation (`align_mag_roll`, `align_mag_pitch`, `align_mag_yaw`) as part of the calibration spin above, so a standard mounting no longer needs its Orientation Preset worked out by hand.
+
+There's nothing extra to do beyond the steps above: while the aircraft is spun during calibration, INAV records the raw compass reading together with the flight controller's own attitude at each moment. Once the spin finishes, it checks whether the compass mounting matches one of 16 standard orientations (upright or inverted, in 45° yaw steps) and, if it's confident in the result, sets the alignment automatically.
+
+:::info
+This detects the compass's mounting **relative to the flight controller**, not which way the flight controller itself is mounted on the airframe. FC alignment must still be set correctly first — see [Compass and Flight Controller Alignment is Coupled](#compass-and-flight-controller-alignment-is-coupled) above.
+:::
+
+- It only covers upright/inverted mountings in 45° yaw steps, not a compass mounted at an arbitrary tilt (e.g. on an angled camera mount). For those, use [Manual Compass Orientation and Placement](#manual-compass-orientation-and-placement) or the [Empirical Method](#empirical-method-for-determining-compass-alignment) above.
+- **Not available on boards with 256KB of RAM or less** (F405, F411, F722, and similar) — there isn't enough spare RAM for this feature, and calibration works exactly as described above.
+  Use the [Alignment Tool Tab](../04-inav-configurator/alignment-tool-tab.mdx)'s wizard instead, which determines board *and* compass orientation together in one guided flow on every board.
+- If the spin doesn't produce a confident result (too few samples, or an ambiguous spin), INAV leaves your existing alignment setting untouched rather than guessing — run the [Alignment Tool Tab](../04-inav-configurator/alignment-tool-tab.mdx)'s wizard instead, or set the alignment by hand.
+
+:::tip
+Not sure whether your board supports this, or what order to do things in?
+See [Which Path Applies to Your Board?](../04-inav-configurator/alignment-tool-tab.mdx#which-path-applies-to-your-board) on the Alignment Tool Tab page.
+:::
+
 ### Compass Calibration Using Stick Commands
 
 Calibrating Mag/Compass without the need to be connected to a computer can extremely convenient while out in the field.