Modernize the python template

.claude/skills/add-docs-page/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: add-docs-page
+description: Scaffold a new MkDocs documentation page and wire it into the navigation. Use when asked to "add a docs page", "add a guide", or "document" a feature in the site.
+---
+
+# Add a docs page
+
+API reference pages are auto-generated from docstrings by
+`docs/generate_api.py`; do not create those by hand. Use this for narrative
+pages (guides, overviews, etc.).
+
+1. Create the Markdown file under `docs/` (group guides under `docs/guides/`).
+   Follow the tone/format of existing pages such as `docs/guides/example.md`.
+2. Add the page to the `nav:` tree in `mkdocs.yml` under the appropriate
+   section, e.g.:
+   ```yaml
+   - Guides:
+       - guides/index.md
+       - My Feature: guides/my-feature.md
+   ```
+3. Cross-reference symbols with mkdocstrings autorefs (e.g. `[pypkg.foo.bar][]`)
+   where helpful.
+4. Build with strict mode to catch broken links and nav issues:
+   ```bash
+   uv sync --group docs
+   mkdocs serve                   # preview locally
+   tox -e docs                    # strict build (must pass)
+   ```

.claude/skills/check/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: check
+description: Run the full local quality gate (prek hooks + tox test matrix) before committing or opening a pull request. Use when asked to "check", "lint", "run CI locally", or verify a change is ready.
+---
+
+# Run the local quality gate
+
+Reproduce what CI runs, in order. Stop and report on the first failure.
+
+1. Sync and activate the environment:
+   ```bash
+   uv sync
+   source .venv/bin/activate
+   ```
+2. Run all pre-commit hooks (Ruff, mypy, typos, complexipy, ...):
+   ```bash
+   prek run --all-files
+   ```
+3. Run the test suite (fast path — current interpreter):
+   ```bash
+   pytest
+   ```
+4. Optionally run the full matrix and docs build (slower):
+   ```bash
+   tox
+   ```
+
+Report which steps passed/failed. If a hook auto-fixed files, re-stage them and
+re-run step 2.

.claude/skills/release/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: release
+description: Cut a new release by tagging a version and publishing via GitHub, which triggers the PyPI Trusted Publishing and docs-deploy workflows. Use when asked to "make a release", "cut a version", or "publish".
+---
+
+# Cut a release
+
+Versioning is derived from git tags via setuptools_scm, and publishing is
+automated by `.github/workflows/publish.yml`. See
+`docs/contributing/releases.md` for the authoritative process.
+
+1. Confirm `main` is green (CI passing) and decide the version `{VERSION}`
+   (semver `major.minor.patch`, optional PEP 440 pre/post/dev suffix).
+2. Create and push an annotated, signed tag prefixed with `v`:
+   ```bash
+   git tag -s v{VERSION} -m "pypkg v{VERSION}"
+   git push origin v{VERSION}
+   ```
+3. Create a GitHub Release from the tag titled `pypkg v{VERSION}`:
+   - Official release: use "Generate release notes", set the previous official
+     tag as the baseline, add an "Upgrade Steps" section, verify PR labels sort
+     the notes correctly, and mark it "latest".
+   - Pre-release: skip generated notes and mark it "pre-release".
+4. Publishing the release triggers the `publish` workflow, which builds with
+   `uv build`, uploads to PyPI via Trusted Publishing, and deploys versioned
+   docs with `mike`. Confirm both the PyPI upload and the docs deploy succeeded.
+
+Do not push tags or create releases without explicit confirmation from the user.

.claude/skills/rename-template/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: rename-template
+description: Replace the template placeholders (pypkg, pypkg-author, gpauloski/python-template) when starting a new project from this template. Use when asked to "rename the template", "set up a new project", or "replace pypkg".
+---
+
+# Rename template placeholders
+
+The template uses placeholders that must be replaced for a new project. Ask the
+user for their values first if not provided:
+
+- `pypkg` — the Python package/import name (e.g. `mypkg`).
+- `pypkg-author` — the GitHub org/user or author handle.
+- `gpauloski/python-template` — the new `owner/repo` slug.
+- author name, email, and description for `pyproject.toml`.
+
+Steps:
+
+1. Find all occurrences so nothing is missed:
+   ```bash
+   git grep -n -e pypkg -e pypkg-author -e gpauloski/python-template
+   ```
+2. Rename the package directory:
+   ```bash
+   git mv pypkg <package_name>
+   ```
+3. Replace the placeholders across the tree (review before running a bulk
+   `sed`). Key files: `pyproject.toml`, `mkdocs.yml`, `README.md`,
+   `.github/**`, `docs/**`, and the custom template
+   `docs/templates/python/material/module.html.jinja`.
+4. Update author, email, description, and URLs in `pyproject.toml`, and the
+   `<CONTACT_EMAIL>` placeholder in `.github/CODE_OF_CONDUCT.md`.
+5. Verify nothing was missed and the project still works:
+   ```bash
+   git grep -n pypkg          # should return nothing meaningful
+   uv sync && pytest
+   ```

.github/CODE_OF_CONDUCT.md

@@ -60,7 +60,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-jgpauloski@uchicago.edu.
+<CONTACT_EMAIL>.
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the

.github/ISSUE_TEMPLATE/01_bug.yml

@@ -2,28 +2,28 @@ name: Bug Report
 description: Report errors or unexpected results.
 labels: ["bug"]
 assignees:
-  - foobar-bug-assign-dev
+  - pypkg-bug-assign-dev
 body:
   - type: textarea
     id: install
     attributes:
-      label: How did you install foobar?
+      label: How did you install pypkg?
       description: >
         E.g., install via pip, install from source, etc. **Note:** this will
         be rendered as console text automatically.
       placeholder: |
-        $ pip install foobar
-        Collecting foobar
+        $ pip install pypkg
+        Collecting pypkg
         ...
-        Successfully installed foobar...
+        Successfully installed pypkg...
       render: console
     validations:
       required: true
 
   - type: input
     id: version
     attributes:
-      label: What version of foobar are you using?
+      label: What version of pypkg are you using?
       description: >
         Package version if installed via Pip or commit ID if installed
         from source.

.github/ISSUE_TEMPLATE/02_enhancement.yml

@@ -2,7 +2,7 @@ name: Enhancement Request
 description: Request a new feature or enhancement.
 labels: ["enhancement"]
 assignees:
-  - foobar-enh-assign-dev
+  - pypkg-enh-assign-dev
 body:
   - type: textarea
     id: request

.github/ISSUE_TEMPLATE/03_docs.yml

@@ -2,7 +2,7 @@ name: Documentation Improvements
 description: Suggest improvements to the documentation.
 labels: ["documentation"]
 assignees:
-  - foobar-doc-assignee-dev
+  - pypkg-doc-assignee-dev
 body:
   - type: textarea
     id: freeform

.github/pull_request_template.md

@@ -28,7 +28,7 @@ N/A
 
 Please confirm the PR meets the following requirements.
 - [ ] Relevant tags are added (breaking, bug, dependencies, documentation, enhancement, refactor).
-- [ ] Code changes pass `pre-commit` (e.g., ruff, mypy, etc.).
+- [ ] Code changes pass `prek` (e.g., ruff, mypy, typos, etc.).
 - [ ] Tests have been added to show the fix is effective or that the new feature works.
 - [ ] New and existing unit tests pass locally with the changes.
 - [ ] Docs have been updated and reviewed if relevant.

.github/workflows/check-docs.yml

@@ -10,36 +10,23 @@ on:
   pull_request:
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   check-docs:
     timeout-minutes: 10
-
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout
         uses: actions/checkout@v7
 
-      - name: Set up Python 3.11
-        uses: actions/setup-python@v6
-        with:
-          python-version: '3.11'
-
-      - name: Get pip cache dir
-        id: pip-cache-dir
-        run: echo "PIP_CACHE_DIR=$(pip cache dir)" >> $GITHUB_ENV
-
-      - name: Use pip cache
-        id: pip-cache
-        uses: actions/cache@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
         with:
-          path: ${{ env.PIP_CACHE_DIR }}
-          key: docs-ubuntu-latest-pip-3.11-${{ hashFiles('pyproject.toml') }}
-          restore-keys: |
-            docs-ubuntu-latest-pip-3.11-
-
-      - name: Install Packages
-        run: pip install --upgrade setuptools pip tox virtualenv
+          enable-cache: true
+          cache-python: true
 
-      - name: Run Tox to build docs
-        run: tox -e docs
+      - name: Build docs with tox
+        run: uv run tox -e docs

.github/workflows/docs.yml

@@ -5,10 +5,12 @@ on:
     branches: [main]
   workflow_dispatch:
 
+permissions:
+  contents: write
+
 jobs:
   docs:
     timeout-minutes: 10
-
     runs-on: ubuntu-latest
 
     steps:
@@ -17,33 +19,19 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Set up Python 3.11
-        uses: actions/setup-python@v6
-        with:
-          python-version: '3.11'
-
-      - name: Get pip cache dir
-        id: pip-cache-dir
-        run: echo "PIP_CACHE_DIR=$(pip cache dir)" >> $GITHUB_ENV
-
-      - name: Use pip cache
-        id: pip-cache
-        uses: actions/cache@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
         with:
-          path: ${{ env.PIP_CACHE_DIR }}
-          key: docs-ubuntu-latest-pip-3.11-${{ hashFiles('pyproject.toml') }}
-          restore-keys: |
-            docs-ubuntu-latest-pip-3.11-
+          enable-cache: true
+          cache-python: true
 
-      - name: Install Packages
-        run: |
-          pip install --upgrade setuptools pip
-          pip install .[docs]
+      - name: Install docs dependencies
+        run: uv sync --group docs
 
       - name: Configure git
         run: |
           git config --local user.name "GitHub Actions Bot"
           git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
       - name: Deploy docs for main:latest to gh-pages branch
-        run: |
-          mike deploy --push --update-aliases main
+        run: uv run mike deploy --push --update-aliases main

.github/workflows/prek-autoupdate.yml

@@ -0,0 +1,47 @@
+name: prek-autoupdate
+
+# Weekly refresh of pinned hook versions in .pre-commit-config.yaml. Runs
+# `prek autoupdate` and opens a pull request if anything changed. Replaces the
+# autoupdate service that pre-commit.ci provided.
+on:
+  schedule:
+    # Mondays at 06:00 UTC.
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  autoupdate:
+    timeout-minutes: 10
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-python: true
+
+      - name: Install the project
+        run: uv sync
+
+      - name: Run prek autoupdate
+        run: uv run prek autoupdate
+
+      - name: Open a pull request
+        uses: peter-evans/create-pull-request@v7
+        with:
+          commit-message: "[prek] autoupdate hooks"
+          title: "[prek] autoupdate hooks"
+          body: >
+            Automated weekly update of pre-commit hook versions via
+            `prek autoupdate`.
+          branch: prek-autoupdate
+          delete-branch: true
+          labels: dependencies

.github/workflows/prek.yml

@@ -0,0 +1,31 @@
+name: prek
+
+on:
+  push:
+    branches: [main, test-me-*]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  prek:
+    timeout-minutes: 10
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-python: true
+
+      - name: Install the project
+        run: uv sync
+
+      - name: Run prek
+        run: uv run prek run --all-files --show-diff-on-failure