@arke-institute/sdk 2.3.11 → 2.3.13

package/dist/generated/index.d.cts

@@ -6,9 +6,66 @@
  *
  * Source: Arke v1 API
  * Version: 1.0.0
- * Generated: 2026-01-14T01:00:30.186Z
+ * Generated: 2026-01-22T16:50:20.274Z
  */
 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,6 +2371,66 @@ type paths = {
         patch?: never;
         trace?: never;
     };
+    "/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}/restore": {
         parameters: {
             query?: never;
@@ -2210,6 +2443,10 @@ type paths = {
         /**
          * 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
          */
         post: {
             parameters: {
@@ -2339,6 +2576,10 @@ type paths = {
         /**
          * 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.
+         *
+         *     ---
+         *     **Permission:** `entity:view`
+         *     **Auth:** optional
          */
         get: {
             parameters: {
@@ -2419,6 +2660,10 @@ type paths = {
          *     - `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: {
@@ -2507,6 +2752,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: {
@@ -2599,6 +2848,108 @@ type paths = {
         patch?: never;
         trace?: never;
     };
+    "/entities/{id}/permissions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get your permissions for an entity
+         * @description Returns the list of actions you can perform on this entity.
+         *
+         *     The response includes:
+         *     - `allowed_actions`: Concrete actions you can perform (no wildcards)
+         *     - `resolution`: How permissions were determined
+         *
+         *     Resolution methods:
+         *     - `collection`: Permissions from your role in the parent collection
+         *     - `self`: You are checking your own user entity (self-ownership)
+         *     - `open_season`: Entity is not in any collection (publicly accessible)
+         *
+         *     Actions are filtered to only those relevant to the entity type:
+         *     - For files: entity:* and file:* actions
+         *     - For collections: entity:* and collection:* actions
+         *     - etc.
+         *
+         *     ---
+         *     **Permission:** `entity:view`
+         *     **Auth:** required
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Entity ID (ULID) */
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Permissions retrieved */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["EntityPermissionsResponse"];
+                    };
+                };
+                /** @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"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/relationships": {
         parameters: {
             query?: never;
@@ -2612,14 +2963,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.**
+         *
+         *     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, creates a **unidirectional** relationship:
-         *     - Adds `source_predicate` relationship on source pointing to target
-         *     - Requires `entity:update` permission on source only
+         *     If `target_predicate` is omitted (unidirectional):
+         *     - Use `PUT /entities/:id` instead
+         *
+         *     ---
+         *     **Permission:** `entity:update`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -2734,14 +3091,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 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
          *
-         *     If `target_predicate` is omitted, removes a **unidirectional** relationship:
-         *     - Removes `source_predicate` relationship from source
-         *     - Requires `entity:update` permission on source only
+         *     ---
+         *     **Permission:** `entity:update`
+         *     **Auth:** required
          */
         delete: {
             parameters: {
@@ -2877,6 +3240,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: {
@@ -3011,6 +3378,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: {
@@ -3149,6 +3520,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: {
@@ -3261,6 +3636,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: {
@@ -3322,6 +3701,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: {
@@ -3460,6 +3843,10 @@ type paths = {
          *
          *     ## Streaming
          *     Response is streamed directly from R2 storage.
+         *
+         *     ---
+         *     **Permission:** `file:download`
+         *     **Auth:** optional
          */
         get: {
             parameters: {
@@ -3533,6 +3920,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: {
@@ -3693,6 +4084,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: {
@@ -3828,6 +4223,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: {
@@ -3922,6 +4321,10 @@ type paths = {
         /**
          * Get folder
          * @description Returns folder metadata including children and parent relationships.
+         *
+         *     ---
+         *     **Permission:** `folder:view`
+         *     **Auth:** optional
          */
         get: {
             parameters: {
@@ -3977,6 +4380,10 @@ type paths = {
         /**
          * Update folder
          * @description Updates folder properties (label, description, metadata). Properties are merged.
+         *
+         *     ---
+         *     **Permission:** `folder:update`
+         *     **Auth:** required
          */
         put: {
             parameters: {
@@ -4115,6 +4522,10 @@ type paths = {
          *     - Child is in folder
          *
          *     **Idempotent**: if relationship already exists, returns current state without error.
+         *
+         *     ---
+         *     **Permission:** `folder:update`
+         *     **Auth:** required
          */
         post: {
             parameters: {
@@ -4247,6 +4658,10 @@ type paths = {
         /**
          * Remove child from folder
          * @description Removes a child entity from this folder (bidirectional).
+         *
+         *     ---
+         *     **Permission:** `folder:update`
+         *     **Auth:** required
          */
         delete: {
             parameters: {
@@ -4389,6 +4804,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: {
@@ -4526,6 +4945,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: {
@@ -4658,6 +5081,10 @@ type paths = {
         /**
          * Remove parent from folder
          * @description Removes this folder from a parent folder (bidirectional).
+         *
+         *     ---
+         *     **Permission:** `folder:update`
+         *     **Auth:** required
          */
         delete: {
             parameters: {
@@ -4788,6 +5215,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: {
@@ -4888,6 +5319,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: {
@@ -4965,6 +5400,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: {
@@ -5006,6 +5445,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: {
@@ -5114,6 +5557,10 @@ type paths = {
         /**
          * Get agent by ID
          * @description Returns an agent entity by ID.
+         *
+         *     ---
+         *     **Permission:** `agent:view`
+         *     **Auth:** optional
          */
         get: {
             parameters: {
@@ -5169,6 +5616,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: {
@@ -5302,11 +5759,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: {
@@ -5427,6 +5890,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: {
@@ -5497,6 +5964,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: {
@@ -5611,6 +6082,10 @@ type paths = {
         /**
          * Revoke API key
          * @description Revokes an API key for the agent.
+         *
+         *     ---
+         *     **Permission:** `agent:manage`
+         *     **Auth:** required
          */
         delete: {
             parameters: {
@@ -5681,24 +6156,237 @@ 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.
+         * Verify agent endpoint ownership
+         * @description Verify that you control the agent's endpoint URL. This is required before activating an agent.
          *
-         *     **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
+         *     **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
          *
-         *     **Sync flow:**
-         *     1. Initial: `GET /events` → get newest, save highest `id` as high-water mark
+         *     **Verification endpoint format:**
+         *     Your endpoint must return JSON:
+         *     ```json
+         *     {
+         *       "verification_token": "vt_xxx...",
+         *       "agent_id": "IIxxx..."
+         *     }
+         *     ```
+         *
+         *     ---
+         *     **Permission:** `agent:manage`
+         *     **Auth:** required
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Entity ID (ULID) */
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["VerifyAgentRequest"];
+                };
+            };
+            responses: {
+                /** @description Verification token (when confirm is false) or verification result (when confirm is true) */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["VerifyAgentTokenResponse"] | components["schemas"]["VerifyAgentSuccessResponse"] | components["schemas"]["VerifyAgentFailureResponse"];
+                    };
+                };
+                /** @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 */
+                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;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/jobs/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * 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
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                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
          *
@@ -5709,6 +6397,10 @@ type paths = {
          *     - `ts`: ISO timestamp
          *
          *     Events are ephemeral (30-day rolling window) - for full sync, use snapshots.
+         *
+         *     ---
+         *     **Permission:** `events:list`
+         *     **Auth:** none
          */
         get: {
             parameters: {
@@ -5756,7 +6448,13 @@ type paths = {
         put?: never;
         /**
          * Find paths between entities
-         * @description Find shortest paths between source and target entity sets using graph traversal.
+         * @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: {
@@ -5823,8 +6521,14 @@ type paths = {
         get?: never;
         put?: never;
         /**
-         * Find reachable entities
-         * @description Find all entities of a specific type reachable from source entities within N hops.
+         * 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: {
@@ -5890,7 +6594,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: {
@@ -5948,7 +6656,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
          *
@@ -5997,6 +6715,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: {
@@ -6067,6 +6790,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: {
@@ -6198,6 +6925,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: {
@@ -6346,6 +7077,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: {
@@ -6442,7 +7177,7 @@ type paths = {
         patch?: never;
         trace?: never;
     };
-    "/search/entities": {
+    "/search/agents": {
         parameters: {
             query?: never;
             header?: never;
@@ -6452,12 +7187,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: {
@@ -6469,21 +7206,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;
                     };
                 };
             };
@@ -6498,16 +7227,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;
                             };
                         };
@@ -6563,7 +7290,7 @@ type paths = {
         patch?: never;
         trace?: never;
     };
-    "/search/discover": {
+    "/search/entities": {
         parameters: {
             query?: never;
             header?: never;
@@ -6573,15 +7300,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: {
@@ -6593,6 +7321,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;
                         /**
@@ -6602,21 +7334,13 @@ type paths = {
                         limit?: number;
                         /** @description Filter by entity types */
                         types?: string[];
-                        /**
-                         * @description Number of collections to search
-                         * @default 10
-                         */
-                        collection_limit?: number;
-                        /**
-                         * @description Max results per collection
-                         * @default 5
-                         */
+                        /** @description Max results per collection for diversity */
                         per_collection_limit?: number;
                     };
                 };
             };
             responses: {
-                /** @description Discovery results */
+                /** @description Search results */
                 200: {
                     headers: {
                         [name: string]: unknown;
@@ -6633,6 +7357,7 @@ type paths = {
                                 updated_at?: string;
                             }[];
                             metadata: {
+                                collection_pis: string[];
                                 query: string;
                                 collections_searched: number;
                                 result_count: number;
@@ -6690,18 +7415,375 @@ type paths = {
         patch?: never;
         trace?: never;
     };
-    "/entities/{id}/attestation": {
+    "/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;
+                        /**
+                         * @description Max results per collection
+                         * @default 5
+                         */
+                        per_collection_limit?: number;
+                    };
+                };
+            };
+            responses: {
+                /** @description Discovery 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: {
+                                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;
+    };
+    "/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;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
          * Get latest attestation
          * @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: {
@@ -6779,44 +7861,105 @@ type paths = {
             cookie?: never;
         };
         /**
-         * Get version attestation
-         * @description Returns the Arweave attestation for a specific version of an entity.
+         * Get version attestation
+         * @description Returns the Arweave attestation for a specific version of an entity.
+         *
+         *     ---
+         *     **Permission:** `entity:view`
+         *     **Auth:** optional
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Entity ID (ULID) */
+                    id: string;
+                    /** @description Version number */
+                    ver: number;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Attestation found */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["AttestationResponse"];
+                    };
+                };
+                /** @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;
+    };
+    "/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: {
-                    /** @description Entity ID (ULID) */
-                    id: string;
-                    /** @description Version number */
-                    ver: number;
-                };
+                path?: never;
                 cookie?: never;
             };
             requestBody?: never;
             responses: {
-                /** @description Attestation found */
+                /** @description Chain head */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["AttestationResponse"];
-                    };
-                };
-                /** @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"];
+                        "application/json": components["schemas"]["ChainHeadResponse"];
                     };
                 };
                 /** @description Not Found - Resource does not exist */
@@ -6855,6 +7998,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: {
@@ -6993,6 +8140,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
@@ -7045,7 +8205,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;
             };
@@ -7388,7 +8548,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;
             };
@@ -7748,6 +8908,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
@@ -7771,7 +8944,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"
@@ -7796,6 +8969,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
@@ -7818,7 +9003,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;
             };
@@ -8105,6 +9290,47 @@ type components = {
             patch: components["schemas"]["PatchOperation"][];
         };
         DiffResponse: components["schemas"]["SemanticDiffResponse"] | components["schemas"]["PatchDiffResponse"];
+        /** @description How permissions were resolved */
+        PermissionResolution: {
+            /**
+             * @description How permissions were resolved
+             * @example collection
+             * @enum {string}
+             */
+            method: "collection" | "self" | "open_season";
+            /**
+             * @description Collection ID if permissions come from a collection role
+             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             */
+            collection_id?: string;
+            /**
+             * @description Role name in the collection
+             * @example editor
+             */
+            role?: string;
+        };
+        EntityPermissionsResponse: {
+            /**
+             * @description The entity ID
+             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             */
+            entity_id: string;
+            /**
+             * @description The entity type
+             * @example file
+             */
+            entity_type: string;
+            /**
+             * @description Actions the user can perform on this entity
+             * @example [
+             *       "entity:view",
+             *       "entity:update",
+             *       "file:download"
+             *     ]
+             */
+            allowed_actions: string[];
+            resolution: components["schemas"]["PermissionResolution"];
+        };
         AddRelationshipResponse: {
             source: components["schemas"]["EntityResponse"] & unknown;
             target?: components["schemas"]["EntityResponse"] & unknown;
@@ -8304,6 +9530,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: {
             /**
@@ -8397,7 +9636,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;
             };
@@ -8550,6 +9789,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: {
             /**
@@ -8621,7 +9873,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;
             };
@@ -8985,6 +10237,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: {
             /**
@@ -9045,6 +10325,7 @@ type components = {
             implications: {
                 [key: string]: string[];
             };
+            type_hierarchy: components["schemas"]["TypeHierarchy"];
             /** @description Wildcard pattern documentation */
             wildcards: {
                 verb: components["schemas"]["WildcardInfo"];
@@ -9078,21 +10359,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: {
             /**
@@ -9129,8 +10407,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;
@@ -9176,7 +10461,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;
             };
@@ -9253,8 +10538,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;
@@ -9292,6 +10584,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;
@@ -9337,7 +10643,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;
@@ -9405,6 +10711,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)
@@ -9656,13 +11062,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;
             /**
@@ -9671,6 +11077,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)
@@ -9731,6 +11211,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: {
@@ -9780,7 +11278,12 @@ type components = {
         };
     };
     responses: never;
-    parameters: never;
+    parameters: {
+        /** @description Target network. Use `test` for isolated test data with II-prefixed IDs. */
+        "X-Arke-Network": "main" | "test";
+        /** @description User entity ID for service accounts acting on behalf of a user. Only valid with `role: service` authentication. */
+        "X-On-Behalf-Of": string;
+    };
     requestBodies: never;
     headers: never;
     pathItems: never;