ci: add prek pre-commit hooks, CI workflows, and tool config

Tooling:
- Add prek/ipykernel/pandas-stubs to dev extras
- Configure ruff (line-length, qmd as markdown, per-file F841 ignore in tests)
- Configure mypy with ignore_missing_imports for arviz/xarray/numpy/pandas/polars
- Add .pre-commit-config.yaml (trailing-ws, EOF, yaml/toml/merge-conflict
  checks, ruff + ruff-format on py/pyi/ipynb/qmd, mypy on tidydraws/)
- Fix __init__.py re-export via __all__ + redundant-alias imports (F401)
- Fix real mypy error in _coerce_to_dataframe (pd=None assigned to Module)
- Makefile: install uses --all-extras, add precommit target, align type-check

CI:
- .github/workflows/ci.yml: test (uv sync --all-extras + pytest) and prek
  (changed-files on PRs, all-files on pushes) jobs
- .github/workflows/docs.yml: build-docs runs on every push/PR to catch
  breakage; publish-docs is manual-only (workflow_dispatch) until the doc
  review pass completes — full Pages publish machinery wired so flipping to
  auto-on-main is a one-line trigger change

PRD milestones ticked to reflect actual implementation status (v0.1 code +
docs complete except GitHub Pages deploy; v0.2 docs partly done).

prek reformatted several files on first run (whitespace/EOF/ruff-format
normalization expected for a repo with no prior formatting); all green now.

Author: drbenvincent

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: ci
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+      - name: Install dependencies
+        run: uv sync --all-extras
+      - name: Run tests
+        run: uv run pytest -v
+
+  prek:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+      - name: Install dependencies
+        # Locked install so the mypy hook sees project deps, matching local
+        # `make lint` behaviour.
+        run: uv sync --all-extras
+      - name: Run prek on changed files in PRs
+        if: github.event_name == 'pull_request'
+        run: uv run prek run --from-ref "$BASE_SHA" --to-ref "$HEAD_SHA"
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+      - name: Run prek on all files on pushes
+        if: github.event_name != 'pull_request'
+        run: uv run prek run --all-files

.github/workflows/docs.yml

@@ -0,0 +1,93 @@
+name: CI Docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      deploy:
+        description: "Publish the built site to GitHub Pages"
+        type: boolean
+        default: false
+
+# The repo is private and the docs are under review, so the site is NOT
+# auto-published yet. `build-docs` runs on every push/PR to catch breakage.
+# `publish-docs` only runs on manual `workflow_dispatch` with `deploy=true`.
+# Once the doc review pass is complete, flip the publish trigger to
+# `if: github.ref == 'refs/heads/main'` (tracked in the go-live issue).
+jobs:
+  build-docs:
+    name: "Build Docs"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history for accurate page timestamps
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+
+      - name: Install package and dependencies
+        # uv sync installs the locked dependency set from uv.lock, so CI
+        # resolves the exact versions used in local dev.
+        run: uv sync --all-extras
+
+      - name: Register `python3` Jupyter kernel
+        # .qmd files (and great-docs.yml) declare `jupyter: python3`, so the
+        # CI runner needs a kernelspec under that name pointing at the same
+        # Python interpreter the package was installed into above.
+        run: uv run python -m ipykernel install --user --name python3
+
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+
+      - name: Build docs
+        run: uv run great-docs build
+
+      - name: Verify agent-context files were generated
+        # great-docs writes llms.txt / llms-full.txt / skill.md at build step,
+        # but llms-full.txt is only emitted if `import tidydraws` succeeds and
+        # that failure is swallowed. Assert the files landed in _site so a
+        # silent skip fails CI instead of shipping an incomplete site.
+        run: |
+          for f in llms.txt llms-full.txt skill.md; do
+            if [[ ! -s "great-docs/_site/$f" ]]; then
+              echo "::error::great-docs/_site/$f missing or empty after build"
+              exit 1
+            fi
+            echo "OK: $f ($(wc -c < "great-docs/_site/$f") bytes)"
+          done
+
+      - name: Save docs artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-html
+          path: great-docs/_site
+
+  publish-docs:
+    name: "Publish Docs"
+    runs-on: ubuntu-latest
+    needs: "build-docs"
+    if: github.event_name == 'workflow_dispatch' && inputs.deploy
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: docs-html
+          path: great-docs/_site
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: great-docs/_site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.pre-commit-config.yaml

@@ -0,0 +1,32 @@
+# Pre-commit hooks run via `prek` (a fast, pre-commit-compatible runner).
+# CI mirrors local behaviour: `uv run prek run --all-files` (pushes) or
+# `uv run prek run --from-ref BASE --to-ref HEAD` (PRs).
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+        exclude_types: [svg]
+      - id: end-of-file-fixer
+        exclude_types: [svg]
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: ["--maxkb=1500"]
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.12
+    hooks:
+      - id: ruff
+        types_or: [python, pyi, jupyter]
+        args: [--fix]
+      - id: ruff-format
+        types_or: [python, pyi, jupyter, text]
+        files: \.(py|pyi|ipynb|qmd)$
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.15.0
+    hooks:
+      - id: mypy
+        args: [--ignore-missing-imports]
+        files: ^tidydraws/
+        additional_dependencies: [numpy>=1.20, pandas-stubs, polars]

CONTRIBUTING.md

@@ -57,7 +57,7 @@ tidydraws uses `uv` for managing dependencies. Make sure you have it installed b
    uv run mypy .
    ```
 
-## Testing 
+## Testing
 Run tests with:
 ```bash
 uv run pytest
@@ -120,7 +120,7 @@ This repo ships the [Great Docs Agent Skills](https://posit-dev.github.io/great-
 
 ## Pull Request Guidelines
 
-- Reference relevant issues in your PR description 
+- Reference relevant issues in your PR description
 - Ensure all tests pass
 - Add or update documentation as needed
-- Keep changes focused and atomic
+- Keep changes focused and atomic

Makefile

@@ -1,22 +1,23 @@
 # Makefile for tidydraws development workflow
 
-.PHONY: help install test lint type-check docs docs-preview cleandocs build clean
+.PHONY: help install test lint type-check precommit docs docs-preview cleandocs build clean
 
 # Help target to show available commands
 help:
 	@echo "Available commands:"
-	@echo "  install       - Install dependencies with uv"
+	@echo "  install       - Install all dependencies (incl. dev) with uv"
 	@echo "  test          - Run all tests"
 	@echo "  lint          - Run code linting with ruff"
 	@echo "  type-check    - Run type checking with mypy"
+	@echo "  precommit     - Run prek (pre-commit) hooks on all files"
 	@echo "  docs          - Build the documentation site (great-docs)"
 	@echo "  docs-preview  - Build and serve the docs locally with live reload"
 	@echo "  cleandocs     - Remove the ephemeral great-docs/ build directory"
 	@echo "  clean         - Clean build artifacts"
 
 # Install dependencies
 install:
-	uv sync
+	uv sync --all-extras
 
 # Run tests
 test:
@@ -28,7 +29,11 @@ lint:
 
 # Type check with mypy
 type-check:
-	uv run mypy .
+	uv run mypy tidydraws
+
+# Run pre-commit hooks via prek
+precommit:
+	uv run prek run --all-files
 
 # Build the documentation site into the ephemeral great-docs/_site/ directory
 docs:
@@ -46,4 +51,4 @@ cleandocs:
 clean: cleandocs
 	rm -rf .pytest_cache/
 	find . -name "*.pyc" -delete
-	find . -name "__pycache__" -type d -exec rm -rf {} +
+	find . -name "__pycache__" -type d -exec rm -rf {} +

PRD.md

@@ -302,7 +302,7 @@ def spread_draws_compare(
     Example
     -------
     # Extract posterior and prior for side-by-side forest plots
-    compare_df = spread_draws_compare(dt, "beta[groups]", 
+    compare_df = spread_draws_compare(dt, "beta[groups]",
                                        groups=["posterior", "prior"])
     # → columns: chain, draw, groups, beta, source
     # → source ∈ {"posterior", "prior"}
@@ -898,5 +898,3 @@ Join only if you genuinely need both:
   spread_draws(...).join(add_epred_draws(...), on=["chain", "draw", "group"])
   → Explicit, and the user understands what they're paying for
 ```
-
-