docs: add UserContext pattern documentation and architecture rules

Documentation:
- docs/architecture/user-context-pattern.md: Comprehensive guide on
  UserContext vs User model, JWT token mapping, common mistakes

Architecture Rules (auth.yaml):
- AUTH-005: Routes must use UserContext, not User model attributes
- AUTH-006: JWT token context fields must be defined in UserContext
- AUTH-007: Response models must match available UserContext data

Architecture Rules (module.yaml):
- MOD-024: Module static file mount order - specific paths first

These rules prevent issues like:
- Accessing SQLAlchemy relationships on Pydantic schemas
- Missing token fields causing fallback warnings
- Response model validation errors from missing timestamps
- 404 errors for module locale files due to mount order

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.architecture-rules/auth.yaml

@@ -61,6 +61,82 @@ auth_rules:
       required_patterns:
         - "require_vendor_context\\(\\)|# public"
 
+  - id: "AUTH-005"
+    name: "Routes must use UserContext, not User model attributes"
+    severity: "error"
+    description: |
+      When using current_user from dependency injection, it is a UserContext
+      (Pydantic schema), NOT a User (SQLAlchemy model). Do not access:
+
+      FORBIDDEN (SQLAlchemy relationships/columns not in UserContext):
+        - current_user.admin_platforms    → Use accessible_platform_ids
+        - current_user.vendors            → Use token_vendor_id
+        - current_user.owned_companies    → Query via service
+        - current_user.hashed_password    → Never needed in routes
+        - current_user.created_at         → Query User if needed
+        - current_user.updated_at         → Query User if needed
+
+      CORRECT ALTERNATIVES:
+        - current_user.accessible_platform_ids  # list[int] | None
+        - current_user.token_platform_id        # Selected platform from JWT
+        - current_user.token_vendor_id          # Vendor from JWT
+        - current_user.is_super_admin           # Boolean
+        - current_user.can_access_platform(id)  # Helper method
+
+      See: docs/architecture/user-context-pattern.md
+    pattern:
+      file_pattern: "app/modules/*/routes/**/*.py"
+      anti_patterns:
+        - "current_user\\.admin_platforms"
+        - "current_user\\.vendors"
+        - "current_user\\.owned_companies"
+        - "current_user\\.hashed_password"
+
+  - id: "AUTH-006"
+    name: "JWT token context fields must be defined in UserContext"
+    severity: "error"
+    description: |
+      When adding new context to JWT tokens, ensure the field is:
+
+      1. Added to UserContext schema (models/schema/auth.py)
+      2. Extracted in verify_token() (middleware/auth.py)
+      3. Attached to User in get_current_user() (middleware/auth.py)
+      4. Copied in UserContext.from_user() method
+
+      Pattern: token_* prefix for JWT-derived fields
+        - token_platform_id, token_platform_code (admin platform context)
+        - token_vendor_id, token_vendor_code, token_vendor_role (vendor context)
+
+      If getattr(current_user, "token_X", None) is needed, the field is missing
+      from UserContext and should be added.
+
+      See: docs/architecture/user-context-pattern.md
+    pattern:
+      file_pattern: "app/modules/*/routes/**/*.py"
+      anti_patterns:
+        - "getattr\\(current_user,\\s*['\"]token_"
+
+  - id: "AUTH-007"
+    name: "Response models must match available UserContext data"
+    severity: "error"
+    description: |
+      When returning user data from endpoints that use UserContext:
+
+      1. Do NOT return LoginResponse(user=current_user) if LoginResponse.user
+         expects UserResponse with created_at/updated_at
+
+      2. Create dedicated response models for different contexts:
+         - LoginResponse: Full user data (from login, has timestamps)
+         - PlatformSelectResponse: Token + platform info (no user data)
+         - TokenRefreshResponse: Just new token data
+
+      3. If user timestamps are needed, query the User model explicitly
+
+      See: docs/architecture/user-context-pattern.md
+    pattern:
+      file_pattern: "app/modules/*/routes/**/*.py"
+      enforcement: "review"
+
 # ============================================================================
 # MULTI-TENANCY RULES
 # ============================================================================

.architecture-rules/module.yaml

@@ -723,3 +723,41 @@ module_rules:
       file_pattern: "app/modules/*/definition.py"
       validates:
         - "router imports -> get_*_with_routers function"
+
+  # =========================================================================
+  # Static File Mounting Rules
+  # =========================================================================
+
+  - id: "MOD-024"
+    name: "Module static file mount order - specific paths first"
+    severity: "error"
+    description: |
+      When mounting module static files in main.py, more specific paths must
+      be mounted BEFORE less specific paths. FastAPI processes mounts in
+      registration order.
+
+      WRONG ORDER (locales 404):
+        # Less specific first - intercepts /static/modules/X/locales/*
+        app.mount("/static/modules/X", StaticFiles(...))
+        # More specific second - never reached!
+        app.mount("/static/modules/X/locales", StaticFiles(...))
+
+      RIGHT ORDER (locales work):
+        # More specific first
+        app.mount("/static/modules/X/locales", StaticFiles(...))
+        # Less specific second - catches everything else
+        app.mount("/static/modules/X", StaticFiles(...))
+
+      This applies to all nested static file mounts:
+        - locales/ must be mounted before static/
+        - img/ or css/ subdirectories must be mounted before parent
+
+      SYMPTOMS OF WRONG ORDER:
+        - 404 errors for nested paths like /static/modules/tenancy/locales/en.json
+        - Requests to subdirectories served as 404 instead of finding files
+
+      See: docs/architecture/user-context-pattern.md (Static File Mount Order section)
+    pattern:
+      file_pattern: "main.py"
+      validates:
+        - "module_locales mount BEFORE module_static mount"