@arke-institute/sdk 2.3.12 → 2.3.14

package/dist/generated/index.d.ts

@@ -6,9 +6,66 @@
  *
  * Source: Arke v1 API
  * Version: 1.0.0
- * Generated: 2026-01-14T16:34:47.055Z
+ * Generated: 2026-01-22T18:25:50.170Z
  */
 type paths = {
+    "/ops-reference": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get LLM-friendly API reference
+         * @description Returns a condensed, plain-text API operations reference optimized for LLM consumption.
+         *
+         *     This endpoint provides the same information as the OpenAPI spec but in a format that:
+         *     - Uses ~80% fewer tokens than the full OpenAPI JSON
+         *     - Preserves full endpoint descriptions
+         *     - Organizes operations by category
+         *     - Marks required fields with `*` suffix
+         *     - Includes auth requirements inline
+         *
+         *     **Format example:**
+         *     ```
+         *     ## Collections
+         *     POST /collections [required] - Create a new collection
+         *       body: {label*:string, description:string}
+         *
+         *       Creates a collection with the authenticated user as owner.
+         *     ```
+         *
+         *     Use this for injecting API knowledge into LLM system prompts.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Condensed API operations reference */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "text/plain": string;
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/auth/register": {
         parameters: {
             query?: never;
@@ -21,6 +78,10 @@ type paths = {
         /**
          * Register new user
          * @description Creates a user entity from JWT claims. Idempotent - returns existing user if already registered.
+         *
+         *     ---
+         *     **Permission:** `user:create`
+         *     **Auth:** jwt-only
          */
         post: {
             parameters: {
@@ -95,6 +156,10 @@ type paths = {
         /**
          * Get current user
          * @description Returns the authenticated user's entity.
+         *
+         *     ---
+         *     **Permission:** `user:view`
+         *     **Auth:** required
          */
         get: {
             parameters: {
@@ -155,6 +220,10 @@ type paths = {
         /**
          * Get user by ID
          * @description Returns a user entity by ID. May require authentication depending on permissions.
+         *
+         *     ---
+         *     **Permission:** `user:view`
+         *     **Auth:** optional
          */
         get: {
             parameters: {
@@ -210,6 +279,10 @@ type paths = {
         /**
          * Update user profile
          * @description Updates a user's profile. Requires user:update permission (typically self-ownership).
+         *
+         *     ---
+         *     **Permission:** `user:update`
+         *     **Auth:** required
          */
         put: {
             parameters: {
@@ -340,6 +413,10 @@ type paths = {
         /**
          * List API keys
          * @description Lists all active API keys for the authenticated user. Returns prefixes only, not full keys.
+         *
+         *     ---
+         *     **Permission:** `user:credentials`
+         *     **Auth:** required
          */
         get: {
             parameters: {
@@ -379,6 +456,10 @@ type paths = {
         /**
          * Create API key
          * @description Creates a new API key for the authenticated user. The full key is only returned once - store it securely.
+         *
+         *     ---
+         *     **Permission:** `user:credentials`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -437,6 +518,10 @@ type paths = {
         /**
          * Revoke API key
          * @description Revokes an API key by prefix. The key will be immediately invalid.
+         *
+         *     ---
+         *     **Permission:** `user:credentials`
+         *     **Auth:** required
          */
         delete: {
             parameters: {
@@ -506,6 +591,10 @@ type paths = {
          *     Results include the role predicate so clients know what access the user has to each collection.
          *
          *     Supports filtering by predicate (role name) and pagination.
+         *
+         *     ---
+         *     **Permission:** `user:view`
+         *     **Auth:** optional
          */
         get: {
             parameters: {
@@ -618,6 +707,11 @@ type paths = {
          *     ## Scoring
          *     - Results use cosine similarity scores (0-1)
          *     - Scores are comparable across collections
+         *
+         *
+         *     ---
+         *     **Permission:** `search:execute`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -707,6 +801,10 @@ type paths = {
         /**
          * Create a new collection
          * @description Creates a collection with the authenticated user as owner.
+         *
+         *     ---
+         *     **Permission:** `collection:create`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -801,6 +899,10 @@ type paths = {
         /**
          * Get collection by ID
          * @description Returns a collection entity by ID.
+         *
+         *     ---
+         *     **Permission:** `collection:view`
+         *     **Auth:** optional
          */
         get: {
             parameters: {
@@ -856,6 +958,10 @@ type paths = {
         /**
          * Update collection properties
          * @description Updates collection properties. Requires collection:update permission.
+         *
+         *     ---
+         *     **Permission:** `collection:update`
+         *     **Auth:** required
          */
         put: {
             parameters: {
@@ -988,6 +1094,10 @@ type paths = {
         /**
          * Add a new role
          * @description Adds a new role to the collection. Requires collection:manage permission.
+         *
+         *     ---
+         *     **Permission:** `collection:manage`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -1100,6 +1210,10 @@ type paths = {
         /**
          * Update role actions
          * @description Updates the actions for an existing role. Requires collection:manage permission.
+         *
+         *     ---
+         *     **Permission:** `collection:manage`
+         *     **Auth:** required
          */
         put: {
             parameters: {
@@ -1201,6 +1315,10 @@ type paths = {
         /**
          * Delete a role
          * @description Deletes a role from the collection. Requires collection:manage permission.
+         *
+         *     ---
+         *     **Permission:** `collection:manage`
+         *     **Auth:** required
          */
         delete: {
             parameters: {
@@ -1284,6 +1402,10 @@ type paths = {
         /**
          * List collection members
          * @description Returns all members of the collection grouped by type. By default, expired memberships are excluded.
+         *
+         *     ---
+         *     **Permission:** `collection:view`
+         *     **Auth:** optional
          */
         get: {
             parameters: {
@@ -1342,6 +1464,10 @@ type paths = {
         /**
          * Assign user to role
          * @description Assigns a user to a role in the collection. Requires collection:manage permission.
+         *
+         *     ---
+         *     **Permission:** `collection:manage`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -1456,6 +1582,10 @@ type paths = {
         /**
          * Remove user from role
          * @description Removes a user from a role in the collection. Requires collection:manage permission.
+         *
+         *     ---
+         *     **Permission:** `collection:manage`
+         *     **Auth:** required
          */
         delete: {
             parameters: {
@@ -1581,6 +1711,10 @@ type paths = {
          *     - Collection → Entity (predicate: 'root')
          *
          *     Requires collection:update permission on the collection.
+         *
+         *     ---
+         *     **Permission:** `collection:update`
+         *     **Auth:** required
          */
         put: {
             parameters: {
@@ -1713,6 +1847,10 @@ type paths = {
          * @description Returns entities belonging to this collection from the graph database.
          *
          *     Supports pagination and optional type filtering. Results are ordered by creation date (newest first).
+         *
+         *     ---
+         *     **Permission:** `collection:view`
+         *     **Auth:** optional
          */
         get: {
             parameters: {
@@ -1796,6 +1934,10 @@ type paths = {
         /**
          * Create a new entity
          * @description Creates a generic entity of any type. For type-specific validation, use type-specific endpoints.
+         *
+         *     ---
+         *     **Permission:** `entity:create`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -1908,6 +2050,10 @@ type paths = {
         /**
          * Get entity by ID
          * @description Returns any entity by ID. Permission check uses parent collection if entity belongs to one.
+         *
+         *     ---
+         *     **Permission:** `entity:view`
+         *     **Auth:** optional
          */
         get: {
             parameters: {
@@ -1962,7 +2108,30 @@ type paths = {
         };
         /**
          * Update entity
-         * @description Updates any entity with merge semantics. Properties are deep merged, relationships use upsert semantics. Use properties_remove and relationships_remove for deletions. Note: entity:update on a collection requires collection:update permission.
+         * @description Updates an entity with merge semantics. **This is the recommended way to manage relationships.**
+         *
+         *     - `relationships_add`: Upsert relationships (properties are merged if relationship exists)
+         *     - `relationships_remove`: Remove by predicate/peer
+         *     - `properties`: Deep merged with existing
+         *     - `properties_remove`: Remove nested properties using nested object structure
+         *
+         *     **properties_remove syntax:**
+         *     - Top-level keys: `["field1", "field2"]`
+         *     - Nested keys: `{ parent: { child: ["key_to_remove"] } }`
+         *     - **Dot notation is NOT supported** - `["parent.child.key"]` will NOT work
+         *
+         *     Example to remove `config.options.debug`:
+         *     ```json
+         *     { "properties_remove": { "config": { "options": ["debug"] } } }
+         *     ```
+         *
+         *     Use `/relationships` only for bidirectional links updating two entities atomically.
+         *
+         *     Note: entity:update on a collection requires collection:update permission.
+         *
+         *     ---
+         *     **Permission:** `entity:update`
+         *     **Auth:** required
          */
         put: {
             parameters: {
@@ -2080,6 +2249,10 @@ type paths = {
         /**
          * Delete entity
          * @description Soft-deletes an entity by creating a tombstone version. The entity can be restored later via POST /entities/:id/restore. Note: entity:delete on a collection requires collection:delete permission.
+         *
+         *     ---
+         *     **Permission:** `entity:delete`
+         *     **Auth:** required
          */
         delete: {
             parameters: {
@@ -2198,7 +2371,67 @@ type paths = {
         patch?: never;
         trace?: never;
     };
-    "/entities/{id}/restore": {
+    "/entities/{id}/tip": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get entity tip CID
+         * @description Returns only the current manifest CID (tip) for an entity. Lightweight endpoint for CAS operations - single Durable Object lookup, no manifest fetch, no permission check.
+         *
+         *     ---
+         *     **Permission:** `entity:tip`
+         *     **Auth:** none
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Entity ID (ULID) */
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Tip found */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["TipResponse"];
+                    };
+                };
+                /** @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}/cascade": {
         parameters: {
             query?: never;
             header?: never;
@@ -2207,11 +2440,47 @@ type paths = {
         };
         get?: never;
         put?: never;
+        post?: never;
         /**
-         * Restore deleted entity
-         * @description Restores a deleted entity by finding the last non-deleted version and creating a new version from it. Note: entity:restore on a collection requires collection:restore permission.
+         * Cascade delete entity and related entities
+         * @description Deletes an entity and all related entities matching predicate patterns within a scoped collection.
+         *
+         *     **Permission Model:**
+         *     - Requires `entity:delete` permission on the specified `collection_id`
+         *     - Single permission check at the start (not per-entity)
+         *     - Individual entity type permissions are NOT checked during cascade
+         *
+         *     **Cascade Rules:**
+         *     - `collection` predicate NEVER cascades (hard rule - protects collection structure)
+         *     - Only entities in the specified collection are deleted
+         *     - Entities outside the collection are skipped (reported in `skipped` array)
+         *
+         *     **Predicate Patterns:**
+         *     - `"child"` - exact match only
+         *     - `"has_*"` - matches has_document, has_image, etc.
+         *     - `"*_copy"` - matches file_copy, document_copy, etc.
+         *     - `"*"` - matches ALL predicates (except collection)
+         *
+         *     **Traversal:**
+         *     - BFS traversal with parallel processing per depth layer
+         *     - Max depth: 20 (default: 10)
+         *     - Optional `edited_by_filter` to only delete entities created by a specific actor (useful for agent cleanup)
+         *
+         *     **CAS Handling:**
+         *     - Root entity uses the provided `expect_tip`
+         *     - Child entities use re-fetch + single retry strategy
+         *     - CAS conflicts are reported as skipped (not failures)
+         *
+         *     **Response:**
+         *     - Lists all deleted entities with their depth from root
+         *     - Lists skipped entities with reasons
+         *     - Provides summary statistics
+         *
+         *     ---
+         *     **Permission:** `entity:delete`
+         *     **Auth:** required
          */
-        post: {
+        delete: {
             parameters: {
                 query?: never;
                 header?: never;
@@ -2223,17 +2492,17 @@ type paths = {
             };
             requestBody?: {
                 content: {
-                    "application/json": components["schemas"]["RestoreEntityRequest"];
+                    "application/json": components["schemas"]["CascadeDeleteRequest"];
                 };
             };
             responses: {
-                /** @description Entity restored */
+                /** @description Cascade delete completed */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["EntityRestoredResponse"];
+                        "application/json": components["schemas"]["CascadeDeleteResponse"];
                     };
                 };
                 /** @description Bad Request - Invalid input */
@@ -2323,24 +2592,29 @@ type paths = {
                 };
             };
         };
-        delete?: never;
         options?: never;
         head?: never;
         patch?: never;
         trace?: never;
     };
-    "/entities/{id}/collection": {
+    "/entities/{id}/restore": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
+        get?: never;
+        put?: never;
         /**
-         * Get entity collection
-         * @description Returns the collection ID that this entity belongs to. Returns null if the entity is not in any collection. If the entity IS a collection, returns its own ID.
+         * Restore deleted entity
+         * @description Restores a deleted entity by finding the last non-deleted version and creating a new version from it. Note: entity:restore on a collection requires collection:restore permission.
+         *
+         *     ---
+         *     **Permission:** `entity:restore`
+         *     **Auth:** required
          */
-        get: {
+        post: {
             parameters: {
                 query?: never;
                 header?: never;
@@ -2350,15 +2624,58 @@ type paths = {
                 };
                 cookie?: never;
             };
-            requestBody?: never;
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["RestoreEntityRequest"];
+                };
+            };
             responses: {
-                /** @description Collection lookup result */
+                /** @description Entity restored */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["EntityCollectionResponse"];
+                        "application/json": components["schemas"]["EntityRestoredResponse"];
+                    };
+                };
+                /** @description Bad Request - Invalid input */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Validation failed",
+                         *       "details": {
+                         *         "issues": [
+                         *           {
+                         *             "path": [
+                         *               "properties",
+                         *               "label"
+                         *             ],
+                         *             "message": "Required"
+                         *           }
+                         *         ]
+                         *       }
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ValidationErrorResponse"];
+                    };
+                };
+                /** @description Unauthorized - Missing or invalid authentication */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Unauthorized: Missing or invalid authentication token"
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
                 /** @description Forbidden - Insufficient permissions */
@@ -2389,17 +2706,33 @@ type paths = {
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
+                /** @description Conflict - CAS validation failed (entity was modified) */
+                409: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Conflict: entity was modified",
+                         *       "details": {
+                         *         "expected": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
+                         *         "actual": "bafyreinewabc123456789defghijklmnopqrstuvwxyz"
+                         *       }
+                         *     }
+                         */
+                        "application/json": components["schemas"]["CASErrorResponse"];
+                    };
+                };
             };
         };
-        put?: never;
-        post?: never;
         delete?: never;
         options?: never;
         head?: never;
         patch?: never;
         trace?: never;
     };
-    "/entities/{id}/tree": {
+    "/entities/{id}/collection": {
         parameters: {
             query?: never;
             header?: never;
@@ -2407,27 +2740,16 @@ type paths = {
             cookie?: never;
         };
         /**
-         * Get entity tree
-         * @description Returns a hierarchical tree of entities reachable from the source entity.
-         *
-         *     Use this to browse collections and folders without making multiple API calls.
-         *     The tree follows relationship edges (optionally filtered by predicate) and
-         *     returns a nested structure suitable for tree UI rendering.
+         * Get entity collection
+         * @description Returns the collection ID that this entity belongs to. Returns null if the entity is not in any collection. If the entity IS a collection, returns its own ID.
          *
-         *     Query parameters:
-         *     - `depth`: Max tree depth (1-4, default 2)
-         *     - `collection`: Constrain to entities in this collection
-         *     - `predicates`: Comma-separated predicates to follow (e.g., "contains")
-         *     - `limit`: Max nodes to return (default 100)
+         *     ---
+         *     **Permission:** `entity:view`
+         *     **Auth:** optional
          */
         get: {
             parameters: {
-                query?: {
-                    depth?: number;
-                    collection?: string;
-                    predicates?: string;
-                    limit?: number;
-                };
+                query?: never;
                 header?: never;
                 path: {
                     /** @description Entity ID (ULID) */
@@ -2437,13 +2759,13 @@ type paths = {
             };
             requestBody?: never;
             responses: {
-                /** @description Tree retrieved */
+                /** @description Collection lookup result */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["TreeResponse"];
+                        "application/json": components["schemas"]["EntityCollectionResponse"];
                     };
                 };
                 /** @description Forbidden - Insufficient permissions */
@@ -2484,7 +2806,7 @@ type paths = {
         patch?: never;
         trace?: never;
     };
-    "/entities/{id}/diff": {
+    "/entities/{id}/tree": {
         parameters: {
             query?: never;
             header?: never;
@@ -2492,8 +2814,97 @@ type paths = {
             cookie?: never;
         };
         /**
-         * Get diff between entity versions
-         * @description Computes the difference between two versions of an entity.
+         * Get entity tree
+         * @description Returns a hierarchical tree of entities reachable from the source entity.
+         *
+         *     Use this to browse collections and folders without making multiple API calls.
+         *     The tree follows relationship edges (optionally filtered by predicate) and
+         *     returns a nested structure suitable for tree UI rendering.
+         *
+         *     Query parameters:
+         *     - `depth`: Max tree depth (1-4, default 2)
+         *     - `collection`: Constrain to entities in this collection
+         *     - `predicates`: Comma-separated predicates to follow (e.g., "contains")
+         *     - `limit`: Max nodes to return (default 100)
+         *
+         *     ---
+         *     **Permission:** `entity:view`
+         *     **Auth:** optional
+         */
+        get: {
+            parameters: {
+                query?: {
+                    depth?: number;
+                    collection?: string;
+                    predicates?: string;
+                    limit?: number;
+                };
+                header?: never;
+                path: {
+                    /** @description Entity ID (ULID) */
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Tree retrieved */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["TreeResponse"];
+                    };
+                };
+                /** @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}/diff": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get diff between entity versions
+         * @description Computes the difference between two versions of an entity.
          *
          *     Query parameters:
          *     - `from`: CID of the "from" version (defaults to prev of "to" version)
@@ -2507,6 +2918,10 @@ type paths = {
          *     - Both: Compare any two versions
          *
          *     For version 1 entities (no previous version), "from" is null and all content appears as added.
+         *
+         *     ---
+         *     **Permission:** `entity:view`
+         *     **Auth:** optional
          */
         get: {
             parameters: {
@@ -2623,6 +3038,10 @@ type paths = {
          *     - For files: entity:* and file:* actions
          *     - For collections: entity:* and collection:* actions
          *     - etc.
+         *
+         *     ---
+         *     **Permission:** `entity:view`
+         *     **Auth:** required
          */
         get: {
             parameters: {
@@ -2710,14 +3129,20 @@ type paths = {
          * Add relationship between entities
          * @description Creates a relationship from source to target entity.
          *
-         *     If `target_predicate` is provided, creates a **bidirectional** relationship:
-         *     - Adds `source_predicate` relationship on source pointing to target
-         *     - Adds `target_predicate` relationship on target pointing to source
-         *     - Requires `entity:update` permission on both entities
+         *     **⚠️ For single-entity updates, prefer `PUT /entities/:id` with `relationships_add` - simpler API, one CAS guard, can update properties too.**
          *
-         *     If `target_predicate` is omitted, creates a **unidirectional** relationship:
-         *     - Adds `source_predicate` relationship on source pointing to target
-         *     - Requires `entity:update` permission on source only
+         *     Use this endpoint only for **bidirectional** relationships requiring atomic updates to TWO entities.
+         *
+         *     If `target_predicate` is provided (bidirectional):
+         *     - Updates both source and target entities
+         *     - Requires `entity:update` on both, plus two CAS guards
+         *
+         *     If `target_predicate` is omitted (unidirectional):
+         *     - Use `PUT /entities/:id` instead
+         *
+         *     ---
+         *     **Permission:** `entity:update`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -2832,14 +3257,20 @@ type paths = {
          * Remove relationship between entities
          * @description Removes a relationship from source to target entity.
          *
-         *     If `target_predicate` is provided, removes a **bidirectional** relationship:
-         *     - Removes `source_predicate` relationship from source
-         *     - Removes `target_predicate` relationship from target
-         *     - Requires `entity:update` permission on both entities
+         *     **⚠️ For single-entity updates, prefer `PUT /entities/:id` with `relationships_remove` - simpler API, one CAS guard, can update properties too.**
+         *
+         *     Use this endpoint only for **bidirectional** relationships requiring atomic updates to TWO entities.
          *
-         *     If `target_predicate` is omitted, removes a **unidirectional** relationship:
-         *     - Removes `source_predicate` relationship from source
-         *     - Requires `entity:update` permission on source only
+         *     If `target_predicate` is provided (bidirectional):
+         *     - Updates both source and target entities
+         *     - Requires `entity:update` on both, plus two CAS guards
+         *
+         *     If `target_predicate` is omitted (unidirectional):
+         *     - Use `PUT /entities/:id` instead
+         *
+         *     ---
+         *     **Permission:** `entity:update`
+         *     **Auth:** required
          */
         delete: {
             parameters: {
@@ -2975,6 +3406,10 @@ type paths = {
          *
          *     Use this for simple entity linking. For bidirectional relationships or
          *     advanced options, use the `/relationships` endpoint.
+         *
+         *     ---
+         *     **Permission:** `entity:update`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -3109,6 +3544,10 @@ type paths = {
          *     - Only requires `entity:update` permission on source entity
          *
          *     For bidirectional removal, use the `/relationships` endpoint.
+         *
+         *     ---
+         *     **Permission:** `entity:update`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -3247,6 +3686,10 @@ type paths = {
          *     ## Key Best Practice
          *     Use a unique identifier as the key (e.g., version number, timestamp).
          *     The actual CID is computed during upload.
+         *
+         *     ---
+         *     **Permission:** `file:create`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -3359,6 +3802,10 @@ type paths = {
         /**
          * Get file metadata
          * @description Returns file entity metadata. Use /{id}/content to download the file content.
+         *
+         *     ---
+         *     **Permission:** `file:view`
+         *     **Auth:** optional
          */
         get: {
             parameters: {
@@ -3420,6 +3867,10 @@ type paths = {
          *     This allows "regressing" to a previous file version.
          *
          *     To upload a new file, use POST /{id}/reupload instead.
+         *
+         *     ---
+         *     **Permission:** `file:update`
+         *     **Auth:** required
          */
         put: {
             parameters: {
@@ -3558,6 +4009,10 @@ type paths = {
          *
          *     ## Streaming
          *     Response is streamed directly from R2 storage.
+         *
+         *     ---
+         *     **Permission:** `file:download`
+         *     **Auth:** optional
          */
         get: {
             parameters: {
@@ -3631,6 +4086,10 @@ type paths = {
          *     ## Idempotency
          *     Re-uploading content for an already-uploaded file will fail with 409 Conflict.
          *     Use POST /{id}/reupload first to create a new version.
+         *
+         *     ---
+         *     **Permission:** `file:upload`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -3791,6 +4250,10 @@ type paths = {
          *     ## Key Requirement
          *     The new key must NOT already exist in R2 (no overwrites).
          *     Previous file versions remain accessible via manifest history.
+         *
+         *     ---
+         *     **Permission:** `file:reupload`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -3926,6 +4389,10 @@ type paths = {
          *     If a parent folder is specified, a bidirectional relationship is created:
          *     - Parent folder contains this folder
          *     - This folder is in parent folder
+         *
+         *     ---
+         *     **Permission:** `folder:create`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -4020,6 +4487,10 @@ type paths = {
         /**
          * Get folder
          * @description Returns folder metadata including children and parent relationships.
+         *
+         *     ---
+         *     **Permission:** `folder:view`
+         *     **Auth:** optional
          */
         get: {
             parameters: {
@@ -4075,6 +4546,10 @@ type paths = {
         /**
          * Update folder
          * @description Updates folder properties (label, description, metadata). Properties are merged.
+         *
+         *     ---
+         *     **Permission:** `folder:update`
+         *     **Auth:** required
          */
         put: {
             parameters: {
@@ -4213,6 +4688,10 @@ type paths = {
          *     - Child is in folder
          *
          *     **Idempotent**: if relationship already exists, returns current state without error.
+         *
+         *     ---
+         *     **Permission:** `folder:update`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -4345,6 +4824,10 @@ type paths = {
         /**
          * Remove child from folder
          * @description Removes a child entity from this folder (bidirectional).
+         *
+         *     ---
+         *     **Permission:** `folder:update`
+         *     **Auth:** required
          */
         delete: {
             parameters: {
@@ -4487,6 +4970,10 @@ type paths = {
          *
          *     **Idempotent**: skips children that already have the relationship.
          *     Returns both added and skipped children in the response.
+         *
+         *     ---
+         *     **Permission:** `folder:update`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -4624,6 +5111,10 @@ type paths = {
          *     - This folder is in parent
          *
          *     **Idempotent**: if relationship already exists, returns current state without error.
+         *
+         *     ---
+         *     **Permission:** `folder:update`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -4756,6 +5247,10 @@ type paths = {
         /**
          * Remove parent from folder
          * @description Removes this folder from a parent folder (bidirectional).
+         *
+         *     ---
+         *     **Permission:** `folder:update`
+         *     **Auth:** required
          */
         delete: {
             parameters: {
@@ -4886,6 +5381,10 @@ type paths = {
         /**
          * List version history
          * @description Returns version metadata for an entity (newest first). Use pagination for entities with many versions.
+         *
+         *     ---
+         *     **Permission:** `entity:view`
+         *     **Auth:** optional
          */
         get: {
             parameters: {
@@ -4986,6 +5485,10 @@ type paths = {
         /**
          * Get manifest by CID
          * @description Returns the full manifest for any version by its CID. Permission is checked against the entity ID in the manifest.
+         *
+         *     ---
+         *     **Permission:** `entity:view`
+         *     **Auth:** optional
          */
         get: {
             parameters: {
@@ -5063,6 +5566,10 @@ type paths = {
          *     - Validating actions client-side
          *
          *     All data is auto-generated from the actual permission system, so it's always in sync with the code.
+         *
+         *     ---
+         *     **Permission:** `permissions:read`
+         *     **Auth:** none
          */
         get: {
             parameters: {
@@ -5104,6 +5611,10 @@ type paths = {
         /**
          * Create an agent
          * @description Creates a new agent entity. Requires agent:create permission in the target collection.
+         *
+         *     ---
+         *     **Permission:** `agent:create`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -5212,6 +5723,10 @@ type paths = {
         /**
          * Get agent by ID
          * @description Returns an agent entity by ID.
+         *
+         *     ---
+         *     **Permission:** `agent:view`
+         *     **Auth:** optional
          */
         get: {
             parameters: {
@@ -5267,6 +5782,16 @@ type paths = {
         /**
          * Update agent
          * @description Updates an agent. Requires agent:update permission.
+         *
+         *     **Field placement:** Agent-specific fields (`label`, `endpoint`, `actions_required`, `input_schema`, etc.) must be at the root level, NOT inside `properties`. The `properties` bag is for additional custom data only.
+         *
+         *     **properties_remove syntax:** Use nested objects, not dot notation.
+         *     - Correct: `{ "input_schema": { "properties": ["field_to_remove"] } }`
+         *     - Wrong: `["input_schema.properties.field_to_remove"]`
+         *
+         *     ---
+         *     **Permission:** `agent:update`
+         *     **Auth:** required
          */
         put: {
             parameters: {
@@ -5400,11 +5925,17 @@ type paths = {
          * Invoke an agent
          * @description Invoke an agent to perform work on a target collection.
          *
+         *     **Note:** The `target` parameter must be a collection ID. Agents receive permissions scoped to collections, not individual entities. To process a specific entity, pass the collection it belongs to.
+         *
          *     **Two-phase interaction:**
-         *     1. First call with `confirm: false` (default) returns a preview of permissions that will be granted
-         *     2. After user reviews and confirms, call again with `confirm: true` to execute
+         *     1. `confirm: false` (default) - preview permissions that will be granted
+         *     2. `confirm: true` - execute the agent
          *
          *     The agent receives temporal (time-limited) permissions on the target collection.
+         *
+         *     ---
+         *     **Permission:** `agent:invoke`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -5525,6 +6056,10 @@ type paths = {
         /**
          * List API keys for agent
          * @description Lists all active API keys for the agent (without the actual key values).
+         *
+         *     ---
+         *     **Permission:** `agent:manage`
+         *     **Auth:** required
          */
         get: {
             parameters: {
@@ -5595,6 +6130,10 @@ type paths = {
         /**
          * Create API key for agent
          * @description Creates an API key for the agent. The full key is only returned once.
+         *
+         *     ---
+         *     **Permission:** `agent:manage`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -5709,6 +6248,10 @@ type paths = {
         /**
          * Revoke API key
          * @description Revokes an API key for the agent.
+         *
+         *     ---
+         *     **Permission:** `agent:manage`
+         *     **Auth:** required
          */
         delete: {
             parameters: {
@@ -5779,103 +6322,60 @@ type paths = {
         patch?: never;
         trace?: never;
     };
-    "/events": {
+    "/agents/{id}/verify": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
+        get?: never;
+        put?: never;
         /**
-         * List entity change events
-         * @description Returns a cursor-based list of entity change events for client synchronization.
-         *
-         *     **Usage:**
-         *     - Call without cursor to get newest events
-         *     - Use returned `cursor` as `?cursor=` to get older events
-         *     - Poll without cursor periodically to check for new events
+         * Verify agent endpoint ownership
+         * @description Verify that you control the agent's endpoint URL. This is required before activating an agent.
          *
-         *     **Sync flow:**
-         *     1. Initial: `GET /events` → get newest, save highest `id` as high-water mark
-         *     2. Paginate: `GET /events?cursor=X` → get older events until `has_more=false`
-         *     3. Poll: `GET /events` → if newest `id` > high-water mark, process new events
+         *     **Two-phase flow:**
+         *     1. Call without `confirm` to get a verification token
+         *     2. Deploy `/.well-known/arke-verification` endpoint returning the token
+         *     3. Call with `confirm: true` to complete verification
          *
-         *     **Event data:**
-         *     - `id`: Auto-increment ID
-         *     - `pi`: Entity ID that changed
-         *     - `cid`: New manifest CID
-         *     - `ts`: ISO timestamp
+         *     **Verification endpoint format:**
+         *     Your endpoint must return JSON:
+         *     ```json
+         *     {
+         *       "verification_token": "vt_xxx...",
+         *       "agent_id": "IIxxx..."
+         *     }
+         *     ```
          *
-         *     Events are ephemeral (30-day rolling window) - for full sync, use snapshots.
-         */
-        get: {
-            parameters: {
-                query?: {
-                    /** @description Return events older than this id (from previous response cursor) */
-                    cursor?: number;
-                    /** @description Maximum number of events to return (default: 100, max: 1000) */
-                    limit?: number;
-                    /** @description Network to query (default: main) */
-                    network?: "main" | "test";
-                };
-                header?: never;
-                path?: never;
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Events list */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": components["schemas"]["EventsListResponse"];
-                    };
-                };
-            };
-        };
-        put?: never;
-        post?: never;
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/graph/paths": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /**
-         * Find paths between entities
-         * @description Find shortest paths between source and target entity sets using graph traversal.
+         *     ---
+         *     **Permission:** `agent:manage`
+         *     **Auth:** required
          */
         post: {
             parameters: {
                 query?: never;
                 header?: never;
-                path?: never;
+                path: {
+                    /** @description Entity ID (ULID) */
+                    id: string;
+                };
                 cookie?: never;
             };
             requestBody?: {
                 content: {
-                    "application/json": components["schemas"]["PathsBetweenRequest"];
+                    "application/json": components["schemas"]["VerifyAgentRequest"];
                 };
             };
             responses: {
-                /** @description Paths found */
+                /** @description Verification token (when confirm is false) or verification result (when confirm is true) */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["PathsBetweenResponse"];
+                        "application/json": components["schemas"]["VerifyAgentTokenResponse"] | components["schemas"]["VerifyAgentSuccessResponse"] | components["schemas"]["VerifyAgentFailureResponse"];
                     };
                 };
                 /** @description Bad Request - Invalid input */
@@ -5903,6 +6403,48 @@ type paths = {
                         "application/json": components["schemas"]["ValidationErrorResponse"];
                     };
                 };
+                /** @description Unauthorized - Missing or invalid authentication */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Unauthorized: Missing or invalid authentication token"
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @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"];
+                    };
+                };
             };
         };
         delete?: never;
@@ -5911,29 +6453,259 @@ type paths = {
         patch?: never;
         trace?: never;
     };
-    "/graph/reachable": {
+    "/jobs/{id}": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get?: never;
-        put?: never;
         /**
-         * Find reachable entities
-         * @description Find all entities of a specific type reachable from source entities within N hops.
+         * Get job status
+         * @description Returns focused job status and summary. Use this endpoint for quick status polling.
+         *
+         *     Returns 404 if the entity is not a job collection.
+         *
+         *     **Response includes:**
+         *     - Current status (running/done/error)
+         *     - Timestamps (started_at, completed_at)
+         *     - Agent references (agent, main_agent, target)
+         *     - Counts (files_count, sub_jobs_count)
+         *
+         *     ---
+         *     **Permission:** `collection:view`
+         *     **Auth:** optional
          */
-        post: {
+        get: {
             parameters: {
                 query?: never;
                 header?: never;
-                path?: never;
-                cookie?: never;
-            };
-            requestBody?: {
-                content: {
-                    "application/json": components["schemas"]["PathsReachableRequest"];
+                path: {
+                    /** @description Entity ID (ULID) */
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Job status */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["JobStatusResponse"];
+                    };
+                };
+                /** @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;
+    };
+    "/events": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List entity change events
+         * @description Returns a cursor-based list of entity change events for client synchronization.
+         *
+         *     **Usage:**
+         *     - Call without cursor to get newest events
+         *     - Use returned `cursor` as `?cursor=` to get older events
+         *     - Poll without cursor periodically to check for new events
+         *
+         *     **Sync flow:**
+         *     1. Initial: `GET /events` → get newest, save highest `id` as high-water mark
+         *     2. Paginate: `GET /events?cursor=X` → get older events until `has_more=false`
+         *     3. Poll: `GET /events` → if newest `id` > high-water mark, process new events
+         *
+         *     **Event data:**
+         *     - `id`: Auto-increment ID
+         *     - `pi`: Entity ID that changed
+         *     - `cid`: New manifest CID
+         *     - `ts`: ISO timestamp
+         *
+         *     Events are ephemeral (30-day rolling window) - for full sync, use snapshots.
+         *
+         *     ---
+         *     **Permission:** `events:list`
+         *     **Auth:** none
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description Return events older than this id (from previous response cursor) */
+                    cursor?: number;
+                    /** @description Maximum number of events to return (default: 100, max: 1000) */
+                    limit?: number;
+                    /** @description Network to query (default: main) */
+                    network?: "main" | "test";
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Events list */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["EventsListResponse"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/graph/paths": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Find paths between entities
+         * @description Find shortest paths between source and target entity sets. Returns all paths up to the limit (default 100).
+         *
+         *     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.
+         *
+         *     ---
+         *     **Permission:** `graph:query`
+         *     **Auth:** required
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["PathsBetweenRequest"];
+                };
+            };
+            responses: {
+                /** @description Paths found */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["PathsBetweenResponse"];
+                    };
+                };
+                /** @description Bad Request - Invalid input */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Validation failed",
+                         *       "details": {
+                         *         "issues": [
+                         *           {
+                         *             "path": [
+                         *               "properties",
+                         *               "label"
+                         *             ],
+                         *             "message": "Required"
+                         *           }
+                         *         ]
+                         *       }
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ValidationErrorResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/graph/reachable": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Find reachable entities (exhaustive)
+         * @description Find all entities of a specific type reachable from source entities within N hops. Returns up to 100 results by default.
+         *
+         *     **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.
+         *
+         *     ---
+         *     **Permission:** `graph:query`
+         *     **Auth:** required
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["PathsReachableRequest"];
                 };
             };
             responses: {
@@ -5988,7 +6760,11 @@ type paths = {
         };
         /**
          * Get entity from graph
-         * @description Get entity details with all relationships from the graph database.
+         * @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.
+         *
+         *     ---
+         *     **Permission:** `graph:query`
+         *     **Auth:** required
          */
         get: {
             parameters: {
@@ -6046,7 +6822,17 @@ type paths = {
         put?: never;
         /**
          * Execute Argo query
-         * @description Execute an Argo DSL query for path-based graph traversal.
+         * @description Execute an Argo DSL query for path-based graph traversal with relevance ranking.
+         *
+         *     ## When to Use This Endpoint
+         *
+         *     | Endpoint | Use Case |
+         *     |----------|----------|
+         *     | `POST /query` | Semantic search + graph traversal with **relevance-ranked** results (default k=25) |
+         *     | `POST /graph/reachable` | **Exhaustive** graph exploration from known entities (default limit=100) |
+         *     | `POST /graph/paths` | Find all shortest paths between two entity sets |
+         *
+         *     This endpoint combines semantic similarity scores with path length to rank results. For exhaustive graph traversal without ranking, use the `/graph/*` endpoints directly.
          *
          *     ## Query Syntax
          *
@@ -6095,6 +6881,11 @@ type paths = {
          *     @:discover "alice" -[*]{,2}-> type:person     # Discover, then traverse
          *     @01KE4ZY... -[*]{,2}-> type:person            # From exact entity
          *     ```
+         *
+         *
+         *     ---
+         *     **Permission:** `query:execute`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -6165,6 +6956,10 @@ type paths = {
          * @description Find collections that are semantically similar to a given collection.
          *
          *     Uses the collection's weighted centroid vector (combination of description and entity embeddings) to find related collections.
+         *
+         *     ---
+         *     **Permission:** `search:similar`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -6296,6 +7091,10 @@ type paths = {
          *     1. First finds collections similar to the entity's collection
          *     2. Then searches within each collection for similar items
          *     3. Aggregates and ranks results with diversity weighting
+         *
+         *     ---
+         *     **Permission:** `search:similar`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -6444,6 +7243,10 @@ type paths = {
          * @description Search for collections using semantic text search.
          *
          *     Use this endpoint to discover collections about a topic. Results are ranked by semantic similarity to your query.
+         *
+         *     ---
+         *     **Permission:** `search:query`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -6540,7 +7343,7 @@ type paths = {
         patch?: never;
         trace?: never;
     };
-    "/search/entities": {
+    "/search/agents": {
         parameters: {
             query?: never;
             header?: never;
@@ -6550,12 +7353,14 @@ type paths = {
         get?: never;
         put?: never;
         /**
-         * Search entities within collection(s)
-         * @description Search for entities within one or more collections using semantic text search.
+         * Search agents by text
+         * @description Search for agents using semantic text search.
          *
-         *     Provide either `collection_pi` for a single collection or `collection_pis` for multiple collections (searched in parallel).
+         *     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.
          *
-         *     Use `per_collection_limit` to ensure result diversity when searching multiple collections.
+         *     ---
+         *     **Permission:** `search:query`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -6567,21 +7372,13 @@ type paths = {
             requestBody?: {
                 content: {
                     "application/json": {
-                        /** @description Single collection PI to search within */
-                        collection_pi?: string;
-                        /** @description Multiple collection PIs to search (max 20) */
-                        collection_pis?: string[];
                         /** @description Search query text */
                         query: string;
                         /**
-                         * @description Maximum total results to return
-                         * @default 20
+                         * @description Maximum results to return
+                         * @default 10
                          */
                         limit?: number;
-                        /** @description Filter by entity types */
-                        types?: string[];
-                        /** @description Max results per collection for diversity */
-                        per_collection_limit?: number;
                     };
                 };
             };
@@ -6596,16 +7393,14 @@ type paths = {
                             results: {
                                 pi: string;
                                 label: string;
-                                type: string;
                                 score: number;
-                                collection_pi: string;
+                                collection_pi: string | null;
+                                status?: string;
                                 created_at?: string;
                                 updated_at?: string;
                             }[];
                             metadata: {
-                                collection_pis: string[];
                                 query: string;
-                                collections_searched: number;
                                 result_count: number;
                             };
                         };
@@ -6661,7 +7456,7 @@ type paths = {
         patch?: never;
         trace?: never;
     };
-    "/search/discover": {
+    "/search/entities": {
         parameters: {
             query?: never;
             header?: never;
@@ -6671,15 +7466,16 @@ type paths = {
         get?: never;
         put?: never;
         /**
-         * Discover entities across all collections
-         * @description Two-step discovery search: first finds relevant collections, then searches within them.
+         * Search entities within collection(s)
+         * @description Search for entities within one or more collections using semantic text search.
          *
-         *     Use this endpoint when you don't know which collections to search. The system will:
-         *     1. Find collections semantically related to your query
-         *     2. Search within each collection in parallel
-         *     3. Aggregate and rank results across all collections
+         *     Provide either `collection_pi` for a single collection or `collection_pis` for multiple collections (searched in parallel).
          *
-         *     Great for exploration and AI agents navigating the network.
+         *     Use `per_collection_limit` to ensure result diversity when searching multiple collections.
+         *
+         *     ---
+         *     **Permission:** `search:query`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -6691,6 +7487,10 @@ type paths = {
             requestBody?: {
                 content: {
                     "application/json": {
+                        /** @description Single collection PI to search within */
+                        collection_pi?: string;
+                        /** @description Multiple collection PIs to search (max 20) */
+                        collection_pis?: string[];
                         /** @description Search query text */
                         query: string;
                         /**
@@ -6700,8 +7500,132 @@ type paths = {
                         limit?: number;
                         /** @description Filter by entity types */
                         types?: string[];
-                        /**
-                         * @description Number of collections to search
+                        /** @description Max results per collection for diversity */
+                        per_collection_limit?: number;
+                    };
+                };
+            };
+            responses: {
+                /** @description Search results */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            results: {
+                                pi: string;
+                                label: string;
+                                type: string;
+                                score: number;
+                                collection_pi: string;
+                                created_at?: string;
+                                updated_at?: string;
+                            }[];
+                            metadata: {
+                                collection_pis: string[];
+                                query: string;
+                                collections_searched: number;
+                                result_count: number;
+                            };
+                        };
+                    };
+                };
+                /** @description Bad Request - Invalid input */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Validation failed",
+                         *       "details": {
+                         *         "issues": [
+                         *           {
+                         *             "path": [
+                         *               "properties",
+                         *               "label"
+                         *             ],
+                         *             "message": "Required"
+                         *           }
+                         *         ]
+                         *       }
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ValidationErrorResponse"];
+                    };
+                };
+                /** @description Service Unavailable - External service not available */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Service unavailable",
+                         *       "details": {
+                         *         "service": "pinecone"
+                         *       }
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/search/discover": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Discover entities across all collections
+         * @description Two-step discovery search: first finds relevant collections, then searches within them.
+         *
+         *     Use this endpoint when you don't know which collections to search. The system will:
+         *     1. Find collections semantically related to your query
+         *     2. Search within each collection in parallel
+         *     3. Aggregate and rank results across all collections
+         *
+         *     Great for exploration and AI agents navigating the network.
+         *
+         *     ---
+         *     **Permission:** `search:query`
+         *     **Auth:** required
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": {
+                        /** @description Search query text */
+                        query: string;
+                        /**
+                         * @description Maximum total results to return
+                         * @default 20
+                         */
+                        limit?: number;
+                        /** @description Filter by entity types */
+                        types?: string[];
+                        /**
+                         * @description Number of collections to search
                          * @default 10
                          */
                         collection_limit?: number;
@@ -6788,6 +7712,228 @@ type paths = {
         patch?: never;
         trace?: never;
     };
+    "/chat": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Send chat message
+         * @description Send a message to the Arke chat agent and receive a streaming response.
+         *
+         *     The agent can execute Arke API operations on your behalf using the authenticated user's permissions.
+         *
+         *     ## Headers
+         *
+         *     - `X-Chat-ID`: Optional. Specify to continue an existing chat session. If omitted, a new session is created.
+         *
+         *     ## Response Format
+         *
+         *     The response is a Server-Sent Events (SSE) stream in AI SDK v5 UIMessage format.
+         *     Stream chunks include text deltas, tool calls, and usage information.
+         *
+         *     ## Token Usage Tracking
+         *
+         *     Usage information is included at the end of the stream in the format:
+         *     ```json
+         *     {"type":"message_delta","delta":{"usage":{"input_tokens":123,"output_tokens":456}}}
+         *     ```
+         *
+         *
+         *     ---
+         *     **Permission:** `chat:send`
+         *     **Auth:** required
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["SendChatRequest"];
+                };
+            };
+            responses: {
+                /** @description Streaming SSE response */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "text/event-stream": string;
+                    };
+                };
+                /** @description Unauthorized - Missing or invalid authentication */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Unauthorized: Missing or invalid authentication token"
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @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"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/chat/sessions/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get chat session
+         * @description Get information about a chat session including message history.
+         *
+         *     Sessions are publicly viewable for sharing purposes. Only the owner can send messages or delete the session.
+         *
+         *     ---
+         *     **Permission:** `chat:view`
+         *     **Auth:** optional
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Chat session info */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ChatSession"];
+                    };
+                };
+                /** @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 chat session
+         * @description Delete a chat session. Only the session owner can delete it.
+         *
+         *     ---
+         *     **Permission:** `chat:delete`
+         *     **Auth:** required
+         */
+        delete: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Session deleted */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ChatSessionDeleteResponse"];
+                    };
+                };
+                /** @description Unauthorized - Missing or invalid authentication */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Unauthorized: Missing or invalid authentication token"
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @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"];
+                    };
+                };
+            };
+        };
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/entities/{id}/attestation": {
         parameters: {
             query?: never;
@@ -6800,6 +7946,10 @@ type paths = {
          * @description Returns the Arweave attestation for the current (latest) version of an entity.
          *
          *     Returns 202 Accepted if the attestation upload is still pending.
+         *
+         *     ---
+         *     **Permission:** `entity:view`
+         *     **Auth:** optional
          */
         get: {
             parameters: {
@@ -6879,6 +8029,10 @@ type paths = {
         /**
          * Get version attestation
          * @description Returns the Arweave attestation for a specific version of an entity.
+         *
+         *     ---
+         *     **Permission:** `entity:view`
+         *     **Auth:** optional
          */
         get: {
             parameters: {
@@ -6941,6 +8095,63 @@ type paths = {
         patch?: never;
         trace?: never;
     };
+    "/attestations/head": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get chain head
+         * @description Returns the latest Arweave attestation transaction ID (network head).
+         *
+         *     ---
+         *     **Permission:** `attestation:view`
+         *     **Auth:** none
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Chain head */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ChainHeadResponse"];
+                    };
+                };
+                /** @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;
+    };
     "/attestations/verify/{tx}": {
         parameters: {
             query?: never;
@@ -6953,6 +8164,10 @@ type paths = {
          * @description Fetches an attestation from Arweave and verifies the CID matches the manifest content.
          *
          *     This is a public endpoint - anyone can verify attestations.
+         *
+         *     ---
+         *     **Permission:** `attestation:verify`
+         *     **Auth:** none
          */
         get: {
             parameters: {
@@ -7091,6 +8306,19 @@ type components = {
              * @example 1735214400000
              */
             ts: number;
+            /**
+             * @description Audit trail for edits
+             * @example {
+             *       "user_id": "01JCAPTAINAHAB000000000000",
+             *       "method": "manual"
+             *     }
+             */
+            edited_by: {
+                user_id: string;
+                /** @enum {string} */
+                method: "manual" | "ai_generated" | "system" | "import";
+                on_behalf_of?: string;
+            };
             /**
              * @description Previous version CID (present on updates)
              * @example bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy
@@ -7143,7 +8371,7 @@ type components = {
             properties?: {
                 [key: string]: unknown;
             };
-            /** @description Properties to remove */
+            /** @description Properties to remove. Use string[] for top-level keys (e.g., ["old_field"]), or nested objects for deep removal (e.g., { config: { options: ["debug"] } }). Dot notation like "config.options.debug" is NOT supported. */
             properties_remove?: string[] | {
                 [key: string]: unknown;
             };
@@ -7486,7 +8714,7 @@ type components = {
             properties?: {
                 [key: string]: unknown;
             };
-            /** @description Properties to remove */
+            /** @description Properties to remove. Use string[] for top-level keys (e.g., ["old_field"]), or nested objects for deep removal (e.g., { config: { options: ["debug"] } }). Dot notation like "config.options.debug" is NOT supported. */
             properties_remove?: string[] | {
                 [key: string]: unknown;
             };
@@ -7846,6 +9074,19 @@ type components = {
              * @example 1735214400000
              */
             ts: number;
+            /**
+             * @description Audit trail for edits
+             * @example {
+             *       "user_id": "01JCAPTAINAHAB000000000000",
+             *       "method": "manual"
+             *     }
+             */
+            edited_by: {
+                user_id: string;
+                /** @enum {string} */
+                method: "manual" | "ai_generated" | "system" | "import";
+                on_behalf_of?: string;
+            };
             /**
              * @description Previous version CID (present on updates)
              * @example bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy
@@ -7869,7 +9110,7 @@ type components = {
              */
             type: string;
             /**
-             * @description Entity properties (type-specific)
+             * @description Entity properties (type-specific). Text properties may contain inline entity references using the arke: URI scheme (e.g., [Label](arke:01JENTITY123...)) for domain-agnostic linking.
              * @example {
              *       "label": "Chapter 1: Loomings",
              *       "author": "Herman Melville"
@@ -7894,6 +9135,18 @@ type components = {
              */
             collection?: string;
         };
+        TipResponse: {
+            /**
+             * @description Entity ID (ULID format)
+             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             */
+            id: string;
+            /**
+             * @description Content Identifier (CID) - content-addressed hash
+             * @example bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy
+             */
+            cid: string;
+        };
         EntityUpdatedResponse: components["schemas"]["EntityResponse"] & {
             /**
              * @description Previous version CID
@@ -7916,7 +9169,7 @@ type components = {
             properties?: {
                 [key: string]: unknown;
             };
-            /** @description Properties to remove */
+            /** @description Properties to remove. Use string[] for top-level keys (e.g., ["old_field"]), or nested objects for deep removal (e.g., { config: { options: ["debug"] } }). Dot notation like "config.options.debug" is NOT supported. */
             properties_remove?: string[] | {
                 [key: string]: unknown;
             };
@@ -8014,6 +9267,110 @@ type components = {
              */
             reason?: string;
         };
+        CascadeDeletedEntity: {
+            /**
+             * @description Entity ID (ULID format)
+             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             */
+            id: string;
+            /**
+             * @description Content Identifier (CID) - content-addressed hash
+             * @example bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy
+             */
+            cid: string;
+            /**
+             * @description Entity type
+             * @example file
+             */
+            type: string;
+            /**
+             * @description Depth from root entity at which this entity was found
+             * @example 1
+             */
+            depth: number;
+        };
+        CascadeSkippedEntity: {
+            /**
+             * @description Entity ID (ULID format)
+             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             */
+            id: string;
+            /**
+             * @description Entity type
+             * @example file
+             */
+            type: string;
+            /**
+             * @description Reason an entity was skipped during cascade delete
+             * @enum {string}
+             */
+            reason: "not_in_collection" | "already_deleted" | "edited_by_mismatch" | "cas_conflict";
+        };
+        CascadeDeleteResponse: {
+            root: components["schemas"]["EntityDeletedResponse"] & unknown;
+            /** @description Entities successfully deleted (ordered by depth, deepest first) */
+            deleted: components["schemas"]["CascadeDeletedEntity"][];
+            /** @description Entities skipped during traversal with reasons */
+            skipped: components["schemas"]["CascadeSkippedEntity"][];
+            /** @description Summary statistics for the cascade delete operation */
+            summary: {
+                /** @description Total entities visited during BFS traversal */
+                total_traversed: number;
+                /** @description Total entities successfully deleted (excluding root) */
+                total_deleted: number;
+                /** @description Total entities skipped during traversal */
+                total_skipped: number;
+                /** @description Maximum depth reached during traversal */
+                max_depth_reached: number;
+            };
+        };
+        CascadeDeleteRequest: {
+            /**
+             * @description Current tip CID for CAS validation. Request fails with 409 if this does not match.
+             * @example bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy
+             */
+            expect_tip: string;
+            /**
+             * @description Optional note describing this change
+             * @example Added Chapter 42: The Whiteness of the Whale
+             */
+            note?: string;
+            /**
+             * @description Collection to scope the cascade delete. Only entities in this collection will be deleted. Permission check is performed on this collection.
+             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             */
+            collection_id: string;
+            /**
+             * @description Predicate patterns to follow during cascade traversal. Supports wildcards:
+             *     - `"child"` - exact match only
+             *     - `"has_*"` - matches has_document, has_image, etc.
+             *     - `"*_copy"` - matches file_copy, document_copy, etc.
+             *     - `"*"` - matches ALL predicates
+             *
+             *     **Important:** The `collection` predicate NEVER cascades, even if `"*"` is specified. This protects the collection structure from accidental deletion.
+             * @example [
+             *       "child",
+             *       "has_*"
+             *     ]
+             */
+            cascade_predicates: string[];
+            /**
+             * @description Only delete entities where edited_by.user_id matches this PI. Useful for cleaning up entities created by a specific agent.
+             * @example 01KAGENTXXXXXXXXXXXXXXXX
+             */
+            edited_by_filter?: string;
+            /**
+             * @description Maximum relationship depth to traverse (default: 10, max: 20)
+             * @default 10
+             * @example 10
+             */
+            max_depth: number;
+            /**
+             * @description Reason for deleting the entities (applied to all deleted entities)
+             * @example Cleanup after agent task
+             */
+            reason?: string;
+        };
         EntityUpdateResponse: components["schemas"]["EntityResponse"] & {
             /**
              * @description Previous version CID
@@ -8443,6 +9800,19 @@ type components = {
              * @example 1735214400000
              */
             ts: number;
+            /**
+             * @description Audit trail for edits
+             * @example {
+             *       "user_id": "01JCAPTAINAHAB000000000000",
+             *       "method": "manual"
+             *     }
+             */
+            edited_by: {
+                user_id: string;
+                /** @enum {string} */
+                method: "manual" | "ai_generated" | "system" | "import";
+                on_behalf_of?: string;
+            };
         };
         CreateFileRequest: {
             /**
@@ -8536,7 +9906,7 @@ type components = {
             properties?: {
                 [key: string]: unknown;
             };
-            /** @description Properties to remove */
+            /** @description Properties to remove. Use string[] for top-level keys (e.g., ["old_field"]), or nested objects for deep removal (e.g., { config: { options: ["debug"] } }). Dot notation like "config.options.debug" is NOT supported. */
             properties_remove?: string[] | {
                 [key: string]: unknown;
             };
@@ -8689,6 +10059,19 @@ type components = {
              * @example 1735214400000
              */
             ts: number;
+            /**
+             * @description Audit trail for edits
+             * @example {
+             *       "user_id": "01JCAPTAINAHAB000000000000",
+             *       "method": "manual"
+             *     }
+             */
+            edited_by: {
+                user_id: string;
+                /** @enum {string} */
+                method: "manual" | "ai_generated" | "system" | "import";
+                on_behalf_of?: string;
+            };
         };
         CreateFolderRequest: {
             /**
@@ -8760,7 +10143,7 @@ type components = {
             properties?: {
                 [key: string]: unknown;
             };
-            /** @description Properties to remove */
+            /** @description Properties to remove. Use string[] for top-level keys (e.g., ["old_field"]), or nested objects for deep removal (e.g., { config: { options: ["debug"] } }). Dot notation like "config.options.debug" is NOT supported. */
             properties_remove?: string[] | {
                 [key: string]: unknown;
             };
@@ -9124,6 +10507,34 @@ type components = {
                 note?: string;
             };
         };
+        TypeRestriction: {
+            /**
+             * @description The type with restricted implications
+             * @example collection
+             */
+            type: string;
+            /**
+             * @description Verbs for which the base type DOES imply this type
+             * @example [
+             *       "view"
+             *     ]
+             */
+            allowed_verbs: string[];
+            /** @description Explanation of the restriction */
+            description: string;
+        };
+        /** @description Type hierarchy. The base type implies all other types, with restrictions for certain types. */
+        TypeHierarchy: {
+            /**
+             * @description The base type that implies all other types
+             * @example entity
+             */
+            base_type: string;
+            /** @description Explanation of type hierarchy behavior */
+            description: string;
+            /** @description Types with restricted implication rules */
+            restrictions: components["schemas"]["TypeRestriction"][];
+        };
         /** @description Verb wildcard pattern (*:verb) */
         WildcardInfo: {
             /**
@@ -9184,6 +10595,7 @@ type components = {
             implications: {
                 [key: string]: string[];
             };
+            type_hierarchy: components["schemas"]["TypeHierarchy"];
             /** @description Wildcard pattern documentation */
             wildcards: {
                 verb: components["schemas"]["WildcardInfo"];
@@ -9217,21 +10629,18 @@ type components = {
         AgentResponse: components["schemas"]["EntityResponse"] & {
             /** @enum {string} */
             type?: "agent";
-        };
-        SubAgentRef: {
-            pi: string;
-            /** @description Display label for the sub-agent */
-            label?: string;
-            /** @description Description of the sub-agent role */
-            description?: string;
-            /**
-             * @description Actions this sub-agent requires
-             * @example [
-             *       "entity:view",
-             *       "entity:update"
-             *     ]
-             */
-            actions_required: string[];
+            /** @description Warnings about sub-agent references that could not be validated. Present only when uses_agents contains references to non-existent, non-agent, or disabled entities. */
+            warnings?: {
+                /** @description The sub-agent ID that has an issue */
+                sub_agent_id: string;
+                /**
+                 * @description Why this is a warning: not_found (entity does not exist), not_an_agent (entity exists but is not an agent), or disabled (agent is disabled)
+                 * @enum {string}
+                 */
+                reason: "not_found" | "not_an_agent" | "disabled";
+                /** @description Human-readable explanation */
+                message: string;
+            }[];
         };
         CreateAgentRequest: {
             /**
@@ -9268,8 +10677,15 @@ type components = {
              * @example Extracts text from scanned documents using OCR
              */
             description?: string;
-            /** @description Sub-agents used by this orchestrator */
-            uses_agents?: components["schemas"]["SubAgentRef"][];
+            /** @description Sub-agents this orchestrator delegates work to. Only provide the sub-agent ID (pi) - their permissions are fetched dynamically at invocation time. Warnings are returned if any referenced sub-agents do not exist or are disabled. */
+            uses_agents?: {
+                /** @description Sub-agent entity ID. The sub-agent's actions_required will be fetched dynamically at invocation time. */
+                pi: string;
+                /** @description Optional display label override (defaults to sub-agent's own label) */
+                label?: string;
+                /** @description Optional description of the sub-agent's role in this orchestrator's workflow */
+                description?: string;
+            }[];
             /** @description JSON Schema for input validation */
             input_schema?: {
                 [key: string]: unknown;
@@ -9315,7 +10731,7 @@ type components = {
             properties?: {
                 [key: string]: unknown;
             };
-            /** @description Properties to remove */
+            /** @description Properties to remove. Use string[] for top-level keys (e.g., ["old_field"]), or nested objects for deep removal (e.g., { config: { options: ["debug"] } }). Dot notation like "config.options.debug" is NOT supported. */
             properties_remove?: string[] | {
                 [key: string]: unknown;
             };
@@ -9392,8 +10808,15 @@ type components = {
              * @enum {string}
              */
             status?: "development" | "active" | "disabled";
-            /** @description Updated sub-agents */
-            uses_agents?: components["schemas"]["SubAgentRef"][];
+            /** @description Updated sub-agent references. Only provide sub-agent IDs (pi) - their permissions are fetched dynamically at invocation time. */
+            uses_agents?: {
+                /** @description Sub-agent entity ID. The sub-agent's actions_required will be fetched dynamically at invocation time. */
+                pi: string;
+                /** @description Optional display label override (defaults to sub-agent's own label) */
+                label?: string;
+                /** @description Optional description of the sub-agent's role in this orchestrator's workflow */
+                description?: string;
+            }[];
             /** @description Updated input schema */
             input_schema?: {
                 [key: string]: unknown;
@@ -9431,6 +10854,20 @@ type components = {
             can_proceed: boolean;
             /** @description True if some agents need permission grants */
             grants_needed: boolean;
+            /** @description Warnings about sub-agents that were skipped */
+            warnings?: {
+                /** @description The sub-agent ID that could not be resolved */
+                sub_agent_id: string;
+                /** @description The orchestrator or parent agent that declared this sub-agent reference */
+                parent_agent_id: string;
+                /**
+                 * @description Why the sub-agent was skipped: not_found (entity does not exist) or disabled (agent status is disabled)
+                 * @enum {string}
+                 */
+                reason: "not_found" | "disabled";
+                /** @description Human-readable explanation of the warning */
+                message: string;
+            }[];
         };
         InvokeGrantResult: {
             agent_id: string;
@@ -9476,7 +10913,7 @@ type components = {
         };
         InvokeConfirmedResponse: components["schemas"]["InvokeStartedResponse"] | components["schemas"]["InvokeRejectedResponse"];
         InvokeAgentRequest: {
-            /** @description Target collection ID to operate on */
+            /** @description Collection ID to grant the agent access to. All agent permissions are collection-scoped. */
             target: string;
             /** @description Job collection where agent should write logs. If not provided, creates new root collection. */
             job_collection?: string;
@@ -9544,6 +10981,106 @@ type components = {
         ListAgentApiKeysResponse: {
             keys: components["schemas"]["AgentApiKeyInfo"][];
         };
+        VerifyAgentTokenResponse: {
+            /**
+             * @description Token to deploy at your endpoint
+             * @example vt_abc123def456...
+             */
+            verification_token: string;
+            /** @description Agent ID to include in verification response */
+            agent_id: string;
+            /**
+             * Format: uri
+             * @description Your agent endpoint URL
+             */
+            endpoint: string;
+            /** @description How to complete verification */
+            instructions: string;
+            /**
+             * Format: date-time
+             * @description Token expiration time
+             */
+            expires_at: string;
+        };
+        VerifyAgentSuccessResponse: {
+            /** @enum {boolean} */
+            verified: true;
+            /**
+             * Format: date-time
+             * @description When the endpoint was verified
+             */
+            verified_at: string;
+        };
+        VerifyAgentFailureResponse: {
+            /** @enum {boolean} */
+            verified: false;
+            /**
+             * @description Verification error code
+             * @enum {string}
+             */
+            error: "no_token" | "token_expired" | "fetch_failed" | "invalid_response" | "token_mismatch" | "agent_id_mismatch";
+            /** @description Human-readable error description */
+            message: string;
+        };
+        VerifyAgentRequest: {
+            /**
+             * @description Set to true to perform verification. Omit or false to generate/get verification token.
+             * @example true
+             */
+            confirm?: boolean;
+        };
+        EntityRef: {
+            /**
+             * @description Entity ID (ULID format)
+             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             */
+            pi: string;
+            type?: string;
+            label?: string;
+        };
+        JobStatusResponse: {
+            /**
+             * @description Entity ID (ULID format)
+             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             */
+            id: string;
+            /**
+             * @description Content Identifier (CID) - content-addressed hash
+             * @example bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy
+             */
+            cid: string;
+            /**
+             * @description Job collection status
+             * @example running
+             * @enum {string}
+             */
+            status: "running" | "done" | "error";
+            /**
+             * Format: date-time
+             * @description ISO 8601 datetime
+             * @example 2025-12-26T12:00:00.000Z
+             */
+            started_at: string;
+            /**
+             * Format: date-time
+             * @description ISO 8601 datetime
+             * @example 2025-12-26T12:00:00.000Z
+             */
+            completed_at: string | null;
+            agent: components["schemas"]["EntityRef"];
+            target?: components["schemas"]["EntityRef"];
+            main_agent?: components["schemas"]["EntityRef"];
+            /**
+             * @description Number of files contained in this job collection
+             * @example 5
+             */
+            files_count: number;
+            /**
+             * @description Number of sub-job collections
+             * @example 2
+             */
+            sub_jobs_count: number;
+        };
         Event: {
             /**
              * @description Auto-increment event ID (use as cursor)
@@ -9795,13 +11332,13 @@ type components = {
             path: string;
             /**
              * @description Maximum number of results to return
-             * @default 10
-             * @example 10
+             * @default 25
+             * @example 25
              */
             k: number;
             /**
              * @description Beam width for exploration (default: k * 3)
-             * @example 30
+             * @example 75
              */
             k_explore?: number;
             /**
@@ -9810,6 +11347,80 @@ type components = {
              */
             collection?: string;
         };
+        TextPart: {
+            /** @enum {string} */
+            type: "text";
+            text: string;
+        };
+        ToolPart: {
+            type: string;
+            toolCallId?: string;
+            toolName?: string;
+            args?: {
+                [key: string]: unknown;
+            };
+            output?: unknown;
+            /** @enum {string} */
+            state?: "partial-call" | "call" | "output-available";
+        };
+        MessagePart: components["schemas"]["TextPart"] | components["schemas"]["ToolPart"] | {
+            type: string;
+        };
+        ChatMessage: {
+            id: string;
+            /** @enum {string} */
+            role: "user" | "assistant" | "system" | "tool";
+            parts?: components["schemas"]["MessagePart"][];
+            content?: string;
+        };
+        SendChatRequest: {
+            /** @description Array of chat messages in AI SDK v5 UIMessage format */
+            messages: components["schemas"]["ChatMessage"][];
+        };
+        ChatSession: {
+            /**
+             * @description Chat session ID
+             * @example chat_abc123
+             */
+            id: string;
+            /**
+             * @description ISO 8601 creation timestamp
+             * @example 2025-01-14T12:00:00.000Z
+             */
+            createdAt: string;
+            /**
+             * @description ISO 8601 last update timestamp
+             * @example 2025-01-14T12:30:00.000Z
+             */
+            updatedAt: string;
+            /** @description Owner user ID (Arke PI or Supabase ID) */
+            ownerId: string | null;
+            /**
+             * @description Auto-generated chat title from first message
+             * @example Help me understand the codebase...
+             */
+            title: string | null;
+            /** @description Full message history (only included in session detail) */
+            messages?: {
+                id: string;
+                /** @enum {string} */
+                role: "user" | "assistant" | "system" | "tool";
+                content: string;
+                createdAt: string;
+                toolInvocations?: {
+                    toolCallId: string;
+                    toolName: string;
+                    args?: {
+                        [key: string]: unknown;
+                    };
+                    result?: unknown;
+                    state: string;
+                }[];
+            }[];
+        };
+        ChatSessionDeleteResponse: {
+            success: boolean;
+        };
         AttestationResponse: {
             /**
              * @description Entity ID (ULID format)
@@ -9870,6 +11481,24 @@ type components = {
              */
             message: string;
         };
+        ChainHeadResponse: {
+            /**
+             * @description Sequence number of the latest attestation
+             * @example 784
+             */
+            seq: number;
+            /**
+             * @description Arweave transaction ID
+             * @example Rxv_BpobNBUr0x5DstsAEUVxCO12hKxv7cnHnGLYp2c
+             */
+            tx: string;
+            /**
+             * Format: uri
+             * @description Arweave gateway URL for direct access
+             * @example https://arweave.net/Rxv_BpobNBUr0x5DstsAEUVxCO12hKxv7cnHnGLYp2c
+             */
+            arweave_url: string;
+        };
         VerifyAttestationResponse: {
             arweave_tx: string;
             attestation: {