@semiont/backend 0.4.20 → 0.4.22

package/dist/openapi.json

@@ -12,303 +12,6 @@
     }
   ],
   "paths": {
-    "/resources/{id}": {
-      "get": {
-        "summary": "Get Resource by URI (W3C Content Negotiation)",
-        "description": "W3C-compliant globally resolvable resource URI with content negotiation. Returns JSON-LD metadata (Accept: application/ld+json), raw representation (Accept: text/plain, text/markdown, etc.), or redirects to frontend (?view=semiont). Requires authentication.",
-        "tags": [
-          "W3C URIs"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string"
-            },
-            "description": "Resource ID"
-          },
-          {
-            "name": "view",
-            "in": "query",
-            "required": false,
-            "schema": {
-              "type": "string",
-              "enum": [
-                "semiont"
-              ]
-            },
-            "description": "Optional view parameter. If set to 'semiont', redirects to frontend viewer."
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Resource metadata (JSON-LD) or raw representation",
-            "content": {
-              "application/ld+json": {
-                "schema": {
-                  "$ref": "#/components/schemas/GetResourceResponse"
-                }
-              },
-              "text/plain": {
-                "schema": {
-                  "type": "string"
-                }
-              },
-              "text/markdown": {
-                "schema": {
-                  "type": "string"
-                }
-              }
-            }
-          },
-          "302": {
-            "description": "Redirect to frontend viewer (when ?view=semiont)"
-          },
-          "404": {
-            "description": "Resource not found"
-          }
-        }
-      },
-      "patch": {
-        "summary": "Update Resource",
-        "description": "Update resource metadata (append-only operations - name and content are immutable)",
-        "tags": [
-          "W3C URIs"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string"
-            },
-            "description": "Resource ID"
-          }
-        ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/UpdateResourceRequest"
-              }
-            }
-          }
-        },
-        "responses": {
-          "202": {
-            "description": "Update accepted"
-          },
-          "404": {
-            "description": "Resource not found"
-          }
-        }
-      }
-    },
-    "/annotations/{id}": {
-      "get": {
-        "summary": "Get Annotation by URI (W3C Content Negotiation)",
-        "description": "W3C-compliant globally resolvable annotation URI with content negotiation. Returns JSON-LD for API clients (Accept: application/ld+json or application/json). Redirects to frontend for browsers (Accept: text/html or browser User-Agent). Requires authentication and resourceId query parameter.",
-        "tags": [
-          "W3C URIs"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string"
-            },
-            "description": "Annotation ID"
-          },
-          {
-            "name": "resourceId",
-            "in": "query",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "format": "uri"
-            },
-            "description": "Resource ID or URI containing the annotation"
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Annotation representation (JSON-LD)",
-            "content": {
-              "application/ld+json": {
-                "schema": {
-                  "$ref": "#/components/schemas/GetAnnotationResponse"
-                }
-              }
-            }
-          },
-          "302": {
-            "description": "Redirect to frontend (for browsers)"
-          },
-          "400": {
-            "description": "Missing resourceId parameter"
-          },
-          "404": {
-            "description": "Annotation not found"
-          }
-        }
-      }
-    },
-    "/api/annotations/{id}/context": {
-      "get": {
-        "summary": "Get Annotation Context",
-        "description": "Get the text context around an annotation with configurable before/after window",
-        "tags": [
-          "Annotations",
-          "Context"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string"
-            },
-            "description": "Annotation ID"
-          },
-          {
-            "name": "resourceId",
-            "in": "query",
-            "required": true,
-            "schema": {
-              "type": "string"
-            },
-            "description": "Resource ID containing the annotation"
-          },
-          {
-            "name": "contextBefore",
-            "in": "query",
-            "required": false,
-            "schema": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 5000,
-              "default": 100
-            },
-            "description": "Number of characters before the selection"
-          },
-          {
-            "name": "contextAfter",
-            "in": "query",
-            "required": false,
-            "schema": {
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 5000,
-              "default": 100
-            },
-            "description": "Number of characters after the selection"
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Annotation context",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/AnnotationContextResponse"
-                }
-              }
-            }
-          },
-          "400": {
-            "description": "Invalid query parameters"
-          },
-          "401": {
-            "description": "Authentication required"
-          },
-          "404": {
-            "description": "Annotation not found"
-          }
-        }
-      }
-    },
-    "/api/annotations/{id}/summary": {
-      "get": {
-        "summary": "Get Annotation Summary",
-        "description": "Get an AI-generated summary of the annotation in context",
-        "tags": [
-          "Annotations",
-          "AI"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string"
-            },
-            "description": "Annotation ID"
-          },
-          {
-            "name": "resourceId",
-            "in": "query",
-            "required": true,
-            "schema": {
-              "type": "string"
-            },
-            "description": "Resource ID containing the annotation"
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "AI-generated annotation summary",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ContextualSummaryResponse"
-                }
-              }
-            }
-          },
-          "400": {
-            "description": "Missing resourceId parameter"
-          },
-          "401": {
-            "description": "Authentication required"
-          },
-          "404": {
-            "description": "Annotation not found"
-          }
-        }
-      }
-    },
     "/api/health": {
       "get": {
         "summary": "Health Check",
@@ -453,7 +156,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/GoogleAuthRequest"
+                  "$ref": "#/components/schemas/TokenRefreshResponse"
                 }
               }
             }
@@ -553,21 +256,91 @@
         }
       }
     },
-    "/api/users/me": {
-      "get": {
-        "summary": "Get Current User",
-        "description": "Get information about the authenticated user",
+    "/api/tokens/worker": {
+      "post": {
+        "summary": "Worker Token Exchange",
+        "description": "Exchange a shared secret for a bearer JWT. Used by workers and actors connecting to the EventBus.",
         "tags": [
-          "Users"
+          "Authentication"
         ],
-        "security": [
-          {
-            "bearerAuth": []
+        "security": [],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "secret": {
+                    "type": "string",
+                    "description": "The shared worker secret (SEMIONT_WORKER_SECRET)"
+                  }
+                },
+                "required": [
+                  "secret"
+                ]
+              }
+            }
           }
-        ],
+        },
         "responses": {
           "200": {
-            "description": "User information",
+            "description": "Token issued",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "token": {
+                      "type": "string",
+                      "description": "Bearer JWT for subsequent authenticated requests"
+                    }
+                  },
+                  "required": [
+                    "token"
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Invalid worker secret",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Worker authentication not configured",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/users/me": {
+      "get": {
+        "summary": "Get Current User",
+        "description": "Get information about the authenticated user",
+        "tags": [
+          "Users"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "User information",
             "content": {
               "application/json": {
                 "schema": {
@@ -1109,12 +882,12 @@
         }
       }
     },
-    "/api/admin/exchange/export": {
+    "/api/moderate/exchange/export": {
       "post": {
         "summary": "Export Knowledge Base as JSON-LD",
         "description": "Export the knowledge base as a JSON-LD Linked Data tar.gz archive",
         "tags": [
-          "Admin"
+          "Moderation"
         ],
         "security": [
           {
@@ -1156,7 +929,7 @@
             }
           },
           "403": {
-            "description": "Forbidden - Admin access required",
+            "description": "Forbidden - moderator or admin role required",
             "content": {
               "application/json": {
                 "schema": {
@@ -1168,12 +941,12 @@
         }
       }
     },
-    "/api/admin/exchange/import": {
+    "/api/moderate/exchange/import": {
       "post": {
         "summary": "Import Knowledge Base from JSON-LD",
         "description": "Import resources from a JSON-LD Linked Data archive. Returns SSE progress events.",
         "tags": [
-          "Admin"
+          "Moderation"
         ],
         "security": [
           {
@@ -1232,7 +1005,7 @@
             }
           },
           "403": {
-            "description": "Forbidden - Admin access required",
+            "description": "Forbidden - moderator or admin role required",
             "content": {
               "application/json": {
                 "schema": {
@@ -1244,299 +1017,138 @@
         }
       }
     },
-    "/resources": {
-      "post": {
-        "summary": "Create Resource",
-        "description": "Create a new resource",
+    "/api/cookies/consent": {
+      "get": {
+        "summary": "Get cookie consent preferences",
+        "description": "Returns the current user's cookie consent preferences.",
         "tags": [
-          "Resources"
+          "Cookies"
         ],
         "security": [
           {
             "bearerAuth": []
           }
         ],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "multipart/form-data": {
-              "schema": {
-                "type": "object",
-                "required": [
-                  "name",
-                  "file",
-                  "format"
-                ],
-                "properties": {
-                  "name": {
-                    "type": "string",
-                    "description": "Resource name"
-                  },
-                  "file": {
-                    "type": "string",
-                    "format": "binary",
-                    "description": "Binary content of the resource"
-                  },
-                  "format": {
-                    "type": "string",
-                    "description": "MIME type (e.g., text/markdown, image/png)"
-                  },
-                  "entityTypes": {
-                    "type": "string",
-                    "description": "JSON-encoded array of entity types"
-                  },
-                  "language": {
-                    "type": "string",
-                    "description": "ISO 639-1 language code"
-                  },
-                  "creationMethod": {
-                    "type": "string",
-                    "description": "How the resource was created"
-                  },
-                  "sourceAnnotationId": {
-                    "type": "string",
-                    "description": "Source annotation ID (for generated resources)"
-                  },
-                  "sourceResourceId": {
-                    "type": "string",
-                    "description": "Source resource ID (for cloned resources)"
-                  }
-                }
-              }
-            }
-          }
-        },
         "responses": {
-          "202": {
-            "description": "Resource creation accepted",
+          "200": {
+            "description": "Current consent preferences",
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "properties": {
-                    "resourceId": {
-                      "type": "string"
-                    }
-                  },
-                  "required": [
-                    "resourceId"
-                  ]
+                  "$ref": "#/components/schemas/CookieConsentResponse"
                 }
               }
             }
-          }
-        }
-      },
-      "get": {
-        "summary": "List Resources",
-        "description": "List all resources with optional filters",
-        "tags": [
-          "Resources"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "number",
-              "nullable": true,
-              "default": 0
-            },
-            "required": false,
-            "name": "offset",
-            "in": "query"
-          },
-          {
-            "schema": {
-              "type": "number",
-              "nullable": true,
-              "default": 50
-            },
-            "required": false,
-            "name": "limit",
-            "in": "query"
-          },
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": false,
-            "name": "entityType",
-            "in": "query"
-          },
-          {
-            "schema": {
-              "anyOf": [
-                {
-                  "type": "string",
-                  "enum": [
-                    "true"
-                  ]
-                },
-                {
-                  "type": "string",
-                  "enum": [
-                    "false"
-                  ]
-                },
-                {
-                  "type": "boolean"
-                }
-              ]
-            },
-            "required": false,
-            "name": "archived",
-            "in": "query"
-          },
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": false,
-            "name": "search",
-            "in": "query"
           },
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": false,
-            "name": "q",
-            "in": "query",
-            "description": "Search query"
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Resources listed successfully",
+          "401": {
+            "description": "Authentication required",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ListResourcesResponse"
+                  "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
             }
           }
         }
-      }
-    },
-    "/resources/{id}/annotate-references": {
+      },
       "post": {
-        "summary": "Annotate References with Progress (SSE)",
-        "description": "Stream real-time reference annotation progress via Server-Sent Events",
+        "summary": "Update cookie consent preferences",
+        "description": "Update the current user's cookie consent preferences. The `necessary` flag must be true — necessary cookies cannot be disabled.",
         "tags": [
-          "Resources",
-          "Annotations",
-          "Real-time"
+          "Cookies"
         ],
         "security": [
           {
             "bearerAuth": []
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          }
-        ],
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/AnnotateReferencesStreamRequest"
+                "$ref": "#/components/schemas/CookieConsentRequest"
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "SSE stream opened successfully",
+            "description": "Consent updated",
             "content": {
-              "text/event-stream": {
+              "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/EventStreamResponse"
+                  "$ref": "#/components/schemas/CookieConsentResponse"
                 }
               }
             }
           },
-          "401": {
-            "description": "Authentication required"
+          "400": {
+            "description": "Invalid consent data (non-boolean fields, missing fields, or necessary=false)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CookieConsentResponse"
+                }
+              }
+            }
           },
-          "404": {
-            "description": "Resource not found"
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
           }
         }
       }
     },
-    "/resources/{id}/annotate-highlights": {
-      "post": {
-        "summary": "Annotate Highlights with Progress (SSE)",
-        "description": "Stream real-time highlight annotation progress via Server-Sent Events",
+    "/api/cookies/export": {
+      "get": {
+        "summary": "Export cookie data (GDPR)",
+        "description": "Export the current user's cookie-related data as a downloadable JSON file. Response sets `Content-Disposition: attachment; filename=\"cookie-data-export-<timestamp>.json\"`.",
         "tags": [
-          "Resources",
-          "Annotations",
-          "Real-time"
+          "Cookies"
         ],
         "security": [
           {
             "bearerAuth": []
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          }
-        ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/AnnotateHighlightsStreamRequest"
-              }
-            }
-          }
-        },
         "responses": {
           "200": {
-            "description": "SSE stream opened successfully",
+            "description": "User cookie data as attachment",
             "content": {
-              "text/event-stream": {
+              "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/EventStreamResponse"
+                  "$ref": "#/components/schemas/CookieExportResponse"
                 }
               }
             }
           },
           "401": {
-            "description": "Authentication required"
-          },
-          "404": {
-            "description": "Resource not found"
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
           }
         }
       }
     },
-    "/resources/{id}/annotate-assessments": {
-      "post": {
-        "summary": "Annotate Assessments with Progress (SSE)",
-        "description": "Stream real-time assessment annotation progress via Server-Sent Events",
+    "/api/tokens/mcp-setup": {
+      "get": {
+        "summary": "MCP Setup (browser-driven CLI handoff)",
+        "description": "Browser flow that generates a long-lived (30 day) MCP refresh token for the authenticated user and redirects to a localhost callback URL with the token as a query parameter. Used by CLI tooling (similar to Google's OAuth CLI flow).\n\nThe callback URL must match one of the localhost patterns (`http://localhost:<port>/...`, `http://127.0.0.1:<port>/...`, or `http://[::1]:<port>/...`).",
         "tags": [
-          "Resources",
-          "Annotations",
-          "Real-time"
+          "Authentication"
         ],
         "security": [
           {
@@ -1545,51 +1157,58 @@
         ],
         "parameters": [
           {
+            "name": "callback",
+            "in": "query",
+            "required": true,
+            "description": "Localhost URL to redirect to with `?token=<refresh-token>` on success.",
             "schema": {
               "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
+            }
           }
         ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/AnnotateAssessmentsStreamRequest"
-              }
-            }
-          }
-        },
         "responses": {
-          "200": {
-            "description": "SSE stream opened successfully",
+          "302": {
+            "description": "Redirect to the callback URL with the newly-issued refresh token appended as a `?token=` query parameter."
+          },
+          "400": {
+            "description": "Missing or non-localhost callback URL",
             "content": {
-              "text/event-stream": {
+              "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/EventStreamResponse"
+                  "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
             }
           },
           "401": {
-            "description": "Authentication required"
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
           },
-          "404": {
-            "description": "Resource not found"
+          "500": {
+            "description": "Failed to generate refresh token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
           }
         }
       }
     },
-    "/resources/{id}/annotate-comments": {
-      "post": {
-        "summary": "Annotate Comments with Progress (SSE)",
-        "description": "Stream real-time comment annotation progress via Server-Sent Events",
+    "/bus/subscribe": {
+      "get": {
+        "summary": "Subscribe to the Semiont event bus (SSE)",
+        "description": "Opens a long-lived Server-Sent Events stream over which the bus delivers events matching the requested channels and scopes.\n\nEach SSE frame has `event: bus-event`, a JSON-encoded `data` of the form `{ channel, payload, scope? }`, and an `id` (either a persisted event id, `scope:seq`, for domain events; or an ephemeral id for job-lifecycle / result channels).\n\nPass the last-received id as `Last-Event-ID` to resume — the server replays missed persisted events and emits a `bus:resume-gap` synthetic event when the gap exceeds the replay window.",
         "tags": [
-          "Resources",
-          "Annotations",
-          "Real-time"
+          "Bus"
         ],
         "security": [
           {
@@ -1598,79 +1217,51 @@
         ],
         "parameters": [
           {
+            "name": "channel",
+            "in": "query",
+            "required": false,
+            "description": "Unscoped channels to subscribe to. Repeat the parameter for multiple channels. At least one of `channel` or `scoped` is required.",
             "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          }
-        ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/AnnotateCommentsStreamRequest"
+              "type": "array",
+              "items": {
+                "type": "string"
               }
             }
-          }
-        },
-        "responses": {
-          "200": {
-            "description": "SSE stream opened successfully",
-            "content": {
-              "text/event-stream": {
-                "schema": {
-                  "$ref": "#/components/schemas/EventStreamResponse"
-                }
+          },
+          {
+            "name": "scoped",
+            "in": "query",
+            "required": false,
+            "description": "Resource-scoped channels to subscribe to (requires `scope`). Repeat for multiple.",
+            "schema": {
+              "type": "array",
+              "items": {
+                "type": "string"
               }
             }
           },
-          "401": {
-            "description": "Authentication required"
-          },
-          "404": {
-            "description": "Resource not found"
-          }
-        }
-      }
-    },
-    "/resources/{id}/annotate-tags": {
-      "post": {
-        "summary": "Annotate Tags with Progress (SSE)",
-        "description": "Stream real-time tag annotation progress via Server-Sent Events. Identifies passages serving specific structural roles (IRAC, IMRAD, Toulmin frameworks).",
-        "tags": [
-          "Resources",
-          "Annotations",
-          "Real-time"
-        ],
-        "security": [
           {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
+            "name": "scope",
+            "in": "query",
+            "required": false,
+            "description": "Resource scope for scoped channels (typically a resourceId).",
+            "schema": {
+              "type": "string"
+            }
+          },
           {
+            "name": "Last-Event-ID",
+            "in": "header",
+            "required": false,
+            "description": "Id of the last event the client received. On reconnect, the server replays persisted events after this id and emits `bus:resume-gap` if the gap exceeds the replay cap.",
             "schema": {
               "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          }
-        ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/AnnotateTagsStreamRequest"
-              }
             }
           }
-        },
+        ],
         "responses": {
           "200": {
-            "description": "SSE stream opened successfully",
+            "description": "SSE stream opened",
             "content": {
               "text/event-stream": {
                 "schema": {
@@ -1679,139 +1270,196 @@
               }
             }
           },
-          "401": {
-            "description": "Authentication required"
+          "400": {
+            "description": "No channels requested (at least one `channel` or `scoped` parameter required)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
           },
-          "404": {
-            "description": "Resource not found"
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
           }
         }
       }
     },
-    "/resources/{id}/gather-resource-stream": {
+    "/bus/emit": {
       "post": {
-        "summary": "Gather Resource LLM Context (SSE Stream)",
-        "description": "Stream real-time resource LLM context gathering progress via Server-Sent Events",
+        "summary": "Emit an event on the Semiont bus",
+        "description": "Publishes an event to the bus. The channel name must be registered in `bus-protocol.ts` (`EventMap`); the payload is validated against the channel's schema in `CHANNEL_SCHEMAS` when one is registered.\n\nWhen `scope` is set, the event publishes on `eventBus.scope(scope)` rather than the global bus, routing it to per-resource SSE subscribers only. The authenticated user's DID is attached to the payload as `_userId` automatically.\n\nReturns 202 Accepted — the event is delivered to in-memory subscribers synchronously, but downstream persistence (Stower) and materialization happen asynchronously.",
         "tags": [
-          "Resources",
-          "Real-time",
-          "AI"
+          "Bus"
         ],
         "security": [
           {
             "bearerAuth": []
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          }
-        ],
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/GatherResourceStreamRequest"
+                "$ref": "#/components/schemas/BusEmitRequest"
               }
             }
           }
         },
         "responses": {
-          "200": {
-            "description": "SSE stream opened successfully",
+          "202": {
+            "description": "Event accepted and published to subscribers"
+          },
+          "400": {
+            "description": "Missing/invalid channel, payload, or scope; or payload failed schema validation for the channel",
             "content": {
-              "text/event-stream": {
+              "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/EventStreamResponse"
+                  "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
             }
           },
           "401": {
-            "description": "Authentication required"
-          },
-          "404": {
-            "description": "Resource not found"
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
           }
         }
       }
     },
-    "/resources/{id}/match-search": {
+    "/resources": {
       "post": {
-        "summary": "Match Search",
-        "description": "Submit a match-search command for binding candidates. Returns {correlationId} immediately. Results are delivered asynchronously via the long-lived events-stream as match:search-results or match:search-failed events.",
+        "summary": "Create a resource",
+        "description": "Upload binary content + metadata as multipart/form-data. The backend writes content to disk, then emits yield:create on the bus; Stower persists it and returns a 202 with the new resourceId. Full reconciliation happens via SSE domain events (yield:created).\n\nGeneration workers and the /know/compose page both hit this route — bytes always travel on the HTTP wire, never on the bus.",
         "tags": [
-          "Resources",
-          "Annotations",
-          "AI"
+          "Resources"
         ],
         "security": [
           {
             "bearerAuth": []
           }
         ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path",
-            "description": "Resource ID"
-          }
-        ],
         "requestBody": {
           "required": true,
           "content": {
-            "application/json": {
+            "multipart/form-data": {
               "schema": {
-                "$ref": "#/components/schemas/MatchSearchRequest"
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "Human-readable resource name"
+                  },
+                  "file": {
+                    "type": "string",
+                    "format": "binary",
+                    "description": "Binary content"
+                  },
+                  "format": {
+                    "type": "string",
+                    "description": "Media type of the content (e.g. text/plain, text/markdown, image/png)"
+                  },
+                  "storageUri": {
+                    "type": "string",
+                    "description": "Where the content has been / should be placed (file://... for local). If omitted, derived from name + format."
+                  },
+                  "language": {
+                    "type": "string",
+                    "description": "ISO 639-1 language code"
+                  },
+                  "entityTypes": {
+                    "type": "string",
+                    "description": "JSON-stringified array of entity type names"
+                  },
+                  "creationMethod": {
+                    "type": "string",
+                    "description": "How this resource was created (api, ui, upload, reference, cli, clone, generated)"
+                  },
+                  "sourceAnnotationId": {
+                    "type": "string",
+                    "description": "For AI-generated resources: the annotation that triggered generation. Nested into generatedFrom.annotationId on the persisted event."
+                  },
+                  "sourceResourceId": {
+                    "type": "string",
+                    "description": "For AI-generated resources: the source resource the generating annotation lives on. Nested into generatedFrom.resourceId on the persisted event."
+                  },
+                  "generationPrompt": {
+                    "type": "string",
+                    "description": "For AI-generated resources: the prompt that drove generation"
+                  },
+                  "generator": {
+                    "type": "string",
+                    "description": "For AI-generated resources: JSON-stringified Agent (single object or array), capturing which model/worker produced the content"
+                  },
+                  "isDraft": {
+                    "type": "string",
+                    "description": "'true' or 'false' — whether the resource is a draft"
+                  }
+                },
+                "required": [
+                  "name",
+                  "file",
+                  "format"
+                ]
               }
             }
           }
         },
         "responses": {
           "202": {
-            "description": "Search command accepted. Results delivered via events-stream.",
+            "description": "Resource accepted for creation",
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "properties": {
-                    "correlationId": {
-                      "type": "string"
-                    }
-                  },
-                  "required": [
-                    "correlationId"
-                  ]
+                  "$ref": "#/components/schemas/CreateResourceResponse"
                 }
               }
             }
           },
-          "401": {
-            "description": "Authentication required"
+          "400": {
+            "description": "Missing required fields (name, file, or format)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
           },
-          "404": {
-            "description": "Resource not found"
+          "401": {
+            "description": "Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
           }
         }
       }
     },
-    "/resources/{resourceId}/annotations/{annotationId}/gather": {
-      "post": {
-        "summary": "Gather Annotation Context",
-        "description": "Submit a gather-context command for an annotation. Returns {correlationId} immediately. The Gatherer assembles passage + graph context (long-running, involves LLM calls) and delivers results via the events-stream as gather:complete, gather:failed, or gather:annotation-progress events.",
+    "/resources/{id}": {
+      "get": {
+        "summary": "Get a resource (content-negotiated)",
+        "description": "Content negotiation via the Accept header:\n- application/ld+json (default) — returns JSON-LD metadata including all annotations + inbound entity references\n- text/* or image/* or application/pdf — returns the raw representation bytes\n\nBinary payloads flow directly from the content store; metadata payloads go through the bus gateway.",
         "tags": [
-          "Resources",
-          "Annotations",
-          "AI"
+          "Resources"
         ],
         "security": [
           {
@@ -1820,922 +1468,87 @@
         ],
         "parameters": [
           {
+            "name": "id",
+            "in": "path",
+            "required": true,
             "schema": {
               "type": "string"
-            },
-            "required": true,
-            "name": "resourceId",
-            "in": "path",
-            "description": "Resource ID"
+            }
           },
           {
+            "name": "Accept",
+            "in": "header",
+            "required": false,
             "schema": {
               "type": "string"
             },
-            "required": true,
-            "name": "annotationId",
-            "in": "path",
-            "description": "Annotation ID"
+            "description": "application/ld+json for metadata, or a text/image/pdf media type for raw content"
           }
         ],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/GatherAnnotationStreamRequest"
-              }
-            }
-          }
-        },
         "responses": {
-          "202": {
-            "description": "Gather command accepted. Results delivered via events-stream.",
+          "200": {
+            "description": "Resource content or metadata, depending on Accept",
             "content": {
-              "application/json": {
+              "application/ld+json": {
                 "schema": {
-                  "type": "object",
-                  "properties": {
-                    "correlationId": {
-                      "type": "string"
-                    }
-                  },
-                  "required": [
-                    "correlationId"
-                  ]
+                  "$ref": "#/components/schemas/GetResourceResponse"
                 }
-              }
-            }
-          },
-          "401": {
-            "description": "Authentication required"
-          }
-        }
-      }
-    },
-    "/resources/{id}/referenced-by": {
-      "get": {
-        "summary": "Get Referenced By",
-        "description": "Get resources that reference this resource",
-        "tags": [
-          "Resources",
-          "Graph"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          },
-          {
-            "schema": {
-              "$ref": "#/components/schemas/Motivation"
-            },
-            "required": false,
-            "name": "motivation",
-            "in": "query",
-            "description": "Filter incoming references by W3C motivation type (e.g., 'linking', 'commenting', 'highlighting')"
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Resources that reference this resource",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/GetReferencedByResponse"
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    "/api/clone-tokens/{token}": {
-      "get": {
-        "summary": "Get Resource by Clone Token",
-        "description": "Retrieve a resource using a clone token",
-        "tags": [
-          "Resources"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "token",
-            "in": "path"
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Resource retrieved successfully",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/GetResourceByTokenResponse"
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    "/api/clone-tokens/create-resource": {
-      "post": {
-        "summary": "Create Resource from Clone Token",
-        "description": "Create a new resource using a clone token",
-        "tags": [
-          "Resources"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/CreateResourceFromTokenRequest"
-              }
-            }
-          }
-        },
-        "responses": {
-          "202": {
-            "description": "Resource creation accepted",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "object",
-                  "properties": {
-                    "resourceId": {
-                      "type": "string"
-                    }
-                  },
-                  "required": [
-                    "resourceId"
-                  ]
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    "/resources/{id}/clone-with-token": {
-      "post": {
-        "summary": "Clone Resource with Token",
-        "description": "Generate a temporary token for cloning a resource",
-        "tags": [
-          "Resources"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Clone token generated successfully",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/CloneResourceWithTokenResponse"
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    "/resources/{id}/annotations": {
-      "get": {
-        "summary": "Get Resource Annotations",
-        "description": "Get all annotations (both highlights and references) in a resource",
-        "tags": [
-          "Resources",
-          "Annotations"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Resource annotations",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/CreateResourceResponse"
-                }
-              }
-            }
-          }
-        }
-      },
-      "post": {
-        "summary": "Create Annotation",
-        "description": "Create a new annotation/reference in a resource",
-        "tags": [
-          "Resources",
-          "Annotations"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path",
-            "description": "Resource ID"
-          }
-        ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/CreateAnnotationRequest"
-              }
-            }
-          }
-        },
-        "responses": {
-          "202": {
-            "description": "Annotation creation accepted",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "object",
-                  "properties": {
-                    "annotationId": {
-                      "type": "string"
-                    }
-                  },
-                  "required": [
-                    "annotationId"
-                  ]
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    "/resources/{id}/events": {
-      "get": {
-        "summary": "Get Resource Event History",
-        "description": "Get full event history for a resource with optional filtering",
-        "tags": [
-          "Resources",
-          "Events"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          },
-          {
-            "schema": {
-              "type": "string",
-              "enum": [
-                "resource.created",
-                "resource.cloned",
-                "resource.updated",
-                "resource.moved",
-                "resource.archived",
-                "resource.unarchived",
-                "annotation.added",
-                "annotation.removed",
-                "annotation.body.updated",
-                "entitytag.added",
-                "entitytag.removed",
-                "entitytype.added"
-              ]
-            },
-            "required": false,
-            "name": "type",
-            "in": "query"
-          },
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": false,
-            "name": "userId",
-            "in": "query"
-          },
-          {
-            "schema": {
-              "type": "number",
-              "minimum": 1,
-              "maximum": 1000,
-              "default": 100
-            },
-            "required": false,
-            "name": "limit",
-            "in": "query"
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Events retrieved successfully",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/GetEventsResponse"
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    "/resources/{id}/events/stream": {
-      "get": {
-        "summary": "Subscribe to Resource Events (SSE)",
-        "description": "Open a Server-Sent Events stream to receive real-time resource events",
-        "tags": [
-          "Resources",
-          "Events",
-          "Real-time"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "SSE stream opened successfully",
-            "content": {
-              "text/event-stream": {
-                "schema": {
-                  "$ref": "#/components/schemas/EventStreamResponse"
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    "/resources/{resourceId}/annotations/{annotationId}": {
-      "get": {
-        "summary": "Get Annotation",
-        "description": "Get a specific annotation from a resource using nested path",
-        "tags": [
-          "Resources",
-          "Annotations"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "resourceId",
-            "in": "path",
-            "description": "Resource ID"
-          },
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "annotationId",
-            "in": "path",
-            "description": "Annotation ID"
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Annotation retrieved successfully",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/GetAnnotationResponse"
-                }
-              }
-            }
-          },
-          "404": {
-            "description": "Annotation not found"
-          }
-        }
-      },
-      "delete": {
-        "summary": "Delete Annotation",
-        "description": "Delete an annotation from a resource",
-        "tags": [
-          "Resources",
-          "Annotations"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "resourceId",
-            "in": "path",
-            "description": "Resource ID"
-          },
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "annotationId",
-            "in": "path",
-            "description": "Annotation ID"
-          }
-        ],
-        "responses": {
-          "202": {
-            "description": "Annotation deletion accepted"
-          }
-        }
-      }
-    },
-    "/resources/{resourceId}/annotations/{annotationId}/body": {
-      "put": {
-        "summary": "Update Annotation Body",
-        "description": "Apply fine-grained operations to modify annotation body items (add, remove, or replace TextualBody and SpecificResource items)",
-        "tags": [
-          "Resources",
-          "Annotations"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "resourceId",
-            "in": "path",
-            "description": "Resource ID"
-          },
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "annotationId",
-            "in": "path",
-            "description": "Annotation ID"
-          }
-        ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/UpdateAnnotationBodyRequest"
-              }
-            }
-          }
-        },
-        "responses": {
-          "202": {
-            "description": "Annotation body update accepted"
-          }
-        }
-      }
-    },
-    "/resources/{resourceId}/annotations/{annotationId}/yield-resource": {
-      "post": {
-        "summary": "Generate Resource from Annotation",
-        "description": "Submit a resource generation command. Returns {correlationId, jobId} immediately. The generation worker processes the job asynchronously and delivers progress (yield:progress) and completion (yield:finished) or failure (yield:failed) via the events-stream to all connected clients.",
-        "tags": [
-          "Resources",
-          "Annotations",
-          "AI"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "resourceId",
-            "in": "path",
-            "description": "Source resource ID"
-          },
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "annotationId",
-            "in": "path",
-            "description": "Reference annotation ID"
-          }
-        ],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/YieldResourceStreamRequest"
-              }
-            }
-          }
-        },
-        "responses": {
-          "202": {
-            "description": "Generation command accepted. Progress and results delivered via events-stream.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "object",
-                  "properties": {
-                    "correlationId": {
-                      "type": "string"
-                    },
-                    "jobId": {
-                      "type": "string"
-                    }
-                  },
-                  "required": [
-                    "correlationId",
-                    "jobId"
-                  ]
-                }
-              }
-            }
-          },
-          "400": {
-            "description": "Context is required for generation"
-          },
-          "401": {
-            "description": "Authentication required"
-          },
-          "404": {
-            "description": "Annotation not found"
-          }
-        }
-      }
-    },
-    "/resources/{resourceId}/annotations/{annotationId}/history": {
-      "get": {
-        "summary": "Get Annotation History",
-        "description": "Get full event history for a specific annotation (highlight or reference)",
-        "tags": [
-          "Selections",
-          "Events"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "resourceId",
-            "in": "path"
-          },
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "annotationId",
-            "in": "path"
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Annotation history retrieved successfully",
-            "content": {
-              "application/json": {
+              },
+              "text/plain": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetAnnotationHistoryResponse"
+                  "type": "string"
                 }
-              }
-            }
-          },
-          "404": {
-            "description": "Annotation not found"
-          }
-        }
-      }
-    },
-    "/api/entity-types": {
-      "get": {
-        "summary": "Get Entity Types",
-        "description": "Get list of available entity types for references",
-        "tags": [
-          "Selections"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Entity types retrieved successfully",
-            "content": {
-              "application/json": {
+              },
+              "text/markdown": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetEntityTypesResponse"
+                  "type": "string"
                 }
-              }
-            }
-          }
-        }
-      },
-      "post": {
-        "summary": "Add Entity Type",
-        "description": "Add a new entity type to the collection (append-only, requires moderator/admin)",
-        "tags": [
-          "Selections"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/AddEntityTypeRequest"
-              }
-            }
-          }
-        },
-        "responses": {
-          "202": {
-            "description": "Entity type addition accepted"
-          },
-          "403": {
-            "description": "Forbidden - Moderator or Admin access required",
-            "content": {
-              "application/json": {
+              },
+              "text/html": {
                 "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
+                  "type": "string"
                 }
-              }
-            }
-          }
-        }
-      }
-    },
-    "/api/entity-types/bulk": {
-      "post": {
-        "summary": "Bulk Add Entity Types",
-        "description": "Add multiple entity types to the collection (append-only, requires moderator/admin)",
-        "tags": [
-          "Selections"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/BulkAddEntityTypesRequest"
-              }
-            }
-          }
-        },
-        "responses": {
-          "202": {
-            "description": "Entity types addition accepted"
-          },
-          "403": {
-            "description": "Forbidden - Moderator or Admin access required",
-            "content": {
-              "application/json": {
+              },
+              "image/*": {
                 "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
+                  "type": "string",
+                  "format": "binary"
                 }
-              }
-            }
-          }
-        }
-      }
-    },
-    "/api/events/stream": {
-      "get": {
-        "summary": "Subscribe to Global Events (SSE)",
-        "description": "Open a Server-Sent Events stream to receive real-time system-level events (e.g., entity type changes). Events not scoped to a specific resource are delivered on this channel.",
-        "tags": [
-          "Events",
-          "Real-time"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "SSE stream opened successfully",
-            "content": {
-              "text/event-stream": {
+              },
+              "application/pdf": {
                 "schema": {
-                  "$ref": "#/components/schemas/EventStreamResponse"
+                  "type": "string",
+                  "format": "binary"
                 }
               }
             }
-          }
-        }
-      }
-    },
-    "/api/jobs/{id}": {
-      "get": {
-        "summary": "Get Job Status",
-        "description": "Get the current status and progress of an async job",
-        "tags": [
-          "Jobs"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path"
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Job status retrieved successfully",
+          },
+          "404": {
+            "description": "Resource not found",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/JobStatusResponse"
+                  "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
             }
           },
-          "404": {
-            "description": "Job not found"
-          }
-        }
-      }
-    },
-    "/api/participants/{id}/attention": {
-      "post": {
-        "summary": "Beckon Participant",
-        "description": "Direct a participant's attention to a resource or annotation. Produces no persistent annotations — attention signal only. The participant may be a human username or an agent identifier.",
-        "tags": [
-          "Participants"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": true,
-            "name": "id",
-            "in": "path",
-            "description": "Participant username or agent identifier"
-          }
-        ],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/BeckonRequest"
-              }
-            }
-          }
-        },
-        "responses": {
-          "202": {
-            "description": "Attention signal accepted",
+          "500": {
+            "description": "Failed to retrieve resource",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/BeckonResponse"
+                  "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
             }
-          }
-        }
-      }
-    },
-    "/api/participants/me/attention-stream": {
-      "get": {
-        "summary": "Participant Attention Stream",
-        "description": "Open a persistent SSE connection to receive beckon signals directed at the authenticated participant. Signals are ephemeral — delivered if connected, dropped if not. No queue, no replay.",
-        "tags": [
-          "Participants"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "SSE stream of beckon:focus events",
+          },
+          "504": {
+            "description": "Request timed out (bus gateway)",
             "content": {
-              "text/event-stream": {
+              "application/json": {
                 "schema": {
-                  "type": "string"
+                  "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
             }
@@ -2743,12 +1556,12 @@
         }
       }
     },
-    "/api/browse/files": {
+    "/api/resources/{id}": {
       "get": {
-        "summary": "Browse project directory",
-        "description": "List files and directories in a project directory, merged with Knowledge Base metadata for tracked resources.",
+        "summary": "Get raw resource content (browser-friendly alias)",
+        "description": "Browser-friendly alternative to GET /resources/{id} that always returns the raw representation, never JSON-LD. Used by `<img>` / PDF.js / `<video>` tags and anywhere an httpOnly cookie is the only feasible auth vector. Behaves like GET /resources/{id} with JSON-LD stripped from the Accept header before content negotiation.\n\nSets long-lived immutable Cache-Control (content is addressed by checksum upstream, so bytes never change for a given resource id).",
         "tags": [
-          "Browse"
+          "Resources"
         ],
         "security": [
           {
@@ -2757,44 +1570,49 @@
         ],
         "parameters": [
           {
-            "name": "path",
-            "in": "query",
-            "required": false,
-            "schema": {
-              "type": "string",
-              "default": ""
-            },
-            "description": "Directory path relative to project root. Empty string or omit for project root."
-          },
-          {
-            "name": "sort",
-            "in": "query",
-            "required": false,
+            "name": "id",
+            "in": "path",
+            "required": true,
             "schema": {
-              "type": "string",
-              "enum": [
-                "name",
-                "mtime",
-                "annotationCount"
-              ],
-              "default": "name"
-            },
-            "description": "Sort order for directory entries."
+              "type": "string"
+            }
           }
         ],
         "responses": {
           "200": {
-            "description": "Directory listing with KB metadata merged",
+            "description": "Raw representation bytes with appropriate Content-Type",
             "content": {
-              "application/json": {
+              "text/plain": {
+                "schema": {
+                  "type": "string"
+                }
+              },
+              "text/markdown": {
+                "schema": {
+                  "type": "string"
+                }
+              },
+              "text/html": {
+                "schema": {
+                  "type": "string"
+                }
+              },
+              "image/*": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              },
+              "application/pdf": {
                 "schema": {
-                  "$ref": "#/components/schemas/BrowseFilesResponse"
+                  "type": "string",
+                  "format": "binary"
                 }
               }
             }
           },
-          "400": {
-            "description": "Invalid path (e.g. path escapes project root)",
+          "404": {
+            "description": "Resource or representation not found",
             "content": {
               "application/json": {
                 "schema": {
@@ -2803,8 +1621,8 @@
               }
             }
           },
-          "404": {
-            "description": "Directory not found",
+          "500": {
+            "description": "Failed to retrieve resource",
             "content": {
               "application/json": {
                 "schema": {
@@ -2834,19 +1652,6 @@
           "message"
         ]
       },
-      "AddEntityTypeRequest": {
-        "type": "object",
-        "properties": {
-          "tag": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 100
-          }
-        },
-        "required": [
-          "tag"
-        ]
-      },
       "AdminUpdateUserResponse": {
         "type": "object",
         "properties": {
@@ -3148,14 +1953,6 @@
           },
           "body": {
             "oneOf": [
-              {
-                "type": "array",
-                "items": {
-                  "$ref": "#/components/schemas/AnnotationBody"
-                },
-                "maxItems": 0,
-                "description": "Empty array for stub references (Phase 1 pattern)"
-              },
               {
                 "$ref": "#/components/schemas/AnnotationBody",
                 "description": "Single body (TextualBody or SpecificResource)"
@@ -3165,10 +1962,11 @@
                 "items": {
                   "$ref": "#/components/schemas/AnnotationBody"
                 },
-                "description": "Array of mixed TextualBody (tagging) and SpecificResource (linking) bodies"
+                "minItems": 1,
+                "description": "Non-empty array of mixed TextualBody (tagging) and SpecificResource (linking) bodies"
               }
             ],
-            "description": "W3C Web Annotation body - can be empty array, single body, or array of bodies"
+            "description": "W3C Web Annotation body. Optional per the W3C spec — annotations whose motivation alone is meaningful (highlighting) legitimately omit it. Present values are either a single body or a non-empty array of bodies; the prior empty-array 'stub' branch has been removed (it was a naming lie shared between highlights and never-actually-emitted stub references, and the source of the #651 reference-annotation validator bug)."
           },
           "creator": {
             "$ref": "#/components/schemas/Agent"
@@ -3188,8 +1986,7 @@
           "type",
           "id",
           "motivation",
-          "target",
-          "body"
+          "target"
         ]
       },
       "AnnotationBody": {
@@ -3369,40 +2166,6 @@
         ],
         "description": "W3C Web Annotation target object - source is required, selector is optional"
       },
-      "AsyncJobResponse": {
-        "type": "object",
-        "properties": {
-          "jobId": {
-            "type": "string"
-          },
-          "status": {
-            "type": "string",
-            "enum": [
-              "pending",
-              "running",
-              "complete",
-              "failed",
-              "cancelled"
-            ]
-          },
-          "type": {
-            "type": "string",
-            "enum": [
-              "reference-annotation",
-              "generation"
-            ]
-          },
-          "created": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "jobId",
-          "status",
-          "type",
-          "created"
-        ]
-      },
       "AuthResponse": {
         "type": "object",
         "properties": {
@@ -3482,6 +2245,148 @@
         },
         "additionalProperties": false
       },
+      "BusEmitRequest": {
+        "type": "object",
+        "description": "Emit an event on the Semiont bus. Channel names come from bus-protocol.ts; payload shape is validated against the channel's registered schema (CHANNEL_SCHEMAS). An optional scope routes resource-scoped broadcasts (e.g. mark:added, job:complete) to per-resource subscribers via eventBus.scope(scope); leave it unset for unscoped/global events.",
+        "properties": {
+          "channel": {
+            "type": "string",
+            "description": "Channel name from bus-protocol.ts EventMap"
+          },
+          "payload": {
+            "type": "object",
+            "description": "Channel-specific payload, validated against CHANNEL_SCHEMAS",
+            "additionalProperties": true
+          },
+          "scope": {
+            "type": "string",
+            "description": "Optional resource scope for broadcast channels (e.g. resourceId). Publishers only — frontends must never set this.",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "channel",
+          "payload"
+        ]
+      },
+      "CookieConsent": {
+        "type": "object",
+        "description": "User's cookie consent preferences. `necessary` is always true — necessary cookies cannot be disabled. Timestamps and version are stamped server-side.",
+        "properties": {
+          "necessary": {
+            "type": "boolean",
+            "enum": [
+              true
+            ]
+          },
+          "analytics": {
+            "type": "boolean"
+          },
+          "marketing": {
+            "type": "boolean"
+          },
+          "preferences": {
+            "type": "boolean"
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "version": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "necessary",
+          "analytics",
+          "marketing",
+          "preferences",
+          "timestamp",
+          "version"
+        ]
+      },
+      "CookieConsentRequest": {
+        "type": "object",
+        "description": "Request body for POST /api/cookies/consent. All four preference fields must be booleans; `necessary` must be true.",
+        "properties": {
+          "necessary": {
+            "type": "boolean",
+            "enum": [
+              true
+            ]
+          },
+          "analytics": {
+            "type": "boolean"
+          },
+          "marketing": {
+            "type": "boolean"
+          },
+          "preferences": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "necessary",
+          "analytics",
+          "marketing",
+          "preferences"
+        ]
+      },
+      "CookieConsentResponse": {
+        "type": "object",
+        "description": "Standard envelope for cookie consent endpoints. On success `success: true` and `consent` carries the current preferences; on error `success: false` and `error` carries a human-readable message.",
+        "properties": {
+          "success": {
+            "type": "boolean"
+          },
+          "consent": {
+            "$ref": "#/components/schemas/CookieConsent"
+          },
+          "error": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "success"
+        ]
+      },
+      "CookieExportResponse": {
+        "type": "object",
+        "description": "GDPR data export of a user's cookie-related data. The response is returned as a file download (Content-Disposition: attachment).",
+        "properties": {
+          "user": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "email": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "id",
+              "email"
+            ]
+          },
+          "consent": {
+            "$ref": "#/components/schemas/CookieConsent"
+          },
+          "exportDate": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "dataRetentionPolicy": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "user",
+          "consent",
+          "exportDate",
+          "dataRetentionPolicy"
+        ]
+      },
       "DirectoryEntry": {
         "oneOf": [
           {
@@ -3647,92 +2552,26 @@
               {
                 "$ref": "#/components/schemas/TextualBody"
               },
-              {
-                "$ref": "#/components/schemas/SpecificResource"
-              }
-            ]
-          },
-          "newItem": {
-            "oneOf": [
-              {
-                "$ref": "#/components/schemas/TextualBody"
-              },
-              {
-                "$ref": "#/components/schemas/SpecificResource"
-              }
-            ]
-          }
-        },
-        "required": [
-          "op",
-          "oldItem",
-          "newItem"
-        ]
-      },
-      "BodyType": {
-        "type": "string",
-        "enum": [
-          "TextualBody",
-          "SpecificResource"
-        ],
-        "description": "Annotation body type - TextualBody for textual content, SpecificResource for resource links"
-      },
-      "BeckonRequest": {
-        "type": "object",
-        "properties": {
-          "resourceId": {
-            "type": "string",
-            "description": "Resource to direct attention at"
-          },
-          "annotationId": {
-            "type": "string",
-            "description": "Specific annotation within the resource (optional)"
-          },
-          "message": {
-            "type": "string",
-            "description": "Human-readable context for the participant (max 500 chars)",
-            "maxLength": 500
-          }
-        },
-        "required": [
-          "resourceId"
-        ]
-      },
-      "BeckonResponse": {
-        "type": "object",
-        "properties": {
-          "participant": {
-            "type": "string",
-            "description": "Username or agent identifier that was beckoned"
-          },
-          "resourceId": {
-            "type": "string",
-            "description": "Resource the attention was directed at"
+              {
+                "$ref": "#/components/schemas/SpecificResource"
+              }
+            ]
           },
-          "annotationId": {
-            "type": "string",
-            "description": "Annotation the attention was directed at (if provided)"
-          }
-        },
-        "required": [
-          "participant",
-          "resourceId"
-        ]
-      },
-      "BulkAddEntityTypesRequest": {
-        "type": "object",
-        "properties": {
-          "tags": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "minLength": 1,
-              "maxLength": 100
-            }
+          "newItem": {
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/TextualBody"
+              },
+              {
+                "$ref": "#/components/schemas/SpecificResource"
+              }
+            ]
           }
         },
         "required": [
-          "tags"
+          "op",
+          "oldItem",
+          "newItem"
         ]
       },
       "CloneResourceWithTokenResponse": {
@@ -3760,6 +2599,10 @@
         "type": "object",
         "description": "Error response for failed bus commands. Replaces native Error objects on the EventBus so payloads are serializable and OpenAPI-typed.",
         "properties": {
+          "correlationId": {
+            "type": "string",
+            "description": "Optional correlation id echoed from the originating command. When present, the failure event can be matched back to the specific command that failed."
+          },
           "message": {
             "type": "string",
             "description": "Human-readable error message"
@@ -3909,11 +2752,6 @@
           },
           "body": {
             "oneOf": [
-              {
-                "type": "array",
-                "maxItems": 0,
-                "description": "Empty array (Phase 1 stub pattern - will be migrated to contain entity tag bodies in Phase 2)"
-              },
               {
                 "$ref": "#/components/schemas/AnnotationBody",
                 "description": "Single body (TextualBody or SpecificResource)"
@@ -3921,260 +2759,27 @@
               {
                 "type": "array",
                 "items": {
-                  "$ref": "#/components/schemas/AnnotationBody"
-                },
-                "minItems": 1,
-                "description": "Array of mixed TextualBody (tagging) and SpecificResource (linking) bodies"
-              }
-            ]
-          }
-        },
-        "required": [
-          "target",
-          "body",
-          "motivation"
-        ]
-      },
-      "CreateFromAnnotationRequest": {
-        "type": "object",
-        "properties": {
-          "resourceId": {
-            "type": "string",
-            "description": "ID of the resource containing the annotation"
-          },
-          "name": {
-            "type": "string"
-          },
-          "content": {
-            "type": "string"
-          },
-          "format": {
-            "$ref": "#/components/schemas/ContentFormat"
-          }
-        },
-        "required": [
-          "resourceId",
-          "name",
-          "content",
-          "format"
-        ]
-      },
-      "CreateFromAnnotationResponse": {
-        "type": "object",
-        "properties": {
-          "resource": {
-            "$ref": "#/components/schemas/ResourceDescriptor"
-          },
-          "annotations": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/Annotation"
-            }
-          }
-        },
-        "required": [
-          "resource",
-          "annotations"
-        ]
-      },
-      "CreateJobResponse": {
-        "type": "object",
-        "properties": {
-          "jobId": {
-            "type": "string"
-          },
-          "type": {
-            "type": "string",
-            "enum": [
-              "reference-annotation",
-              "generation"
-            ]
-          },
-          "status": {
-            "type": "string",
-            "enum": [
-              "pending",
-              "running",
-              "complete",
-              "failed",
-              "cancelled"
-            ]
-          },
-          "created": {
-            "type": "string"
-          },
-          "resourceId": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "jobId",
-          "type",
-          "status",
-          "created"
-        ]
-      },
-      "CreateResourceFromAnnotationResponse": {
-        "type": "object",
-        "properties": {
-          "resource": {
-            "$ref": "#/components/schemas/ResourceDescriptor"
-          },
-          "annotation": {
-            "$ref": "#/components/schemas/Annotation"
-          }
-        },
-        "required": [
-          "resource",
-          "annotation"
-        ]
-      },
-      "CreateResourceFromSelectionRequest": {
-        "type": "object",
-        "properties": {
-          "resourceId": {
-            "type": "string",
-            "description": "ID of the resource containing the annotation"
-          },
-          "content": {
-            "type": "string"
-          },
-          "name": {
-            "type": "string"
-          },
-          "format": {
-            "$ref": "#/components/schemas/ContentFormat"
-          },
-          "entityTypes": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            }
-          },
-          "metadata": {
-            "type": "object",
-            "additionalProperties": true
-          },
-          "prompt": {
-            "type": "string"
-          },
-          "language": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "resourceId",
-          "content",
-          "name",
-          "format"
-        ]
-      },
-      "CreateResourceFromSelectionResponse": {
-        "type": "object",
-        "properties": {
-          "resource": {
-            "$ref": "#/components/schemas/ResourceDescriptor"
-          },
-          "annotation": {
-            "$ref": "#/components/schemas/Annotation"
-          }
-        },
-        "required": [
-          "resource",
-          "annotation"
-        ]
-      },
-      "CreateResourceFromTokenRequest": {
-        "type": "object",
-        "properties": {
-          "token": {
-            "type": "string",
-            "description": "Clone token"
-          },
-          "name": {
-            "type": "string",
-            "description": "Name for the new resource"
-          },
-          "content": {
-            "type": "string",
-            "description": "Content for the new resource"
-          },
-          "archiveOriginal": {
-            "type": "boolean",
-            "description": "Whether to archive the original resource"
-          }
-        },
-        "required": [
-          "token",
-          "name",
-          "content"
-        ]
-      },
-      "CreateResourceRequest": {
-        "type": "object",
-        "properties": {
-          "name": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 500
-          },
-          "content": {
-            "type": "string"
-          },
-          "format": {
-            "$ref": "#/components/schemas/ContentFormat"
-          },
-          "entityTypes": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            }
-          },
-          "language": {
-            "type": "string"
-          },
-          "creationMethod": {
-            "type": "string"
-          },
-          "sourceAnnotationId": {
-            "type": "string"
-          },
-          "sourceResourceId": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "name",
-          "content",
-          "format",
-          "entityTypes"
-        ]
-      },
-      "CreateResourceResponse": {
-        "type": "object",
-        "properties": {
-          "resource": {
-            "$ref": "#/components/schemas/ResourceDescriptor"
-          },
-          "annotations": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/Annotation"
-            }
+                  "$ref": "#/components/schemas/AnnotationBody"
+                },
+                "minItems": 1,
+                "description": "Non-empty array of mixed TextualBody (tagging) and SpecificResource (linking) bodies"
+              }
+            ],
+            "description": "Optional body. Omit for annotations whose motivation alone is meaningful (highlighting) or whose user-supplied content is empty. Shape matches Annotation.body."
           }
         },
         "required": [
-          "resource",
-          "annotations"
+          "target",
+          "motivation"
         ]
       },
-      "DeleteAnnotationRequest": {
+      "CreateResourceResponse": {
         "type": "object",
+        "description": "Response body for POST /resources (202 Accepted). Resource creation is asynchronous — the backend writes content to disk, emits yield:create on the bus, and returns the newly-minted resourceId immediately. Consumers watch SSE domain events (yield:created) to observe the fully-persisted state.",
         "properties": {
           "resourceId": {
             "type": "string",
-            "format": "uri",
-            "description": "Resource URI containing the annotation (required for O(1) Layer 3 lookup)"
+            "description": "The id of the newly-created resource. Assigned by Stower when it persists yield:create."
           }
         },
         "required": [
@@ -4196,100 +2801,6 @@
           "message"
         ]
       },
-      "AnnotateReferencesStreamRequest": {
-        "type": "object",
-        "properties": {
-          "entityTypes": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            },
-            "description": "Entity types to annotate (e.g., 'Person', 'Organization', 'Location')"
-          },
-          "includeDescriptiveReferences": {
-            "type": "boolean",
-            "description": "Include anaphoric/cataphoric references (e.g., 'the CEO', 'the tech giant') in addition to direct mentions"
-          }
-        },
-        "required": [
-          "entityTypes"
-        ]
-      },
-      "GatherResourceStreamRequest": {
-        "type": "object",
-        "properties": {
-          "correlationId": {
-            "type": "string",
-            "description": "Client-generated correlation ID to thread the response back to the originating request"
-          },
-          "depth": {
-            "type": "integer",
-            "minimum": 1,
-            "maximum": 3,
-            "description": "Graph traversal depth (default: 2)"
-          },
-          "maxResources": {
-            "type": "integer",
-            "minimum": 1,
-            "maximum": 20,
-            "description": "Maximum related resources to include (default: 10)"
-          },
-          "includeContent": {
-            "type": "boolean",
-            "description": "Include full resource content (default: true)"
-          },
-          "includeSummary": {
-            "type": "boolean",
-            "description": "Include AI-generated summary (default: false)"
-          }
-        }
-      },
-      "GatherAnnotationStreamRequest": {
-        "type": "object",
-        "properties": {
-          "correlationId": {
-            "type": "string",
-            "description": "Client-generated correlation ID to thread the response back to the originating request"
-          },
-          "contextWindow": {
-            "type": "integer",
-            "minimum": 100,
-            "maximum": 5000,
-            "description": "Characters of surrounding text context (default: 1000)"
-          }
-        }
-      },
-      "BindAnnotationStreamRequest": {
-        "type": "object",
-        "properties": {
-          "resourceId": {
-            "type": "string",
-            "description": "Resource ID containing the annotation (required for O(1) Layer 3 lookup)"
-          },
-          "operations": {
-            "type": "array",
-            "items": {
-              "oneOf": [
-                {
-                  "$ref": "#/components/schemas/BodyOperationAdd"
-                },
-                {
-                  "$ref": "#/components/schemas/BodyOperationRemove"
-                },
-                {
-                  "$ref": "#/components/schemas/BodyOperationReplace"
-                }
-              ]
-            },
-            "minItems": 1,
-            "description": "Array of body modification operations to apply"
-          }
-        },
-        "required": [
-          "resourceId",
-          "operations"
-        ]
-      },
       "GatherProgress": {
         "type": "object",
         "description": "Progress payload emitted on gather:annotation-progress and gather:progress SSE channels during LLM context gathering.",
@@ -4344,150 +2855,6 @@
           "response"
         ]
       },
-      "MarkProgress": {
-        "type": "object",
-        "description": "Progress state for mark (annotation) workflows. Supports both entity-type-step and percentage-based progress strategies. Emitted on mark:progress SSE channel.",
-        "properties": {
-          "correlationId": {
-            "type": "string",
-            "description": "Echoes the correlationId from the originating mark:assist-request command, if any. Lets clients match progress events back to the operation that initiated them."
-          },
-          "status": {
-            "type": "string",
-            "description": "Current status of the annotation workflow"
-          },
-          "message": {
-            "type": "string",
-            "description": "Human-readable status message"
-          },
-          "resourceId": {
-            "type": "string",
-            "description": "Resource being annotated"
-          },
-          "currentEntityType": {
-            "type": "string",
-            "description": "Reference annotation: currently scanning entity type"
-          },
-          "completedEntityTypes": {
-            "type": "array",
-            "description": "Reference annotation: completed entity types with counts",
-            "items": {
-              "type": "object",
-              "properties": {
-                "entityType": {
-                  "type": "string"
-                },
-                "foundCount": {
-                  "type": "integer"
-                }
-              },
-              "required": [
-                "entityType",
-                "foundCount"
-              ]
-            }
-          },
-          "percentage": {
-            "type": "number",
-            "minimum": 0,
-            "maximum": 100,
-            "description": "Percentage-based motivations (highlight, assessment, comment, tag)"
-          },
-          "currentCategory": {
-            "type": "string",
-            "description": "Category-based motivations (tag): current category"
-          },
-          "processedCategories": {
-            "type": "integer",
-            "description": "Category-based motivations (tag): number processed"
-          },
-          "totalCategories": {
-            "type": "integer",
-            "description": "Category-based motivations (tag): total categories"
-          },
-          "requestParams": {
-            "type": "array",
-            "description": "Request parameters for display in progress UI",
-            "items": {
-              "type": "object",
-              "properties": {
-                "label": {
-                  "type": "string"
-                },
-                "value": {
-                  "type": "string"
-                }
-              },
-              "required": [
-                "label",
-                "value"
-              ]
-            }
-          }
-        },
-        "required": [
-          "status"
-        ]
-      },
-      "MarkAssistFinished": {
-        "type": "object",
-        "description": "Completion payload emitted on mark:assist-finished SSE channel when AI-assisted annotation completes.",
-        "properties": {
-          "correlationId": {
-            "type": "string",
-            "description": "Echoes the correlationId from the originating mark:assist-request command, if any."
-          },
-          "motivation": {
-            "$ref": "#/components/schemas/Motivation"
-          },
-          "resourceId": {
-            "type": "string"
-          },
-          "status": {
-            "type": "string"
-          },
-          "percentage": {
-            "type": "number"
-          },
-          "foundCount": {
-            "type": "integer",
-            "description": "Number of annotations found/created"
-          },
-          "createdCount": {
-            "type": "integer",
-            "description": "Number of annotations actually created"
-          },
-          "byCategory": {
-            "type": "object",
-            "description": "Counts by category (for tag annotations)",
-            "additionalProperties": {
-              "type": "integer"
-            }
-          },
-          "message": {
-            "type": "string"
-          },
-          "progress": {
-            "$ref": "#/components/schemas/MarkProgress"
-          }
-        }
-      },
-      "MarkAssistFailed": {
-        "type": "object",
-        "description": "Error payload emitted on mark:assist-failed SSE channel when AI-assisted annotation fails.",
-        "properties": {
-          "correlationId": {
-            "type": "string",
-            "description": "Echoes the correlationId from the originating mark:assist-request command, if any."
-          },
-          "resourceId": {
-            "type": "string"
-          },
-          "message": {
-            "type": "string"
-          }
-        }
-      },
       "MatchSearchResult": {
         "type": "object",
         "description": "Search results payload emitted on match:search-results SSE channel.",
@@ -4523,108 +2890,30 @@
           }
         },
         "required": [
-          "correlationId",
-          "referenceId",
-          "response"
-        ]
-      },
-      "MatchSearchFailed": {
-        "type": "object",
-        "description": "Error payload emitted on match:search-failed SSE channel.",
-        "properties": {
-          "correlationId": {
-            "type": "string"
-          },
-          "referenceId": {
-            "type": "string"
-          },
-          "error": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "correlationId",
-          "referenceId",
-          "error"
-        ]
-      },
-      "YieldProgress": {
-        "type": "object",
-        "description": "Progress state for resource yield (generation) workflow. Emitted as SSE events on yield:progress and yield:finished channels.",
-        "properties": {
-          "correlationId": {
-            "type": "string",
-            "description": "Echoes the correlationId from the originating yield:request command, if any. Lets clients match progress events back to the operation that initiated them."
-          },
-          "status": {
-            "type": "string",
-            "enum": [
-              "started",
-              "fetching",
-              "generating",
-              "creating",
-              "complete",
-              "error"
-            ]
-          },
-          "referenceId": {
-            "type": "string",
-            "description": "ID of the reference annotation that triggered generation"
-          },
-          "resourceName": {
-            "type": "string",
-            "description": "Name of the resource being generated"
-          },
-          "resourceId": {
-            "type": "string",
-            "description": "ID of the generated resource (available after creation)"
-          },
-          "sourceResourceId": {
-            "type": "string",
-            "description": "ID of the source resource containing the reference"
-          },
-          "percentage": {
-            "type": "number",
-            "minimum": 0,
-            "maximum": 100,
-            "description": "Progress percentage (0-100)"
-          },
-          "message": {
-            "type": "string",
-            "description": "Human-readable status message"
-          }
-        },
-        "required": [
-          "status",
+          "correlationId",
           "referenceId",
-          "percentage"
+          "response"
         ]
       },
-      "YieldStreamError": {
+      "MatchSearchFailed": {
         "type": "object",
-        "description": "Error payload emitted on yield:failed SSE channel when resource generation fails.",
+        "description": "Error payload emitted on match:search-failed SSE channel.",
         "properties": {
           "correlationId": {
-            "type": "string",
-            "description": "Echoes the correlationId from the originating yield:request command, if any."
-          },
-          "error": {
-            "type": "string",
-            "description": "Error message"
-          },
-          "status": {
             "type": "string"
           },
           "referenceId": {
             "type": "string"
           },
-          "percentage": {
-            "type": "number"
-          },
-          "message": {
+          "error": {
             "type": "string"
           }
-        }
+        },
+        "required": [
+          "correlationId",
+          "referenceId",
+          "error"
+        ]
       },
       "EventMetadata": {
         "type": "object",
@@ -5065,6 +3354,10 @@
           "jobType": {
             "$ref": "#/components/schemas/JobType"
           },
+          "annotationId": {
+            "type": "string",
+            "description": "Annotation this job is attached to, when applicable"
+          },
           "totalSteps": {
             "type": "integer"
           }
@@ -5128,6 +3421,10 @@
           "jobType": {
             "$ref": "#/components/schemas/JobType"
           },
+          "annotationId": {
+            "type": "string",
+            "description": "Annotation this job was attached to, when applicable"
+          },
           "totalSteps": {
             "type": "integer"
           },
@@ -5167,6 +3464,10 @@
           "jobType": {
             "$ref": "#/components/schemas/JobType"
           },
+          "annotationId": {
+            "type": "string",
+            "description": "Annotation this job was attached to, when applicable"
+          },
           "error": {
             "type": "string"
           },
@@ -5180,99 +3481,6 @@
           "error"
         ]
       },
-      "AnnotateHighlightsStreamRequest": {
-        "type": "object",
-        "properties": {
-          "instructions": {
-            "type": "string",
-            "description": "Optional instructions to guide AI highlight annotation"
-          },
-          "density": {
-            "type": "number",
-            "minimum": 1,
-            "maximum": 15,
-            "description": "Optional density: desired number of highlights per 2000 words of text (1-15)"
-          }
-        }
-      },
-      "AnnotateAssessmentsStreamRequest": {
-        "type": "object",
-        "properties": {
-          "instructions": {
-            "type": "string",
-            "description": "Optional instructions to guide AI assessment annotation"
-          },
-          "tone": {
-            "type": "string",
-            "enum": [
-              "analytical",
-              "critical",
-              "balanced",
-              "constructive"
-            ],
-            "description": "Optional tone/style for generated assessments"
-          },
-          "density": {
-            "type": "number",
-            "minimum": 1,
-            "maximum": 10,
-            "description": "Optional density: desired number of assessments per 2000 words of text (1-10)"
-          },
-          "language": {
-            "type": "string",
-            "description": "BCP 47 language tag for the generated assessment text (e.g. \"en\", \"fr\", \"de\")"
-          }
-        }
-      },
-      "AnnotateCommentsStreamRequest": {
-        "type": "object",
-        "properties": {
-          "instructions": {
-            "type": "string",
-            "description": "Optional instructions to guide AI comment annotation"
-          },
-          "tone": {
-            "type": "string",
-            "enum": [
-              "scholarly",
-              "explanatory",
-              "conversational",
-              "technical"
-            ],
-            "description": "Optional tone/style for generated comments"
-          },
-          "density": {
-            "type": "number",
-            "minimum": 2,
-            "maximum": 12,
-            "description": "Optional density: desired number of comments per 2000 words of text (2-12)"
-          },
-          "language": {
-            "type": "string",
-            "description": "BCP 47 language tag for the generated comment text (e.g. 'en', 'fr', 'de')"
-          }
-        }
-      },
-      "AnnotateTagsStreamRequest": {
-        "type": "object",
-        "properties": {
-          "schemaId": {
-            "type": "string",
-            "description": "Tag schema ID (e.g., 'legal-irac', 'scientific-imrad', 'argument-toulmin')"
-          },
-          "categories": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            },
-            "description": "Categories to annotate from the selected schema (e.g., ['Issue', 'Rule', 'Application', 'Conclusion'])"
-          }
-        },
-        "required": [
-          "schemaId",
-          "categories"
-        ]
-      },
       "ErrorResponse": {
         "type": "object",
         "properties": {
@@ -5306,114 +3514,6 @@
           "data"
         ]
       },
-      "YieldResourceFromAnnotationRequest": {
-        "type": "object",
-        "properties": {
-          "name": {
-            "type": "string",
-            "description": "Optional name for the generated resource"
-          },
-          "entityTypes": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            },
-            "description": "Entity types for the generated resource"
-          },
-          "prompt": {
-            "type": "string",
-            "description": "Optional AI prompt for generation"
-          },
-          "language": {
-            "type": "string",
-            "description": "Language code (e.g., 'en', 'es')"
-          }
-        }
-      },
-      "YieldResourceFromAnnotationResponse": {
-        "type": "object",
-        "properties": {
-          "resource": {
-            "$ref": "#/components/schemas/ResourceDescriptor"
-          },
-          "annotation": {
-            "$ref": "#/components/schemas/Annotation"
-          },
-          "generated": {
-            "type": "boolean"
-          }
-        },
-        "required": [
-          "resource",
-          "annotation",
-          "generated"
-        ]
-      },
-      "YieldResourceRequest": {
-        "type": "object",
-        "properties": {
-          "resourceId": {
-            "type": "string",
-            "description": "Resource ID containing the annotation"
-          },
-          "title": {
-            "type": "string",
-            "description": "Custom title for generated resource"
-          },
-          "prompt": {
-            "type": "string",
-            "description": "Custom prompt for content generation"
-          },
-          "language": {
-            "type": "string",
-            "description": "Language locale (e.g., \"es\", \"fr\", \"ja\")"
-          }
-        },
-        "required": [
-          "resourceId"
-        ]
-      },
-      "YieldResourceStreamRequest": {
-        "type": "object",
-        "properties": {
-          "title": {
-            "type": "string",
-            "description": "Custom title for generated resource"
-          },
-          "prompt": {
-            "type": "string",
-            "description": "Custom prompt for content generation"
-          },
-          "language": {
-            "type": "string",
-            "description": "Language locale for generated content (e.g., \"es\", \"fr\", \"ja\")"
-          },
-          "context": {
-            "$ref": "#/components/schemas/GatheredContext",
-            "description": "Gathered context including source document excerpts, metadata, and graph context"
-          },
-          "temperature": {
-            "type": "number",
-            "minimum": 0,
-            "maximum": 1,
-            "description": "Inference temperature (0.0 = focused, 1.0 = creative)"
-          },
-          "maxTokens": {
-            "type": "number",
-            "minimum": 100,
-            "maximum": 4000,
-            "description": "Maximum tokens to generate"
-          },
-          "storageUri": {
-            "type": "string",
-            "description": "file://-relative URI where the generated resource will be saved (e.g. file://generated/overview.md)"
-          }
-        },
-        "required": [
-          "context",
-          "storageUri"
-        ]
-      },
       "GetAnnotationHistoryResponse": {
         "type": "object",
         "properties": {
@@ -5730,32 +3830,6 @@
           "created"
         ]
       },
-      "ListAnnotationsResponse": {
-        "type": "object",
-        "properties": {
-          "annotations": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/Annotation"
-            }
-          },
-          "total": {
-            "type": "number"
-          },
-          "offset": {
-            "type": "number"
-          },
-          "limit": {
-            "type": "number"
-          }
-        },
-        "required": [
-          "annotations",
-          "total",
-          "offset",
-          "limit"
-        ]
-      },
       "ListResourcesResponse": {
         "type": "object",
         "properties": {
@@ -5975,37 +4049,6 @@
           }
         }
       },
-      "BindAnnotationRequest": {
-        "type": "object",
-        "properties": {
-          "resourceId": {
-            "type": "string",
-            "description": "Target resource ID to resolve reference to"
-          }
-        },
-        "required": [
-          "resourceId"
-        ]
-      },
-      "BindAnnotationResponse": {
-        "type": "object",
-        "properties": {
-          "annotation": {
-            "$ref": "#/components/schemas/Annotation"
-          },
-          "targetResource": {
-            "nullable": true,
-            "allOf": [
-              {
-                "$ref": "#/components/schemas/ResourceDescriptor"
-              }
-            ]
-          }
-        },
-        "required": [
-          "annotation"
-        ]
-      },
       "ResourceDescriptor": {
         "type": "object",
         "description": "Metadata about a resource (1:1 with its URI). JSON-LD subject is @id. Link to concrete bytes via representations.",
@@ -6632,20 +4675,6 @@
           "operations"
         ]
       },
-      "UpdateResourceRequest": {
-        "type": "object",
-        "properties": {
-          "entityTypes": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            }
-          },
-          "archived": {
-            "type": "boolean"
-          }
-        }
-      },
       "UpdateUserRequest": {
         "type": "object",
         "properties": {
@@ -6827,14 +4856,19 @@
       },
       "BindBodyUpdated": {
         "type": "object",
-        "description": "Event payload emitted on the bind:body-updated bus channel after annotation bodies are modified.",
+        "description": "Success result emitted on the bind:body-updated bus channel after bind:update-body has been applied.",
         "properties": {
+          "correlationId": {
+            "type": "string",
+            "description": "Correlation ID echoed from the originating bind:update-body command"
+          },
           "annotationId": {
             "type": "string",
             "description": "Branded AnnotationId of the annotation whose body was updated"
           }
         },
         "required": [
+          "correlationId",
           "annotationId"
         ]
       },
@@ -6873,6 +4907,10 @@
         "type": "object",
         "description": "Command payload sent on the bind:update-body bus channel to modify annotation bodies.",
         "properties": {
+          "_userId": {
+            "type": "string",
+            "description": "Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this."
+          },
           "correlationId": {
             "type": "string",
             "description": "Client-supplied id used to match this command to its result event(s) on the events-stream. Generated by the route handler if absent."
@@ -6885,10 +4923,6 @@
             "type": "string",
             "description": "Branded ResourceId of the resource the annotation belongs to"
           },
-          "userId": {
-            "type": "string",
-            "description": "Branded UserId of the user performing the update"
-          },
           "operations": {
             "type": "array",
             "items": {
@@ -7018,7 +5052,37 @@
         },
         "required": [
           "correlationId",
-          "response"
+          "response"
+        ]
+      },
+      "BrowseAnnotationContextRequest": {
+        "type": "object",
+        "description": "Request to get contextual text around an annotation",
+        "properties": {
+          "correlationId": {
+            "type": "string"
+          },
+          "annotationId": {
+            "type": "string"
+          },
+          "resourceId": {
+            "type": "string"
+          },
+          "contextBefore": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 5000
+          },
+          "contextAfter": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 5000
+          }
+        },
+        "required": [
+          "correlationId",
+          "annotationId",
+          "resourceId"
         ]
       },
       "BrowseAnnotationsRequest": {
@@ -7481,7 +5545,7 @@
       },
       "GatherAnnotationRequest": {
         "type": "object",
-        "description": "Request payload sent on the gather:annotation-request bus channel to gather context for an annotation.",
+        "description": "Request payload sent on the gather:requested bus channel to gather context for an annotation.",
         "properties": {
           "correlationId": {
             "type": "string",
@@ -7705,7 +5769,7 @@
       },
       "GatherResourceRequest": {
         "type": "object",
-        "description": "Request payload sent on the gather:resource-request bus channel to gather context for a resource.",
+        "description": "Request payload sent on the gather:resource-requested bus channel to gather context for a resource.",
         "properties": {
           "correlationId": {
             "type": "string",
@@ -7750,6 +5814,26 @@
           "options"
         ]
       },
+      "GatherSummaryRequest": {
+        "type": "object",
+        "description": "Request to generate an AI summary of an annotation",
+        "properties": {
+          "correlationId": {
+            "type": "string"
+          },
+          "annotationId": {
+            "type": "string"
+          },
+          "resourceId": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "correlationId",
+          "annotationId",
+          "resourceId"
+        ]
+      },
       "JobAssessmentAnnotationResult": {
         "type": "object",
         "description": "Result of a completed assessment-annotation job.",
@@ -7782,6 +5866,79 @@
           "jobType"
         ]
       },
+      "JobClaimCommand": {
+        "type": "object",
+        "description": "Command to claim a pending job (atomic CAS: pending → running)",
+        "properties": {
+          "correlationId": {
+            "type": "string"
+          },
+          "jobId": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "correlationId",
+          "jobId"
+        ]
+      },
+      "JobCreateCommand": {
+        "type": "object",
+        "description": "Command to create a new job via the event bus",
+        "properties": {
+          "correlationId": {
+            "type": "string"
+          },
+          "jobType": {
+            "type": "string",
+            "enum": [
+              "reference-annotation",
+              "highlight-annotation",
+              "assessment-annotation",
+              "comment-annotation",
+              "tag-annotation",
+              "generation"
+            ]
+          },
+          "resourceId": {
+            "type": "string"
+          },
+          "params": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        },
+        "required": [
+          "correlationId",
+          "jobType",
+          "resourceId",
+          "params"
+        ]
+      },
+      "JobCreatedResult": {
+        "type": "object",
+        "description": "Result of a job:create command",
+        "properties": {
+          "correlationId": {
+            "type": "string"
+          },
+          "response": {
+            "type": "object",
+            "properties": {
+              "jobId": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "jobId"
+            ]
+          }
+        },
+        "required": [
+          "correlationId",
+          "response"
+        ]
+      },
       "JobCommentAnnotationResult": {
         "type": "object",
         "description": "Result of a completed comment-annotation job.",
@@ -7802,10 +5959,11 @@
         "type": "object",
         "description": "Command to mark a job as complete",
         "properties": {
-          "resourceId": {
-            "type": "string"
+          "_userId": {
+            "type": "string",
+            "description": "Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this."
           },
-          "userId": {
+          "resourceId": {
             "type": "string"
           },
           "jobId": {
@@ -7814,13 +5972,16 @@
           "jobType": {
             "$ref": "#/components/schemas/JobType"
           },
+          "annotationId": {
+            "type": "string",
+            "description": "Annotation this job is attached to, when applicable. Lets the UI route completion feedback (toast, resolve state) to a specific annotation."
+          },
           "result": {
             "$ref": "#/components/schemas/JobResult"
           }
         },
         "required": [
           "resourceId",
-          "userId",
           "jobId",
           "jobType"
         ]
@@ -7829,10 +5990,11 @@
         "type": "object",
         "description": "Command to mark a job as failed",
         "properties": {
-          "resourceId": {
-            "type": "string"
+          "_userId": {
+            "type": "string",
+            "description": "Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this."
           },
-          "userId": {
+          "resourceId": {
             "type": "string"
           },
           "jobId": {
@@ -7841,13 +6003,16 @@
           "jobType": {
             "$ref": "#/components/schemas/JobType"
           },
+          "annotationId": {
+            "type": "string",
+            "description": "Annotation this job is attached to, when applicable. Lets the UI route failure feedback (error toast, revert state) to a specific annotation."
+          },
           "error": {
             "type": "string"
           }
         },
         "required": [
           "resourceId",
-          "userId",
           "jobId",
           "jobType",
           "error"
@@ -7855,11 +6020,11 @@
       },
       "JobGenerationResult": {
         "type": "object",
-        "description": "Result of a completed generation job.",
+        "description": "Result of a completed generation job. resourceId is assigned by Stower when yield:create is processed; the worker emits job:complete with only resourceName, and Stower populates resourceId on the persisted payload.",
         "properties": {
           "resourceId": {
             "type": "string",
-            "description": "ID of the generated resource"
+            "description": "ID of the generated resource (populated by Stower, not by the worker)"
           },
           "resourceName": {
             "type": "string",
@@ -7867,7 +6032,6 @@
           }
         },
         "required": [
-          "resourceId",
           "resourceName"
         ]
       },
@@ -7889,11 +6053,11 @@
       },
       "JobProgress": {
         "type": "object",
-        "description": "Progress report from a running job. Common fields are stage/percentage/message; job-type-specific fields may also be present.",
+        "description": "Progress report from a running job. Common fields are stage/percentage/message; job-type-specific fields may also be present. This is the single progress shape for every job type — annotation workers and generation alike.",
         "properties": {
           "stage": {
             "type": "string",
-            "description": "Current processing stage"
+            "description": "Current processing stage (e.g. 'analyzing', 'creating', 'complete', 'error')"
           },
           "percentage": {
             "type": "number",
@@ -7903,6 +6067,10 @@
             "type": "string",
             "description": "Human-readable progress message"
           },
+          "annotationId": {
+            "type": "string",
+            "description": "Annotation this job is attached to, when applicable. Echoed inside JobProgress (in addition to the outer command envelope) so consumers that only see the inner progress object (e.g. client.yield.fromAnnotation's Observable) can still route visual feedback to a specific annotation."
+          },
           "totalEntityTypes": {
             "type": "integer",
             "description": "Total entity types to process (reference-annotation)"
@@ -7923,6 +6091,25 @@
             "type": "string",
             "description": "Entity type currently being processed"
           },
+          "completedEntityTypes": {
+            "type": "array",
+            "description": "Reference annotation: completed entity types with per-type counts, for UI progress display",
+            "items": {
+              "type": "object",
+              "properties": {
+                "entityType": {
+                  "type": "string"
+                },
+                "foundCount": {
+                  "type": "integer"
+                }
+              },
+              "required": [
+                "entityType",
+                "foundCount"
+              ]
+            }
+          },
           "processedCategories": {
             "type": "integer",
             "description": "Categories processed (tag-annotation)"
@@ -7934,6 +6121,25 @@
           "currentCategory": {
             "type": "string",
             "description": "Category currently being processed (tag-annotation)"
+          },
+          "requestParams": {
+            "type": "array",
+            "description": "Echoed job parameters for display in the progress UI (e.g. entity types or categories the user asked to detect)",
+            "items": {
+              "type": "object",
+              "properties": {
+                "label": {
+                  "type": "string"
+                },
+                "value": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "label",
+                "value"
+              ]
+            }
           }
         },
         "required": [
@@ -7954,12 +6160,17 @@
           },
           "resourceId": {
             "type": "string"
+          },
+          "userId": {
+            "type": "string",
+            "description": "DID of the user who initiated the job (audit)."
           }
         },
         "required": [
           "jobId",
           "jobType",
-          "resourceId"
+          "resourceId",
+          "userId"
         ]
       },
       "JobReferenceAnnotationResult": {
@@ -7989,10 +6200,11 @@
         "type": "object",
         "description": "Command to report progress on a job",
         "properties": {
-          "resourceId": {
-            "type": "string"
+          "_userId": {
+            "type": "string",
+            "description": "Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this."
           },
-          "userId": {
+          "resourceId": {
             "type": "string"
           },
           "jobId": {
@@ -8001,6 +6213,10 @@
           "jobType": {
             "$ref": "#/components/schemas/JobType"
           },
+          "annotationId": {
+            "type": "string",
+            "description": "Annotation this job is attached to, when applicable. Lets the UI attach progress visuals to a specific annotation (e.g. a reference whose generation is running)."
+          },
           "percentage": {
             "type": "number"
           },
@@ -8010,7 +6226,6 @@
         },
         "required": [
           "resourceId",
-          "userId",
           "jobId",
           "jobType",
           "percentage"
@@ -8043,10 +6258,11 @@
         "type": "object",
         "description": "Command to start a job",
         "properties": {
-          "resourceId": {
-            "type": "string"
+          "_userId": {
+            "type": "string",
+            "description": "Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this."
           },
-          "userId": {
+          "resourceId": {
             "type": "string"
           },
           "jobId": {
@@ -8054,11 +6270,14 @@
           },
           "jobType": {
             "$ref": "#/components/schemas/JobType"
+          },
+          "annotationId": {
+            "type": "string",
+            "description": "Annotation this job is attached to, when applicable. Set for annotation-scoped jobs like generation (from a specific reference). Unset for resource-scoped jobs like bulk reference/tag/highlight detection."
           }
         },
         "required": [
           "resourceId",
-          "userId",
           "jobId",
           "jobType"
         ]
@@ -8126,21 +6345,22 @@
           "tag": {
             "type": "string"
           },
-          "userId": {
-            "type": "string"
+          "_userId": {
+            "type": "string",
+            "description": "Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this."
           }
         },
         "required": [
-          "tag",
-          "userId"
+          "tag"
         ]
       },
       "MarkArchiveCommand": {
         "type": "object",
         "description": "Bus command to archive a resource and optionally remove its file.",
         "properties": {
-          "userId": {
-            "type": "string"
+          "_userId": {
+            "type": "string",
+            "description": "Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this."
           },
           "resourceId": {
             "type": "string"
@@ -8237,19 +6457,23 @@
         "type": "object",
         "description": "Bus command to create an annotation on a resource.",
         "properties": {
+          "_userId": {
+            "type": "string",
+            "description": "Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this."
+          },
+          "correlationId": {
+            "type": "string",
+            "description": "Optional correlation id threaded from the originating mark:create-request. Propagated into event metadata by Stower so annotation-assembly can emit mark:create-ok after persistence completes."
+          },
           "annotation": {
             "$ref": "#/components/schemas/Annotation"
           },
-          "userId": {
-            "type": "string"
-          },
           "resourceId": {
             "type": "string"
           }
         },
         "required": [
           "annotation",
-          "userId",
           "resourceId"
         ]
       },
@@ -8265,14 +6489,35 @@
           "annotationId"
         ]
       },
+      "MarkCreateRequest": {
+        "type": "object",
+        "description": "Raw annotation creation intent — bus handler assembles the W3C annotation",
+        "properties": {
+          "correlationId": {
+            "type": "string"
+          },
+          "resourceId": {
+            "type": "string"
+          },
+          "request": {
+            "$ref": "#/components/schemas/CreateAnnotationRequest"
+          }
+        },
+        "required": [
+          "correlationId",
+          "resourceId",
+          "request"
+        ]
+      },
       "MarkDeleteCommand": {
         "type": "object",
         "description": "Bus command to delete an annotation.",
         "properties": {
-          "annotationId": {
-            "type": "string"
+          "_userId": {
+            "type": "string",
+            "description": "Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this."
           },
-          "userId": {
+          "annotationId": {
             "type": "string"
           },
           "resourceId": {
@@ -8413,24 +6658,35 @@
             ]
           },
           "body": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/AnnotationBody"
-            }
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/AnnotationBody",
+                "description": "Single body (TextualBody or SpecificResource)"
+              },
+              {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/AnnotationBody"
+                },
+                "minItems": 1,
+                "description": "Non-empty array of mixed TextualBody / SpecificResource bodies"
+              }
+            ],
+            "description": "Optional body. Omit for annotations whose motivation alone is meaningful (e.g. highlighting) or whose user-supplied content is empty (e.g. an assessing annotation saved without comment text). Shape matches Annotation.body."
           }
         },
         "required": [
           "motivation",
-          "selector",
-          "body"
+          "selector"
         ]
       },
       "MarkUnarchiveCommand": {
         "type": "object",
         "description": "Bus command to unarchive a previously archived resource.",
         "properties": {
-          "userId": {
-            "type": "string"
+          "_userId": {
+            "type": "string",
+            "description": "Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this."
           },
           "resourceId": {
             "type": "string"
@@ -8447,6 +6703,10 @@
         "type": "object",
         "description": "Bus command to update an annotation's body with patch operations.",
         "properties": {
+          "_userId": {
+            "type": "string",
+            "description": "Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this."
+          },
           "correlationId": {
             "type": "string",
             "description": "Correlation id threaded from the originating route through to event metadata. Lets the events-stream deliver matched results to the client that initiated the bind."
@@ -8454,9 +6714,6 @@
           "annotationId": {
             "type": "string"
           },
-          "userId": {
-            "type": "string"
-          },
           "resourceId": {
             "type": "string"
           },
@@ -8479,7 +6736,6 @@
         },
         "required": [
           "annotationId",
-          "userId",
           "resourceId",
           "operations"
         ]
@@ -8491,8 +6747,9 @@
           "resourceId": {
             "type": "string"
           },
-          "userId": {
-            "type": "string"
+          "_userId": {
+            "type": "string",
+            "description": "Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this."
           },
           "currentEntityTypes": {
             "type": "array",
@@ -8509,7 +6766,6 @@
         },
         "required": [
           "resourceId",
-          "userId",
           "currentEntityTypes",
           "updatedEntityTypes"
         ]
@@ -8722,6 +6978,10 @@
         "type": "object",
         "description": "Bus command to create a yielded resource in the knowledge base.",
         "properties": {
+          "_userId": {
+            "type": "string",
+            "description": "Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this."
+          },
           "name": {
             "type": "string"
           },
@@ -8737,9 +6997,6 @@
           "format": {
             "$ref": "#/components/schemas/ContentFormat"
           },
-          "userId": {
-            "type": "string"
-          },
           "language": {
             "type": "string"
           },
@@ -8791,8 +7048,7 @@
           "storageUri",
           "contentChecksum",
           "byteSize",
-          "format",
-          "userId"
+          "format"
         ]
       },
       "YieldCreateOk": {
@@ -8827,23 +7083,23 @@
         "type": "object",
         "description": "Bus command to move (rename) a yielded resource.",
         "properties": {
+          "_userId": {
+            "type": "string",
+            "description": "Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this."
+          },
           "fromUri": {
             "type": "string"
           },
           "toUri": {
             "type": "string"
           },
-          "userId": {
-            "type": "string"
-          },
           "noGit": {
             "type": "boolean"
           }
         },
         "required": [
           "fromUri",
-          "toUri",
-          "userId"
+          "toUri"
         ]
       },
       "YieldRequestCommand": {
@@ -8901,6 +7157,10 @@
         "type": "object",
         "description": "Bus command to update a yielded resource's storage content.",
         "properties": {
+          "_userId": {
+            "type": "string",
+            "description": "Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this."
+          },
           "resourceId": {
             "type": "string"
           },
@@ -8913,9 +7173,6 @@
           "byteSize": {
             "type": "integer"
           },
-          "userId": {
-            "type": "string"
-          },
           "noGit": {
             "type": "boolean"
           }
@@ -8924,8 +7181,7 @@
           "resourceId",
           "storageUri",
           "contentChecksum",
-          "byteSize",
-          "userId"
+          "byteSize"
         ]
       },
       "YieldUpdateOk": {