Add full process docs

.vscode/launch.json

@@ -5,50 +5,50 @@
     "version": "0.2.0",
     "configurations": [
         {
-            "name": "Debug Unit Test",
+            "name": "Debug Validation",
             "type": "debugpy",
             "request": "launch",
             "justMyCode": false,
-            "program": "${file}",
-            "purpose": [
-                "debug-test"
-            ],
+            "program": "/venv/bin/deploy-tools",
+            "args": "validate ${input:allow-all} ${input:from-scratch} ${input:test-build} ${input:deploy-folder} ${input:config-folder}",
             "console": "integratedTerminal",
         },
         {
-            "name": "Debug Schema Generation",
+            "name": "Debug Sync",
             "type": "debugpy",
             "request": "launch",
             "justMyCode": false,
             "program": "/venv/bin/deploy-tools",
-            "args": "schema ${input:schema-folder}",
+            "args": "sync ${input:allow-all} ${input:from-scratch} ${input:deploy-folder} ${input:config-folder}",
             "console": "integratedTerminal",
         },
         {
-            "name": "Debug Validation",
+            "name": "Debug Compare",
             "type": "debugpy",
             "request": "launch",
             "justMyCode": false,
             "program": "/venv/bin/deploy-tools",
-            "args": "validate ${input:allow-all} ${input:from-scratch} ${input:test-build} ${input:deploy-folder} ${input:config-folder}",
+            "args": "compare ${input:compare-mode} ${input:deploy-folder}",
             "console": "integratedTerminal",
         },
         {
-            "name": "Debug Compare",
+            "name": "Debug Schema Generation",
             "type": "debugpy",
             "request": "launch",
             "justMyCode": false,
             "program": "/venv/bin/deploy-tools",
-            "args": "compare ${input:compare-mode} ${input:deploy-folder}",
+            "args": "schema ${input:schema-folder}",
             "console": "integratedTerminal",
         },
         {
-            "name": "Debug Sync",
+            "name": "Debug Unit Test",
             "type": "debugpy",
             "request": "launch",
             "justMyCode": false,
-            "program": "/venv/bin/deploy-tools",
-            "args": "sync ${input:allow-all} ${input:from-scratch} ${input:deploy-folder} ${input:config-folder}",
+            "program": "${file}",
+            "purpose": [
+                "debug-test"
+            ],
             "console": "integratedTerminal",
         },
     ],

.vscode/tasks.json

@@ -4,18 +4,15 @@
     "version": "2.0.0",
     "tasks": [
         {
+            "label": "Clean deployment",
             "type": "shell",
-            "label": "Tests, lint and docs",
-            "command": "tox -p",
-            "options": {
-                "cwd": "${workspaceRoot}"
-            },
-            "problemMatcher": [],
+            "command": "rm -rf ${workspaceFolder}/demo-output/ && mkdir ${workspaceFolder}/demo-output/",
+            "problemMatcher": []
         },
         {
-            "label": "Generate schema",
+            "label": "Validate deployment",
             "type": "shell",
-            "command": "deploy-tools schema ${input:schema-folder}",
+            "command": "deploy-tools validate ${input:allow-all} ${input:from-scratch} ${input:test-build} ${input:deploy-folder} ${input:config-folder}",
             "problemMatcher": []
         },
         {
@@ -25,27 +22,30 @@
             "problemMatcher": []
         },
         {
-            "label": "Clean deployment",
+            "label": "Compare deployment to snapshot",
             "type": "shell",
-            "command": "rm -rf ${workspaceFolder}/demo-output/ && mkdir ${workspaceFolder}/demo-output/",
+            "command": "deploy-tools compare ${input:compare-mode} ${input:deploy-folder}",
             "problemMatcher": []
         },
         {
-            "label": "Validate deployment",
+            "label": "Generate schema",
             "type": "shell",
-            "command": "deploy-tools validate ${input:allow-all} ${input:from-scratch} ${input:test-build} ${input:deploy-folder} ${input:config-folder}",
+            "command": "deploy-tools schema ${input:schema-folder}",
             "problemMatcher": []
         },
         {
-            "label": "Compare deployment to snapshot",
             "type": "shell",
-            "command": "deploy-tools compare ${input:compare-mode} ${input:deploy-folder}",
-            "problemMatcher": []
+            "label": "Recreate tests sample output from golden-master configuration",
+            "command": "tests/generate_samples.sh",
+            "options": {
+                "cwd": "${workspaceRoot}"
+            },
+            "problemMatcher": [],
         },
         {
             "type": "shell",
-            "label": "Recreate tests sample output from demo_configuration",
-            "command": "tests/generate_samples.sh",
+            "label": "Tests, lint and docs",
+            "command": "tox -p",
             "options": {
                 "cwd": "${workspaceRoot}"
             },

docs/how-to.md

@@ -4,7 +4,9 @@ Practical step-by-step guides for the more experienced user.
 
 ```{toctree}
 :maxdepth: 1
-:glob:
 
-how-to/*
+how-to/ci-pipeline
+how-to/run-container
+how-to/vscode-tasks
+how-to/contribute
 ```

docs/how-to/ci-pipeline.md

@@ -0,0 +1,58 @@
+# Drive deploy-tools from CI
+
+In normal use, nobody should run `sync`, `validate` or `compare` by hand. Those commands
+touch a shared deployment area, so they belong to a CI pipeline in the configuration
+repository, gated by change review. End users only edit configuration and open a change;
+merging it deploys.
+
+This guide describes what that pipeline must do. It is deliberately independent of any
+particular CI system — translate the responsibilities below into your own.
+
+## On a proposed change
+
+When someone opens a change (before it is merged), run, without altering the area:
+
+- `deploy-tools compare <area>` — confirm the area still matches its last snapshot, so
+  the change is being checked against a known-healthy baseline.
+- `deploy-tools validate <area> <config>` — confirm the new configuration is valid and its
+  [lifecycle transitions](../explanations/deprecation-lifecycle.md) are permitted. Add
+  `--test-build` to build every changed Module in a temporary directory, catching build
+  failures before merge.
+
+This gives reviewers a green light that the change is deployable without changing anything
+on the filesystem.
+
+## On acceptance
+
+When the change is merged to the main branch, deploy it:
+
+- `deploy-tools compare <area>` — re-check the area is healthy immediately before the sync.
+- `deploy-tools sync <area> <config>` — validate again, build, and move the results into
+  place.
+
+## Run one at a time
+
+`deploy-tools` has no locking of its own. The pipeline must ensure only one run
+touches the area at a time — two concurrent `sync`s, or a `sync` racing a `compare`,
+can corrupt the area or report false drift. Serialise the relevant jobs (and, if
+possible, restrict them to a single runner).
+
+## Manual operations
+
+Some tasks fall outside the automatic flows and are best run from a manually-triggered
+pipeline, exposing the relevant options as parameters:
+
+- **The first deployment.** A brand-new area has no snapshot to compare against, so it is
+  run manually rather than triggered by a merge. Use `--from-scratch`, which assumes the
+  area is empty: `compare --from-scratch` to confirm it, then `sync --from-scratch` to
+  deploy. This
+  path is walked through in [your first deployment](../tutorials/your-first-deployment.md).
+- **Comparing against an earlier snapshot.** `compare --use-ref <ref>` compares the area
+  against the snapshot from an earlier commit (e.g. `HEAD~1`), to check how it matches the
+  configuration from before the last `sync`.
+- **Forcing blocked transitions.** `--allow-all` (on `validate`/`sync`) permits lifecycle
+  transitions that are otherwise rejected, such as removing a live version. The area must
+  still be healthy.
+
+See [snapshots and the compare safety net](../explanations/snapshots-and-compare.md) for
+how these fit into recovery.

docs/how-to/vscode-tasks.md

@@ -0,0 +1,37 @@
+# Run the VSCode tasks and debug configurations
+
+The repository ships with [VSCode tasks](https://code.visualstudio.com/docs/editor/tasks)
+and [debug launch configurations](https://code.visualstudio.com/docs/editor/debugging)
+so that contributors can exercise the `deploy-tools` CLI without typing out full
+commands. They run the same subcommands documented in the [CLI reference](../cli.md),
+pre-filled to operate on the bundled `demo_configuration`.
+
+## The demo configuration
+
+`src/deploy_tools/demo_configuration/` holds a small, self-contained set of module
+definitions used as sample input. The tasks default to reading this configuration and
+writing the generated deployment to `demo-output/`, giving you a realistic deployment to
+inspect without needing a real configuration repository.
+
+## Running a task
+
+Open the command palette and choose **Tasks: Run Task**, then pick one of:
+
+- **Clean deployment** — empty and recreate `demo-output/`.
+- **Validate deployment** — preview the changes a sync would make (read-only).
+- **Sync modules** — build and deploy the demo configuration into `demo-output/`.
+- **Compare deployment to snapshot** — diff the deployment against a previous snapshot.
+- **Generate schema** — regenerate the JSON schemas under `models/schemas/`.
+- **Recreate tests sample output from golden-master configuration** — regenerate the
+  golden-master test samples via `tests/generate_samples.sh`.
+- **Tests, lint and docs** — run `tox -p` (type checking, tests, and the docs build).
+
+Tasks that take flags (such as `--allow-all`, `--from-scratch`, or the compare mode)
+prompt for those options when run, defaulting to the most common choice.
+
+## Debugging a command
+
+The **Run and Debug** panel offers equivalent launch configurations (Debug Validation,
+Debug Sync, Debug Compare, Debug Schema Generation, and Debug Unit Test). These
+invoke the same commands under `debugpy` so you can set breakpoints and step through the
+CLI while it processes the demo configuration.

docs/tutorials.md

@@ -4,7 +4,7 @@ Tutorials for installation and typical usage. New users start here.
 
 ```{toctree}
 :maxdepth: 1
-:glob:
 
-tutorials/*
+tutorials/installation
+tutorials/your-first-deployment
 ```