docs: document site template architecture and APIs

- add architecture notes for backend/app/sites layer
- document agent template-awareness behavior
- add /api/sites endpoint usage examples in API docs

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

docs/agents.md

@@ -27,6 +27,7 @@ Explores pages and search results:
 - URL prioritization
 - Link traversal policy
 - Page relevance scoring
+- Site-template lookup (`/api/sites/match`) for domain-specific guidance
 
 ### 3. Extractor Agent
 
@@ -66,11 +67,19 @@ Cons: weaker specialization.
 Coordinator delegates work:
 
 1. Planner emits execution graph
-2. Navigator discovers candidate pages
+2. Navigator discovers candidate pages and loads site templates
 3. Extractor parses and emits data
 4. Verifier validates outputs
 5. Memory Agent stores reusable patterns
 
+## Site Template Awareness
+
+Agents can reference inbuilt templates from `backend/app/sites/`:
+
+- Planner resolves template context early (site id, strategy, output fields)
+- Navigator refreshes template context per URL
+- Execution steps include template provenance (`site_template` action)
+
 Pros: modular, robust, scalable.
 Cons: coordination overhead.
 

docs/api.md

@@ -898,4 +898,25 @@ async for chunk in api.generate_stream(prompt="...", model="claude-3-5-sonnet"):
 
 ---
 
+## Site Template APIs
+
+The backend now exposes inbuilt site templates for agent orchestration:
+
+- `GET /api/sites`  
+  Returns full template catalog (50+ domains).
+- `GET /api/sites/{site_id}`  
+  Returns one template definition.
+- `POST /api/sites/match`  
+  Resolves best template from `instructions` + `assets`.
+
+Example:
+
+```bash
+curl -X POST http://localhost:8000/api/sites/match \
+  -H "Content-Type: application/json" \
+  -d "{\"instructions\":\"get trending communities\",\"assets\":[\"https://reddit.com\"]}"
+```
+
+---
+
 **Next:** See [mcp.md](./mcp.md) for MCP server integration.

docs/architecture.md

@@ -69,6 +69,15 @@ Responsibilities:
 - lazy installation
 - composition workflows
 
+### 3.5 Site Template Layer
+
+Responsibilities:
+
+- maintain inbuilt domain templates (`backend/app/sites/`)
+- map instructions/assets to known site behavior
+- provide reusable navigation goals/fields for planner and navigator agents
+- expose template catalog through `/api/sites*` endpoints
+
 ### 4. Data Plane
 
 Responsibilities:
@@ -127,6 +136,15 @@ Task queue supports:
 - Logs/metrics: append-only time-series-friendly sink
 - Exports: JSON/CSV trace packs
 
+## Backend Folder Notes (Template System)
+
+```text
+backend/app/sites/
+  - models.py      # SiteTemplate dataclass
+  - templates.py   # 50+ inbuilt site templates
+  - registry.py    # list/get/match/serialize helpers
+```
+
 ## Reliability
 
 - per-tool timeout and retry