@arke-institute/sdk 2.3.14 → 2.6.1

package/dist/generated/index.d.ts

@@ -6,7 +6,7 @@
  *
  * Source: Arke v1 API
  * Version: 1.0.0
- * Generated: 2026-01-22T18:25:50.170Z
+ * Generated: 2026-01-26T22:08:41.056Z
  */
 type paths = {
     "/ops-reference": {
@@ -708,6 +708,17 @@ type paths = {
          *     - Results use cosine similarity scores (0-1)
          *     - Scores are comparable across collections
          *
+         *     ## Entity Expansion
+         *
+         *     Use `expand` in the request body to fetch entity data inline with search results:
+         *
+         *     - **`expand: "preview"` (default)**: Adds `entity_preview` with fresh lightweight data (id, type, label, timestamps)
+         *     - **`expand: "full"`**: Adds `entity` with complete manifest including all properties and relationships
+         *     - **`expand: "none"`**: Returns search metadata only (fastest, lowest bandwidth)
+         *
+         *     Preview mode is recommended for most use cases. Full expansion can result in large payloads.
+         *     Gracefully handles deleted or inaccessible entities (returns results without expansion data).
+         *
          *
          *     ---
          *     **Permission:** `search:execute`
@@ -1848,6 +1859,18 @@ type paths = {
          *
          *     Supports pagination and optional type filtering. Results are ordered by creation date (newest first).
          *
+         *     **Expansion Modes:**
+         *
+         *     By default, returns lightweight summaries from GraphDB (pi, type, label, timestamps).
+         *
+         *     Use the `expand` parameter to hydrate entity data from storage:
+         *
+         *     - **`?expand=preview`**: Adds `preview` field with fresh lightweight data (label, truncated description/text, timestamps). ~5-10KB per entity.
+         *
+         *     - **`?expand=full`**: Adds `entity` field with complete manifest (all properties, relationships, version history). ~20-50KB per entity.
+         *
+         *     **Performance Note:** Expansion requires fetching each entity from storage. Limited to 100 entities per request. Use smaller `limit` values when expanding.
+         *
          *     ---
          *     **Permission:** `collection:view`
          *     **Auth:** optional
@@ -1858,6 +1881,7 @@ type paths = {
                     type?: string;
                     limit?: number;
                     offset?: number | null;
+                    expand?: "preview" | "full";
                 };
                 header?: never;
                 path: {
@@ -2051,13 +2075,69 @@ type paths = {
          * Get entity by ID
          * @description Returns any entity by ID. Permission check uses parent collection if entity belongs to one.
          *
+         *     **Relationship Expansion:**
+         *
+         *     Use the `expand=relationships[:mode]` query parameter to hydrate relationship peer data:
+         *
+         *     - **No expansion (default)**: Returns relationships with stored `peer_label`/`peer_type` (may be stale)
+         *       ```json
+         *       { "predicate": "contains", "peer": "01KDOC...", "peer_label": "Old Label" }
+         *       ```
+         *
+         *     - **`?expand=relationships:preview`**: Adds `peer_preview` with fresh lightweight data (id, type, label, truncated description/text, timestamps)
+         *       ```json
+         *       {
+         *         "predicate": "contains",
+         *         "peer": "01KDOC...",
+         *         "peer_label": "Old Label",
+         *         "peer_preview": {
+         *           "id": "01KDOC...",
+         *           "type": "document",
+         *           "label": "Updated Label",
+         *           "description_preview": "This is a document with...",
+         *           "created_at": "2025-01-15T10:00:00Z",
+         *           "updated_at": "2025-01-20T14:30:00Z"
+         *         }
+         *       }
+         *       ```
+         *
+         *     - **`?expand=relationships:full`**: Adds `peer_entity` with complete entity manifest (all properties, relationships, version history)
+         *       ```json
+         *       {
+         *         "predicate": "contains",
+         *         "peer": "01KDOC...",
+         *         "peer_label": "Old Label",
+         *         "peer_entity": {
+         *           "id": "01KDOC...",
+         *           "cid": "bafyrei...",
+         *           "type": "document",
+         *           "properties": { "label": "Updated Label", "text": "..." },
+         *           "relationships": [...],
+         *           "ver": 3,
+         *           "created_at": "2025-01-15T10:00:00Z",
+         *           "ts": 1737380000000,
+         *           "edited_by": { "user_id": "01JUSER...", "method": "manual" }
+         *         }
+         *       }
+         *       ```
+         *
+         *     **Performance:** Preview expansion is recommended for most use cases. Full expansion with many large entities can result in multi-MB payloads.
+         *
+         *     **Expansion Limit:**
+         *     Use `?expand_limit=N` to control maximum relationships expanded (1-500, default 100). When truncated, the response includes `_expansion_metadata` with counts.
+         *
          *     ---
          *     **Permission:** `entity:view`
          *     **Auth:** optional
          */
         get: {
             parameters: {
-                query?: never;
+                query?: {
+                    /** @description Comma-separated list of fields to expand. Supports: relationships[:preview|full] */
+                    expand?: string;
+                    /** @description Maximum number of relationships to expand (1-500, default 100). When exceeded, relationships beyond the limit are returned without peer data. */
+                    expand_limit?: number;
+                };
                 header?: never;
                 path: {
                     /** @description Entity ID (ULID) */
@@ -2371,6 +2451,88 @@ type paths = {
         patch?: never;
         trace?: never;
     };
+    "/entities/{id}/preview": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get entity preview
+         * @description Returns lightweight preview data for an entity. Useful for:
+         *     - Link previews and hover cards
+         *     - Relationship metadata freshness (vs stale peer_label)
+         *     - AI context management (smaller payloads)
+         *     - Search result enhancement
+         *
+         *     Returns: id, type, label, collection_pi, description_preview (200 chars), text_preview (200 chars), timestamps.
+         *
+         *     **Performance:** Single KV fetch, ~40-60ms response time, typically <1KB payload.
+         *
+         *     ---
+         *     **Permission:** `entity:view`
+         *     **Auth:** optional
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Entity ID (ULID) */
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Entity preview data */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["EntityPreview"];
+                    };
+                };
+                /** @description Forbidden - Insufficient permissions */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Forbidden: You do not have permission to perform this action"
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Not Found - Resource does not exist */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Entity not found"
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/entities/{id}/tip": {
         parameters: {
             query?: never;
@@ -6453,7 +6615,7 @@ type paths = {
         patch?: never;
         trace?: never;
     };
-    "/jobs/{id}": {
+    "/agents/{id}/jobs/{job_id}/status": {
         parameters: {
             query?: never;
             header?: never;
@@ -6461,68 +6623,110 @@ type paths = {
             cookie?: never;
         };
         /**
-         * Get job status
-         * @description Returns focused job status and summary. Use this endpoint for quick status polling.
+         * Get job status from agent
+         * @description Proxies to the agent's `/status/:job_id` endpoint and returns the response.
+         *
+         *     Use this endpoint to poll job status after invoking an agent. The `agent_id` and `job_id`
+         *     are both returned in the invoke response.
+         *
+         *     **Query Parameters (passed through to agent):**
+         *     - `detail=full` - Include detailed sub-job/dispatch information (orchestrators/workflows)
+         *     - `errors=N` - Include last N errors (orchestrators only)
          *
-         *     Returns 404 if the entity is not a job collection.
+         *     **Response:** Returns the agent's status response directly. Schema varies by agent type
+         *     (service, workflow, orchestrator) but always includes:
+         *     - `job_id` - Job identifier
+         *     - `status` - Current status (pending/running/done/error)
+         *     - `progress` - Progress counters (total/pending/done/error)
+         *     - `started_at` - When the job started
+         *     - `completed_at` - When the job completed (if done/error)
+         *     - `updated_at` - Last state modification
          *
-         *     **Response includes:**
-         *     - Current status (running/done/error)
-         *     - Timestamps (started_at, completed_at)
-         *     - Agent references (agent, main_agent, target)
-         *     - Counts (files_count, sub_jobs_count)
+         *     Agent-specific fields (phase, stages, sub_jobs, folders, dispatches) are also included
+         *     when applicable.
          *
          *     ---
-         *     **Permission:** `collection:view`
+         *     **Permission:** `agent:view`
          *     **Auth:** optional
          */
         get: {
             parameters: {
-                query?: never;
+                query?: {
+                    detail?: "full";
+                    errors?: number | null;
+                };
                 header?: never;
                 path: {
-                    /** @description Entity ID (ULID) */
                     id: string;
+                    job_id: string;
                 };
                 cookie?: never;
             };
             requestBody?: never;
             responses: {
-                /** @description Job status */
+                /** @description Job status from agent */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["JobStatusResponse"];
+                        "application/json": {
+                            /**
+                             * @description Unique job identifier
+                             * @example job_01KFXPQ3ABCDEFGHIJKLMN
+                             */
+                            job_id: string;
+                            /**
+                             * @description Current job status
+                             * @example running
+                             * @enum {string}
+                             */
+                            status: "pending" | "running" | "done" | "error";
+                            progress: components["schemas"]["JobProgress"];
+                            /**
+                             * @description When this job started (ISO timestamp)
+                             * @example 2026-01-26T17:48:15.000Z
+                             */
+                            started_at: string;
+                            /**
+                             * @description When this job completed (ISO timestamp)
+                             * @example 2026-01-26T17:49:30.000Z
+                             */
+                            completed_at?: string;
+                            /**
+                             * @description Last state modification (ISO timestamp)
+                             * @example 2026-01-26T17:49:27.000Z
+                             */
+                            updated_at?: string;
+                            /** @description Final result data (only when status is done) */
+                            result?: {
+                                [key: string]: unknown;
+                            };
+                            error?: components["schemas"]["JobError"];
+                        };
                     };
                 };
-                /** @description Forbidden - Insufficient permissions */
-                403: {
+                /** @description Not Found - Resource does not exist */
+                404: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
                         /**
                          * @example {
-                         *       "error": "Forbidden: You do not have permission to perform this action"
+                         *       "error": "Entity not found"
                          *     }
                          */
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
-                /** @description Not Found - Resource does not exist */
-                404: {
+                /** @description Agent unreachable or returned an error */
+                502: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        /**
-                         * @example {
-                         *       "error": "Entity not found"
-                         *     }
-                         */
-                        "application/json": components["schemas"]["ErrorResponse"];
+                        "application/json": components["schemas"]["AgentUnreachableError"];
                     };
                 };
             };
@@ -6618,13 +6822,28 @@ type paths = {
          *
          *     Use this when you know both endpoints and want to discover how they connect - for example, finding the chain of relationships between a person and a document.
          *
+         *     **Entity Expansion (default: preview):**
+         *     - Omit `expand` or use `?expand=preview` - Lightweight previews for all path entities
+         *     - `?expand=full` - Complete entity manifests (use with caution)
+         *     - `?expand=none` - Disable expansion (graph metadata only)
+         *
+         *     **Performance Warning:** 100 paths can reference 400-800 unique entities, adding 5-10s latency with expansion.
+         *
+         *     **Recommendations:**
+         *     - Use `limit: 10-20` when using expansion
+         *     - Prefer preview over full
+         *     - Use `expand=none` for large result sets, then fetch specific entities separately
+         *
          *     ---
          *     **Permission:** `graph:query`
          *     **Auth:** required
          */
         post: {
             parameters: {
-                query?: never;
+                query?: {
+                    /** @description Entity expansion mode. Omit for preview (default), "full" for complete manifests, "none" to disable */
+                    expand?: "preview" | "full" | "none";
+                };
                 header?: never;
                 path?: never;
                 cookie?: never;
@@ -6692,13 +6911,23 @@ type paths = {
          *
          *     **When to use this vs POST /query:** This endpoint returns exhaustive, unranked results - all reachable entities up to the limit. Use `POST /query` when you want relevance-ranked results combining semantic similarity with graph structure. Use this endpoint when you need comprehensive graph exploration from known entity IDs.
          *
+         *     **Target Expansion (default: preview):**
+         *     - Omit `expand` or use `?expand=preview` - Lightweight target previews
+         *     - `?expand=full` - Complete target manifests
+         *     - `?expand=none` - Disable expansion (graph metadata only)
+         *
+         *     **Performance:** With 100 targets, expansion adds ~1s.
+         *
          *     ---
          *     **Permission:** `graph:query`
          *     **Auth:** required
          */
         post: {
             parameters: {
-                query?: never;
+                query?: {
+                    /** @description Entity expansion mode. Omit for preview (default), "full" for complete manifests, "none" to disable */
+                    expand?: "preview" | "full" | "none";
+                };
                 header?: never;
                 path?: never;
                 cookie?: never;
@@ -6762,13 +6991,23 @@ type paths = {
          * Get entity from graph
          * @description Get entity details with all relationships from the graph database. Unlike the entity manifest, this includes both outgoing and incoming relationships - showing not just what this entity links to, but also what links to it.
          *
+         *     **Peer Expansion (default: preview):**
+         *     - Omit `expand` or use `?expand=preview` - Lightweight peer previews
+         *     - `?expand=full` - Complete peer manifests
+         *     - `?expand=none` - Disable expansion (graph metadata only)
+         *
+         *     **Performance:** With 50 peers, expansion adds ~500ms.
+         *
          *     ---
          *     **Permission:** `graph:query`
          *     **Auth:** required
          */
         get: {
             parameters: {
-                query?: never;
+                query?: {
+                    /** @description Entity expansion mode. Omit for preview (default), "full" for complete manifests, "none" to disable */
+                    expand?: "preview" | "full" | "none";
+                };
                 header?: never;
                 path: {
                     /** @description Entity ID (ULID) */
@@ -6882,6 +7121,23 @@ type paths = {
          *     @01KE4ZY... -[*]{,2}-> type:person            # From exact entity
          *     ```
          *
+         *     ## Entity Expansion
+         *
+         *     Control how much entity data is included in results via the `expand` parameter.
+         *
+         *     | Value | Description | Use Case |
+         *     |-------|-------------|----------|
+         *     | (omitted) | **Preview** (default) - lightweight preview data | Best balance of detail and payload size |
+         *     | `preview` | Same as omitted - lightweight preview data | Explicit preview mode |
+         *     | `full` | Complete entity manifest | When you need all properties, relationships, versions |
+         *     | `none` | No expansion - Pinecone metadata only | Fastest response, smallest payload |
+         *
+         *     **Preview mode** includes: label, truncated description/text (200 chars), created_at, updated_at.
+         *
+         *     **Full mode** includes: all properties, relationships, version info, CID.
+         *
+         *     Both result entities and path step entities are expanded.
+         *
          *
          *     ---
          *     **Permission:** `query:execute`
@@ -6957,6 +7213,17 @@ type paths = {
          *
          *     Uses the collection's weighted centroid vector (combination of description and entity embeddings) to find related collections.
          *
+         *     **Entity Expansion:**
+         *
+         *     Use `expand` in the request body to fetch entity data inline with search results:
+         *
+         *     - **`expand: "preview"` (default)**: Adds `entity_preview` with fresh lightweight data (id, type, label, timestamps)
+         *     - **`expand: "full"`**: Adds `entity` with complete manifest including all properties and relationships
+         *     - **`expand: "none"`**: Returns search metadata only (fastest, lowest bandwidth)
+         *
+         *     Preview mode is recommended for most use cases. Full expansion can result in large payloads.
+         *     Gracefully handles deleted or inaccessible entities (returns results without expansion data).
+         *
          *     ---
          *     **Permission:** `search:similar`
          *     **Auth:** required
@@ -6983,6 +7250,12 @@ type paths = {
                          * @default false
                          */
                         refresh?: boolean;
+                        /**
+                         * @description Entity expansion mode. Default: "preview" for lightweight previews, "full" for complete manifests, "none" for no expansion.
+                         * @example preview
+                         * @enum {string}
+                         */
+                        expand?: "preview" | "full" | "none";
                     };
                 };
             };
@@ -7000,6 +7273,8 @@ type paths = {
                                 score: number;
                                 created_at?: string;
                                 updated_at?: string;
+                                entity_preview?: components["schemas"]["EntityPreview"] & unknown;
+                                entity?: components["schemas"]["EntityResponse"] & unknown;
                             }[];
                             metadata: {
                                 source_pi: string;
@@ -7092,6 +7367,17 @@ type paths = {
          *     2. Then searches within each collection for similar items
          *     3. Aggregates and ranks results with diversity weighting
          *
+         *     **Entity Expansion:**
+         *
+         *     Use `expand` in the request body to fetch entity data inline with search results:
+         *
+         *     - **`expand: "preview"` (default)**: Adds `entity_preview` with fresh lightweight data (id, type, label, timestamps)
+         *     - **`expand: "full"`**: Adds `entity` with complete manifest including all properties and relationships
+         *     - **`expand: "none"`**: Returns search metadata only (fastest, lowest bandwidth)
+         *
+         *     Preview mode is recommended for most use cases. Full expansion can result in large payloads.
+         *     Gracefully handles deleted or inaccessible entities (returns results without expansion data).
+         *
          *     ---
          *     **Permission:** `search:similar`
          *     **Auth:** required
@@ -7135,6 +7421,12 @@ type paths = {
                          * @default false
                          */
                         refresh?: boolean;
+                        /**
+                         * @description Entity expansion mode. Default: "preview" for lightweight previews, "full" for complete manifests, "none" for no expansion.
+                         * @example preview
+                         * @enum {string}
+                         */
+                        expand?: "preview" | "full" | "none";
                     };
                 };
             };
@@ -7154,6 +7446,8 @@ type paths = {
                                 score: number;
                                 created_at?: string;
                                 updated_at?: string;
+                                entity_preview?: components["schemas"]["EntityPreview"] & unknown;
+                                entity?: components["schemas"]["EntityResponse"] & unknown;
                             }[];
                             metadata: {
                                 source_pi: string;
@@ -7244,6 +7538,17 @@ type paths = {
          *
          *     Use this endpoint to discover collections about a topic. Results are ranked by semantic similarity to your query.
          *
+         *     **Entity Expansion:**
+         *
+         *     Use `expand` in the request body to fetch entity data inline with search results:
+         *
+         *     - **`expand: "preview"` (default)**: Adds `entity_preview` with fresh lightweight data (id, type, label, timestamps)
+         *     - **`expand: "full"`**: Adds `entity` with complete manifest including all properties and relationships
+         *     - **`expand: "none"`**: Returns search metadata only (fastest, lowest bandwidth)
+         *
+         *     Preview mode is recommended for most use cases. Full expansion can result in large payloads.
+         *     Gracefully handles deleted or inaccessible entities (returns results without expansion data).
+         *
          *     ---
          *     **Permission:** `search:query`
          *     **Auth:** required
@@ -7267,6 +7572,12 @@ type paths = {
                         limit?: number;
                         /** @description Filter by collection types */
                         types?: string[];
+                        /**
+                         * @description Entity expansion mode. Default: "preview" for lightweight previews, "full" for complete manifests, "none" for no expansion.
+                         * @example preview
+                         * @enum {string}
+                         */
+                        expand?: "preview" | "full" | "none";
                     };
                 };
             };
@@ -7285,6 +7596,8 @@ type paths = {
                                 score: number;
                                 created_at?: string;
                                 updated_at?: string;
+                                entity_preview?: components["schemas"]["EntityPreview"] & unknown;
+                                entity?: components["schemas"]["EntityResponse"] & unknown;
                             }[];
                             metadata: {
                                 query: string;
@@ -7358,6 +7671,17 @@ type paths = {
          *
          *     Use this endpoint to discover agents across the network. Only active agents are returned. Results are ranked by semantic similarity to your query based on agent descriptions and capabilities.
          *
+         *     **Entity Expansion:**
+         *
+         *     Use `expand` in the request body to fetch entity data inline with search results:
+         *
+         *     - **`expand: "preview"` (default)**: Adds `entity_preview` with fresh lightweight data (id, type, label, timestamps)
+         *     - **`expand: "full"`**: Adds `entity` with complete manifest including all properties and relationships
+         *     - **`expand: "none"`**: Returns search metadata only (fastest, lowest bandwidth)
+         *
+         *     Preview mode is recommended for most use cases. Full expansion can result in large payloads.
+         *     Gracefully handles deleted or inaccessible entities (returns results without expansion data).
+         *
          *     ---
          *     **Permission:** `search:query`
          *     **Auth:** required
@@ -7379,6 +7703,12 @@ type paths = {
                          * @default 10
                          */
                         limit?: number;
+                        /**
+                         * @description Entity expansion mode. Default: "preview" for lightweight previews, "full" for complete manifests, "none" for no expansion.
+                         * @example preview
+                         * @enum {string}
+                         */
+                        expand?: "preview" | "full" | "none";
                     };
                 };
             };
@@ -7398,6 +7728,8 @@ type paths = {
                                 status?: string;
                                 created_at?: string;
                                 updated_at?: string;
+                                entity_preview?: components["schemas"]["EntityPreview"] & unknown;
+                                entity?: components["schemas"]["EntityResponse"] & unknown;
                             }[];
                             metadata: {
                                 query: string;
@@ -7473,6 +7805,17 @@ type paths = {
          *
          *     Use `per_collection_limit` to ensure result diversity when searching multiple collections.
          *
+         *     **Entity Expansion:**
+         *
+         *     Use `expand` in the request body to fetch entity data inline with search results:
+         *
+         *     - **`expand: "preview"` (default)**: Adds `entity_preview` with fresh lightweight data (id, type, label, timestamps)
+         *     - **`expand: "full"`**: Adds `entity` with complete manifest including all properties and relationships
+         *     - **`expand: "none"`**: Returns search metadata only (fastest, lowest bandwidth)
+         *
+         *     Preview mode is recommended for most use cases. Full expansion can result in large payloads.
+         *     Gracefully handles deleted or inaccessible entities (returns results without expansion data).
+         *
          *     ---
          *     **Permission:** `search:query`
          *     **Auth:** required
@@ -7502,6 +7845,12 @@ type paths = {
                         types?: string[];
                         /** @description Max results per collection for diversity */
                         per_collection_limit?: number;
+                        /**
+                         * @description Entity expansion mode. Default: "preview" for lightweight previews, "full" for complete manifests, "none" for no expansion.
+                         * @example preview
+                         * @enum {string}
+                         */
+                        expand?: "preview" | "full" | "none";
                     };
                 };
             };
@@ -7521,6 +7870,8 @@ type paths = {
                                 collection_pi: string;
                                 created_at?: string;
                                 updated_at?: string;
+                                entity_preview?: components["schemas"]["EntityPreview"] & unknown;
+                                entity?: components["schemas"]["EntityResponse"] & unknown;
                             }[];
                             metadata: {
                                 collection_pis: string[];
@@ -7601,6 +7952,17 @@ type paths = {
          *
          *     Great for exploration and AI agents navigating the network.
          *
+         *     **Entity Expansion:**
+         *
+         *     Use `expand` in the request body to fetch entity data inline with search results:
+         *
+         *     - **`expand: "preview"` (default)**: Adds `entity_preview` with fresh lightweight data (id, type, label, timestamps)
+         *     - **`expand: "full"`**: Adds `entity` with complete manifest including all properties and relationships
+         *     - **`expand: "none"`**: Returns search metadata only (fastest, lowest bandwidth)
+         *
+         *     Preview mode is recommended for most use cases. Full expansion can result in large payloads.
+         *     Gracefully handles deleted or inaccessible entities (returns results without expansion data).
+         *
          *     ---
          *     **Permission:** `search:query`
          *     **Auth:** required
@@ -7634,6 +7996,12 @@ type paths = {
                          * @default 5
                          */
                         per_collection_limit?: number;
+                        /**
+                         * @description Entity expansion mode. Default: "preview" for lightweight previews, "full" for complete manifests, "none" for no expansion.
+                         * @example preview
+                         * @enum {string}
+                         */
+                        expand?: "preview" | "full" | "none";
                     };
                 };
             };
@@ -7653,6 +8021,8 @@ type paths = {
                                 collection_pi: string;
                                 created_at?: string;
                                 updated_at?: string;
+                                entity_preview?: components["schemas"]["EntityPreview"] & unknown;
+                                entity?: components["schemas"]["EntityResponse"] & unknown;
                             }[];
                             metadata: {
                                 query: string;
@@ -8536,6 +8906,60 @@ type components = {
                 has_more: boolean;
             };
         };
+        /**
+         * @description Lightweight entity preview with fresh data. Included by default (expand: "preview").
+         * @example {
+         *       "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
+         *       "type": "file",
+         *       "label": "Research Paper.pdf",
+         *       "collection_pi": "01JCOLLECTION123456789AB",
+         *       "description_preview": "A comprehensive study on distributed systems architecture...",
+         *       "created_at": "2026-01-12T00:00:00.000Z",
+         *       "updated_at": "2026-01-12T10:30:00.000Z"
+         *     }
+         */
+        EntityPreview: {
+            /**
+             * @description Entity ID (persistent identifier)
+             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             */
+            id: string;
+            /**
+             * @description Entity type
+             * @example document
+             */
+            type: string;
+            /**
+             * @description Entity label (from properties.label, filename, or name)
+             * @example Research Paper.pdf
+             */
+            label: string;
+            /**
+             * @description Collection ID this entity belongs to
+             * @example 01JCOLLECTION123456789ABCD
+             */
+            collection_pi?: string;
+            /**
+             * @description Truncated description (max 200 chars + "...")
+             * @example This document contains research findings from the 2025 study on entity management systems. It covers key architectural decisions and performance benchmarks...
+             */
+            description_preview?: string;
+            /**
+             * @description Truncated text content (max 200 chars + "...")
+             * @example Introduction: The rise of decentralized entity management systems has created new challenges for data integrity and consistency. This paper explores...
+             */
+            text_preview?: string;
+            /**
+             * @description Entity creation timestamp (ISO 8601)
+             * @example 2025-01-15T10:00:00.000Z
+             */
+            created_at: string;
+            /**
+             * @description Last update timestamp (ISO 8601)
+             * @example 2025-01-20T14:30:00.000Z
+             */
+            updated_at: string;
+        };
         SearchResultItem: {
             /**
              * @description Entity persistent identifier
@@ -8572,6 +8996,8 @@ type components = {
              * @example 2026-01-12T10:30:00.000Z
              */
             updated_at?: string;
+            entity_preview?: components["schemas"]["EntityPreview"];
+            entity?: components["schemas"]["EntityResponse"] & unknown;
         };
         /** @description Search metadata and statistics */
         SearchMetadata: {
@@ -8622,6 +9048,12 @@ type components = {
              * @example 50
              */
             limit: number;
+            /**
+             * @description Entity expansion mode. Default: "preview" for lightweight previews, "full" for complete manifests, "none" for no expansion.
+             * @example preview
+             * @enum {string}
+             */
+            expand?: "preview" | "full" | "none";
         };
         CollectionResponse: components["schemas"]["EntityResponse"] & {
             /** @enum {string} */
@@ -8995,7 +9427,7 @@ type components = {
              */
             type: string;
             /**
-             * @description Entity display label
+             * @description Entity display label (from GraphDB, may be stale)
              * @example My Document
              */
             label: string;
@@ -9006,9 +9438,11 @@ type components = {
             created_at: string;
             /**
              * Format: date-time
-             * @description When the entity was last updated
+             * @description When the entity was last updated (from GraphDB)
              */
             updated_at: string;
+            preview?: components["schemas"]["EntityPreview"] & unknown;
+            entity?: components["schemas"]["EntityResponse"] & unknown;
         };
         CollectionEntitiesResponse: {
             /** @description Collection ID */
@@ -11029,57 +11463,51 @@ type components = {
              */
             confirm?: boolean;
         };
-        EntityRef: {
+        JobProgress: {
             /**
-             * @description Entity ID (ULID format)
-             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             * @description Total items to process
+             * @example 10
              */
-            pi: string;
-            type?: string;
-            label?: string;
-        };
-        JobStatusResponse: {
+            total: number;
             /**
-             * @description Entity ID (ULID format)
-             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             * @description Items not yet started
+             * @example 3
              */
-            id: string;
+            pending: number;
             /**
-             * @description Content Identifier (CID) - content-addressed hash
-             * @example bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy
+             * @description Items dispatched but not complete
+             * @example 2
              */
-            cid: string;
+            dispatched?: number;
             /**
-             * @description Job collection status
-             * @example running
-             * @enum {string}
+             * @description Successfully completed items
+             * @example 4
              */
-            status: "running" | "done" | "error";
+            done: number;
             /**
-             * Format: date-time
-             * @description ISO 8601 datetime
-             * @example 2025-12-26T12:00:00.000Z
+             * @description Failed items
+             * @example 1
              */
-            started_at: string;
+            error: number;
+        };
+        JobError: {
             /**
-             * Format: date-time
-             * @description ISO 8601 datetime
-             * @example 2025-12-26T12:00:00.000Z
+             * @description Error code
+             * @example TIMEOUT
              */
-            completed_at: string | null;
-            agent: components["schemas"]["EntityRef"];
-            target?: components["schemas"]["EntityRef"];
-            main_agent?: components["schemas"]["EntityRef"];
+            code: string;
             /**
-             * @description Number of files contained in this job collection
-             * @example 5
+             * @description Human-readable error message
+             * @example Request timed out after 30 seconds
              */
-            files_count: number;
+            message: string;
+        };
+        AgentUnreachableError: {
             /**
-             * @description Number of sub-job collections
-             * @example 2
+             * @description Error message
+             * @example Failed to reach agent: Connection refused
              */
-            sub_jobs_count: number;
+            error: string;
         };
         Event: {
             /**
@@ -11117,6 +11545,35 @@ type components = {
              */
             cursor: number;
         };
+        /**
+         * @example {
+         *       "subject_pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
+         *       "subject_label": "Project Folder",
+         *       "subject_type": "folder",
+         *       "subject_preview": {
+         *         "id": "01KE4ZY69F9R40E88PK9S0TQRQ",
+         *         "type": "folder",
+         *         "label": "Project Folder",
+         *         "collection_pi": "01JCOLLECTION123456789ABCD",
+         *         "description_preview": "Main project folder containing research documents...",
+         *         "created_at": "2025-01-10T08:00:00.000Z",
+         *         "updated_at": "2025-01-18T16:45:00.000Z"
+         *       },
+         *       "predicate": "contains",
+         *       "object_pi": "01KE506KZGD8M2P1XK3VNQT4YR",
+         *       "object_label": "Research Paper.pdf",
+         *       "object_type": "file",
+         *       "object_preview": {
+         *         "id": "01KE506KZGD8M2P1XK3VNQT4YR",
+         *         "type": "file",
+         *         "label": "Research Paper.pdf",
+         *         "collection_pi": "01JCOLLECTION123456789ABCD",
+         *         "description_preview": "Analysis of entity management patterns and best practices...",
+         *         "created_at": "2025-01-15T10:00:00.000Z",
+         *         "updated_at": "2025-01-20T14:30:00.000Z"
+         *       }
+         *     }
+         */
         PathEdge: {
             /**
              * @description Source entity PI
@@ -11127,6 +11584,8 @@ type components = {
             subject_label: string;
             /** @description Source entity type */
             subject_type: string;
+            subject_preview?: components["schemas"]["EntityPreview"] & unknown;
+            subject_entity?: components["schemas"]["EntityResponse"] & unknown;
             /** @description Relationship predicate */
             predicate: string;
             /**
@@ -11138,6 +11597,8 @@ type components = {
             object_label: string;
             /** @description Target entity type */
             object_type: string;
+            object_preview?: components["schemas"]["EntityPreview"] & unknown;
+            object_entity?: components["schemas"]["EntityResponse"] & unknown;
         };
         PathResult: {
             /**
@@ -11194,6 +11655,25 @@ type components = {
              */
             limit: number;
         };
+        /**
+         * @example {
+         *       "source_pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
+         *       "target_pi": "01KE506KZGD8M2P1XK3VNQT4YR",
+         *       "target_label": "Research Paper.pdf",
+         *       "target_type": "file",
+         *       "length": 1,
+         *       "edges": [],
+         *       "target_preview": {
+         *         "id": "01KE506KZGD8M2P1XK3VNQT4YR",
+         *         "type": "file",
+         *         "label": "Research Paper.pdf",
+         *         "collection_pi": "01JCOLLECTION123456789ABCD",
+         *         "description_preview": "Analysis of entity management patterns and best practices...",
+         *         "created_at": "2025-01-15T10:00:00.000Z",
+         *         "updated_at": "2025-01-20T14:30:00.000Z"
+         *       }
+         *     }
+         */
         ReachableResult: {
             /**
              * @description Entity ID (ULID format)
@@ -11210,6 +11690,8 @@ type components = {
             /** @description Path length (number of hops) */
             length: number;
             edges: components["schemas"]["PathEdge"][];
+            target_preview?: components["schemas"]["EntityPreview"] & unknown;
+            target_entity?: components["schemas"]["EntityResponse"] & unknown;
         };
         PathsReachableResponse: {
             results: components["schemas"]["ReachableResult"][];
@@ -11249,6 +11731,25 @@ type components = {
              */
             limit: number;
         };
+        /**
+         * @example {
+         *       "direction": "outgoing",
+         *       "predicate": "contains",
+         *       "peer_pi": "01KE506KZGD8M2P1XK3VNQT4YR",
+         *       "peer_type": "file",
+         *       "peer_label": "Research Paper.pdf",
+         *       "properties": {},
+         *       "peer_preview": {
+         *         "id": "01KE506KZGD8M2P1XK3VNQT4YR",
+         *         "type": "file",
+         *         "label": "Research Paper.pdf",
+         *         "collection_pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
+         *         "description_preview": "Analysis of entity management patterns and best practices...",
+         *         "created_at": "2025-01-15T10:00:00.000Z",
+         *         "updated_at": "2025-01-20T14:30:00.000Z"
+         *       }
+         *     }
+         */
         RelationshipInfo: {
             /** @enum {string} */
             direction: "outgoing" | "incoming";
@@ -11263,7 +11764,38 @@ type components = {
             properties: {
                 [key: string]: unknown;
             };
+            peer_preview?: components["schemas"]["EntityPreview"] & unknown;
+            peer_entity?: components["schemas"]["EntityResponse"] & unknown;
         };
+        /**
+         * @example {
+         *       "pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
+         *       "type": "folder",
+         *       "label": "Project Folder",
+         *       "collection_pi": "01JCOLLECTION123456789ABCD",
+         *       "created_at": "2025-01-10T08:00:00.000Z",
+         *       "updated_at": "2025-01-18T16:45:00.000Z",
+         *       "relationships": [
+         *         {
+         *           "direction": "outgoing",
+         *           "predicate": "contains",
+         *           "peer_pi": "01KE506KZGD8M2P1XK3VNQT4YR",
+         *           "peer_type": "file",
+         *           "peer_label": "Research Paper.pdf",
+         *           "properties": {},
+         *           "peer_preview": {
+         *             "id": "01KE506KZGD8M2P1XK3VNQT4YR",
+         *             "type": "file",
+         *             "label": "Research Paper.pdf",
+         *             "collection_pi": "01JCOLLECTION123456789ABCD",
+         *             "description_preview": "Analysis of entity management patterns and best practices...",
+         *             "created_at": "2025-01-15T10:00:00.000Z",
+         *             "updated_at": "2025-01-20T14:30:00.000Z"
+         *           }
+         *         }
+         *       ]
+         *     }
+         */
         GraphEntityResponse: {
             /**
              * @description Entity ID (ULID format)
@@ -11279,34 +11811,30 @@ type components = {
             updated_at: string;
             relationships: components["schemas"]["RelationshipInfo"][];
         };
-        QueryEntity: {
-            /**
-             * @description Entity ID (ULID format)
-             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
-             */
-            pi: string;
-            type: string;
-            label: string;
-            collection_pi: string | null;
-        };
-        EntityStep: {
-            entity: string;
-            label?: string;
-            type?: string;
-            score?: number;
-        };
         EdgeStep: {
             edge: string;
             /** @enum {string} */
             direction: "outgoing" | "incoming";
             score?: number;
         };
-        PathStep: components["schemas"]["EntityStep"] | components["schemas"]["EdgeStep"];
-        QueryResultItem: {
-            entity: components["schemas"]["QueryEntity"];
-            path: components["schemas"]["PathStep"][];
-            score: number;
-        };
+        PathStep: {
+            /**
+             * @description Entity ID
+             * @example 01KPERSON_EINSTEIN
+             */
+            entity: string;
+            /** @example Albert Einstein */
+            label?: string;
+            /** @example person */
+            type?: string;
+            /**
+             * @description Semantic similarity score (0-1)
+             * @example 0.92
+             */
+            score?: number;
+            preview_data?: components["schemas"]["EntityPreview"] & unknown;
+            full_entity?: components["schemas"]["EntityResponse"] & unknown;
+        } | components["schemas"]["EdgeStep"];
         QueryMetadata: {
             query: string;
             hops: number;
@@ -11321,7 +11849,48 @@ type components = {
             stopped_at_hop?: number;
         };
         QueryResponse: {
-            results: components["schemas"]["QueryResultItem"][];
+            results: {
+                /**
+                 * @description Query result entity with optional expansion data
+                 * @example {
+                 *       "pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
+                 *       "type": "person",
+                 *       "label": "Albert Einstein",
+                 *       "collection_pi": "01JCOLL_RESEARCH",
+                 *       "preview_data": {
+                 *         "id": "01KE4ZY69F9R40E88PK9S0TQRQ",
+                 *         "type": "person",
+                 *         "label": "Albert Einstein",
+                 *         "collection_pi": "01JCOLL_RESEARCH",
+                 *         "description_preview": "German-born theoretical physicist who developed the theory of relativity...",
+                 *         "created_at": "2025-01-15T10:00:00.000Z",
+                 *         "updated_at": "2025-01-20T14:30:00.000Z"
+                 *       }
+                 *     }
+                 */
+                entity: {
+                    /**
+                     * @description Entity ID (ULID format)
+                     * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+                     */
+                    pi: string;
+                    /** @example person */
+                    type: string;
+                    /** @example Albert Einstein */
+                    label: string;
+                    /** @example 01JCOLL_RESEARCH */
+                    collection_pi: string | null;
+                    preview_data?: components["schemas"]["EntityPreview"] & unknown;
+                    full_entity?: components["schemas"]["EntityResponse"] & unknown;
+                };
+                /** @description Path from entry point to result entity (empty for zero-hop queries) */
+                path: components["schemas"]["PathStep"][];
+                /**
+                 * @description Combined relevance score (semantic similarity + path length)
+                 * @example 0.89
+                 */
+                score: number;
+            }[];
             metadata: components["schemas"]["QueryMetadata"];
         };
         QueryRequest: {
@@ -11346,6 +11915,15 @@ type components = {
              * @example 01JCOLL_MEDICAL
              */
             collection?: string;
+            /**
+             * @description Control entity expansion in results and path steps.
+             *     - **omitted/preview** (default): Attach lightweight preview data (label, timestamps, truncated description/text)
+             *     - **full**: Attach complete entity manifest (all properties, relationships, version info)
+             *     - **none**: No expansion - return only Pinecone metadata (fastest, smallest payload)
+             * @example preview
+             * @enum {string}
+             */
+            expand?: "none" | "preview" | "full";
         };
         TextPart: {
             /** @enum {string} */