docs: add docs/agent-runtime/agent-card.md

content/docs/agent-runtime/agent-card.md

@@ -0,0 +1,84 @@
+# Agent Card
+
+Every workspace publishes an Agent Card at `/.well-known/agent-card.json`. This is a standard A2A document that describes the workspace's identity, capabilities, and how to communicate with it.
+
+## Example
+
+```json
+{
+  "name": "Reno Stars SEO Agent",
+  "description": "Bilingual EN/ZH SEO page builder for Vancouver renovation companies",
+  "version": "1.2.0",
+  "url": "https://seo-agent.reno-stars.com",
+  "capabilities": {
+    "streaming": true,
+    "pushNotifications": true
+  },
+  "defaultInputModes": ["text/plain", "application/json"],
+  "defaultOutputModes": ["text/plain", "application/json", "text/html"],
+  "skills": [
+    {
+      "id": "generate_seo_page",
+      "name": "Generate SEO Landing Page",
+      "description": "Creates a bilingual EN/ZH Next.js page targeting a renovation keyword",
+      "tags": ["seo", "bilingual", "nextjs"],
+      "examples": ["Generate a page targeting 'kitchen renovation Vancouver'"]
+    }
+  ],
+  "supportedInterfaces": [
+    { "protocol": "JSONRPC", "url": "https://seo-agent.reno-stars.com/a2a" }
+  ]
+}
+```
+
+## How the Agent Card Is Used
+
+### By the Platform
+- The platform reads the card when a workspace registers
+- Stores the full card in Postgres (`workspaces.agent_card` JSONB column)
+- Caches the workspace URL in Redis for fast resolution
+
+### By the Canvas
+- The canvas renders node UI **directly from the card**
+- Node title comes from `name`
+- Skill badges come from `skills[].name`
+- Input/output port types come from `defaultInputModes` / `defaultOutputModes`
+
+### By Peer Workspaces (Automatic Skill Injection)
+
+When a workspace builds its system prompt, it pulls Agent Cards from all reachable peer workspaces (siblings, children, parent) and appends their skill descriptions. This way a calling workspace (e.g. Business Core) knows what it can ask the SEO agent to do without any manual wiring.
+
+The mechanism:
+1. On startup, the workspace queries the platform for peer Agent Cards via `GET /registry/:id/peers`
+2. Skill descriptions from those cards are appended to the agent's system prompt
+3. When a peer updates its card (`AGENT_CARD_UPDATED` event), the workspace rebuilds its system prompt automatically
+
+This means adding a new skill to a workspace makes it immediately available to all reachable peers — no manual wiring, no restarts.
+
+## Lifecycle
+
+1. Workspace container starts
+2. Agent Card is generated from the workspace config
+3. A2A server publishes it at `/.well-known/agent-card.json`
+4. Workspace sends `POST /registry/register` with the card
+5. Platform stores the card in Postgres
+6. Canvas reads the card and renders the node
+
+## Live Updates
+
+When a workspace's skills change at runtime:
+1. Workspace rescans skills folder, rebuilds Agent Card
+2. Workspace sends `POST /registry/update-card` with the new card
+3. Platform stores the updated card, writes `AGENT_CARD_UPDATED` event
+4. Platform broadcasts via WebSocket to **all subscribers** — both canvas clients and peer workspaces
+
+Both canvas clients and workspace agents subscribe to the same platform WebSocket at `/ws`. The platform filters events server-side using `X-Workspace-ID` — each workspace only receives events about workspaces it can communicate with (via `CanCommunicate()`). Canvas clients receive all events (no workspace ID header).
+
+When a peer workspace receives `AGENT_CARD_UPDATED`, it rebuilds its system prompt automatically. When the canvas receives it, it updates the node's skill badges.
+
+## Related Docs
+
+- [Core Concepts](../product/core-concepts.md) — What an Agent Card is
+- [A2A Protocol](../api-protocol/a2a-protocol.md) — How the card fits into A2A
+- [Workspace Runtime](./workspace-runtime.md) — How the card is generated at startup
+- [Canvas UI](../frontend/canvas.md) — How the card drives node rendering