Polish template initialization and reproducible verification

.devcontainer/Dockerfile

@@ -1,24 +1,17 @@
 FROM python:3.11-slim
 
-# Basic OS deps
+ARG UV_VERSION=0.10.0
+
 RUN apt-get update \
-    && apt-get install -y --no-install-recommends \
-         git \
-         make \
-         build-essential \
+    && apt-get install -y --no-install-recommends git make build-essential \
+    && python -m pip install --no-cache-dir "uv==${UV_VERSION}" \
     && rm -rf /var/lib/apt/lists/*
 
-# Upgrade pip tooling
-RUN python -m pip install --upgrade pip setuptools wheel
-
-# Create non-root user with fixed home directory
 RUN groupadd -r app && useradd -r -g app -d /home/app -m app
 
-# Set environment for the user
-ENV HOME=/home/app
+ENV HOME=/home/app \
+    PYTHONNOUSERSITE=1 \
+    UV_LINK_MODE=copy
 
-# Devcontainers typically mount the repo; keep workdir generic
 WORKDIR /work
-
-# Switch to non-root user
 USER app

.devcontainer/devcontainer.json

@@ -4,12 +4,12 @@
     "dockerfile": "Dockerfile",
     "context": ".."
   },
+  "postCreateCommand": "if [ -f uv.lock ]; then uv sync --group dev --group docs --frozen; else uv sync --group dev --group docs; fi",
   "customizations": {
     "vscode": {
       "extensions": [
         "ms-python.python",
         "ms-python.vscode-pylance",
-        "ms-python.black-formatter",
         "charliermarsh.ruff",
         "ms-toolsai.jupyter"
       ]

.dockerignore

@@ -1,20 +1,10 @@
-# Python bytecode / caches
+.git/
+.venv/
 __pycache__/
 *.py[cod]
-
-# Test caches
 .pytest_cache/
-
-# Packaging artifacts
+.ruff_cache/
 *.egg-info/
 build/
 dist/
-
-# Docs build output
 docs/build/
-
-# VCS
-.git/
-
-# Local automation state
-.sisyphus/

.github/workflows/ci.yml

@@ -2,25 +2,16 @@ name: CI
 
 on:
   push:
-    branches: [ main, master, develop ]
+    branches: [main]
   pull_request:
-    branches: [ main, master, develop ]
+    branches: [main]
 
 jobs:
-  test:
+  verify:
     runs-on: ubuntu-latest
-
     steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Verify (Docker build + pytest + app/main.py)
-        run: make docker-verify
-
-      - name: Check for workspace changes
-        run: |
-          if [ -n "$(git status --porcelain)" ]; then
-            echo "Error: Workspace modified by verification. Run 'make docker-verify' locally and commit the changes."
-            git status --porcelain
-            exit 1
-          fi
+      - uses: actions/checkout@v4
+      - name: Canonical verification
+        run: make verify
+      - name: Assert verification did not mutate checkout
+        run: test -z "$(git status --porcelain)"

.github/workflows/docs.yml

@@ -1,62 +1,50 @@
-name: Deploy Docs to GitHub Pages
+name: Docs
 
 on:
   push:
-    branches:
-      - main
-      - master
+    branches: [main]
   workflow_dispatch:
 
 permissions:
   contents: read
   pages: write
   id-token: write
 
-# Allow only one concurrent deployment
 concurrency:
-  group: "pages"
+  group: pages
   cancel-in-progress: false
 
-env:
-  PYTHON_VERSION: '3.11'
-  DOCS_DIR: docs/build/html
-
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
-          python-version: ${{ env.PYTHON_VERSION }}
-          cache: 'pip'
-
-      - name: Install dependencies
+          python-version: "3.11"
+      - name: Install uv
+        run: python -m pip install "uv==0.10.0"
+      - name: Build docs
         run: |
-          pip install -U pip
-          pip install '.[docs]'
-
-      - name: Build documentation
-        run: make -C docs apidoc html
-
-      - name: Setup Pages
-        uses: actions/configure-pages@v5
-
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+          if [ -f uv.lock ]; then
+            uv sync --group docs --frozen
+          else
+            echo "WARNING: uv.lock missing; resolving dependencies"
+            uv sync --group docs
+          fi
+          uv run --no-sync sphinx-build -W -b html docs/source docs/build/html
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
         with:
-          path: ${{ env.DOCS_DIR }}
+          path: docs/build/html
 
   deploy:
+    needs: build
+    runs-on: ubuntu-latest
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
     steps:
-      - name: Deploy to GitHub Pages
+      - name: Deploy
         id: deployment
         uses: actions/deploy-pages@v4