Update API docs for 2.4 (#960)

- Update API specs for 2.4 (#960)
- Update API docs
- Regenerate Python docs

specs/api/paths/collection-management.yaml

@@ -1,10 +1,13 @@
 post:
   tags:
     - Collection
-  summary: Collection metadata management
+  summary: Collection metadata management (workspace-scoped)
   description: |
     Manage collection metadata for organizing documents and knowledge.
 
+    This is a **workspace-scoped** service. All operations apply to the
+    workspace associated with the authenticated bearer token.
+
     ## Collections
 
     Collections are organizational units for grouping:

specs/api/paths/config.yaml

@@ -1,9 +1,13 @@
 post:
   tags:
     - Config
-  summary: Configuration service
+  summary: Configuration service (workspace-scoped)
   description: |
-    Manage TrustGraph configuration including flows, prompts, token costs, parameter types, and more.
+    Manage TrustGraph configuration including flows, prompts, token costs,
+    parameter types, and more.
+
+    This is a **workspace-scoped** service. All operations apply to the
+    workspace associated with the authenticated bearer token.
 
     ## Operations
 

specs/api/paths/flow.yaml

@@ -1,10 +1,13 @@
 post:
   tags:
     - Flow
-  summary: Flow lifecycle and blueprint management
+  summary: Flow lifecycle and blueprint management (workspace-scoped)
   description: |
     Manage flow instances and blueprints.
 
+    This is a **workspace-scoped** service. All operations apply to the
+    workspace associated with the authenticated bearer token.
+
     ## Important Distinction
 
     The **flow service** manages *running flow instances*.

specs/api/paths/flow/agent.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     AI agent that can understand questions, reason about them, and take actions.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Agent Overview
 
     The agent service provides a conversational AI that:

specs/api/paths/flow/document-embeddings.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Query document embeddings to find similar text chunks by vector similarity.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Document Embeddings Query Overview
 
     Find document chunks semantically similar to a query vector:

specs/api/paths/flow/document-load.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Load binary documents (PDF, Word, etc.) into processing pipeline.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Document Load Overview
 
     Fire-and-forget binary document loading:

specs/api/paths/flow/document-rag.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Retrieval-Augmented Generation over document embeddings.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Document RAG Overview
 
     Document RAG combines:

specs/api/paths/flow/embeddings.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Convert text to embedding vectors for semantic similarity search.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Embeddings Overview
 
     Embeddings transform text into dense vector representations that:

specs/api/paths/flow/graph-embeddings.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Query graph embeddings to find similar entities by vector similarity.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Graph Embeddings Query Overview
 
     Find entities semantically similar to a query vector:

specs/api/paths/flow/graph-rag.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Retrieval-Augmented Generation over knowledge graph.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Graph RAG Overview
 
     Graph RAG combines:

specs/api/paths/flow/mcp-tool.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Execute MCP (Model Context Protocol) tools for agent capabilities.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## MCP Tool Overview
 
     MCP tools provide agent capabilities through standardized protocol:

specs/api/paths/flow/nlp-query.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Convert natural language questions to structured GraphQL queries.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## NLP Query Overview
 
     Transforms user questions into executable GraphQL:

specs/api/paths/flow/prompt.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Execute stored prompt templates with variable substitution.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Prompt Service Overview
 
     The prompt service enables:

specs/api/paths/flow/row-embeddings.yaml

@@ -4,6 +4,11 @@ post:
   summary: Row Embeddings Query - semantic search on structured data
   description: |
     Query row embeddings to find similar rows by vector similarity on indexed fields.
+
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     Enables fuzzy/semantic matching on structured data.
 
     ## Row Embeddings Query Overview

specs/api/paths/flow/rows.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Query structured data using GraphQL for row-oriented data access.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Rows Query Overview
 
     GraphQL interface to structured data:

specs/api/paths/flow/sparql-query.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Execute a SPARQL 1.1 query against the knowledge graph.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Supported Query Types
 
     - **SELECT**: Returns variable bindings as a table of results

specs/api/paths/flow/structured-diag.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Analyze and understand structured data (CSV, JSON, XML).
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Structured Diag Overview
 
     Helps process unknown structured data:

specs/api/paths/flow/structured-query.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Ask natural language questions and get results directly.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Structured Query Overview
 
     Combines two operations in one call:

specs/api/paths/flow/text-completion.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Direct text completion using LLM without retrieval augmentation.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Text Completion Overview
 
     Pure LLM generation for:

specs/api/paths/flow/text-load.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Load text documents into processing pipeline for indexing and embedding.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Text Load Overview
 
     Fire-and-forget document loading:

specs/api/paths/flow/triples.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Query knowledge graph using subject-predicate-object patterns.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Triples Query Overview
 
     Query RDF triples with flexible pattern matching:

specs/api/paths/knowledge.yaml

@@ -1,9 +1,13 @@
 post:
   tags:
     - Knowledge
-  summary: Knowledge graph core management
+  summary: Knowledge graph core management (workspace-scoped)
   description: |
-    Manage knowledge graph cores - persistent storage of triples and embeddings.
+    Manage knowledge graph cores - persistent storage of triples and
+    embeddings.
+
+    This is a **workspace-scoped** service. All operations apply to the
+    workspace associated with the authenticated bearer token.
 
     ## Knowledge Cores
 

specs/api/paths/librarian.yaml

@@ -1,9 +1,13 @@
 post:
   tags:
     - Librarian
-  summary: Document library management
+  summary: Document library management (workspace-scoped)
   description: |
-    Manage document library: add, remove, list documents, and control processing.
+    Manage document library: add, remove, list documents, and control
+    processing.
+
+    This is a **workspace-scoped** service. All operations apply to the
+    workspace associated with the authenticated bearer token.
 
     ## Document Library
 

specs/api/paths/websocket.yaml

@@ -26,7 +26,7 @@ get:
 
     ### Request Message Format
 
-    **Global Service Request** (no flow parameter):
+    **Workspace-Scoped Service Request** (no flow parameter):
     ```json
     {
       "id": "req-123",
@@ -38,7 +38,7 @@ get:
     }
     ```
 
-    **Flow-Hosted Service Request** (with flow parameter):
+    **Flow-Scoped Service Request** (with flow parameter):
     ```json
     {
       "id": "req-456",
@@ -54,7 +54,7 @@ get:
     **Request Fields**:
     - `id` (string, required): Client-generated unique identifier for this request within the session. Used to match responses to requests.
     - `service` (string, required): Service identifier (e.g., "config", "agent", "document-rag"). Same as `{kind}` in REST URLs.
-    - `flow` (string, optional): Flow ID for flow-hosted services. Omit for global services.
+    - `flow` (string, optional): Flow ID for flow-scoped services. Omit for workspace-scoped and global services.
     - `request` (object, required): Service-specific request payload. Same structure as REST API request body.
 
     ### Response Message Format
@@ -96,14 +96,14 @@ get:
     | `POST /api/v1/config` | `{"service": "config"}` |
     | `POST /api/v1/flow/{flow}/service/agent` | `{"service": "agent", "flow": "my-flow"}` |
 
-    **Global Services** (no `flow` parameter):
+    **Workspace-Scoped Services** (no `flow` parameter, workspace from token):
     - `config` - Configuration management
     - `flow` - Flow lifecycle and blueprints
     - `librarian` - Document library management
     - `knowledge` - Knowledge graph core management
     - `collection-management` - Collection metadata
 
-    **Flow-Hosted Services** (require `flow` parameter):
+    **Flow-Scoped Services** (require `flow` parameter, workspace from token):
     - AI services: `agent`, `text-completion`, `prompt`, `document-rag`, `graph-rag`
     - Embeddings: `embeddings`, `graph-embeddings`, `document-embeddings`
     - Query: `triples`, `objects`, `nlp-query`, `structured-query`
@@ -146,9 +146,11 @@ get:
 
     ## Authentication
 
-    When `GATEWAY_SECRET` is set, include bearer token:
-    - As query parameter: `ws://localhost:8088/api/v1/socket?token=<token>`
-    - Or in WebSocket subprotocol header
+    The `/api/v1/socket` endpoint uses in-band authentication.
+    The WebSocket handshake is accepted unconditionally.  After
+    connecting, the client sends a bearer token as the first frame.
+    The gateway resolves the token to an identity and workspace.
+    All subsequent requests operate within that workspace context.
 
     ## Benefits Over REST