feat: add scan documentation

Author: wakonig

docs/learn/scans/fast-axis-slow-axis.md

@@ -0,0 +1,131 @@
+---
+related:
+  - title: Position Generators
+    url: learn/scans/position-generators.md
+  - title: ScanArgument
+    url: learn/scans/scanargument.md
+  - title: Learn by Example
+    url: learn/scans/learn-by-example.md
+---
+
+# Fast Axis and Slow Axis
+
+When a scan moves more than one axis, the order of those axes matters.
+
+BEC follows one consistent convention:
+
+- the outermost axis is the slow axis
+- the innermost axis is the fast axis
+
+That means the fast axis changes most often, while the slow axis changes only after the inner sweep
+has finished.
+
+## What That Means In Practice
+
+A useful way to read the convention is:
+
+For every point in `samx` from `-5` to `5`, move `samy` from `-10` to `10`.
+
+In that example:
+
+- `samx` is the slow axis
+- `samy` is the fast axis
+
+So the scan stays on one `samx` value while it sweeps through the full `samy` range, then advances
+to the next `samx` value and repeats.
+
+!!! example
+    A 2D grid scan like this:
+
+    ```py
+    scans.grid_scan(dev.samx, -5, 5, 3, dev.samy, -10, 10, 5, snaked=False, relative=False)
+    ```
+
+    would have `samx` as the slow axis and `samy` as the fast axis, so the scan would:
+
+    1. keep `samx` fixed at `-5` while it sweeps `samy` from `-10` to `10`
+    2. advance `samx` to the next value (in this case `0`) while it again sweeps `samy` from `-10` to `10`
+    3. advance `samx` to the next value (in this case `5`) while it again sweeps `samy` from `-10` to `10`
+    4. finish the scan after the last `samx` value has been reached and its inner sweep has completed
+
+    If the requirement is to have `samy` as the slow axis and `samx` as the fast axis, one would just swap the order of the motor arguments:
+
+    ```py
+    scans.grid_scan(dev.samy, -10, 10, 5, dev.samx, -5, 5, 3, snaked=False, relative=False)
+    ```
+
+## Why This Matters
+
+This convention affects how you read and define multi-axis scans:
+
+- the order of axes in a grid or nested scan is meaningful
+- the generated point order follows that nesting
+- snaking typically changes the traversal direction of the fast axis while keeping the same slow-axis structure
+
+Keeping that convention stable makes scan definitions easier to reason about and makes generated
+point lists more predictable.
+
+## A Simple Example
+
+At the user level, a grid scan might look like this:
+
+```py
+scans.grid_scan(dev.samx, -5, 5, 3, dev.samy, -10, 10, 5, snaked=False)
+```
+
+The same ordering appears in the generated positions:
+
+```py
+positions = position_generators.nd_grid_positions(
+    [(-5.0, 5.0, 3), (-10.0, 10.0, 5)],
+    snaked=False,
+)
+
+for point in positions:
+    samx_position = point[0]
+    samy_position = point[1]
+```
+
+Here the first axis is the outer loop and the second axis is the inner loop:
+
+- axis 1: slow axis
+- axis 2: fast axis
+
+So the point order follows this pattern:
+
+1. keep the first axis fixed
+2. sweep the second axis through all of its values
+3. advance the first axis
+4. repeat
+
+## How To Read Existing Scan Code
+
+When you see code such as:
+
+```py
+positions = position_generators.nd_grid_positions(
+    [(start_motor1, stop_motor1, steps_motor1), (start_motor2, stop_motor2, steps_motor2)],
+    snaked=True,
+)
+```
+
+read it as:
+
+- the first tuple defines the slow axis
+- the second tuple defines the fast axis
+
+That same idea also applies more generally to nested point generation: outer definitions correspond
+to slower-changing axes, and inner definitions correspond to faster-changing axes.
+
+## Next Step
+
+After axis-order conventions, continue with [ScanArgument](scanargument.md).
+
+That page covers the rich input metadata used in scan signatures.
+
+## What To Remember
+
+!!! info "What to remember"
+    - In BEC, the outermost axis is the slow axis and the innermost axis is the fast axis.
+    - The fast axis changes most often within the generated point list.
+    - This convention makes multi-axis scan definitions and point ordering easier to read.

docs/learn/scans/introduction.md

@@ -0,0 +1,128 @@
+---
+related:
+  - title: System architecture overview
+    url: learn/system-architecture/overview/index.md
+  - title: File writing
+    url: learn/file-writer/introduction.md
+  - title: Access BEC history
+    url: how-to/scans/access-bec-history.md
+---
+
+# Scans in BEC
+
+!!! Info "Overview"
+    Scans are the core of BEC's functionality. They are the tools that move your devices, trigger readouts, and produce the data you analyze. In BEC, all scans follow a shared structure and report themselves in a consistent way, even when their motion logic differs.
+
+BEC scans follow one shared model. Whether you run a simple acquisition, a line scan, a grid scan,
+or a continuous scan, BEC handles them in the same overall way.
+
+
+## The Main Idea
+
+The most important idea in BEC scan execution is simple:
+
+- all scans follow the same overall structure
+- all scans are reported through the same backend model
+- all scans are executed on the server
+- all scans produce data that can be accessed in the same general way afterward
+- the client learns the available scans from the scan server, including their current signatures and metadata
+
+That is true even when the middle of the scan is very different.
+
+For example, a line scan, a grid scan, and a continuous scan may move differently, but they still fit into one common scan framework.
+
+## What Happens During A Scan
+
+!!! Note "Dataflow during a scan"
+    A general overview of the dataflow in BEC can be found in the [system architecture overview](../../learn/system-architecture/overview/data-flow.md){ data-preview }.
+
+At a high level, a scan in BEC follows this path:
+
+1. The scan server publishes the available scan classes together with their serialized signatures, grouped inputs, and GUI metadata.
+2. The client exposes those scans dynamically, so commands such as `scans.line_scan(...)` use the current server-side definition.
+3. When a scan is called, the client validates the user inputs, resolves device-name strings to device objects where needed, and bundles repeated positional inputs for scans such as `line_scan` or `umv` before sending the request to the server.
+4. On the server, the request is queued and receives runtime identifiers.
+5. Once it is the scan's turn to run, the scan server queue hands over the request to a scan worker.
+6. The scan worker runs the scan class's lifecycle hooks and sends device instructions through Redis.
+7. Devices publish readouts and status updates.
+8. The scan bundler groups those readouts into logical scan points.
+9. Clients, history, and the file writer consume the resulting scan data.
+
+From the user side, the important part is consistency: every scan goes through the same backend
+steps, reports its progress in the same general way, and produces scan data that can be accessed
+through the same tools afterward.
+
+## The Shared Scan Shape
+
+As mentioned above, all BEC scans follow the same overall shape. They share the same lifecycle steps, and they use the same helpers to report themselves and produce data. This allows users to be always prompted with a familiar structure, even when the motion logic of the scan differs. The shared shape also makes it easier to learn new scans, since you can focus on the differences in motion logic rather than having to learn a new overall structure for each scan. The lifecycle steps are:
+
+<!-- The table is in html as the columns would otherwise wrap. There seems to be no internal way to control column width in markdown -->
+<table>
+  <colgroup>
+    <col style="width: 24%;">
+    <col style="width: 76%;">
+  </colgroup>
+  <thead>
+    <tr>
+      <th>Hook</th>
+      <th>Role</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td style="white-space: nowrap;"><code>prepare_scan</code></td>
+      <td>Prepare the scan for the upcoming acquisition.</td>
+    </tr>
+    <tr>
+      <td style="white-space: nowrap;"><code>open_scan</code></td>
+      <td>Open the scan and emit a new scan status message with all relevant metadata.</td>
+    </tr>
+    <tr>
+      <td style="white-space: nowrap;"><code>stage</code></td>
+      <td>Stage the devices for the upcoming acquisition.</td>
+    </tr>
+    <tr>
+      <td style="white-space: nowrap;"><code>pre_scan</code></td>
+      <td>Run any pre-scan logic, such as preparing time-critical devices.</td>
+    </tr>
+    <tr>
+      <td style="white-space: nowrap;"><code>scan_core</code></td>
+      <td>Run the core logic of the scan; trigger readouts if needed and optionally call <code>at_each_point()</code> for per-point logic.</td>
+    </tr>
+    <tr>
+      <td style="white-space: nowrap;"><code>post_scan</code></td>
+      <td>Run any post-scan logic, such as moving devices back to their original position.</td>
+    </tr>
+    <tr>
+      <td style="white-space: nowrap;"><code>unstage</code></td>
+      <td>Unstage the devices.</td>
+    </tr>
+    <tr>
+      <td style="white-space: nowrap;"><code>close_scan</code></td>
+      <td>Close the scan and emit a final scan status message with all relevant metadata.</td>
+    </tr>
+    <tr>
+      <td style="white-space: nowrap;"><code>on_exception</code></td>
+      <td>If an exception is raised during any earlier step, run cleanup logic here.</td>
+    </tr>
+  </tbody>
+</table>
+
+BEC runs these lifecycle steps in the same order every time.
+
+This shared shape is why BEC scans feel related rather than like separate one-off tools.
+
+## Where To Go Next
+
+If you want the next layer of detail:
+
+- read [Learn by example](../learn/scans/learn-by-example.md){ data-preview } to go through the `acquire` scan example in detail, and see how the shared scan shape applies to a specific scan type.
+
+## What to Remember
+
+!!! info "What to remember"
+    - In BEC, all scans follow the same overall shape.
+    - Different scan types use the same backend framework, even when their motion logic differs.
+    - Every scan reports itself in a common structured way while it runs.
+    - Every scan has to implement the same lifecycle steps, even when some of those steps are empty.
+    - The lifecycle steps are called in the same order for every scan.