BOX-API-SPEC: Add UI/API design principle\n\nUI surfaces allow agent creativity but clearly steer toward API.\nThe UI teaches, the API is the source of truth.

docs/BOX-API-SPEC.md

@@ -482,3 +482,49 @@ This enables:
 - Building dashboards (box UI shows job DMs separately from chat)
 - Audit trails (which jobs were sent, when, to whom)
 - Agent learning (which job types succeed/fail)
+
+## Design Principle: UI for Creativity, API for Steering
+
+The box UI surfaces allow agent creativity but clearly steer toward the API.
+
+**What this means:**
+
+1. **UI empowers exploration**: The web UI lets humans (and curious agents)
+   browse timers, see job definitions, view logs, and understand the system.
+   It's a learning tool.
+
+2. **API is the source of truth**: All UI actions call the same API endpoints
+   that agents use. There is no hidden functionality. If the UI can do it,
+   an agent can do it via API.
+
+3. **UI steers toward API**: Every UI action shows its API equivalent.
+   - Timer creation form has a "View as curl" button
+   - Job list shows the `GET /api/box/jobs` endpoint used
+   - Error messages suggest the API call to debug
+
+4. **Creativity within bounds**: Agents can:
+   - Create novel job combinations via API (creativity)
+   - But must use the defined job schema (steering)
+   - Can chain jobs in unexpected ways (creativity)
+   - But must respect rate limits and auth (steering)
+
+5. **No UI-only features**: If a feature exists in UI, it MUST exist in API.
+   This prevents agents from being second-class citizens.
+
+**Example UI pattern:**
+
+```
+[Create Timer]
+Job YAML: [textarea]
+[Validate] [Create]
+
+API equivalent:
+  curl -X POST -H "Authorization: Bearer $TOKEN" \
+    -H "Content-Type: application/yaml" \
+    --data-binary @job.yaml \
+    https://box.muse-dev.online/api/box/timers
+```
+
+The UI teaches the API. Agents learn by watching UI actions, then automate
+via API directly. This is how we "teach and learn to schedule" — the UI
+is the classroom, the API is the workshop.