Document and verify tutorial commands across backends and shells

.github/workflows/live-shutdown-windows.yml

@@ -1,4 +1,4 @@
-name: Windows live-session shutdown
+name: Windows CLI and live-session checks
 
 on:
   pull_request:
@@ -7,10 +7,14 @@ on:
       - CMakeLists.txt
       - cpp/**
       - python/**
+      - docs/tutorials/**
+      - docs/development/tutorial-command-validation.md
+      - environments/**/README.md
+      - viewer/README.md
       - pyproject.toml
       - uv.lock
   push:
-    branches: [master, marpaia/17]
+    branches: [master, marpaia/17, marpaia/24]
   workflow_dispatch:
 
 permissions:
@@ -31,6 +35,7 @@ jobs:
       CMAKE_BUILD_PARALLEL_LEVEL: "2"
       # Exercise the host reference engine without requiring a GPU toolkit.
       CMAKE_ARGS: -DCM_ENABLE_METAL=OFF -DCM_ENABLE_CUDA=OFF -DCM_BUILD_TESTS=OFF
+      MICROSIMULATOR_COMMAND_REPORT: build/shutdown-evidence/tutorial-commands
     steps:
       - name: Check out source
         uses: actions/checkout@v6
@@ -60,6 +65,11 @@ jobs:
           python/tests/test_viewer_server.py python/tests/test_viewer_shutdown.py
           -v --tb=short --junitxml=build/shutdown-evidence/tests.xml
 
+      - name: Execute the documented PowerShell CLI commands
+        run: >-
+          uv run --no-sync python -m pytest python/tests/test_tutorial_commands.py
+          -v --tb=short --junitxml=build/shutdown-evidence/tutorial-commands.xml
+
       - name: Upload shutdown evidence
         if: ${{ always() }}
         uses: actions/upload-artifact@v7

docs/README.md

@@ -8,6 +8,7 @@ MicroSimulator models microbial populations in microfluidic environments, connec
 | --- | --- |
 | Understand how devices, flow, and cells fit together | [Microfluidics modeling guide](microfluidics.md) |
 | Run a first simulation | [Getting started](tutorials/getting-started.md) |
+| Select a backend or use PowerShell | [Copyable tutorial commands](tutorials/commands.md) |
 | Build a trap or channel with growth and washout | [Microfluidic devices](tutorials/microfluidics.md) |
 | Choose a flow solver and assess its numerical behavior | [Flow models](microfluidics.md#choosing-a-flow-model) and [flow benchmarks](tutorials/flow-solvers.md#numerical-evidence) |
 | Measure nutrient penetration and growth | [Controlled nutrient study](tutorials/nutrient-validation.md) |

docs/development/tutorial-command-validation.md

@@ -0,0 +1,34 @@
+# Tutorial command verification
+
+The [command guide](../tutorials/commands.md) separates shell argument handling, backend availability, and scientific backend validation. The executable examples are read directly from its marked Markdown blocks by [`test_tutorial_commands.py`](../../python/tests/test_tutorial_commands.py).
+
+## Coverage and limits
+
+The command tests exercise human-readable and JSON device discovery; the identical 100-step trap command on every available backend; explicit unavailable-backend failures; JSON string arguments and line continuation; repository, model, checkpoint, and output paths containing spaces; restored seed/parameters/source digest; and uninterrupted versus resumed controller/native state. They launch the documented trap, growth, and resumed live sessions in sequence on port 8765, save a checkpoint, send authenticated Stop, observe Stopped, and verify each process returns successfully before the next launch. A cleanup regression also verifies that a failed test terminates its own subprocess tree and drains inherited pipes. The CLI tests supply minimal static assets and do not claim browser rendering coverage.
+
+PowerShell tests set `$PSNativeCommandArgumentPassing = 'Standard'` exactly as documented. Windows uses `pwsh` 7.3+; Windows PowerShell 5.1 and `cmd.exe` are not covered. POSIX examples are executed in `sh`, Bash, and Zsh when those shells are installed. A missing shell is explicitly skipped. Reports include the exact script text, exit status, stdout/stderr, platform, Python version, shell version, and enumerated devices.
+
+The [Windows CLI and live-session workflow](../../.github/workflows/live-shutdown-windows.yml) builds a native CPU extension on `windows-2025`, executes these command tests and the existing live-session tests, and uploads reports. Its GPU backends are deliberately disabled. The shutdown tests additionally generate an actual Windows `CTRL_C_EVENT` in an isolated console; they do not simulate a human keyboard press in every terminal application. The viewer guide retains a [manual terminal procedure](../../viewer/README.md#stop-one-model-and-start-another).
+
+## Execution record
+
+The local command run on 2026-09-24 passed all ten tests with Python 3.12.8, Bash 3.2.57, Zsh 5.9, and PowerShell 7.6.4. Windows verification also passed on 2026-09-24 at commit `215e87dbf58c9964aef5a7821cdb3cb494c91490`: [workflow run 36068841367](https://github.com/DRAGGON-Lab/MicroSimulator/actions/runs/36068841367) recorded four command/cleanup tests passing in 17.934 seconds and all 28 live-session shutdown tests passing. Reports are retained as CI artifacts.
+
+| Platform and shell | Backend execution | Command coverage |
+| --- | --- | --- |
+| macOS, POSIX `sh`, Bash, Zsh | Native CPU and Apple M4 Max Metal | Passed: discovery, 100-step CPU/Metal trap, JSON/space paths, headless CPU resume, live CPU checkpoint/Stop/restart |
+| macOS, PowerShell 7.6.4 with Standard arguments | Native CPU and Apple M4 Max Metal | Passed: same commands, PowerShell backtick continuation and string quoting |
+| Windows Server 2025 build 26100, PowerShell 7.6.6, Python 3.12.10 | Native CPU | Passed: discovery, 100-step trap, PowerShell JSON/space paths, resume, three live Stop/restarts, cleanup regression; Metal/CUDA unavailable as expected |
+| NVIDIA CUDA hardware | Not available in the command-verification campaign | Unavailable-backend error checked; no CUDA runtime or numerical claim |
+
+The test runner reports actual Metal availability for each macOS run. This run executed Metal headless trap commands; its JSON scenario, resume, and live-session examples selected CPU. A skipped/unavailable Metal result does not count as GPU execution. Backend support still requires the independent [native and application conformance gates](validation.md), even when a tutorial smoke command succeeds.
+
+## Reproduce
+
+After installing the development environment, run:
+
+```console
+uv run --no-sync python -m pytest python/tests/test_tutorial_commands.py -v
+```
+
+Set `MICROSIMULATOR_COMMAND_REPORT` to a new output directory to retain per-shell JSON reports; the Windows workflow supplies this environment variable. Run from an environment with loopback networking enabled and port 8765 free. The tests use their own temporary working directories and never overwrite tutorial outputs in the source checkout.

docs/tutorials/README.md

@@ -2,6 +2,8 @@
 
 These tutorials explore cells in microfluidic devices through runnable models: geometry and flow supply the environment, while growth, mechanics, and circuits determine how populations respond. The [modeling guide](../microfluidics.md) introduces the full workflow and its assumptions. Each example can also be used independently.
 
+For backend selection, PowerShell syntax, quoted JSON parameters, and paths with spaces, see [tutorial commands by backend and shell](commands.md#choose-a-shell). Multiline commands on this page use POSIX shell backslashes; the guide provides the PowerShell equivalents and [explicit CPU, Metal, and CUDA trap launches](commands.md#run-the-same-trap-on-cpu-metal-or-cuda).
+
 ## Start here
 
 Follow [getting started](getting-started.md) to run a nutrient-fed trap, configure the viewer, and resume a checkpoint. Then choose a path below.

docs/tutorials/analysis.md

@@ -2,6 +2,8 @@
 
 MicroSimulator separates simulation output into three artifacts:
 
+For backend selection, PowerShell syntax, quoted JSON parameters, and paths with spaces, see [tutorial commands by backend and shell](commands.md#choose-a-shell). Multiline commands on this page use POSIX shell backslashes; the guide provides the PowerShell equivalents and [explicit CPU, Metal, and CUDA trap launches](commands.md#run-the-same-trap-on-cpu-metal-or-cuda).
+
 - a checkpoint is an exact, integrity-checked restart artifact;
 - a scene is an immutable presentation snapshot; and
 - an analysis dataset is an immutable Parquet/Zarr projection with schemas and provenance.
@@ -13,6 +15,7 @@ Use checkpoints for resuming, scenes for viewing, and datasets for statistics.
 ```console
 uv run microsimulator run \
   --model examples/tutorials/biophysics.py \
+  --backend cpu \
   --parameter scenario='"basics"' \
   --seed 42 \
   --steps 200 \

docs/tutorials/biophysics-and-growth.md

@@ -4,13 +4,16 @@ This tutorial introduces cell geometry, growth, division, lineage, cell types, m
 
 The `basics`, `two_types`, and `competition` scenarios add XY-only division jitter but retain unrestricted 3D mechanics. `short_cells` adds XYZ jitter. `box` also adds XYZ jitter and has a floor and four lateral walls, with no ceiling. None guarantees a planar colony; see [division jitter and out-of-plane motion](planarity.md) for the full contract and reproducible diagnostics.
 
+For backend selection, PowerShell syntax, quoted JSON parameters, and paths with spaces, see [tutorial commands by backend and shell](commands.md#choose-a-shell). Multiline commands on this page use POSIX shell backslashes; the guide provides the PowerShell equivalents and [explicit CPU, Metal, and CUDA trap launches](commands.md#run-the-same-trap-on-cpu-metal-or-cuda).
+
 ## 1. A founder that grows and divides
 
 Run the basic model:
 
 ```console
 uv run microsimulator view \
   --model examples/tutorials/biophysics.py \
+  --backend cpu \
   --parameter scenario='"basics"' \
   --seed 42 \
   --dt 0.05 \
@@ -51,6 +54,7 @@ During new tutorial construction, each founder target is sampled exactly once fr
 ```console
 uv run microsimulator view \
   --model examples/tutorials/biophysics.py \
+  --backend cpu \
   --parameter scenario='"two_types"' \
   --seed 42 \
   --dt 0.02 \
@@ -64,6 +68,7 @@ The model places type 0 at `x = -10` and type 1 at `x = 10`. Both use the same g
 ```console
 uv run microsimulator view \
   --model examples/tutorials/biophysics.py \
+  --backend cpu \
   --parameter scenario='"short_cells"' \
   --seed 42 \
   --dt 0.01 \
@@ -77,6 +82,7 @@ This scenario lowers the post-founder division length to produce short spherocyl
 ```console
 uv run microsimulator view \
   --model examples/tutorials/biophysics.py \
+  --backend cpu \
   --parameter scenario='"competition"' \
   --seed 7 \
   --dt 0.01 \
@@ -100,6 +106,7 @@ Use `Growth rate` coloring to see the active zone and `Cell type` coloring to se
 ```console
 uv run microsimulator view \
   --model examples/tutorials/biophysics.py \
+  --backend cpu \
   --parameter scenario='"box"' \
   --seed 42 \
   --dt 0.01 \