docs: migrate to Sphinx + ReadTheDocs

.github/workflows/docs-sphinx.yml

@@ -0,0 +1,29 @@
+name: Docs (Sphinx)
+
+on:
+  push:
+    branches: [dev]
+  pull_request:
+    branches: [dev]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+
+      - name: Install docs dependencies
+        run: uv sync --extra docs --frozen
+
+      - name: Build Sphinx HTML
+        run: uv run --no-sync --frozen sphinx-build -b html docs docs/_build/html -W

.github/workflows/publish.yml

@@ -3,14 +3,19 @@ name: Publish to PyPI
 on:
   release:
     types: [published]
-  workflow_dispatch: null
+  workflow_dispatch: {}
+
 
 jobs:
   publish:
     runs-on: ubuntu-latest
     permissions:
       id-token: write
       contents: read
+      packages: write
+
+    # Only publish on valid version tags
+    if: startsWith(github.ref, 'refs/tags/v') && contains(github.ref, '.')
 
     environment:
       name: pypi
@@ -42,5 +47,10 @@ jobs:
       - name: Build
         run: uv build
 
+      - name: Check build artifacts
+        run: uv run --no-sync --frozen twine check dist/*
+
       - name: Publish
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

.readthedocs.yaml

@@ -0,0 +1,17 @@
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  jobs:
+    create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    install:
+      - uv sync --extra docs --frozen
+    build:
+      html:
+        - uv run sphinx-build -b html docs $READTHEDOCS_OUTPUT/html

CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.1.0b1 - 2026-04-08
+
+### Added
+- Config-relative path resolution for `PatchFile`, `SeedFile`, `NetworkFile`, and `OutputDir`.
+- Built-in YAML model templates for `sir`, `seir`, and `sirs` under package templates.
+- `list-models` now reports both Python reference models and YAML templates.
+
+### Changed
+- Validation now checks transition source/target compartments explicitly.
+- Validation now checks transition expression identifiers against `compartments ∪ Parameters`.
+- Compartment source-of-truth reconciled: when `compartments` is provided in config, it must match `SeedFile` columns.
+- Package metadata updated to `Development Status :: 4 - Beta`.
+- Runtime dependencies now include conservative minimum version floors.
+
+### Removed
+- Removed unused `patchsim.utils.loader` module and its documentation reference.

README.md

@@ -101,14 +101,29 @@ uv run patchsim --version
 # Initialize a new self-contained project
 uv run patchsim init my-project
 
+# Initialize with a starter template
+uv run patchsim init my-project --template seir
+
 # Validate config without running
 uv run patchsim validate -c my-project/config.yaml
 
+# Print the JSON Schema for configs
+uv run patchsim validate --schema
+
+# Emit machine-readable JSON output
+uv run patchsim validate -c my-project/config.yaml --json
+
 # Run simulation
 uv run patchsim run -c my-project/config.yaml
 
-# List built-in models
+# Run and emit machine-readable JSON output
+uv run patchsim run -c my-project/config.yaml --json
+
+# List built-in model references and YAML templates
 uv run patchsim list-models
+
+# List models as JSON
+uv run patchsim list-models --json
 ```
 
 ### Python SDK