ci: enable the pre-commit hooks, minus ruff-format

The hooks in this file had never been active: .git/hooks/pre-commit did not
exist, so check-added-large-files never ran and a 4.7 MB GIF went in under a
500 KB limit without a word. `pre-commit install` refused because
core.hooksPath was set in .git/config — pointing at .git/hooks, i.e. the
default, so it gated nothing and only blocked the installer. Unset locally.

ruff-format stays OFF. It would rewrite 722 of 811 files, nothing enforces
formatting today (CI runs ruff check, never ruff format --check), and it finds
no bugs while a repo-wide reformat destroys git blame. The header note now says
that, and lists what adopting it actually requires — the hook, a lone reformat
commit recorded in .git-blame-ignore-revs, and a CI check — so the next person
does not just uncomment the line and get the churn.

check-added-large-files raised to 5 MB. The docs carry demo assets now and the
500 KB default blocked those while catching nothing; the accidents worth
stopping (weights, checkpoints, dumps) are orders of magnitude larger and are
still caught. Verified: the 4.7 MB GIF is the largest tracked file, next is
251 KB, and the hook passes repo-wide.

.pre-commit-config.yaml

@@ -4,17 +4,32 @@
 #   Run on staged:  pre-commit run
 #   Run everything: pre-commit run --all-files
 #
-# NOTE: `ruff format` has never been run across this codebase, so the FIRST
-# `pre-commit run --all-files` will reformat MANY files. That one-time churn is
-# expected. Normal commits only run the hooks against staged files, so day-to-
-# day use is non-invasive.
+# NOTE: `ruff-format` is DISABLED ON PURPOSE. Do not just uncomment it.
+#
+# `ruff format` has never been run across this codebase: it would rewrite 722
+# of 811 files, i.e. nearly everything. Nothing enforces formatting today — CI
+# runs `ruff check`, never `ruff format --check` — so enabling the hook alone
+# would impose a standard no gate actually checks, and would quietly fold
+# whole-file reformatting into unrelated commits as people touch files.
+#
+# It also finds no bugs. `ruff check` is already clean repo-wide; formatting
+# only moves whitespace, while a repo-wide reformat destroys `git blame` (every
+# line points at the reformat instead of its author).
+#
+# To adopt it, do all three IN ONE commit, not just this line:
+#   1. re-enable the hook below
+#   2. run `ruff format src/soup_cli/ tests/` and commit the result alone,
+#      then add that commit's SHA to `.git-blame-ignore-revs` so blame skips it
+#   3. add `ruff format --check src/soup_cli/ tests/` to the CI lint job, or
+#      the hook is the only thing enforcing it and drifts the moment someone
+#      commits without hooks installed
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.9.4
     hooks:
       - id: ruff
         args: [--fix]
-      - id: ruff-format
+      # - id: ruff-format   # see the NOTE at the top before enabling
 
   # Validates .github/workflows/*.yml against the GitHub Actions schema —
   # context availability, expression syntax, action inputs, shellcheck over
@@ -38,3 +53,9 @@ repos:
       - id: check-toml
       - id: check-merge-conflict
       - id: check-added-large-files
+        # 5 MB, not the 500 KB default. README and the docs carry demo assets
+        # (docs/assets/layer-streaming.gif is 4.7 MB), and the default blocked
+        # those while catching nothing else. The real accidents this guards
+        # against — model weights, checkpoints, core dumps — are orders of
+        # magnitude past 5 MB and are still caught.
+        args: ['--maxkb=5000']