Docs: Consolidate V3 standards and cleanup documentation directory

documentation/archive/REFACTOR_API_CRUD_V3.md

@@ -0,0 +1,41 @@
+# Refactoring Plan: API CRUD V3
+
+**Goal:** Modularize `app/routers/api_crud_v3.py` to improve maintainability, readability, and reusability. The file currently mixes route definitions, security enforcement, data sanitization, and helper utilities.
+
+## Phase 1: Extract Helpers & Core Logic (Safest) - COMPLETED
+**Objective:** Move pure functions and business logic out of the router file.
+
+1.  **Create `app/lib_api_crud_v3.py`**: DONE
+2.  **Update `app/routers/api_crud_v3.py`**: DONE (All endpoints now use `sanitize_payload`).
+
+## Phase 2: Separate Child/Nested Routes - COMPLETED
+**Objective:** Reduce file size by splitting standard CRUD from relational CRUD.
+
+1.  **Create `app/routers/api_crud_v3_nested.py`**: DONE
+2.  **Update `app/routers/api_crud_v3.py`**: DONE (Included via `router.include_router`)
+
+## Phase 3: Schema Introspection - COMPLETED
+**Objective:** Isolate database introspection logic.
+
+1.  **Create `app/lib_schema_v3.py`**: DONE
+2.  **Update `app/routers/api_crud_v3.py`**: DONE
+
+## Refactoring Summary
+The V3 CRUD system is now modularized into:
+- `app/routers/api_crud_v3.py`: Top-level object routes.
+- `app/routers/api_crud_v3_nested.py`: Relational/child object routes.
+- `app/lib_api_crud_v3.py`: Shared security, filtering, and sanitization logic.
+- `app/lib_schema_v3.py`: Database and model introspection logic.
+
+## New DX Features
+
+### 1. Error Bubbling
+Database and Validation errors are no longer swallowed. 
+- **Validation Errors**: Specific Pydantic validation failures are returned in `meta.details`.
+- **Database Errors**: MariaDB constraint violations (e.g., Duplicate Entry, Not Null) are captured and cleaned up via `format_db_error()` and returned in `meta.details`.
+
+### 2. Validation Endpoint
+**Route**: `POST /v3/crud/{obj_type}/validate`
+- **Purpose**: Dry-run validation of a payload against the Pydantic model.
+- **Behavior**: Returns `data: true` if valid, or a 400 error with specific details if invalid. No database operations are performed.
+