chore: add Pixi, CI, pre-commit, contributor guides and PR template

.github/copilot-instructions.md

@@ -0,0 +1,11 @@
+# KonfAI — GitHub Copilot Instructions
+
+Follow the canonical repository instructions in `AGENTS.md`.
+
+- Never commit directly to `main`; always use a focused feature branch.
+- Keep each diff small and open a pull request for review.
+- Do not merge your own pull request.
+- Use Conventional Commits.
+- Never include Maestro, Claude, Codex, generated-by/generated-with text, or AI co-author branding in commit messages.
+- Run `pixi run format`, `pixi run check`, and relevant pre-commit hooks before finalising.
+- Do not introduce dependencies silently or load complete medical imaging datasets into RAM.

.github/pull_request_template.md

@@ -0,0 +1,48 @@
+<!--
+Thanks for contributing to KonfAI!
+PR titles must follow Conventional Commits, e.g.:
+  feat(utils): add OME-Zarr resolution selection
+  fix(data): correct degree-to-radian rotation
+Types: feat | fix | perf | refactor | docs | test | build | ci | chore
+-->
+
+## Description
+
+<!-- What does this PR change, and why? Keep it focused on one logical change. -->
+
+## Related issues
+
+<!-- e.g. "Closes #123", "Refs #456". Delete if none. -->
+
+## Type of change
+
+- [ ] `feat` — new feature
+- [ ] `fix` — bug fix
+- [ ] `perf` — performance improvement
+- [ ] `refactor` — no behaviour change
+- [ ] `docs` — documentation only
+- [ ] `test` — tests only
+- [ ] `build` / `ci` / `chore` — tooling, deps, CI
+- [ ] Breaking change (describe the migration below)
+
+## How has this been tested?
+
+<!-- Commands run and what you observed. -->
+
+```bash
+pixi run check
+```
+
+## Checklist
+
+- [ ] PR title and commits follow **Conventional Commits**
+- [ ] `pixi run check` passes (ruff lint + format + tests)
+- [ ] `pixi run --environment dev python -m pytest konfai-apps/tests` passes *(if `konfai-apps/` changed)*
+- [ ] Tests added/updated for the change
+- [ ] Docs updated *(if user-facing CLI/config behaviour changed)*
+- [ ] No new runtime dependency without a matching `pyproject.toml` extra
+- [ ] Lazy/patch data access preserved (no full-volume reads added)
+
+## Breaking changes & migration
+
+<!-- Describe any breaking change and how users should migrate. Delete if none. -->

.github/workflows/commit-hygiene.yml

@@ -0,0 +1,53 @@
+name: commit-hygiene
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  validate-commits:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out full history
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install Commitizen
+        run: python -m pip install commitizen==4.13.0
+
+      - name: Validate Conventional Commits
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: cz check --rev-range "${BASE_SHA}..${HEAD_SHA}"
+
+      - name: Reject agent branding
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          status=0
+
+          while IFS= read -r commit; do
+            message_file="$(mktemp)"
+            git show --no-patch --format=%B "$commit" > "$message_file"
+            echo "Checking $(git show --no-patch --format='%h %s' "$commit")"
+
+            if ! python scripts/check_commit_message.py "$message_file"; then
+              status=1
+            fi
+
+            rm -f "$message_file"
+          done < <(git rev-list --reverse "${BASE_SHA}..${HEAD_SHA}")
+
+          exit "$status"

.github/workflows/konfai_ci.yml

@@ -5,13 +5,15 @@ on:
     paths:
       - ".github/workflows/konfai_ci.yml"
       - "konfai/**"
+      - "konfai-apps/**"
       - "tests/**"
       - "pyproject.toml"
       - "README.md"
   pull_request:
     paths:
       - ".github/workflows/konfai_ci.yml"
       - "konfai/**"
+      - "konfai-apps/**"
       - "tests/**"
       - "pyproject.toml"
       - "README.md"
@@ -27,7 +29,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@v5
-      
+
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
@@ -37,7 +39,63 @@ jobs:
         run: |
           python -m pip install -U pip
           pip install -e ".[dev]"
-      
+
       - name: Run pytest
         run: |
           pytest -q tests
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install ruff
+        run: pip install ruff==0.15.2
+
+      - name: Run ruff lint
+        run: ruff check konfai konfai-apps/konfai_apps
+
+  format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install ruff
+        run: pip install ruff==0.15.2
+
+      - name: Check formatting
+        run: ruff format --check konfai konfai-apps/konfai_apps
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install build
+        run: pip install build setuptools-scm
+
+      - name: Build sdist and wheel
+        run: python -m build --sdist --wheel
+
+      - name: Upload wheel artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: konfai-wheel
+          path: dist/*.whl

.github/workflows/pre-commit.yml

@@ -1,9 +1,14 @@
 name: pre-commit
 
+# Run repository hygiene, Ruff, mypy, and Bandit hooks on pull requests.
+# Commit-message hooks are exercised separately by commit-hygiene.yml because
+# pre-commit/action runs the pre-commit stage, not the commit-msg stage.
 on:
-  push:
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   pre-commit:
     runs-on: ubuntu-latest

.gitignore

@@ -16,3 +16,4 @@ apps/impact_reg
 apps/impact_seg
 docs/build/
 .codex
+docs/_build/

.pre-commit-config.yaml

@@ -1,48 +1,55 @@
+exclude: ^(?:\.pixi/|docs/_build/|dist/|.*\.egg-info/)
+
+default_install_hook_types:
+  - pre-commit
+  - commit-msg
+
+default_stages:
+  - pre-commit
+
 repos:
-  - repo: https://github.com/psf/black
-    rev: 25.1.0
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
     hooks:
-      - id: black
-        args: ["--line-length=120"]
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-xml
+      - id: check-yaml
+      - id: debug-statements
+      - id: detect-private-key
+      - id: end-of-file-fixer
+        exclude: ^apps/mrsegmentator/README\.md$
+      - id: mixed-line-ending
+        exclude: ^apps/mrsegmentator/README\.md$
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+        exclude: ^apps/mrsegmentator/README\.md$
 
-  - repo: https://github.com/PyCQA/flake8
-    rev: 7.3.0
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.2
     hooks:
-      - id: flake8
-        additional_dependencies:
-          - flake8-bugbear
-          - pep8-naming
-          - flake8-builtins
-          - flake8-comprehensions
-        args:
-            - --max-line-length=120
-            - --extend-ignore=E203,W503,B006,B008
-
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+        files: ^(konfai/|konfai-apps/konfai_apps/|scripts/)
+      - id: ruff-format
+        files: ^(konfai/|konfai-apps/konfai_apps/|scripts/)
 
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.17.0
     hooks:
       - id: mypy
         additional_dependencies:
           - types-requests
+        files: ^konfai/
         args:
           - --ignore-missing-imports
           - --check-untyped-defs
           - --install-types
           - --non-interactive
 
-  - repo: https://github.com/asottile/pyupgrade
-    rev: v3.21.2
-    hooks:
-      - id: pyupgrade
-        args: ["--py310-plus"]
-
-  - repo: https://github.com/pre-commit/mirrors-isort
-    rev: v5.10.1
-    hooks:
-      - id: isort
-        args: ["--profile=black", "--line-length=120"]
-
   - repo: https://github.com/PyCQA/bandit
     rev: 1.8.6
     hooks:
@@ -51,3 +58,17 @@ repos:
         files: ^(konfai/|konfai-apps/konfai_apps/)
         exclude: ^(tests/|konfai-apps/tests/)
         pass_filenames: false
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.13.0
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]
+
+  - repo: local
+    hooks:
+      - id: forbid-agent-commit-branding
+        name: Forbid AI agent branding in commit messages
+        entry: python scripts/check_commit_message.py
+        language: python
+        stages: [commit-msg]

.readthedocs.yaml

@@ -21,4 +21,4 @@ python:
   install:
     - requirements: docs/requirements.txt
     - method: pip
-      path: .
+      path: .