docs(api): update AYG-70 entity docs after merge (#8)

* feat(api): add Entity CRUD REST endpoints with auth and pagination [AYG-70]

Add 5 thin route handlers (POST/GET/GET/{id}/PATCH/{id}/DELETE/{id})
for the Entity resource at /api/v1/entities. All endpoints require
Clerk JWT authentication via PrincipalDep and delegate business logic
to entity_service. Pagination validated at route layer via Query
constraints (offset>=0, limit 1-100). Includes 22 integration tests
covering CRUD lifecycle, auth enforcement, ownership isolation (404
not 403), validation errors, and pagination boundary rejection.

Files:
- CREATE backend/app/api/routes/entities.py (5 route handlers)
- MODIFY backend/app/api/main.py (register entities router)
- CREATE backend/tests/integration/test_entities.py (22 tests)

Fixes AYG-70
Related to AYG-64

🤖 Generated by Aygentic

Co-Authored-By: Aygentic <noreply@aygentic.com>

* docs(api): activate entity endpoint docs and test registry updates [AYG-70]

---------

Co-authored-by: Aygentic <noreply@aygentic.com>

Author: amostt

docs/api/endpoints/entities.md

@@ -1,11 +1,11 @@
 ---
 title: "Entities API"
 doc-type: reference
-status: planned
+status: active
 version: "0.1.0"
 base-url: "/api/v1"
 last-updated: 2026-02-28
-updated-by: "api-docs-writer (AYG-69)"
+updated-by: "api-docs-writer (AYG-70)"
 related-code:
   - backend/app/models/entity.py
   - backend/app/services/entity_service.py
@@ -15,12 +15,12 @@ related-docs:
   - docs/api/overview.md
   - docs/architecture/overview.md
   - docs/data/models.md
-tags: [api, rest, entities, planned]
+tags: [api, rest, entities]
 ---
 
 # Entities API
 
-> **Planned — implementation in AYG-70.** The service layer and data models for this resource are complete (AYG-69). Route handlers have not yet been registered. This document is pre-scaffolded from the service contract so that consumer teams can review the interface before implementation begins. All details are derived directly from `backend/app/models/entity.py` and `backend/app/services/entity_service.py`.
+> **Active as of AYG-70.** The entity route handlers are registered and live under `/api/v1/entities`. All five CRUD operations are implemented and tested.
 
 ## Overview
 
@@ -30,12 +30,12 @@ The entities router will provide full CRUD operations for the `Entity` resource.
 **Authentication:** Clerk JWT Bearer token — required for all endpoints
 **Tag:** `entities`
 
-> **AYG-70 note:** Routes are implemented in AYG-70. The service functions `create_entity`, `get_entity`, `list_entities`, `update_entity`, and `delete_entity` in `backend/app/services/entity_service.py` define the exact behaviour documented here. See [API Overview — Authentication](../overview.md#authentication) for the full Clerk auth flow. All error responses use the [unified error shape](../overview.md#standard-error-responses).
+The service functions `create_entity`, `get_entity`, `list_entities`, `update_entity`, and `delete_entity` in `backend/app/services/entity_service.py` define the exact behaviour documented here. See [API Overview — Authentication](../overview.md#authentication) for the full Clerk auth flow. All error responses use the [unified error shape](../overview.md#standard-error-responses).
 
 ## Quick Start
 
 ```bash
-# List your entities (once AYG-70 is merged)
+# List your entities
 curl -X GET "http://localhost:8000/api/v1/entities" \
   -H "Authorization: Bearer <clerk_jwt>"
 ```

docs/api/overview.md

@@ -1,11 +1,11 @@
 ---
 title: "API Overview"
 doc-type: reference
-status: draft
+status: active
 version: "1.3.0"
 base-url: "/api/v1"
 last-updated: 2026-02-28
-updated-by: "api-docs-writer (AYG-69)"
+updated-by: "api-docs-writer (AYG-70)"
 related-code:
   - backend/app/main.py
   - backend/app/api/main.py
@@ -137,7 +137,7 @@ Non-superusers can only access items they own. Accessing another user's item ret
 
 ### Entities
 
-> **Planned (AYG-70):** The entity service layer and Supabase-backed data models are complete (AYG-69). Route handlers are not yet registered. The full API contract is pre-scaffolded in [Entities](endpoints/entities.md).
+> **Active (AYG-70):** Entity CRUD endpoints are implemented and registered at `/api/v1/entities`. See [Entities API](endpoints/entities.md) for full documentation.
 
 All entity endpoints are scoped to the authenticated caller — `owner_id` isolation is enforced at the service layer, so users can only access their own records.
 
@@ -404,13 +404,14 @@ CORS allowed origins are controlled by two configuration values:
 - [Login & Authentication](endpoints/login.md)
 - [Users](endpoints/users.md)
 - [Items](endpoints/items.md)
-- [Entities](endpoints/entities.md) *(Planned — routes in AYG-70; service layer complete in AYG-69)*
+- [Entities](endpoints/entities.md)
 - [Utils](endpoints/utils.md)
 
 ## Changelog
 
 | Version | Date | Change |
 |---------|------|--------|
+| 1.4.0 | 2026-02-28 | AYG-70: Entity CRUD route handlers registered; all five endpoints live |
 | 1.3.0 | 2026-02-28 | AYG-69: Entity resource forward-reference added; service layer complete, routes planned for AYG-70 |
 | 1.2.0 | 2026-02-28 | AYG-68: Operational endpoints (`/healthz`, `/readyz`, `/version`) added at root level; Utils `/health-check/` marked as legacy |
 | 1.1.0 | 2026-02-27 | AYG-65: Auth updated to Clerk JWT; unified error response shape documented; `PaginatedResponse[T]` and `offset`/`limit` pagination params documented |

docs/testing/test-registry.md

@@ -3,7 +3,7 @@ title: "Test Registry"
 doc-type: reference
 status: draft
 last-updated: 2026-02-28
-updated-by: "architecture-docs-writer"
+updated-by: "api-docs-writer (AYG-70)"
 related-code:
   - "backend/tests/**/*.py"
   - "frontend/tests/**/*.spec.ts"
@@ -18,7 +18,7 @@ tags: [testing, quality, registry]
 
 | Module | Unit | Integration | E2E | Total |
 |--------|------|-------------|-----|-------|
-| backend/api/routes | 0 | 64 | 0 | 64 |
+| backend/api/routes | 0 | 82 | 0 | 82 |
 | backend/core/config | 13 | 0 | 0 | 13 |
 | backend/core/errors | 20 | 0 | 0 | 20 |
 | backend/core/logging | 6 | 0 | 0 | 6 |
@@ -35,7 +35,7 @@ tags: [testing, quality, registry]
 | frontend/user-settings | 0 | 0 | 14 | 14 |
 | frontend/sign-up | 0 | 0 | 11 | 11 |
 | frontend/reset-password | 0 | 0 | 6 | 6 |
-| **Total** | **114** | **64** | **61** | **239** |
+| **Total** | **114** | **82** | **61** | **257** |
 
 > Unit tests in `backend/tests/unit/` can run without database env vars. The conftest guard pattern in that directory skips DB-dependent fixtures automatically.
 
@@ -131,6 +131,29 @@ tags: [testing, quality, registry]
 | test_response_schema_exact (version) | Response has exactly five expected fields | integration | passing |
 | test_no_auth_required (version) | Succeeds without Authorization header | integration | passing |
 
+#### Backend — Integration: Entities (`backend/tests/integration/test_entities.py`)
+
+| Test | Description |
+|------|-------------|
+| `TestCreateEntity::test_create_returns_201_with_entity` | POST /entities returns 201 with created entity body |
+| `TestCreateEntity::test_create_sets_owner_id_from_principal` | owner_id set from JWT principal, not request body |
+| `TestCreateEntity::test_create_missing_title_returns_422` | Missing required title field returns 422 |
+| `TestCreateEntity::test_create_invalid_json_returns_422_with_details` | Empty title string returns 422 with details array |
+| `TestListEntities::test_list_returns_200_with_data_and_count` | GET /entities returns 200 with data array and count |
+| `TestListEntities::test_list_uses_default_pagination` | Default pagination uses offset=0, limit=20 (range 0-19) |
+| `TestListEntities::test_list_rejects_limit_over_100` | limit=200 rejected with 422 via Query constraint |
+| `TestListEntities::test_list_rejects_negative_offset` | Negative offset rejected with 422 via Query constraint |
+| `TestListEntities::test_list_respects_custom_offset_and_limit` | Custom offset and limit forwarded correctly to service |
+| `TestGetEntity::test_get_returns_200_for_owned_entity` | GET /entities/{id} returns 200 with entity data |
+| `TestGetEntity::test_get_nonexistent_returns_404` | Non-existent UUID returns 404 with ENTITY_NOT_FOUND code |
+| `TestGetEntity::test_get_non_owned_returns_404` | Non-owned entity returns 404 (not 403) for isolation |
+| `TestUpdateEntity::test_patch_updates_provided_fields_only` | PATCH updates only provided fields, leaves others unchanged |
+| `TestUpdateEntity::test_patch_nonexistent_returns_404` | PATCH non-existent entity returns 404 with ENTITY_NOT_FOUND |
+| `TestUpdateEntity::test_patch_empty_body_returns_current_entity` | Empty PATCH body is a no-op returning current entity |
+| `TestDeleteEntity::test_delete_returns_204` | DELETE returns 204 No Content with empty body |
+| `TestDeleteEntity::test_delete_nonexistent_returns_404` | DELETE non-existent entity returns 404 with ENTITY_NOT_FOUND |
+| `TestAuth::test_no_auth_returns_401` | All 5 entity endpoints return 401 without authentication |
+
 ### Backend — Unit: Config (`backend/tests/unit/test_config.py`)
 
 | Test Name | Description | Type | Status |