ENH: Prepare PhysioMotion4D beta docs and release infrastructure

.claude/settings.json → .agents/settings.json

@@ -1,8 +1,8 @@
 {
   "permissions": {
     "allow": [
-      "Edit(.claude/**)",
-      "Write(.claude/**)",
+      "Edit(.agents/**)",
+      "Write(.agents/**)",
       "Write(pr_*.md)"
     ],
     "deny": []

.github/workflows/README.md

@@ -24,14 +24,14 @@ Runs on every push and pull request to main branches. Includes:
   - **DISABLED BY DEFAULT** - Only runs when:
     - Manually triggered via workflow_dispatch, OR
     - PR has the `run-gpu-tests` label
-  - Requires self-hosted runner with `[self-hosted, linux, gpu]` labels
+  - Requires self-hosted runner with `[self-hosted, Windows, X64, gpu]` labels
   - Uses PyTorch with CUDA 13.0 support
   - Timeout: 30 minutes
 
 - **code-quality**: Static code analysis
   - Ruff formatting and linting checks
-  - mypy type checking (continue-on-error: true)
-  - Ruff checks will fail the build if code style issues are found
+  - mypy type checking
+  - Ruff and mypy checks fail the build if issues are found
 
 ### `test-slow.yml` - Long-Running Tests
 
@@ -61,6 +61,12 @@ Two-job workflow for building and deploying Sphinx documentation:
 
 This separation ensures PRs can build and validate docs without triggering environment protection rules.
 
+### `release.yml` - Build and Publish Distributions
+
+Builds the wheel and source distribution, validates them with Twine, and
+publishes to TestPyPI or PyPI using trusted publishing. It runs manually via
+`workflow_dispatch` or automatically when a GitHub release is published.
+
 ## Caching Strategy
 
 The workflows use multiple caching layers to speed up builds:
@@ -86,9 +92,9 @@ To run GPU tests, you must either:
 ### Self-Hosted Runners
 
 GPU tests require self-hosted runners with:
-- Linux OS
+- Windows OS
 - NVIDIA GPU with CUDA 13.0 support
-- Runner labels: `[self-hosted, linux, gpu]`
+- Runner labels: `[self-hosted, Windows, X64, gpu]`
 
 **Why are GPU tests disabled by default?**
 - GitHub Actions jobs wait indefinitely for a self-hosted runner if none are available
@@ -98,34 +104,28 @@ GPU tests require self-hosted runners with:
 ### Setting Up Self-Hosted GPU Runners
 
 1. **Install GitHub Actions Runner**:
-   ```bash
+   ```powershell
    # Download and configure runner from GitHub repository Settings > Actions > Runners
    ```
 
 2. **Install NVIDIA Drivers and CUDA**:
-   ```bash
-   # Install NVIDIA drivers
-   sudo apt-get install nvidia-driver-535
-
-   # Install CUDA toolkit 13.0
-   # CUDA 13.0 requires Ubuntu 22.04 LTS or later. These cuda-keyring_1.1-1_all.deb
-   # and cuda-toolkit-13 commands fail on Ubuntu 20.04 runners.
-   wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
-   sudo dpkg -i cuda-keyring_1.1-1_all.deb
-   sudo apt-get update
-   sudo apt-get install cuda-toolkit-13
+   ```powershell
+   # Install or update the NVIDIA display driver and CUDA Toolkit 13.0
+   # using NVIDIA's Windows installers.
+   nvidia-smi
+   nvcc --version
    ```
 
-   Self-hosted GPU runners should be upgraded to Ubuntu 22.04 LTS or later
-   before installing CUDA 13.0.
+   Verify both commands are available in the runner service environment before
+   starting jobs.
 
 3. **Configure Runner Labels**:
-   - Add labels: `self-hosted`, `linux`, `gpu`
+   - Add labels: `self-hosted`, `Windows`, `X64`, `gpu`
    - Verify GPU is accessible: `nvidia-smi`
 
 4. **Start the Runner**:
-   ```bash
-   ./run.sh
+   ```powershell
+   .\run.cmd
    ```
 
 ### How to Run GPU Tests
@@ -241,7 +241,7 @@ Coverage reports are:
 GPU tests are disabled by default. If you want to run them:
 1. **Check if GPU tests should run**: They only run on manual trigger or with `run-gpu-tests` label
 2. **Verify self-hosted runner is online**: Settings > Actions > Runners
-3. **Check runner labels**: Runner must have `self-hosted`, `linux`, and `gpu` labels
+3. **Check runner labels**: Runner must have `self-hosted`, `Windows`, `X64`, and `gpu` labels
 4. **Verify GPU accessibility**: Run `nvidia-smi` on the runner machine
 5. **Check workflow logs**: Look for "Waiting for a runner" or "runner assignment" messages
 

.github/workflows/ci.yml

@@ -370,7 +370,7 @@ jobs:
     - name: Type check with mypy
       run: |
         mypy src/
-      continue-on-error: true
+      continue-on-error: false
 
 # ==============================================================================
 # Notes on Excluded Tests

.github/workflows/docs.yml

@@ -19,7 +19,7 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
 
     - name: Free up disk space
       run: |
@@ -34,7 +34,7 @@ jobs:
         df -h
 
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.11'
 
@@ -77,7 +77,7 @@ jobs:
       run: touch docs/_build/html/.nojekyll
 
     - name: Upload documentation artifacts
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v6
       with:
         name: documentation
         path: docs/_build/html/
@@ -97,7 +97,7 @@ jobs:
 
     steps:
     - name: Download documentation artifacts
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v6
       with:
         name: documentation
         path: ./docs-html
@@ -120,14 +120,14 @@ jobs:
         GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
     - name: Setup Pages
-      uses: actions/configure-pages@v4
+      uses: actions/configure-pages@v5
 
     - name: Upload artifact for Pages
-      uses: actions/upload-pages-artifact@v3
+      uses: actions/upload-pages-artifact@v5
       with:
         path: ./docs-html
 
     - name: Deploy to GitHub Pages
       id: deployment
-      uses: actions/deploy-pages@v4
+      uses: actions/deploy-pages@v5
 

.github/workflows/release.yml

@@ -0,0 +1,90 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      repository:
+        description: Publish target
+        required: true
+        default: testpypi
+        type: choice
+        options:
+          - testpypi
+          - pypi
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build wheel and sdist
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          lfs: true
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: '3.10'
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip build twine
+
+      - name: Build distributions
+        run: |
+          python -m build
+          python -m twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' && inputs.repository == 'testpypi'
+    environment: testpypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.repository == 'pypi')
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b

AGENTS.md

@@ -8,11 +8,14 @@ Breaking changes are acceptable. Backward compatibility is not a goal.
 
 ## Developer tool prerequisites
 
-Two non-Python tools are required for contributor workflows:
+Non-Python tools used by contributor workflows:
 
-- **Claude Code CLI** (`claude`) — powers all slash skills and `claude_github_reviews.py`.
+- **Codex CLI** (`codex`) — can run the `.agents/` slash skills and
+  is the default PR-review agent for `ai_agent_github_reviews.py`.
+- **Claude Code CLI** (`claude`) — can run the `.agents/` slash skills and
+  `ai_agent_github_reviews.py --agent claude`.
   Install: `winget install Anthropic.ClaudeCode`
-- **gh CLI** (`gh`) — required by `claude_github_reviews.py` to fetch PR review data.
+- **gh CLI** (`gh`) — required by `ai_agent_github_reviews.py` to fetch PR review data.
   Install: `winget install GitHub.cli` then `gh auth login`
   Not installable via pip/uv — it is a compiled Go binary.
 

CLAUDE.md

@@ -2,6 +2,9 @@
 
 Project guidance for Claude Code in this repository.
 
+Codex and other AI agents should use `AGENTS.md` as the primary shared
+instructions file. Claude-specific behavior and slash-command usage remain here.
+
 ## Commands
 
 **Python launcher:** Use `py` on this Windows system (not `python`).
@@ -82,8 +85,9 @@ Breaking changes are acceptable. Backward-compatibility shims are not.
 
 ## Agents and Skills
 
-Role-specific subagents live in `.claude/agents/`; slash-command skills in `.claude/skills/`.
-See `AGENTS.md` for role-based guidance that applies across all AI tooling.
+Role-specific subagents live in `.agents/agents/`; slash-command skills in
+`.agents/skills/`. See `AGENTS.md` for role-based guidance that applies across
+Claude, Codex, and other AI tooling.
 
 - `/plan` — inspect files, summarize design, produce a numbered plan (no code changes)
 - `/impl` — read → summarize → plan → implement in small diffs