feat: Complete assets proxy implementation with documentation

- Add comprehensive documentation in docs/ASSETS_PROXY.md
- Add contract comments in normalizeAssetUrl and proxy_asset
- Verify all components use normalizeAssetUrl
- Verify ENV variables are correctly set
- Add troubleshooting guide

apps/web/src/lib/utils/assetUrl.ts

@@ -6,6 +6,17 @@
  * 
  * IMPORTANT: Do NOT manually concatenate /api/static anywhere in the codebase.
  * Always use this function instead.
+ * 
+ * CONTRACT with Asset Proxy (/city/assets/proxy/{path}):
+ * 
+ * Input from DB:  https://assets.daarion.space/daarion-assets/microdao/logo/2025/12/02/abc123.png
+ * Output:         /api/city/assets/proxy/microdao/logo/2025/12/02/abc123.png
+ * 
+ * The proxy endpoint receives: microdao/logo/2025/12/02/abc123.png
+ * And prepends ASSETS_BUCKET (daarion-assets) internally.
+ * 
+ * @param url - Asset URL from database (can be MinIO URL, legacy /static/ path, etc.)
+ * @returns Normalized URL for use in <img src> or CSS backgroundImage
  */
 export function normalizeAssetUrl(url: string | null | undefined): string | null {
   if (!url) return null;
@@ -17,6 +28,7 @@ export function normalizeAssetUrl(url: string | null | undefined): string | null
     if (url.includes('assets.daarion.space')) {
       // Extract path after /daarion-assets/: https://assets.daarion.space/daarion-assets/microdao/logo/...
       // Convert to: /api/city/assets/proxy/microdao/logo/...
+      // Note: /daarion-assets/ prefix is removed - proxy will add ASSETS_BUCKET internally
       const match = url.match(/\/daarion-assets\/(.+)$/);
       if (match) {
         return `/api/city/assets/proxy/${match[1]}`;