chore: import upstream snapshot with attribution

docs/api/README.md

@@ -0,0 +1,91 @@
+# API Directory - Documentation
+
+This directory contains **static files** for the Claude Code Templates project deployed on Vercel.
+
+## 📁 Structure Overview
+
+```
+docs/api/
+├── README.md     # This file
+└── agents.json   # Static JSON file for agent queries
+```
+
+## 🔍 Why This Structure?
+
+The project uses **TWO separate API directories**:
+
+### 1. `/api/` (Root) - Serverless Functions ✅
+```
+/api/
+├── track-download-supabase.js     # Serverless function
+└── package.json                   # Dependencies
+```
+
+- **Purpose:** Vercel serverless functions (Edge Functions)
+- **Auto-detected by Vercel:** Functions in `/api/` are automatically deployed
+- **Runtime:** Node.js with ES Modules
+- **URL:** `https://www.aitmpl.com/api/track-download-supabase`
+
+### 2. `/docs/api/` - Static Files ✅
+```
+/docs/api/
+├── README.md      # This documentation
+└── agents.json    # Static data file
+```
+
+- **Purpose:** Static JSON files served with the frontend
+- **Served from:** `outputDirectory: "docs"` in `vercel.json`
+- **URL:** `https://www.aitmpl.com/api/agents.json`
+
+## ⚠️ Important: Why Two Directories?
+
+Vercel has a specific requirement:
+- **Serverless functions MUST be in `/api/`** at the project root
+- **Static files can be in `/docs/api/`** when using `outputDirectory: "docs"`
+
+You **cannot** put serverless functions in `/docs/api/` - Vercel will serve them as static HTML files instead of executing them.
+
+---
+
+## 📄 Files in This Directory
+
+### `agents.json` (Static File)
+- **Type:** Static JSON data
+- **Purpose:** Contains the list of available agents for the frontend
+- **Accessed by:** Frontend application via fetch
+- **URL:** `https://www.aitmpl.com/api/agents.json`
+- **Size:** ~25KB
+- **Updates:** Generated by `/scripts/generate_components_json.py` script
+
+**Usage:**
+```javascript
+fetch('https://www.aitmpl.com/api/agents.json')
+  .then(res => res.json())
+  .then(data => console.log(data));
+```
+
+---
+
+## 🔗 Related Files
+
+### Serverless Functions (in `/api/`)
+
+See `/api/README.md` for documentation on:
+- `track-download-supabase.js` - Download tracking endpoint
+- Environment variables required
+- Request/response formats
+- Database schema
+
+---
+
+## 📝 Best Practices
+
+1. **Static Files:** Keep in `/docs/api/`
+2. **Serverless Functions:** Keep in `/api/` (root)
+3. **Never Mix:** Don't put serverless functions in `/docs/api/`
+4. **Version Control:** Commit both directories separately
+
+---
+
+**Last Updated:** October 22, 2025
+**Maintained by:** Claude Code Templates Team