docs: fix documentation inconsistencies in copilot-instructions and AGENTS

Author: nanotaboada

.github/copilot-instructions.md

@@ -1,14 +1,14 @@
 # GitHub Copilot Instructions
 
-> **⚡ Token Efficiency Note**: This is a minimal pointer file (~500 tokens, auto-loaded by Copilot).  
-> For complete operational details, reference: `#file:AGENTS.md` (~2,500 tokens, loaded on-demand)  
+> **⚡ Token Efficiency Note**: This is a minimal pointer file (~500 tokens, auto-loaded by Copilot).
+> For complete operational details, reference: `#file:AGENTS.md` (~2,500 tokens, loaded on-demand)
 > For specialized knowledge, use: `#file:SKILLS/<skill-name>/SKILL.md` (loaded on-demand when needed)
 
 ## 🎯 Quick Context
 
-**Project**: FastAPI REST API demonstrating modern Python async patterns  
-**Stack**: Python 3.13 • FastAPI • SQLAlchemy (async) • SQLite • Docker • pytest  
-**Pattern**: Routes → Services → Database (layered architecture)  
+**Project**: FastAPI REST API demonstrating modern Python async patterns
+**Stack**: Python 3.13 • FastAPI • SQLAlchemy (async) • SQLite • Docker • pytest
+**Pattern**: Routes → Services → Database (layered architecture)
 **Philosophy**: Learning-focused PoC emphasizing async/await and type safety
 
 ## 📐 Core Conventions
@@ -21,7 +21,7 @@
 
 ## 🏗️ Architecture at a Glance
 
-```
+```text
 Route → Service → Database
   ↓         ↓
 Cache    Session
@@ -31,7 +31,7 @@ Cache    Session
 - **Services**: Async database operations via SQLAlchemy
 - **Database**: SQLite with async support (`aiosqlite`)
 - **Models**: Pydantic for validation, SQLAlchemy for ORM
-- **Cache**: aiocache SimpleMemoryCache (10min/1hr TTL)
+- **Cache**: aiocache SimpleMemoryCache (TTL: 600s / 10 min)
 
 ## ✅ Copilot Should
 
@@ -56,28 +56,26 @@ Cache    Session
 
 ```bash
 # Run with hot reload
-uvicorn main:app --reload --host 0.0.0.0 --port 8000
+uvicorn main:app --reload --host 0.0.0.0 --port 9000
 
 # Test with coverage
 pytest --cov=. --cov-report=term-missing
 
 # Docker
 docker compose up
 
-# Swagger: http://localhost:8000/docs
+# Swagger: http://localhost:9000/docs
 ```
 
 ## 📚 Need More Detail?
 
-**For operational procedures**: Load `#file:AGENTS.md`  
-**For Docker expertise**: *(Planned)* `#file:SKILLS/docker-containerization/SKILL.md`  
+**For operational procedures**: Load `#file:AGENTS.md`
+**For Docker expertise**: *(Planned)* `#file:SKILLS/docker-containerization/SKILL.md`
 **For testing patterns**: *(Planned)* `#file:SKILLS/testing-patterns/SKILL.md`
 
 ---
 
 💡 **Why this structure?** Copilot auto-loads this file on every chat (~500 tokens). Loading `AGENTS.md` or `SKILLS/` explicitly gives you deep context only when needed, saving 80% of your token budget!
-5. **Caching**: In-memory cache (10 min TTL) with `X-Cache` headers (HIT/MISS)
-6. **Async/Await**: All database operations are async
 
 ## Coding Guidelines
 
@@ -93,13 +91,15 @@ docker compose up
 ### File Exclusions
 
 Black and flake8 exclude:
+
 - `.venv`, `.git`, `.github`, `.pytest_cache`, `__pycache__`
 - `assets/`, `htmlcov/`, `postman_collections/`, `scripts/`, `storage/`
 - Exception: `tests/test_main.py` allows E501 (long lines for test names)
 
 ### Commit Conventions
 
 Follow **Conventional Commits** (enforced by commitlint):
+
 - `feat:` for new features
 - `fix:` for bug fixes
 - `chore:` for maintenance/tooling
@@ -163,17 +163,18 @@ docker compose down -v
 
 ## API Endpoints
 
-| Method | Path                                | Description                  | Cache |
-|--------|-------------------------------------|------------------------------|-------|
-| GET    | `/health`                           | Health check                 | No    |
-| GET    | `/players/`                         | Get all players              | Yes   |
-| GET    | `/players/{player_id}`              | Get player by ID             | No    |
-| GET    | `/players/squadnumber/{squad_number}` | Get player by squad number | No    |
-| POST   | `/players/`                         | Create new player            | Clears|
-| PUT    | `/players/{player_id}`              | Update existing player       | Clears|
-| DELETE | `/players/{player_id}`              | Delete player                | Clears|
+| Method | Path                                 | Description                  | Cache |
+|--------|--------------------------------------|------------------------------|-------|
+| GET    | `/health`                            | Health check                 | No    |
+| GET    | `/players/`                          | Get all players              | Yes   |
+| GET    | `/players/{player_id}`               | Get player by ID             | No    |
+| GET    | `/players/squadnumber/{squad_number}`| Get player by squad number   | No    |
+| POST   | `/players/`                          | Create new player            | Clears|
+| PUT    | `/players/{player_id}`               | Update existing player       | Clears|
+| DELETE | `/players/{player_id}`               | Delete player                | Clears|
 
 **Cache Notes**:
+
 - Cache key: `"players"`, TTL: 600s (10 min)
 - Cache is cleared on POST/PUT/DELETE operations
 - Response header `X-Cache: HIT` or `MISS` indicates cache status
@@ -189,6 +190,7 @@ docker compose down -v
 ## CI/CD Pipeline
 
 GitHub Actions workflow (`.github/workflows/python-app.yml`):
+
 1. **Lint Job**: Commitlint → Flake8 → Black (check mode)
 2. **Test Job**: pytest with coverage report generation
 3. **Coverage Job**: Upload to Codecov and Codacy (only for same-repo PRs)
@@ -198,18 +200,21 @@ GitHub Actions workflow (`.github/workflows/python-app.yml`):
 ## Common Pitfalls & Solutions
 
 1. **Virtual Environment**: Always activate `.venv` before running black, flake8, or pytest:
+
    ```bash
    source .venv/bin/activate
    ```
 
 2. **FastAPI Route Ordering**: Static routes MUST be defined before dynamic path parameters. Place `/players/statistics` before `/players/{player_id}`, or FastAPI will try to parse "statistics" as a player_id.
+
    ```python
    # CORRECT order:
    @api_router.get("/players/statistics")  # Static route first
    @api_router.get("/players/{player_id}") # Dynamic route after
    ```
 
 3. **SQLAlchemy 2.0 Migration**: Use `select()` not `session.query()`. Example:
+
    ```python
    statement = select(Player).where(Player.id == player_id)
    result = await async_session.execute(statement)
@@ -220,6 +225,7 @@ GitHub Actions workflow (`.github/workflows/python-app.yml`):
 5. **Cache Invalidation**: Remember to call `await simple_memory_cache.clear(CACHE_KEY)` after mutations (POST/PUT/DELETE).
 
 6. **Pydantic Model Conversion**: Use `player_model.model_dump()` to convert Pydantic to dict for SQLAlchemy:
+
    ```python
    player = Player(**player_model.model_dump())
    ```
@@ -231,11 +237,13 @@ GitHub Actions workflow (`.github/workflows/python-app.yml`):
 ## VS Code Configuration
 
 Recommended extensions (`.vscode/extensions.json`):
+
 - `ms-python.python`, `ms-python.flake8`, `ms-python.black-formatter`
 - `github.vscode-pull-request-github`, `github.vscode-github-actions`
 - `ms-azuretools.vscode-containers`, `sonarsource.sonarlint-vscode`
 
 Settings (`.vscode/settings.json`):
+
 - Auto-format on save with Black
 - Pytest enabled (not unittest)
 - Flake8 integration with matching CLI args
@@ -245,6 +253,6 @@ Settings (`.vscode/settings.json`):
 
 - **Postman Collection**: `postman_collections/python-samples-fastapi-restful.postman_collection.json`
 - **Architecture Diagram**: `assets/images/structure.svg`
-- **FastAPI Docs**: https://fastapi.tiangolo.com/
-- **SQLAlchemy 2.0**: https://docs.sqlalchemy.org/en/20/
-- **Conventional Commits**: https://www.conventionalcommits.org/
+- **FastAPI Docs**: <https://fastapi.tiangolo.com/>
+- **SQLAlchemy 2.0**: <https://docs.sqlalchemy.org/en/20/>
+- **Conventional Commits**: <https://www.conventionalcommits.org/>

AGENTS.md

@@ -1,8 +1,8 @@
 # AGENTS.md
 
-> **⚡ Token Efficiency Note**: This file contains complete operational instructions (~2,500 tokens).  
-> **Auto-loaded**: NO (load explicitly with `#file:AGENTS.md` when you need detailed procedures)  
-> **When to load**: Complex workflows, troubleshooting, CI/CD setup, detailed architecture questions  
+> **⚡ Token Efficiency Note**: This file contains complete operational instructions (~2,500 tokens).
+> **Auto-loaded**: NO (load explicitly with `#file:AGENTS.md` when you need detailed procedures)
+> **When to load**: Complex workflows, troubleshooting, CI/CD setup, detailed architecture questions
 > **Related files**: See `#file:.github/copilot-instructions.md` for quick context (auto-loaded, ~500 tokens)
 
 ---
@@ -12,7 +12,7 @@
 ```bash
 # Install all dependencies
 pip install -r requirements.txt
-pip install -r requirements-lint.txt  
+pip install -r requirements-lint.txt
 pip install -r requirements-test.txt
 
 # Start development server
@@ -62,11 +62,13 @@ black .
 ```
 
 **Pre-commit checklist**:
+
 1. Run `flake8 .` - must pass with no errors
 2. Run `black --check .` - must pass with no formatting changes needed (or run `black .` to auto-fix)
 3. Run `pytest --cov=./ --cov-report=term` - all tests must pass
 
 **Style rules** (enforced by Black + Flake8):
+
 - Line length: 88 characters
 - Target: Python 3.13
 - Black configuration in `pyproject.toml`
@@ -123,11 +125,13 @@ curl http://localhost:9000/health
 **Trigger**: Push to `master` or PR to `master`
 
 **Jobs**:
+
 1. **Lint**: Commit messages (commitlint) → Flake8 → Black check
 2. **Test**: pytest with verbose output → coverage report generation
 3. **Coverage**: Upload to Codecov and Codacy (requires secrets)
 
 **Local validation** (run this before pushing):
+
 ```bash
 # Matches CI exactly
 flake8 . && \
@@ -141,12 +145,14 @@ pytest --cov=./ --cov-report=xml --cov-report=term
 **Trigger**: Version tags in format `v{MAJOR}.{MINOR}.{PATCH}-{COACH}`
 
 Example:
+
 ```bash
 git tag -a v1.0.0-ancelotti -m "Release 1.0.0 - Ancelotti"
 git push origin v1.0.0-ancelotti
 ```
 
 **Pipeline automatically**:
+
 - Runs full test suite with coverage
 - Builds multi-stage Docker image
 - Pushes to GHCR with multiple tags (version, coach name, latest)
@@ -159,7 +165,7 @@ git push origin v1.0.0-ancelotti
 
 **Structure**: Layered architecture (Routes → Services → Database)
 
-```
+```text
 routes/          # FastAPI endpoints with caching
   ├── player_route.py    # CRUD endpoints
   └── health_route.py    # Health check
@@ -183,6 +189,7 @@ tests/           # Test suite
 ```
 
 **Key patterns**:
+
 - Dependency injection: `AsyncSession` via `Depends(generate_async_session)`
 - Async everywhere: SQLAlchemy async, aiocache, FastAPI async endpoints
 - Pydantic validation: Request/response with camelCase aliasing
@@ -192,12 +199,14 @@ tests/           # Test suite
 ## Troubleshooting
 
 ### Port already in use
+
 ```bash
 # Kill process on port 9000
 lsof -ti:9000 | xargs kill -9
 ```
 
 ### Module import errors
+
 ```bash
 # Ensure all dependencies installed
 pip install -r requirements.txt -r requirements-lint.txt -r requirements-test.txt
@@ -207,6 +216,7 @@ python --version  # Should be 3.13.3
 ```
 
 ### Database locked errors
+
 ```bash
 # Stop all running instances
 pkill -f uvicorn
@@ -216,6 +226,7 @@ rm storage/players.db
 ```
 
 ### Docker issues
+
 ```bash
 # Clean slate
 docker compose down -v
@@ -226,12 +237,15 @@ docker compose up
 ## Testing the API
 
 ### Using FastAPI Docs (Recommended)
-Open http://localhost:9000/docs - Interactive Swagger UI with "Try it out" buttons
+
+Open <http://localhost:9000/docs> - Interactive Swagger UI with "Try it out" buttons
 
 ### Using Postman
+
 Pre-configured collection available in `postman_collections/`
 
 ### Using curl
+
 ```bash
 # Health check
 curl http://localhost:9000/health