Improve schema docs and regenerate schemas automatically

.pre-commit-config.yaml

@@ -31,6 +31,13 @@ repos:
         entry: uv sync
         files: ^(uv\.lock|pyproject\.toml)$
 
+      - id: generate-schema
+        name: regenerate JSON schemas from models
+        pass_filenames: false
+        language: system
+        entry: deploy-tools schema src/deploy_tools/models/schemas
+        files: ^src/deploy_tools/models/.*\.py$
+
   - repo: https://github.com/DavidAnson/markdownlint-cli2
     rev: v0.23.1
     hooks:

docs/how-to.md

@@ -8,5 +8,6 @@ Practical step-by-step guides for the more experienced user.
 how-to/ci-pipeline
 how-to/run-container
 how-to/vscode-tasks
+how-to/regenerate-schemas
 how-to/contribute
 ```

docs/how-to/regenerate-schemas.md

@@ -0,0 +1,23 @@
+# Regenerate the JSON schemas
+
+The JSON schema files under `src/deploy_tools/models/schemas` are generated from the
+Pydantic models in `src/deploy_tools/models` by
+`deploy_tools.models.schema.generate_schema`. They are checked in and do not update
+automatically, so they must be regenerated and committed after changing any model.
+
+A `generate-schema` pre-commit hook does this for you: when you commit a change to
+any file under `src/deploy_tools/models`, it regenerates the schemas. If they changed,
+pre-commit reports the modified files and aborts the commit, so you just `git add` the
+schemas and commit again.
+
+If you bypass the hooks (for example with `git commit --no-verify`), regenerate the
+schemas manually. The simplest way is the **Generate Schema** VSCode task (see
+[the VSCode tasks guide](vscode-tasks.md)), which writes to the correct location.
+Equivalently, run the CLI, pointing it at that folder:
+
+```bash
+deploy-tools schema src/deploy_tools/models/schemas
+```
+
+Either way, commit the regenerated files alongside your model change. CI fails if they
+are out of date.

docs/schemas.md

@@ -28,6 +28,14 @@ This requires an editor with a YAML language server — e.g. VS Code with the
 or any [LSP](https://microsoft.github.io/language-server-protocol/)-capable editor
 running [`yaml-language-server`](https://github.com/redhat-developer/yaml-language-server).
 
+```{note}
+The bundled `demo_configuration` instead points at the locally generated schemas via an
+absolute workspace path (e.g.
+`/workspaces/deploy-tools/src/deploy_tools/models/schemas/release.json`), so it validates
+against uncommitted schema changes during development. This dev-container-only path is not
+suitable for production configuration.
+```
+
 The other two generated schemas cover files you don't normally author by hand:
 `deployment.json` (the `deployment.yaml` snapshot written by `sync`) and `module.json`
 (the `Module` that a `Release` wraps).
@@ -41,11 +49,8 @@ schemas/deployment-settings
 schemas/release
 ```
 
-## How the schemas are generated
+## Regenerating the schemas
 
-`deploy_tools.models.schema.generate_schema` writes these files from the corresponding
-Pydantic models. To regenerate them manually:
-
-```bash
-deploy-tools schema path/to/output/folder
-```
+These files are checked in and do not update automatically when the models change.
+Contributors who change the models must regenerate them — see
+[regenerate the JSON schemas](how-to/regenerate-schemas.md).