Merge pull request #12 from Molecule-AI/docs/canvas-features-751-759

docs(canvas): A2A topology overlay and audit trail panel

content/docs/api-reference.mdx

@@ -232,10 +232,50 @@ Activity logging and search for A2A communications, task updates, and agent logs
 
 | Method | Path | Auth | Description |
 |--------|------|------|-------------|
-| GET | `/workspaces/:id/activity` | WorkspaceAuth | List activity logs for a workspace. Supports `?source=canvas` or `?source=agent` filter. |
+| GET | `/workspaces/:id/activity` | WorkspaceAuth | List activity logs for a workspace. Supports `?source=canvas` or `?source=agent` filter, and `?type=delegation` for A2A topology overlay polling. |
 | POST | `/workspaces/:id/activity` | WorkspaceAuth | Log an activity entry (used by workspace runtimes to self-report). |
 | POST | `/workspaces/:id/notify` | WorkspaceAuth | Agent-to-user push message via WebSocket. Delivers a notification to connected Canvas clients. |
 
+---
+
+## Audit Ledger
+
+Tamper-evident audit trail for workspace events. Used by the Canvas Audit Trail panel.
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/workspaces/:id/audit` | WorkspaceAuth | List audit entries for a workspace. Supports `?event_type=delegation\|decision\|gate\|hitl`, `?cursor=<cursor>`, and `?limit=<n>` (default 50). |
+
+### Audit entry schema
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique entry ID |
+| `event_type` | string | `delegation`, `decision`, `gate`, or `hitl` |
+| `actor` | string | Workspace ID that generated the event |
+| `summary` | string | Human-readable event description |
+| `chain_valid` | bool | `false` if the entry's hash does not match the prior chain — indicates possible tampering |
+| `created_at` | string (ISO 8601) | Event timestamp |
+| `cursor` | string \| null | Opaque pagination cursor; `null` when there are no more entries |
+
+Example response:
+
+```json
+{
+  "entries": [
+    {
+      "id": "aud_xyz789",
+      "event_type": "delegation",
+      "actor": "ws_abc123",
+      "summary": "Delegated task 'fix CI' to Backend Engineer",
+      "chain_valid": true,
+      "created_at": "2026-04-17T14:05:00Z"
+    }
+  ],
+  "cursor": "eyJpZCI6ImF1ZF94eXo3ODkifQ"
+}
+```
+
 ### Session Search
 
 | Method | Path | Auth | Description |

content/docs/concepts.mdx

@@ -138,6 +138,38 @@ The canvas isn't just a viewer — it's the operator surface. Drag nodes
 to reorganise teams, click to chat, right-click for actions, watch the
 team work in real time.
 
+### A2A Topology Overlay
+
+The canvas renders **live delegation edges** on top of the workspace graph.
+When one agent delegates to another, a directed edge appears:
+
+- **Animated violet** — delegation occurred within the last 5 minutes
+- **Static blue** — delegation occurred earlier
+
+The overlay polls `GET /workspaces/:id/activity?type=delegation` for every
+visible node every 60 seconds. Toggle it on/off with the **A2A** button in
+the toolbar (⊞ mesh icon) — the setting persists across page loads.
+
+### Audit Trail Panel
+
+Every workspace's **Side Panel → Audit** tab (⊟ ledger icon) shows the
+workspace's tamper-evident audit ledger via `GET /workspaces/:id/audit`.
+Each entry records what happened (event type, actor, outcome) and whether
+its hash chain is intact.
+
+| Event type | Colour | Meaning |
+|-----------|--------|---------|
+| `delegation` | Blue | An A2A delegation was made or received |
+| `decision` | Violet | A gate or approval decision was recorded |
+| `gate` | Yellow | A HITL or automated gate was evaluated |
+| `hitl` | Orange | A human-in-the-loop approval request |
+
+Entries with `chain_valid: false` display a red ⚠ tamper indicator —
+investigate immediately; the audit chain may have been modified offline.
+
+Use the event-type filter bar at the top of the panel to narrow results.
+Click **Load more** to paginate (cursor-based, 50 entries per page).
+
 ## How they fit together
 
 A typical org definition: