supervaize · alain-sv · Aug 26, 2026 · Aug 23, 2026 · Aug 26, 2026 · Aug 26, 2026
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -14,8 +14,16 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 
+- **Generic job setup contract** — New `V2JobSetupPolicy` on `V2JobPolicy.setup` lets an agent declare the actions Studio may use to preview, start, and submit a job setup (`preview_action`, `start_action`, `submit_action`, defaulting to `job.start.preview`, `job.start`, and `step.awaiting.submit`), the contexts those actions apply to (`action_scopes`), and an opaque `plan` payload. Declared actions are folded into the registration's capability action list. `V2ActionResult.setup_plan` carries the agent's plan back to Studio. `V2JobSetupPolicy` is exported at package level. Additive only; agents that omit `setup` are unaffected.
+
+  `action_scopes` defaults to an empty list: an agent that opts in with `setup: {}` declares no scopes rather than claiming all of `workspace`, `job`, `case`, and `step`. This matches `V2JobSyncPolicy.supported_statuses` and avoids advertising context support the agent never configured. The three action ids are validated as non-blank, so a blank id is rejected at registration instead of being silently dropped from `capabilities.actions` while still appearing in the serialized `job_policy.setup`. The same validation was applied to `V2JobSyncPolicy.action`, which had the identical gap.
+
 - **Security & performance review summary** — Added `docs/2026_07_SECURITY_REVIEW.md`, a non-actionable high-level summary of a full-source security and performance/scalability review (posture, verified-sound controls, severity counts, and remediation themes). Per `SECURITY.md`, detailed findings (locations, attack scenarios, remediation specifics) are handled through the private vulnerability channel and are intentionally omitted from the public repository.
 
+### Changed
+
+- **Regenerated model reference and OpenAPI** — `docs/model_reference/` and `docs/api/openapi.json` were rebuilt from the current models, picking up the job setup contract along with accumulated drift since `0.20.1`. `V2JobSetupPolicy` is now declared before `V2JobPolicy` so the public reference renders the real type instead of a `ForwardRef`.
+
 ### Fixed
 
 - **Hardened API-key checks** — API keys are compared in constant time.
@@ -28,10 +36,10 @@ All notable changes to this project will be documented in this file.
 
 | Status     | Count |
 | ---------- | ----- |
-| ✅ Passed  | 683   |
+| ✅ Passed  | 690   |
 | 🤔 Skipped | 0     |
 | 🔴 Failed  | 0     |
-| ⏱️ in      | 83s   |
+| ⏱️ in      | 59s   |
 
 ## [1.3.1] - 2026-07-02
 

diff --git a/docs/api/openapi.json b/docs/api/openapi.json
@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Supervaize API",
-    "description": "API version: v1  Controller version: 0.20.1\n\nAPI for controlling and managing Supervaize agents. \n\nMore information at [https://doc.supervaize.com](https://doc.supervaize.com)\n\n## Authentication\n\nSome endpoints require API key authentication. Protected endpoints expect the API key in the X-API-Key header.\n\n[Swagger](/docs)\n[Redoc](/redoc)\n[OpenAPI](/openapi.json)\n",
+    "description": "API version: v1  Controller version: 1.3.1\n\nAPI for controlling and managing Supervaize agents. \n\nMore information at [https://doc.supervaize.com](https://doc.supervaize.com)\n\n## Authentication\n\nSome endpoints require API key authentication. Protected endpoints expect the API key in the X-API-Key header.\n\n[Swagger](/docs)\n[Redoc](/redoc)\n[OpenAPI](/openapi.json)\n",
     "termsOfService": "https://supervaize.com/terms/",
     "contact": {
       "name": "Support Team",
@@ -1768,26 +1768,44 @@
         "summary": "A2A JSON-RPC Controller",
         "description": "Dispatches Supervaizer v2 controller methods over A2A JSON-RPC.",
         "operationId": "post_a2a_controller_a2a_post",
+        "parameters": [
+          {
+            "name": "X-API-Key",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "X-Api-Key"
+            }
+          }
+        ],
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "additionalProperties": true,
                 "type": "object",
+                "additionalProperties": true,
                 "title": "Body"
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
             "description": "Successful Response",
             "content": {
               "application/json": {
                 "schema": {
-                  "additionalProperties": true,
                   "type": "object",
+                  "additionalProperties": true,
                   "title": "Response Post A2A Controller A2A Post"
                 }
               }
@@ -1815,6 +1833,24 @@
         "summary": "A2A SSE Event Stream",
         "description": "Streams Supervaizer v2 controller effects over Server-Sent Events.",
         "operationId": "get_a2a_events_a2a_events_get",
+        "parameters": [
+          {
+            "name": "X-API-Key",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "X-Api-Key"
+            }
+          }
+        ],
         "responses": {
           "200": {
             "description": "Successful Response",
@@ -1823,6 +1859,16 @@
                 "schema": {}
               }
             }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
           }
         }
       }
@@ -3973,17 +4019,6 @@
               }
             ],
             "title": "Server Agent Onboarding Status"
-          },
-          "server_encrypted_parameters": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "title": "Server Encrypted Parameters"
           }
         },
         "type": "object",
@@ -4152,7 +4187,7 @@
             "type": "string",
             "format": "date-time",
             "title": "Timestamp",
-            "default": "2026-05-15T20:25:32.352375"
+            "default": "2026-08-26T17:21:02.106370"
           },
           "status_code": {
             "type": "integer",
@@ -4317,7 +4352,7 @@
             "additionalProperties": true,
             "type": "object",
             "title": "Metadata",
-            "description": "Agent-provided domain metadata (e.g. campaign context)"
+            "description": "Agent-provided domain metadata (e.g. source object context)"
           }
         },
         "type": "object",

diff --git a/docs/model_reference/model_core.md b/docs/model_reference/model_core.md
@@ -1,10 +1,6 @@
 # Model Reference Core
 
-
-> **Created:** 2025-08-09
-> **Updated:** 2026-05-16
-
-**Version:** 0.20.1
+**Version:** 1.3.1
 
 ### `account.Account`
 
@@ -114,7 +110,7 @@ _No additional fields beyond parent class._
 | Field | Type | Default | Description |
 |---|---|---|---|
 | `name` | `str` | **required** | Display name of the agent |
-| `id` | `str` | **required** | Unique ID generated from name |
+| `id` | `str` | **required** | Stable ID derived from name via shortuuid.uuid(name=...). Renaming the agent changes this value. |
 | `author` | `str` | `None` | Author of the agent |
 | `developer` | `str` | `None` | Developer of the controller integration |
 | `maintainer` | `str` | `None` | Maintainer of the integration |
@@ -128,13 +124,13 @@ _No additional fields beyond parent class._
 | `server_agent_id` | `str` | `None` | ID assigned by server - Do not set this manually |
 | `server_agent_status` | `str` | `None` | Current status on server - Do not set this manually |
 | `server_agent_onboarding_status` | `str` | `None` | Onboarding status - Do not set this manually |
-| `server_encrypted_parameters` | `str` | `None` | Encrypted parameters from server - Do not set this manually |
 | `max_execution_time` | `int` | 3600 | Maximum execution time in seconds, defaults to 1 hour |
 | `supervaize_instructions_template_path` | `str` | `None` | Optional path to a custom template file for supervaize_instructions.html page |
 | `instructions_path` | `str` | 'supervaize_instructions.html' | Path where the supervaize instructions page is served (relative to agent path) |
 | `custom_routes` | `Any` | `None` | Optional FastAPI APIRouter; mounted on the API app at /api/agents/{slug}/... |
 | `data_resources` | `list[data_resource.DataResource]` | — | Data resources this agent exposes for Studio CRUD access |
 | `supervaizer_v2_registration` | `SupervaizerV2AgentRegistrationContract` | `None` | Optional Supervaizer v2 registration contract for A2A/A2UI Studio integrations |
+| `v2_methods` | `V2AgentMethods` | `None` | Optional agent-level Supervaizer v2 method declarations |
 
 ### `agent.AgentMethod`
 
@@ -187,8 +183,8 @@ Attributes:
 |---|---|---|---|
 | `name` | `str` | **required** | The name of the method |
 | `method` | `str` | **required** | The name of the method in the project's codebase that will be called with the provided parameters |
-| `params` | `typing.Dict[str, typing.Any]` | `None` | A simple key-value dictionary of parameters what will be passed to the AgentMethod.method as kwargs |
-| `fields` | `typing.List[supervaizer.agent.AgentMethodField]` | `None` | A list of field specifications for generating forms/UI, following the django.forms.fields definition |
+| `params` | `dict[str, typing.Any]` | `None` | A simple key-value dictionary of parameters what will be passed to the AgentMethod.method as kwargs |
+| `fields` | `list[supervaizer.agent.AgentMethodField]` | `None` | A list of field specifications for generating forms/UI, following the django.forms.fields definition |
 | `description` | `str` | `None` | Optional description of what the method does |
 | `is_async` | `bool` | False | Whether the method is asynchronous |
 | `timeout` | `int` | 600 | Maximum automatic job duration in seconds. Use None for jobs that must run until Studio stops them manually. |
@@ -316,7 +312,7 @@ ParametersSetup.from_list([
 
 | Field | Type | Default | Description |
 |---|---|---|---|
-| `definitions` | `Dict[str, parameter.Parameter]` | **required** | A dictionary of Parameters, where the key is the parameter name and the value is the parameter object. |
+| `definitions` | `dict[str, parameter.Parameter]` | **required** | A dictionary of Parameters, where the key is the parameter name and the value is the parameter object. |
 
 ### `parameter.Parameter`
 
@@ -403,7 +399,7 @@ public_url: full url (including scheme and port) to use for outbound connections
 | `environment` | `str` | **required** | Environment name (e.g., dev, staging, prod) |
 | `mac_addr` | `str` | **required** | MAC address to use for server identification |
 | `debug` | `bool` | **required** | Whether to enable debug mode |
-| `agents` | `List[agent.Agent]` | **required** | List of agents to register with the server |
+| `agents` | `list[agent.Agent]` | **required** | List of agents to register with the server |
 | `app` | `FastAPI` | **required** | FastAPI application instance |
 | `reload` | `bool` | **required** | Whether to enable auto-reload |
 | `supervisor_account` | `Account` | `None` | Account of the supervisor - can be created at supervaize.com |
@@ -413,6 +409,7 @@ public_url: full url (including scheme and port) to use for outbound connections
 | `public_url` | `str` | `None` | Public including scheme and port to use for inbound connections |
 | `api_key` | `str` | `None` | Force the API key to access the supervaizer endpoints - if not provided, a random key will be generated |
 | `api_key_header` | `APIKeyHeader` | `None` | API key header for authentication |
+| `workspace_authorization` | `V2WorkspaceAuthorizationSettings` | — | Optional Studio-signed workspace authorization verifier settings |
 
 #### Examples
 
@@ -446,4 +443,4 @@ public_url: full url (including scheme and port) to use for outbound connections
 ```
 
 
-*Uploaded on 2026-05-15 20:25:31*
+*Uploaded on 2026-08-26 17:21:01*