docs: realign autodoc screenshots with the redesigned file explorer

docs/source/user_guide/00_getting_started.md

@@ -0,0 +1,38 @@
+# Getting Started
+
+## Overview
+
+On first launch ExLab-Wizard shows a welcome card -- the operator's
+entry point into the application. From here the operator either begins
+guided setup or skips straight to the main window. This page is an
+orientation aid; it is not one of the eight numbered capabilities, and
+the guide proper begins with {doc}`01_settings`.
+
+## Walkthrough
+
+1. **Launch ExLab-Wizard.** The tray application shows the welcome card
+   on a fresh install, or whenever required configuration is still
+   missing.
+2. **Choose a start path.** *Get started*
+   (`data-testid="welcome-get-started"`) opens the Settings dialog in
+   setup-incomplete mode to walk through configuration; *Skip for now*
+   (`data-testid="welcome-skip-for-now"`) jumps straight to the main
+   window, leaving setup for later.
+3. **Set the autostart preference.** The *start at login* toggle
+   (`data-testid="welcome-autostart-toggle"`) records whether the tray
+   should launch automatically; the preference is applied whichever
+   start path is chosen.
+
+## Screenshots
+
+```{image} ../_static/screenshots/00_getting_started/01_initial.png
+:alt: First-launch welcome card
+:align: center
+```
+
+## Related material
+
+- {doc}`01_settings` -- the guided setup that *Get started* opens.
+- {doc}`02_browse` -- the main window that *Skip for now* opens.
+- Design spec section 02 (User Interaction) -- the capability set this
+  guide documents.

docs/source/user_guide/06_settings.md → docs/source/user_guide/01_settings.md

@@ -27,13 +27,40 @@ order. See section 02 §3.6 for the authoritative contract and section
    The Discard button (`data-testid="settings-discard"`) abandons
    pending changes.
 
+## Add Equipment wizard
+
+The Settings dialog edits equipment that already exists; registering a
+**new** device uses the dedicated Add-Equipment wizard, opened from the
+main-window toolbar's *Add Equipment* button
+(`data-testid="toolbar-add-equipment"`). The wizard walks five steps --
+identity, paths, sync mode, completeness signal, and a review step --
+then posts the assembled `EquipmentConfig` to the configuration router.
+Editing or removing a registered device stays in the Settings dialog's
+Equipment List section, which the file-explorer tree context menus
+deep-link into (Redesign decision 4A).
+
+1. **Open the wizard.** Click *Add Equipment* on the main-window
+   toolbar to navigate to `/wizard/equipment`.
+2. **Step through the wizard.** Supply the equipment identity
+   (`data-testid="wizard-equipment-id"`), the local and NAS paths, the
+   sync mode (`nas` or `stage`), and the completeness signal
+   (`sentinel_file` or `manifest`).
+3. **Confirm.** The Confirm button on the review step
+   (`data-testid="wizard-equipment-confirm"`) registers the device and
+   returns to the main window.
+
 ## Screenshots
 
-```{image} ../_static/screenshots/06_settings/01_initial.png
+```{image} ../_static/screenshots/01_settings/01_initial.png
 :alt: Settings dialog with the Paths section active
 :align: center
 ```
 
+```{image} ../_static/screenshots/01_settings/02_add_equipment.png
+:alt: Add-Equipment wizard, identity step
+:align: center
+```
+
 ## Related material
 
 - Design spec section 09 (Configuration File) -- the authoritative

docs/source/user_guide/02_browse.md

@@ -0,0 +1,71 @@
+# 3.4 Browse Existing Equipment, Projects, and Runs
+
+## Capability summary
+
+The main window is a three-region file explorer over the
+equipment-first hierarchy rooted at the configured `local_root` (or NAS
+mount). The left pane holds a search box, filter chips, and the
+equipment / project / run tree; the centre pane shows the live file
+list for the selected node; the right pane carries a Metadata / Problems
+tab pair. A header toolbar opens the creation wizards and Settings, a
+breadcrumb tracks the selected node, and a footer status bar reports
+Sync / Validator / LIMS / Staging health. For each discovered run the
+application consults `.exlab-wizard/creation.json` for `run_kind`,
+template, and provenance; test runs are distinguishable from
+experimental runs by a data attribute. The browse view is the
+operator's home base -- every creation wizard and the Settings dialog
+is launched from it. See section 02 §3.4 for the authoritative
+contract.
+
+## Walkthrough
+
+1. **Land on the main window.** After setup the application opens the
+   file explorer. The header toolbar carries *New Project*
+   (`data-testid="toolbar-new-project"`), *New Run*
+   (`data-testid="toolbar-new-run"`), *New Test Run*
+   (`data-testid="toolbar-new-test-run"`), *Add Equipment*
+   (`data-testid="toolbar-add-equipment"`), *Refresh*, and *Settings*.
+2. **Find a node in the left pane.** The left pane holds a search box
+   (`data-testid="main-search"`), the Active / Archived / Test-runs
+   filter chips, and the tree (`data-testid="main-tree"`). Each
+   equipment node holds projects; each project holds experimental runs
+   and test runs.
+3. **Inspect the selection.** Selecting a node fills the centre pane
+   with the folder's live file list and the right pane's Metadata tab
+   (`data-testid="tab-metadata"`) with the node's metadata; the
+   Problems tab (`data-testid="tab-problems"`) lists validation
+   findings for the selection. The breadcrumb
+   (`data-testid="breadcrumb"`) above the panes tracks the path, and
+   each segment is clickable. The right pane can be collapsed with the
+   toggle (`data-testid="toggle-right-pane"`) to widen the file list.
+4. **Act on a row.** Right-click a tree node for context actions --
+   owned-equipment rows offer *Edit equipment* and *Remove* (both
+   deep-link into Settings), run rows offer *Force sync*, *Clear
+   verified*, and *View log*. Right-click a file-list row for *Open in
+   OS* or *Copy path*.
+5. **Watch the footer.** The footer status bar reports the Sync,
+   Validator, LIMS, and Staging segments; the *Clear verified runs*
+   button (`data-testid="footer-clear-verified"`) bulk-clears runs the
+   orchestrator has verified on the NAS.
+
+## Screenshots
+
+```{image} ../_static/screenshots/02_browse/01_initial.png
+:alt: File-explorer main window, no node selected
+:align: center
+```
+
+```{image} ../_static/screenshots/02_browse/02_selected.png
+:alt: File explorer with a project selected -- tree, file list, and metadata pane
+:align: center
+```
+
+## Related material
+
+- {doc}`01_settings` -- the Add-Equipment wizard and the Equipment List
+  editor the tree context menus deep-link into.
+- {doc}`08_problems` -- the Problems tab is mounted in the right pane.
+- Design spec section 03 (Directory Structure) -- the on-disk layout
+  the tree mirrors.
+- Design spec section 11 (Cache Folders) -- the `.exlab-wizard/`
+  subtree the browse view consults for `run_kind` etc.

docs/source/user_guide/01_create_project.md → docs/source/user_guide/03_create_project.md

@@ -33,15 +33,15 @@ The screenshots below are generated by `scripts/generate_screenshots.py`
 against the e2e test surface; each capture matches the corresponding
 NiceGUI page object under `tests/e2e/page_objects/`.
 
-```{image} ../_static/screenshots/01_create_project/01_initial.png
+```{image} ../_static/screenshots/03_create_project/01_initial.png
 :alt: New project wizard, initial render
 :align: center
 ```
 
 ## Related material
 
-- {doc}`05_readme` -- the README form is a sub-step of this wizard.
-- {doc}`06_settings` -- equipment and template directory configuration.
+- {doc}`06_readme` -- the README form is a sub-step of this wizard.
+- {doc}`01_settings` -- equipment and template directory configuration.
 - Design spec section 02 §3.1 (User Interaction) -- authoritative
   capability contract.
 - Design spec section 04 (Backend Architecture) -- creation-session

docs/source/user_guide/02_create_run.md → docs/source/user_guide/04_create_run.md

@@ -24,15 +24,15 @@ sync. See section 02 §3.2 for the authoritative contract.
 
 ## Screenshots
 
-```{image} ../_static/screenshots/02_create_run/01_initial.png
+```{image} ../_static/screenshots/04_create_run/01_initial.png
 :alt: New experimental run wizard, initial render
 :align: center
 ```
 
 ## Related material
 
-- {doc}`03_create_test_run` -- the test-mode counterpart.
-- {doc}`05_readme` -- the README form is a sub-step.
+- {doc}`05_create_test_run` -- the test-mode counterpart.
+- {doc}`06_readme` -- the README form is a sub-step.
 - Design spec section 03 (Directory Structure) -- where the rendered
   run lands on disk.
 - Design spec section 06 (Plugin System) -- plugins execute on the

docs/source/user_guide/03_create_test_run.md → docs/source/user_guide/05_create_test_run.md

@@ -27,14 +27,14 @@ authoritative contract.
 
 ## Screenshots
 
-```{image} ../_static/screenshots/03_create_test_run/01_initial.png
+```{image} ../_static/screenshots/05_create_test_run/01_initial.png
 :alt: New test run wizard, initial render
 :align: center
 ```
 
 ## Related material
 
-- {doc}`02_create_run` -- the experimental counterpart.
+- {doc}`04_create_run` -- the experimental counterpart.
 - Design spec section 03 (Directory Structure) -- the redundant folder
   + leaf-prefix separation that protects against miscategorisation.
 - Design spec section 02 §4 -- the full mode-invariant list.

docs/source/user_guide/05_readme.md → docs/source/user_guide/06_readme.md

@@ -18,8 +18,8 @@ contract.
 ## Walkthrough
 
 The README form is a sub-step of the project wizard
-({doc}`01_create_project`) and the run wizards
-({doc}`02_create_run`, {doc}`03_create_test_run`). It is not a
+({doc}`03_create_project`) and the run wizards
+({doc}`04_create_run`, {doc}`05_create_test_run`). It is not a
 standalone surface; the screenshot below shows the project wizard with
 the README step active.
 
@@ -34,15 +34,15 @@ the README step active.
 
 ## Screenshots
 
-```{image} ../_static/screenshots/05_readme/01_initial.png
+```{image} ../_static/screenshots/06_readme/01_initial.png
 :alt: README step inside the new-project wizard
 :align: center
 ```
 
 ## Related material
 
-- {doc}`01_create_project`, {doc}`02_create_run`,
-  {doc}`03_create_test_run` -- the host wizards.
+- {doc}`03_create_project`, {doc}`04_create_run`,
+  {doc}`05_create_test_run` -- the host wizards.
 - Design spec section 10 (README Generation) -- the merge order, the
   output format, and the rendering contract.
 - Design spec section 11 §11.4 (`readme_fields.json`) -- the cached

docs/source/user_guide/index.md

@@ -1,27 +1,31 @@
 # User Guide
 
 The ExLab-Wizard user guide is organised by **user-visible capability**.
-Each page below corresponds to one of the eight capabilities listed in
-section 02 (User Interaction) of the design specification, and is the
-contract the application is expected to satisfy from the operator's
-point of view. Every page embeds screenshots that are regenerated from
-the live e2e test surface (`tests.e2e._test_app`) by
-`scripts/generate_screenshots.py`; if a particular flow cannot be
-captured in the current environment the page documents the limitation
-inline.
+The eight capability pages each correspond to one of the capabilities
+listed in section 02 (User Interaction) of the design specification,
+and state the contract the application is expected to satisfy from the
+operator's point of view. They are ordered to follow the operator's
+journey -- first-launch setup, then the main window, then the creation
+wizards -- so a page's `NN_` filename prefix is its reading order, not
+the design spec's 3.x capability number. A short {doc}`00_getting_started`
+page precedes them as an orientation aid. Every page embeds screenshots
+that are regenerated from the live e2e test surface
+(`tests.e2e._test_app`) by `scripts/generate_screenshots.py`; if a
+particular flow cannot be captured in the current environment the page
+documents the limitation inline.
 
 ## Capability map
 
-| ID  | Capability                                                                | Surface                                |
-| --- | ------------------------------------------------------------------------- | -------------------------------------- |
-| 3.1 | Create a new project                                                      | New-project wizard (7 steps)           |
-| 3.2 | Create a new experimental run                                             | New-run wizard (6 steps)               |
-| 3.3 | Create a new test run                                                     | New-test-run wizard (6 steps)          |
-| 3.4 | Browse existing equipment, projects, and runs                             | Main window (toolbar + tree + tabs)    |
-| 3.5 | Author a README at creation time                                          | Embedded in 3.1 / 3.2 / 3.3 wizards    |
-| 3.6 | Configure equipment, paths, and integrations                              | Settings dialog (nine sections)        |
-| 3.7 | Monitor orchestrator staging                                              | Staging dock + main-window panel       |
-| 3.8 | Review and resolve naming and validation problems                         | Problems tab + override dialog         |
+| ID  | Capability                                         | Surface                                     |
+| --- | -------------------------------------------------- | ------------------------------------------- |
+| 3.6 | Configure equipment, paths, and integrations       | Settings dialog + Add-Equipment wizard      |
+| 3.4 | Browse existing equipment, projects, and runs      | File-explorer main window (tree/list/meta)  |
+| 3.1 | Create a new project                               | New-project wizard (7 steps)                |
+| 3.2 | Create a new experimental run                      | New-run wizard (6 steps)                    |
+| 3.3 | Create a new test run                              | New-test-run wizard (6 steps)               |
+| 3.5 | Author a README at creation time                   | Embedded in 3.1 / 3.2 / 3.3 wizards         |
+| 3.7 | Monitor orchestrator staging                       | Staging dock + main-window panel            |
+| 3.8 | Review and resolve naming and validation problems  | Problems tab + override dialog              |
 
 The capability set is closed in v1: section 02 of the design spec is the
 authoritative source. Capabilities that require behaviour outside the
@@ -31,14 +35,15 @@ covered by the screenshot pipeline.
 
 ```{toctree}
 :maxdepth: 1
-:caption: Capabilities
-
-01_create_project
-02_create_run
-03_create_test_run
-04_browse
-05_readme
-06_settings
+:caption: User guide
+
+00_getting_started
+01_settings
+02_browse
+03_create_project
+04_create_run
+05_create_test_run
+06_readme
 07_orchestrator
 08_problems
 ```