diff --git a/Tech/Projects/pre-commit-framework-migration.md b/Tech/Projects/pre-commit-framework-migration.md
new file mode 100644
index 0000000..47b7e79
--- /dev/null
+++ b/Tech/Projects/pre-commit-framework-migration.md
@@ -0,0 +1,189 @@
+---
+project: pre-commit-framework-migration
+type: project-plan
+status: active
+path: Tech/Projects
+tags:
+  - homelab
+  - tooling
+  - git
+  - ansible
+  - security
+created: 2026-05-03
+updated: 2026-05-03
+---
+# pre-commit framework migration
+
+## Goal
+
+Replace the raw `.git/hooks/pre-commit` bash script (currently shared via
+`core.hooksPath`) with the [pre-commit framework](https://pre-commit.com),
+and adopt it as the standard for all new repos. Codify a curated set of
+checks that catch the mistakes most likely to bite a solo homelab operator
+working across Python, Go, Ansible, and YAML-heavy infra repos.
+
+## Why
+
+The current raw hook works but has limits:
+
+- not version-controlled (lives in `.git/hooks/`, not tracked)
+- single-purpose (vault encryption check only)
+- adding more checks means growing a bash script
+- no portability across machines without re-running the `core.hooksPath`
+setup
+
+The framework solves all four: config lives in `.pre-commit-config.yaml` at
+the repo root, gets committed, and gives access to a large ecosystem of
+pre-built hooks.
+
+## Scope
+
+### In scope
+
+- Install `pre-commit` framework on dev machines
+- Migrate the existing ansible-vault check from raw bash to a framework hook
+- Curate a default `.pre-commit-config.yaml` template covering Python, Go,
+Ansible, YAML, and secret-detection
+- Document the install/onboarding flow as the standard for new repos
+- Decide how the framework coexists with (or replaces) the current
+`core.hooksPath` setup
+- Add the template to project scaffolding so new repos start with it
+pre-wired
+
+### Out of scope
+
+- Migrating every existing repo today (do them as they're touched)
+- Full CI integration (pre-commit can also run in GitHub Actions, but
+that's a follow-up)
+- Replacing `zero-check` or other post-generation validation skills
+
+## Decisions to confirm
+
+- **Coexistence with `core.hooksPath`** — once the framework is in a repo,
+its `pre-commit install` will overwrite `.git/hooks/pre-commit` for that
+repo. Need to decide: leave `core.hooksPath` as a fallback for repos
+without `.pre-commit-config.yaml`, or unset it once all active repos are
+migrated?
+- **Vault check location** — keep the bash script in-repo at
+`scripts/check-vault.sh` (referenced as a `local` hook), or rewrite as a
+tiny standalone repo and pin like other framework hooks?
+- **Template repo or scaffold-generated** — does the default
+`.pre-commit-config.yaml` live in a `homelab-templates` repo for
+`web_fetch` access, or get generated by the project scaffolding tool?
+
+## Curated check list
+
+Grouped by category. Each is a separate hook entry; opt in per repo by
+what's actually relevant.
+
+### Universal (every repo)
+
+- `trailing-whitespace` — strip trailing spaces
+- `end-of-file-fixer` — ensure files end with a newline
+- `check-merge-conflict` — block commits with unresolved conflict markers
+- `check-added-large-files` — block accidental large file commits (default
+500KB)
+- `mixed-line-ending` — enforce LF
+- `detect-private-key` — block committing SSH/TLS private keys
+
+### Secrets & sensitive data
+
+- `detect-secrets` (Yelp) — broader secret scanning beyond just private
+keys; catches AWS keys, API tokens, high-entropy strings
+- `gitleaks` — alternative or complement; well-maintained, fast
+- **Custom: ansible-vault encryption check** — port of the existing bash
+hook
+
+### YAML / config
+
+- `check-yaml` — basic YAML syntax validation
+- `yamllint` — style + structure (line length, indentation, truthy values)
+- `check-json` — JSON syntax
+- `check-toml` — TOML syntax
+
+### Python
+
+- `ruff` — lint + format in one tool (replaces flake8, isort, black for
+most cases)
+- `ruff-format` — formatter
+- `mypy` — optional, type-checking (heavier; opt in per project)
+
+### Go
+
+- `go-fmt` — gofmt enforcement
+- `go-vet` — basic static analysis
+- `golangci-lint` — broader linting (opt in per project)
+
+### Ansible-specific
+
+- **Custom: ansible-vault encryption check** (existing logic, ported)
+- `ansible-lint` — full Ansible playbook/role linting
+- `yamllint` (already covered above, but Ansible repos lean on it heavily)
+
+### Shell scripts
+
+- `shellcheck` — catches common bash bugs and bad patterns
+- `shfmt` — formatter for shell scripts
+
+### Markdown / docs
+
+- `markdownlint` — style/structure for `.md` files
+- (Skip if it gets noisy on Obsidian-flavored markdown — the project notes
+use front-matter and Obsidian syntax that vanilla markdownlint may complain
+about.)
+
+## Migration path
+
+1. Pick one active repo as the pilot — likely the new project where this
+conversation started.
+2. `pip install pre-commit` (or `uv tool install pre-commit`) on the dev
+machine.
+3. Drop in a starter `.pre-commit-config.yaml` covering universal + secrets
++ ansible + relevant language checks.
+4. Port the vault check as a `local` hook pointing at
+`scripts/check-vault.sh`.
+5. `pre-commit install` to wire it up.
+6. `pre-commit run --all-files` to flush out anything the existing code
+violates.
+7. Iterate on the config until baseline is clean.
+8. Once stable, copy `.pre-commit-config.yaml` to the template location
+(TBD — see decisions).
+9. Decide on `core.hooksPath` — leave or unset.
+10. Add `pre-commit install` to the project scaffolding flow so new repos
+get it automatically.
+
+## Tasks
+
+- [ ] Confirm decisions: coexistence with `core.hooksPath`, vault check
+location, template hosting
+- [ ] Install `pre-commit` framework on dev machines
+- [ ] Pilot on one active repo
+- [ ] Port vault encryption check as a `local` hook
+- [ ] Build default `.pre-commit-config.yaml` template covering universal +
+secrets + Python + Go + Ansible + YAML
+- [ ] Run `pre-commit run --all-files` on pilot, fix or ignore findings
+- [ ] Document the install/onboarding flow (README section or standalone
+doc)
+- [ ] Decide whether to keep or unset `core.hooksPath`
+- [ ] Migrate active repos one by one as they're touched
+- [ ] Add template to scaffolding tool or `homelab-templates` repo
+- [ ] Evaluate whether to add CI run of `pre-commit run --all-files` on PRs
+(follow-up)
+
+## Open questions
+
+- Does `pre-commit` play well with the `zero-check` skill, or is there
+overlap to resolve?
+- For Obsidian-flavored markdown, is `markdownlint` worth the noise or skip
+entirely?
+- Should `mypy` be in the default Python config, or opt-in per project?
+
+## References
+
+- pre-commit docs: https://pre-commit.com
+- Hook list: https://pre-commit.com/hooks.html
+- Existing raw hook: stored at `~/.config/git-hooks/pre-commit` (per
+`core.hooksPath` setup)
+
+
+...sent from Jenny & Travis
\ No newline at end of file