docs(claude): consolidate and align project documentation (#590)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: nanotaboada

.coderabbit.yaml

@@ -116,6 +116,15 @@ reviews:
         - Ensure pytest runs with -v for verbosity and --cov for coverage reporting
         - Validate coverage report upload step is present
 
+    - path: "alembic/versions/**/*.py"
+      instructions: |
+        - Migration files are append-only once merged. Fix forward with a new
+          migration; never edit existing versions. See ADR-0010.
+        - Seed data changes must go in a new migration, not standalone scripts.
+          ADR-0010 superseded direct seed scripts (ADR-0002); do not re-introduce
+          them.
+        - render_as_batch=True must remain enabled for SQLite batch ALTER support.
+
   path_filters:
     - "!**/__pycache__/**"
     - "!**/.pytest_cache/**"
@@ -169,19 +178,23 @@ reviews:
           If so, update the relevant sections of README.md to reflect the current state.
           Do not rewrite sections unrelated to the changes.
 
-          ## 3. .github/copilot-instructions.md
+          ## 3. CLAUDE.md
           If the PR introduces patterns, conventions, or architectural decisions that
           should guide future AI-assisted contributions, add or update the relevant
-          instructions in .github/copilot-instructions.md.
+          instructions in CLAUDE.md.
           Focus on things a developer (or AI assistant) unfamiliar with this specific
           stack implementation should know before writing code here.
 
       - name: "enforce http error handling"
         instructions: |
           Audit all HTTP handler functions in the changed files.
-          Verify that errors return appropriate HTTP status codes (400 for bad input,
-          404 for not found, 500 for unexpected errors) and a consistent JSON error
-          body with at least a "message" field.
+          Verify that errors return appropriate HTTP status codes:
+          - 422 Unprocessable Entity for Pydantic validation failures (payload shape
+            or field constraint violations) — NOT 400
+          - 400 Bad Request ONLY for semantic errors (e.g. squad number in the URL
+            does not match the body on PUT)
+          - 404 Not Found for missing resources
+          - 409 Conflict for duplicate squad number on POST
           Flag handlers that return 200 on error, swallow errors silently, or use
           bare status-only responses without a JSON body.
           Do not make changes; only report findings as a comment so fixes can be
@@ -334,7 +347,7 @@ knowledge_base:
   code_guidelines:
     enabled: true
     filePatterns:
-      - ".github/copilot-instructions.md"
+      - "CLAUDE.md"
   learnings:
     scope: auto
   issues:

.github/copilot-instructions.md

@@ -51,11 +51,27 @@ This project uses famous football coaches as release codenames, following an A-Z
   ...}` to route decorators (OpenAPI schema) and `Raises:` entries to
   docstrings; clarifies the 422 (Pydantic validation failure) vs 400 (semantic
   ambiguity) distinction (#568)
+- `CLAUDE.md`: consolidated from `.github/copilot-instructions.md` as the
+  single source of truth for AI coding assistants; added Invariants section and
+  Architecture Decision Records section; added pre-commit step 7 for ADR
+  updates; corrected cache layer description (caching is in routes, not
+  services) (#590)
+- `.coderabbit.yaml`: updated `enforce http error handling` finishing touch with
+  precise 422/400/404/409 status code guidance; updated `sync documentation`
+  finishing touch and `knowledge_base.code_guidelines` to reference `CLAUDE.md`;
+  added `alembic/versions/**/*.py` path instruction enforcing append-only
+  migration policy (#590)
 
 ### Fixed
 
+- `docs/adr/README.md`: corrected ADR-0002 status from `Accepted` to
+  `Superseded`; added missing ADR-0010 row (#590)
+
 ### Removed
 
+- `.github/copilot-instructions.md`: content consolidated into `CLAUDE.md`;
+  GitHub Copilot is no longer in use (#590)
+
 ---
 
 ## [2.1.1 - Eriksson] - 2026-04-11