Merged in feature/mutable-metadata1 (pull request #221)

M1, M2 and M3 complete

* M1, M2 and M3 complete

* review changes

* docs

* docs

docs/ai.generated/README.md

@@ -2,9 +2,16 @@
 
 ## Overview
 
-
 This documentation provides comprehensive coverage of the DoczyAI Document Processing Platform - a cloud-native document processing system designed to extract structured information from documents.
 
+## Architecture Diagram
+
+The diagram below shows the full API layer architecture — from HTTP endpoints through middleware, controllers, services, and the repository layer, ending at the database and external services. Request flow runs left to right.
+
+[![Query Orchestration API — Software Architecture Layers](architecture-diagram.png)](architecture-diagram.svg)
+
+*[View scalable SVG version](architecture-diagram.svg)*
+
 ## Documentation Structure
 
 ### 📋 System Documentation
@@ -69,6 +76,17 @@ This documentation provides comprehensive coverage of the DoczyAI Document Proce
     - Watching S3 for client document imports
     - Document recovery from S3 buckets
 
+11. **[Custom Metadata Guide](11-custom-metadata-guide.md)**
+    - Overview: custom schemas vs legacy field extractions
+    - Authorization matrix (super_admin, user_admin, client_user, auditor)
+    - Platform operator workflow: define schema, assign to document
+    - End-user workflow: write, read current, read by version, read history
+    - Schema definition requirements and sample schemas
+    - Schema versioning: how POST .../versions works, status lifecycle
+    - Reset-metadata runbook: schema upgrade flow with metadata wipe warning
+    - Cascade deletion behavior (no special steps needed)
+    - Permit.io deployment note
+
 ## Quick Start
 
 ### For New Developers