docs: verify, consolidate and align project documentation

[nanotaboada]

Context

This repo contains a REST API built with Java 25 and Spring Boot 4. Project guidance currently lives in two files: CLAUDE.md (a two-line stub with an @ include) and .github/copilot-instructions.md (the actual content). GitHub Copilot is no longer in use, making the split pointless. No ADR directory exists — architectural decisions are captured only in copilot-instructions.md. The goal is to establish CLAUDE.md as the single source of truth, verify its content against the code, and close gaps in .coderabbit.yaml.

Note: a dedicated ADR issue (#299) is already in the backlog with a full implementation plan. ADR creation is out of scope here. This issue adds a forward reference to the forthcoming docs/adr/ directory and a note that #299's acceptance criteria should target CLAUDE.md (not copilot-instructions.md) once this issue ships.

Conflict resolution rule

The code is the source of truth. When copilot-instructions.md contradicts what the code actually does, fix the documentation — do not change the code.

Implementation steps

1. Verify copilot-instructions.md against the code

Before copying any content, read the actual code and confirm these claims are still accurate:

• No cache TTL: check src/main/java/**/services/PlayersService.java — @Cacheable should have no time-based expiry; cache invalidation should use @CacheEvict(allEntries = true) on writes only
• Constructor injection only: spot-check service and repository classes — no @Autowired field injection should be present
• @Transactional(readOnly = true) on reads: check service read methods
• In-memory SQLite for tests: check src/test/resources/application.properties — should configure an in-memory SQLite datasource
• BDD test naming (givenX_whenY_thenZ): spot-check test class names and method names
• Port 9000: check src/main/resources/application.properties

Document any discrepancies found. Correct copilot-instructions.md content before moving to step 2.

2. Consolidate into CLAUDE.md

Replace the entire content of CLAUDE.md with the (now-verified and corrected) content from .github/copilot-instructions.md. Then add:

## Invariants (never change without explicit discussion)

- Port: 9000
- API contract: endpoints, HTTP status codes, and response shapes are fixed;
  do not change them without explicit discussion
- Commit format: `type(scope): description (#issue)` — max 80 chars
- Conventional Commits types: feat fix chore docs test refactor ci perf
- CHANGELOG.md `[Unreleased]` section must be updated before every commit

## Architecture Decision Records

Architectural decisions will be documented in `docs/adr/` once issue #299 is
implemented. Until then, key decisions are captured in this file. When proposing
structural changes, check this file first. When a decision changes, update this
file and open or reference the relevant issue.

Then update the Pre-commit Checks section to add:

6. If this commit introduces or changes an architectural decision, update
   CLAUDE.md. Once #299 is implemented, also create or amend the relevant ADR.

Delete .github/copilot-instructions.md.

3. Update .coderabbit.yaml

Add to the src/**/services/**/*.java path instruction:

- Spring Cache is configured with NO expiry — this is intentional. Do not
  suggest adding a TTL or time-based eviction. Cache is invalidated only on
  write operations via @CacheEvict(allEntries = true).

Acceptance criteria

• Every claim in CLAUDE.md has been verified against the current code
• Any discrepancies found during verification are corrected in CLAUDE.md
• CLAUDE.md contains all content previously in copilot-instructions.md
• CLAUDE.md has an Invariants section and a forward reference to docs/adr/ (tracking Implement Architecture Decision Records (ADRs) #299)
• CLAUDE.md pre-commit checklist includes the ADR/CLAUDE.md update requirement
• .github/copilot-instructions.md is deleted
• .coderabbit.yaml service path instruction documents the intentional no-expiry cache behaviour
• CHANGELOG.md [Unreleased] updated
• No regressions in existing tests

References

• Implement Architecture Decision Records (ADRs) #299 — Implement Architecture Decision Records (ADRs should target CLAUDE.md once this issue ships)

[coderabbitai]

🔗 Related PRs

#266 - test: adopt BDD Given-When-Then pattern across all tests [merged]
#267 - docs: restructure AI instruction files [merged]
#269 - docs(copilot): unify instructions as canonical single-file format [merged]
#284 - chore(claude): improve Claude Code integration [merged]
#297 - docs: normalize README structure and add RELEASES.md [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!