@opensoha/contracts 0.1.22 → 0.1.24

package/openapi/soha-api.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Soha API
-  version: 0.1.22
+  version: 0.1.24
   description: >
     Public OpenSoha core API contract. This first contract focuses on stable
     cross-repository boundaries: auth, health, runner-facing control-plane
@@ -5366,6 +5366,307 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ExecutionTaskEnvelope"
+  /virtualization/clusters/{connectionID}/capacity-policy:
+    get:
+      tags: [Virtualization]
+      operationId: getVirtualizationCapacityPolicy
+      x-soha-implementation-status: implemented
+      parameters:
+        - { name: connectionID, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: Successful operation.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/VirtualizationCapacityPolicyEnvelope" }
+        "400": { $ref: "#/components/responses/Error" }
+        "403": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+    put:
+      tags: [Virtualization]
+      operationId: updateVirtualizationCapacityPolicy
+      x-soha-implementation-status: implemented
+      parameters:
+        - { name: connectionID, in: path, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/VirtualizationCapacityPolicyInput" }
+      responses:
+        "200":
+          description: Successful operation.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/VirtualizationCapacityPolicyEnvelope" }
+        "400": { $ref: "#/components/responses/Error" }
+        "403": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+  /virtualization/vms/{vmID}/access-binding:
+    get:
+      tags: [Virtualization]
+      operationId: getVirtualMachineAccessBinding
+      x-soha-implementation-status: implemented
+      parameters:
+        - { name: vmID, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: Successful operation.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/VirtualMachineAccessBindingEnvelope" }
+        "400": { $ref: "#/components/responses/Error" }
+        "403": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+    put:
+      tags: [Virtualization]
+      operationId: updateVirtualMachineAccessBinding
+      x-soha-implementation-status: implemented
+      parameters:
+        - { name: vmID, in: path, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/VirtualMachineAccessBindingInput" }
+      responses:
+        "200":
+          description: Successful operation.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/VirtualMachineAccessBindingEnvelope" }
+        "400": { $ref: "#/components/responses/Error" }
+        "403": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+  /virtualization/vms/{vmID}/ssh-sessions:
+    post:
+      tags: [Virtualization]
+      operationId: createVirtualMachineSSHSession
+      x-soha-implementation-status: implemented
+      parameters:
+        - { name: vmID, in: path, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/VirtualMachineSSHSessionInput" }
+      responses:
+        "200":
+          description: Successful operation.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/VirtualMachineSSHSessionEnvelope" }
+        "400": { $ref: "#/components/responses/Error" }
+        "403": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+  /virtualization/vms/{vmID}/ssh-commands:
+    post:
+      tags: [Virtualization]
+      operationId: createVirtualMachineSSHCommand
+      x-soha-implementation-status: implemented
+      parameters:
+        - { name: vmID, in: path, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/VirtualMachineSSHCommandInput" }
+      responses:
+        "200":
+          description: Successful operation.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/VirtualMachineSSHCommandEnvelope" }
+        "400": { $ref: "#/components/responses/Error" }
+        "403": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+  /virtualization/ssh-commands/{commandID}:
+    parameters:
+      - { name: commandID, in: path, required: true, schema: { type: string } }
+    get:
+      tags: [Virtualization]
+      operationId: getVMSSHCommand
+      x-soha-implementation-status: implemented
+      responses:
+        "200":
+          description: Original owner's bounded command receipt under current VM permission.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/VirtualMachineSSHCommandEnvelope" }
+        "403": { $ref: "#/components/responses/Error" }
+    delete:
+      tags: [Virtualization]
+      operationId: cancelVMSSHCommand
+      x-soha-implementation-status: implemented
+      responses:
+        "200":
+          description: Cancellation fences the original task. Dispatched effects remain unknown until independently verified.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/VirtualMachineSSHCommandEnvelope" }
+        "403": { $ref: "#/components/responses/Error" }
+  /virtualization/ssh-sessions/{sessionID}/execution-status:
+    post:
+      tags: [Agent]
+      operationId: checkVMSSHCommandAuthorization
+      x-soha-implementation-status: implemented
+      parameters:
+        - { name: sessionID, in: path, required: true, schema: { type: string } }
+      description: Bound execution Agent rechecks current owner, approval, VM identity and lease before and during a command. Returns no command or credential material.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/VMSSHCredentialRedemptionInput" }
+      responses:
+        "200":
+          description: Authorization and original task remain active.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/VirtualMachineSSHCommandEnvelope" }
+        "400": { $ref: "#/components/responses/Error" }
+        "403": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+  /virtualization/ssh-sessions/{sessionID}:
+    get:
+      tags: [Virtualization]
+      operationId: getVirtualMachineSSHSession
+      x-soha-implementation-status: implemented
+      parameters:
+        - { name: sessionID, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: Successful operation.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/VirtualMachineSSHSessionEnvelope" }
+        "400": { $ref: "#/components/responses/Error" }
+        "403": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+    delete:
+      tags: [Virtualization]
+      operationId: closeVirtualMachineSSHSession
+      x-soha-implementation-status: implemented
+      parameters:
+        - { name: sessionID, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: Successful operation.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/VirtualMachineSSHSessionEnvelope" }
+        "400": { $ref: "#/components/responses/Error" }
+        "403": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+  /virtualization/ssh-sessions/{sessionID}/stream:
+    get:
+      tags: [Virtualization]
+      operationId: streamVirtualMachineSSHSession
+      x-soha-implementation-status: implemented
+      description: Origin-bound, one-use authenticated WebSocket stream of VirtualMachineSSHFrame messages. Maximum lifetime is 30 minutes; idle timeout is 5 minutes. Private keys remain on the execution Agent.
+      parameters:
+        - { name: sessionID, in: path, required: true, schema: { type: string } }
+        - { name: stream_ticket, in: query, required: false, schema: { type: string }, description: One-use browser stream ticket scoped to this session. CLI clients use bearer authentication. }
+      responses:
+        "101":
+          description: WebSocket upgraded; JSON messages use this schema.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/VirtualMachineSSHFrame" }
+        "403": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+  /ssh/capability:
+    get:
+      tags: [Agent]
+      operationId: getAgentSSHCapability
+      x-soha-implementation-status: implemented
+      description: Standalone Agent route /api/v1/ssh/capability; requires its configured bearer token.
+      responses:
+        "200":
+          description: SSH execution capability.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/AgentSSHCapability" }
+        "403": { $ref: "#/components/responses/Error" }
+  /ssh/sessions:
+    post:
+      tags: [Agent]
+      operationId: prepareAgentSSHSession
+      x-soha-implementation-status: implemented
+      description: Standalone Agent route /api/v1/ssh/sessions; stages a one-use request for its session WebSocket.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/AgentSSHSessionRequest" }
+      responses:
+        "200": { description: Session staged. }
+        "403": { $ref: "#/components/responses/Error" }
+  /ssh/sessions/{sessionID}/stream:
+    get:
+      tags: [Agent]
+      operationId: streamAgentSSHSession
+      x-soha-implementation-status: implemented
+      description: Agent bearer authentication. Each staged session can be claimed once.
+      parameters:
+        - { name: sessionID, in: path, required: true, schema: { type: string } }
+      responses:
+        "101":
+          description: Authorized SSH PTY byte stream.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/VirtualMachineSSHFrame" }
+        "403": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+  /virtualization/ssh-sessions/{sessionID}/credentials:
+    post:
+      tags: [Virtualization]
+      operationId: redeemVMSSHCredentials
+      x-soha-implementation-status: implemented
+      description: Execution Agent bearer authentication plus one-use lease, session and Agent identity checks. No human or model credential read endpoint.
+      parameters:
+        - { name: sessionID, in: path, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/VMSSHCredentialRedemptionInput" }
+      responses:
+        "200":
+          description: In-memory Agent credential material.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/SecretLeaseRedemptionEnvelope" }
+        "403": { $ref: "#/components/responses/Error" }
+  /secrets/generate-ssh-key:
+    post:
+      tags: [Secrets]
+      operationId: generateSecretSSHKey
+      x-soha-implementation-status: implemented
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/SecretGenerateSSHKeyRequest" }
+      responses:
+        "200":
+          description: Successful operation.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/SecretMetadataEnvelope" }
+        "400": { $ref: "#/components/responses/Error" }
+        "403": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
   /virtualization/clusters:
     get:
       tags: [Virtualization]
@@ -6607,6 +6908,71 @@ paths:
           $ref: "#/components/responses/Error"
         "404":
           $ref: "#/components/responses/Error"
+  /copilot/sessions/{sessionID}/native-request:
+    get:
+      tags: [AI Workbench]
+      operationId: findNativeRequest
+      description: Read the original Native run by the current user's session and client request ID after a lost creation response. This never creates or resumes a run. A 404 is only absence at the time of the read and does not prove that an in-flight submission cannot commit later.
+      parameters:
+        - $ref: "#/components/parameters/SessionID"
+        - name: requestId
+          in: query
+          required: true
+          schema: { type: string, minLength: 1, maxLength: 128 }
+      responses:
+        "200":
+          description: The original authorized Native run, including its current state.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/WorkbenchAgentRunEnvelope" }
+        "400":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
+        "404":
+          $ref: "#/components/responses/Error"
+  /copilot/agent-runs/{runID}/events:
+    get:
+      tags: [AI Workbench]
+      operationId: listAgentRunEvents
+      description: Read durable Native events owned by the current user. Reconnection only reads; it never resubmits a run or action.
+      parameters:
+        - { name: runID, in: path, required: true, schema: { type: string, minLength: 1 } }
+        - { name: afterSequence, in: query, schema: { type: integer, minimum: 0, default: 0 } }
+      responses:
+        "200":
+          description: Ordered events and the next cursor.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/AgentRunEventListEnvelope" }
+        "403":
+          $ref: "#/components/responses/Error"
+        "404":
+          $ref: "#/components/responses/Error"
+  /copilot/agent-runs/{runID}/resume:
+    post:
+      tags: [AI Workbench]
+      operationId: resumeAgentRun
+      description: Resume the same paused Native run after current authorization and waiting-object checks. Unknown write outcomes cannot be replayed by this operation.
+      parameters:
+        - { name: runID, in: path, required: true, schema: { type: string, minLength: 1 } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/AgentRunResumeRequest" }
+      responses:
+        "200":
+          description: Current run after an idempotent resume.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/WorkbenchAgentRunEnvelope" }
+        "400":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
   /copilot/global-assistant/events:
     post:
       tags: [AI Workbench]
@@ -6996,6 +7362,455 @@ paths:
           $ref: "#/components/responses/Error"
         "404":
           $ref: "#/components/responses/Error"
+  /copilot/assistant/access:
+    get:
+      tags: [AI Workbench]
+      operationId: getPersonalAgentAccess
+      description: Current user's activation state. Ordinary chat permission allows viewing and requesting activation, never approves it.
+      responses:
+        "200":
+          description: Operation result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PersonalAgentAccessEnvelope"
+        "403":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+    post:
+      tags: [AI Workbench]
+      operationId: requestPersonalAgentAccess
+      description: Idempotently requests activation. Rejected or revoked requests may be submitted again. Does not create or wake compute.
+      responses:
+        "200":
+          description: Operation result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PersonalAgentAccessEnvelope"
+        "403":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+  /copilot/assistant/access/requests:
+    get:
+      tags: [AI Workbench]
+      operationId: listPersonalAgentAccessRequests
+      description: Activation applications, restricted to ai.environments.update.
+      responses:
+        "200":
+          description: Operation result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PersonalAgentAccessListEnvelope"
+        "403":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+  /copilot/assistant/access/requests/{userId}:
+    patch:
+      tags: [AI Workbench]
+      operationId: decidePersonalAgentAccess
+      description: Approve or reject a pending request, or revoke approved access. Requires ai.environments.update and the current revision. No self-service approval.
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          schema: { type: string, minLength: 1, maxLength: 128 }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/PersonalAgentAccessDecision" }
+      responses:
+        "200":
+          description: Operation result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PersonalAgentAccessEnvelope"
+        "403":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+  /copilot/assistant/sessions:
+    get:
+      tags: [AI Workbench]
+      operationId: listPersonalAgentSessions
+      description: Only the authenticated activated user's Heya sessions.
+      responses:
+        "200":
+          description: Operation result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkbenchSessionListEnvelope"
+        "403":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+    post:
+      tags: [AI Workbench]
+      operationId: createPersonalAgentSession
+      description: Creates a Heya side chat after activation. Ownership and conversation kind are assigned by the server.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/WorkbenchCreateSessionRequest" }
+      responses:
+        "200":
+          description: Operation result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkbenchSessionEnvelope"
+        "403":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+  /copilot/assistant:
+    post:
+      tags: [AI Workbench]
+      operationId: ensurePersonalAssistant
+      description: Idempotently returns the authenticated user's persistent assistant identity and dedicated Heya main chat after approved activation. Existing ordinary chat history is retained separately. No owner, workspace or runtime identity is accepted from the client.
+      responses:
+        "200":
+          description: Personal assistant.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PersonalAssistantEnvelope"
+        "403":
+          $ref: "#/components/responses/Error"
+    patch:
+      tags: [AI Workbench]
+      operationId: updatePersonalAssistant
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PersonalAssistantUpdateRequest"
+      responses:
+        "200":
+          description: Updated personal assistant.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PersonalAssistantEnvelope"
+        "400":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
+  /copilot/assistant/avatar:
+    patch:
+      tags: [AI Workbench]
+      operationId: updatePersonalAssistantAvatar
+      description: Updates only the authenticated user's assistant image and motion preference; never changes account profile or assistant name. Empty image values restore the default image. Animated formats require a static PNG/JPEG poster. Requires observe.ai.chat permission.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PersonalAssistantAvatarRequest"
+      responses:
+        "200":
+          description: Updated personal assistant.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PersonalAssistantEnvelope"
+        "400":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
+  /copilot/assistant/environment:
+    get:
+      tags: [AI Workbench]
+      operationId: getPersonalEnvironment
+      summary: Read the authenticated assistant's latest environment receipt
+      description: Does not contact the provider or dispatch work. Expired or unconfirmed receipts are unknown. Node credentials and Docker handles remain private.
+      responses:
+        "200":
+          description: Personal environment state
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PersonalEnvironmentEnvelope"
+        default:
+          $ref: "#/components/responses/Error"
+    post:
+      tags: [AI Workbench]
+      operationId: changePersonalEnvironment
+      summary: Wake, sleep or reconcile the authenticated assistant's environment
+      description: Select an administrator-configured template on first wake. Owner, node, quota and original lease are server-derived and immutable. Lost receipts become unknown; reconciliation inspects the original lease without replaying commands. Sleeping retains persistent data. This operation does not delete data.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PersonalEnvironmentActionRequest"
+      responses:
+        "200":
+          description: Actual environment receipt
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PersonalEnvironmentEnvelope"
+        default:
+          $ref: "#/components/responses/Error"
+    delete:
+      tags: [AI Workbench]
+      operationId: deletePersonalEnvironmentData
+      summary: Explicitly delete the authenticated assistant's personal files
+      description: Requires the current assistant ID, exact full name and environment version, a stopped environment and no active task or operation. Deletion retains a private non-recreation marker. Unknown deletion remains unconfirmed; reconciliation never implies that files were deleted. No automatic recreation or request retry.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PersonalEnvironmentDataDeletionRequest"
+      responses:
+        "200":
+          description: Actual deletion receipt
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PersonalEnvironmentEnvelope"
+        default:
+          $ref: "#/components/responses/Error"
+  /copilot/assistant/environment/runtime:
+    get:
+      tags: [AI Workbench]
+      operationId: getPersonalWorkspaceRuntime
+      summary: Read shared workspace runtime state across Web and App
+      description: Reloads approved owner authorization, VM connect scope and current guest identity. Returns the latest retained human operation and authoritative browser control generation, without dispatching work. Browser frames are historical observations; only the current unexpired control can authorize a new action.
+      responses:
+        "200":
+          description: Current workspace identity, latest receipt and browser control.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/PersonalWorkspaceRuntimeEnvelope" }
+        "401": { $ref: "#/components/responses/Error" }
+        "403": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+        "503": { $ref: "#/components/responses/Error" }
+    post:
+      tags: [AI Workbench]
+      operationId: startPersonalGuestRuntime
+      summary: Start one bounded owner-authorized VM workspace operation
+      description: Requires approved personal Agent access, current owned VM connect permission and resource scope, verified runtime readiness and an exact environment revision. Core freezes owner, data, quota, argv and control identity; a durable managed SSH operation only launches the fixed mTLS broker. Client input cannot select a VM, host path, image or credential. Commands and Docker containers have no host credentials, socket or network; files use bounded UTF-8 content and content CAS. Lost receipts are recovered by GET, never by replaying work. A human browser action uses current user control; Agent writes use the separate Gateway approval path.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/PersonalGuestRuntimeInput" }
+      responses:
+        "202":
+          description: Original durable runtime operation.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/PersonalGuestRuntimeEnvelope" }
+        "400": { $ref: "#/components/responses/Error" }
+        "401": { $ref: "#/components/responses/Error" }
+        "403": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+        "503": { $ref: "#/components/responses/Error" }
+  /copilot/assistant/environment/runtime/{operationId}:
+    get:
+      tags: [AI Workbench]
+      operationId: getPersonalGuestRuntime
+      summary: Read the original owner's retained workspace receipt
+      description: Reloads current authorization and scope and correlates the original frozen operation; never dispatches a command, navigates or recreates files. Stale or unconfirmed outcomes remain unknown. A receipt for an older browser control generation cannot mutate the current control.
+      parameters:
+        - name: operationId
+          in: path
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        "200":
+          description: Original runtime state and bounded owner result.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/PersonalGuestRuntimeEnvelope" }
+        "401": { $ref: "#/components/responses/Error" }
+        "403": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+  /copilot/assistant/environment/guest-tools:
+    post:
+      tags: [AI Workbench]
+      operationId: installPersonalGuestTools
+      summary: Install the owned VM's fixed execution tools without initializing data
+      description: Requires the current approved owner, VM connect/resize permissions and resource scope, initialized data, the exact environment revision and no active task. Core freezes signed Debian package versions, a digest-pinned Docker image, artifact and quota; the durable provider task executes only the fixed installer on this VM. No commands, paths, format, delete or other VM configuration are accepted. The same idempotency key reads the original operation; uncertain effects never trigger automatic redispatch. Installation leaves execution readiness pending until a current isolated runtime probe is verified.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/PersonalGuestToolsInput" }
+      responses:
+        "202":
+          description: Original owner-bound retained tools operation.
+          headers:
+            Cache-Control: { schema: { type: string, const: no-store } }
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/VirtualizationOperationEnvelope" }
+        "400": { $ref: "#/components/responses/Error" }
+        "401": { $ref: "#/components/responses/Error" }
+        "403": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+        "503": { $ref: "#/components/responses/Error" }
+  /copilot/assistant/environment/guest-provisioning:
+    post:
+      tags: [AI Workbench]
+      operationId: provisionPersonalGuest
+      summary: Initialize the current owner's personal VM data and managed guest service
+      description: Requires approved personal Agent access, VM connect and resize permissions and resource scope for the frozen owned VM. An Ed25519 public CSR is the only key input; the matching private key remains in the VM at the fixed bootstrap path. Core atomically reserves the environment CAS, certificate and encrypted durable task. The provider executes a fixed privileged installer with a Core-pinned artifact; no arbitrary command, path, resource deletion or other VM configuration change is accepted. Initialization is dispatched once; uncertain outcomes retain the original operation and cannot be automatically retried or canceled. A verified data receipt does not grant task/tool execution readiness. Recover a lost response by reading the current environment and operations rather than repeating the POST.
+      x-soha-implementation-status: implemented
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/PersonalGuestPreparationInput" }
+      responses:
+        "202":
+          description: Owner-bound durable provisioning operation; no private key or bootstrap challenge is returned.
+          headers:
+            Cache-Control: { schema: { type: string, const: no-store } }
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/VirtualizationOperationEnvelope" }
+        "400": { $ref: "#/components/responses/Error" }
+        "401": { $ref: "#/components/responses/Error" }
+        "403": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+        "503": { $ref: "#/components/responses/Error" }
+  /copilot/assistant/environment/guest-provisioning/{operationId}/reconcile:
+    post:
+      tags: [AI Workbench]
+      operationId: reconcilePersonalGuestProvisioning
+      summary: Explicitly reconcile the original retained personal guest operation
+      description: Requires the current approved owner, VM connect/resize permission, resource scope, exact environment CAS and the original failed/timed-out owned operation. At most three total dispatch attempts are permitted. Core retains operation and frozen data identity, prepares a fresh guest identity and encrypted bootstrap, and records explicit reconciliation. A root bootstrap lock prevents concurrent installers. The protected original format receipt remains authoritative; a dispatched format never repeats, even if the disk still looks blank. A matching filesystem UUID permits completion; mismatched/absent evidence fails closed. No resource is deleted and no generic root command is accepted.
+      x-soha-implementation-status: implemented
+      parameters:
+        - name: operationId
+          in: path
+          required: true
+          schema: { type: string, format: uuid }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/PersonalGuestPreparationInput" }
+      responses:
+        "202":
+          description: The same retained operation queued for explicit reconciliation.
+          headers:
+            Cache-Control: { schema: { type: string, const: no-store } }
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/VirtualizationOperationEnvelope" }
+        "400": { $ref: "#/components/responses/Error" }
+        "401": { $ref: "#/components/responses/Error" }
+        "403": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+        "503": { $ref: "#/components/responses/Error" }
+  /copilot/assistant/environment/guest-enrollment:
+    post:
+      tags: [AI Workbench]
+      operationId: preparePersonalGuestEnrollment
+      summary: Prepare the current owner's dedicated personal VM guest identity
+      description: Requires an approved current personal Agent owner and the frozen personal VM, provider and independent disk proof. Core derives the binding identity and revision and signs only the submitted Ed25519 public key for dedicated guest mTLS. Returns a short single-use challenge without granting readiness or task execution. Private keys remain in the VM. Do not automatically retry an uncertain response; explicit preparation supersedes the previous guest revision while retaining its audit history.
+      x-soha-implementation-status: implemented
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/PersonalGuestPreparationInput" }
+      responses:
+        "201":
+          description: Owner-bound public certificate and private one-time bootstrap challenge; response must not be cached or logged.
+          headers:
+            Cache-Control: { schema: { type: string, const: no-store } }
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/PersonalGuestPreparationEnvelope" }
+        "400": { $ref: "#/components/responses/Error" }
+        "401": { $ref: "#/components/responses/Error" }
+        "403": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+        "503": { $ref: "#/components/responses/Error" }
+  /copilot/assistant/environment/export:
+    post:
+      tags: [AI Workbench]
+      operationId: exportPersonalEnvironmentData
+      summary: Download the authenticated assistant's retained personal files
+      description: Requires the current assistant ID and environment version, a sleeping environment and no active task. Returns a verified TAR archive up to 256 MiB after the Agent stream and SHA-256 receipt are complete. Symlinks are stored as links and never followed. Does not wake, delete, extract or publish data. Temporary server files are removed when the response ends; no server export history is retained. No automatic retry.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PersonalEnvironmentDataExportRequest"
+      responses:
+        "200":
+          description: Complete verified personal data archive
+          headers:
+            X-Content-SHA256:
+              schema: { type: string, pattern: "^[a-f0-9]{64}$" }
+            X-Assistant-ID:
+              schema: { type: string, minLength: 1 }
+          content:
+            application/x-tar:
+              schema: { type: string, format: binary }
+        default:
+          $ref: "#/components/responses/Error"
+  /copilot/assistant/environment/templates:
+    get:
+      tags: [AI Workbench]
+      operationId: listPersonalEnvironmentTemplates
+      summary: List personal Docker template choices within the current user's node scope
+      description: Returns active supported administrator templates without node IDs, credentials or internal policies. A choice describes configuration only; acquisition must obtain a fresh Agent receipt before readiness is claimed.
+      responses:
+        "200":
+          description: Authorized template choices
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PersonalEnvironmentTemplateListEnvelope"
+        default:
+          $ref: "#/components/responses/Error"
+  /copilot/assistant/tasks:
+    get:
+      tags: [AI Workbench]
+      operationId: listPersonalAssistantTasks
+      description: Returns at most 50 recent tasks belonging to the authenticated user across their conversations. Requires chat access; does not grant access to other users or platform-wide AI administration.
+      responses:
+        "200":
+          description: Recent personal tasks.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkbenchAgentRunListEnvelope"
+        "403":
+          $ref: "#/components/responses/Error"
+  /copilot/assistant/artifacts:
+    get:
+      tags: [AI Workbench]
+      operationId: listPersonalAssistantArtifacts
+      description: Returns at most 50 recent saved artifacts owned by the authenticated user across chats and background tasks. A task result mirrored into a message appears once. Requires chat access.
+      responses:
+        "200":
+          description: Recent personal artifacts.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PersonalAssistantArtifactListEnvelope"
+        "403":
+          $ref: "#/components/responses/Error"
   /copilot/sessions:
     get:
       tags: [AI Workbench]
@@ -7029,6 +7844,28 @@ paths:
           $ref: "#/components/responses/Error"
         "403":
           $ref: "#/components/responses/Error"
+  /copilot/sessions/main:
+    post:
+      tags: [AI Workbench]
+      operationId: ensureWorkbenchMainSession
+      description: Returns the current user's persistent main chat, creating it only once. Concurrent requests return the same session. Existing sessions remain separate. The initial provider is applied only when creating the main chat.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/WorkbenchMainSessionRequest"
+      responses:
+        "200":
+          description: The current user's main chat.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkbenchSessionEnvelope"
+        "400":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
   /copilot/sessions/{sessionID}:
     get:
       tags: [AI Workbench]
@@ -7070,6 +7907,8 @@ paths:
           $ref: "#/components/responses/Error"
         "404":
           $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
     delete:
       tags: [AI Workbench]
       operationId: deleteWorkbenchSession
@@ -7082,6 +7921,21 @@ paths:
           $ref: "#/components/responses/Error"
         "404":
           $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+  /copilot/messages/search:
+    get: {"tags":["AI Workbench"],"operationId":"searchWorkbenchMessages","description":"Search owned, unarchived user and assistant messages. Current source ACL applies before matching and snippets; opaque cursor follows stable descending message time and ID.","responses":{"200":{"description":"Search owned, unarchived user and assistant messages. Current source ACL applies before matching and snippets; opaque cursor follows stable descending message time and ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkbenchMessageSearchEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}},"parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string","minLength":1,"maxLength":120}},{"in":"query","name":"cursor","required":false,"schema":{"type":"string","maxLength":512}},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"in":"query","name":"workspace","required":false,"schema":{"type":"string","enum":["chat","heya"],"default":"chat"}}]}
+  /copilot/sessions/{sessionID}/messages/window:
+    get: {"tags":["AI Workbench"],"operationId":"getWorkbenchMessageWindow","description":"Read a chronological message window, latest by default. around, before and after are mutually exclusive owned message IDs; cursors allow stable adjacent windows. Does not change the legacy message list.","responses":{"200":{"description":"Read a chronological message window, latest by default. around, before and after are mutually exclusive owned message IDs; cursors allow stable adjacent windows. Does not change the legacy message list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkbenchMessageWindowEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}},"parameters":[{"$ref":"#/components/parameters/SessionID"},{"in":"query","name":"around","required":false,"schema":{"type":"string","maxLength":128}},{"in":"query","name":"before","required":false,"schema":{"type":"string","maxLength":128}},{"in":"query","name":"after","required":false,"schema":{"type":"string","maxLength":128}},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":3,"maximum":100,"default":40}}]}
+  /copilot/assistant/feed:
+    get: {"tags":["AI Workbench"],"operationId":"listPersonalFeed","description":"Read owned content feed, settings, refresh state and eligible search sources. Does not enqueue work on read.","responses":{"200":{"description":"Read owned content feed, settings, refresh state and eligible search sources. Does not enqueue work on read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonalFeedEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}},"parameters":[{"in":"query","name":"before","required":false,"schema":{"type":"string","maxLength":128}},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}]}
+  /copilot/assistant/feed/settings:
+    put: {"tags":["AI Workbench"],"operationId":"updatePersonalFeedSettings","description":"Update owned content instructions/source and optional daily updates. Automatic updates are disabled by default; changes invalidate unfinished refreshes.","responses":{"200":{"description":"Update owned content instructions/source and optional daily updates. Automatic updates are disabled by default; changes invalidate unfinished refreshes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonalFeedEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonalFeedSettings"}}}}}
+  /copilot/assistant/feed/refresh:
+    post: {"tags":["AI Workbench"],"operationId":"refreshPersonalFeed","description":"Queue one bounded refresh; duplicate active refreshes coalesce. User scoped cooldown prevents repeated paid calls. A valid read-only synchronous search source is required.","responses":{"202":{"description":"Queue one bounded refresh; duplicate active refreshes coalesce. User scoped cooldown prevents repeated paid calls. A valid read-only synchronous search source is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonalFeedEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}
+  /copilot/assistant/feed/items/{itemID}:
+    get: {"tags":["AI Workbench"],"operationId":"getPersonalFeedItem","description":"Read an owned post for discussion context.","responses":{"200":{"description":"Read an owned post for discussion context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonalFeedItemEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}},"parameters":[{"in":"path","name":"itemID","required":true,"schema":{"type":"string","maxLength":128}}]}
+    patch: {"tags":["AI Workbench"],"operationId":"updatePersonalFeedFeedback","description":"Save liked/hidden feedback for an owned post. Hidden posts remain stored and can be referenced by their owner.","responses":{"200":{"description":"Save liked/hidden feedback for an owned post. Hidden posts remain stored and can be referenced by their owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonalFeedItemEnvelope"}}}},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}},"parameters":[{"in":"path","name":"itemID","required":true,"schema":{"type":"string","maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonalFeedFeedback"}}}}}
   /copilot/sessions/{sessionID}/messages:
     get:
       tags: [AI Workbench]
@@ -7544,6 +8398,40 @@ paths:
           $ref: "#/components/responses/Error"
         "503":
           $ref: "#/components/responses/Error"
+    post:
+      tags:
+        - Platform
+      operationId: createKubernetesNamespace
+      x-soha-permissions:
+        mode: all
+        keys:
+          - platform.namespaces.create
+      x-soha-implementation-status: implemented
+      parameters:
+        - $ref: "#/components/parameters/ClusterID"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/KubernetesNamespaceCreateInput"
+      responses:
+        "201":
+          description: Kubernetes operation result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/KubernetesNamespaceEnvelope"
+        "400":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
+        "404":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+        "503":
+          $ref: "#/components/responses/Error"
   /clusters/{clusterID}/infrastructure/nodes:
     get:
       tags: [Platform]
@@ -9548,6 +10436,39 @@ paths:
         "403": { $ref: "#/components/responses/Error" }
         "404": { $ref: "#/components/responses/Error" }
         "503": { $ref: "#/components/responses/Error" }
+  /clusters/{clusterID}/extensions/crds/{crdName}:
+    delete:
+      tags: [Platform]
+      operationId: deleteKubernetesCustomResourceDefinition
+      x-soha-permissions: { mode: all, keys: [platform.extensions.crds.delete] }
+      x-soha-implementation-status: implemented
+      description: Delete one cluster-scoped CRD definition and all of its custom resource instances. This does not uninstall its operator or Helm release. UID and resourceVersion preconditions protect against replacement; finalizers may delay removal.
+      parameters:
+        - $ref: "#/components/parameters/ClusterID"
+        - $ref: "#/components/parameters/KubernetesCRDName"
+        - name: expectedUid
+          in: query
+          required: true
+          description: UID observed in the CRD catalog. A same-name replacement is rejected.
+          schema: { type: string, minLength: 1, maxLength: 128 }
+      responses:
+        "204": { description: Deletion requested. Refresh the catalog to confirm disappearance; finalizers may still be pending. }
+        "400": { $ref: "#/components/responses/Error" }
+        "403": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+        "503": { $ref: "#/components/responses/Error" }
+  /clusters/{clusterID}/extensions/crds/{crdName}/access:
+    get:
+      tags: [Platform]
+      operationId: getKubernetesCustomResourceAccess
+      x-soha-permissions: { mode: all, keys: [platform.extensions.view] }
+      parameters: [{ $ref: "#/components/parameters/ClusterID" }, { $ref: "#/components/parameters/KubernetesCRDName" }, { $ref: "#/components/parameters/KubernetesNamespaceQuery" }]
+      responses:
+        "200": { description: Soha and runtime permissions for this custom resource collection., content: { application/json: { schema: { $ref: "#/components/schemas/KubernetesCustomResourceAccessEnvelope" } } } }
+        "403": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+        "503": { $ref: "#/components/responses/Error" }
   /clusters/{clusterID}/extensions/crds/{crdName}/resources:
     get:
       tags: [Platform]
@@ -10193,6 +11114,65 @@ paths:
           $ref: "#/components/responses/Error"
         "409":
           $ref: "#/components/responses/Error"
+  /clusters/{clusterID}/agent-upgrade:
+    get:
+      tags: [Platform]
+      operationId: getClusterAgentUpgradeStatus
+      description: Read the running Agent version and standard Agent Deployment rollout through the existing cluster connection.
+      x-soha-permissions:
+        mode: all
+        keys: [platform.clusters.view]
+      parameters:
+        - $ref: "#/components/parameters/ClusterID"
+      responses:
+        "200":
+          description: Agent version, recommended version bundled with this server, and rollout status. The recommendation is not a live latest-release lookup.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ClusterAgentUpgradeStatusEnvelope"
+        "400":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
+        "404":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+        "503":
+          $ref: "#/components/responses/Error"
+    post:
+      tags: [Platform]
+      operationId: upgradeClusterAgent
+      description: Update only the standard Agent container to an explicit official release version using the Agent connection. Kubernetes owns the rollout; HTTP 202 means the image update was accepted, not that rollout completed. Non-direct resource owners must use their owning delivery tool.
+      x-soha-permissions:
+        mode: all
+        keys: [platform.clusters.update]
+      parameters:
+        - $ref: "#/components/parameters/ClusterID"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ClusterAgentUpgradeInput"
+      responses:
+        "202":
+          description: Image update accepted. Read upgrade status until the target version reconnects and rollout is healthy.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ClusterAgentUpgradeResultEnvelope"
+        "400":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
+        "404":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+        "503":
+          $ref: "#/components/responses/Error"
   /kubernetes/agent-installations/{installTicket}/manifest.yaml:
     get:
       tags: [Platform]
@@ -11118,6 +12098,32 @@ paths:
           $ref: "#/components/responses/Error"
         "404":
           $ref: "#/components/responses/Error"
+  /secrets/{secretID}/references:
+    get:
+      tags: [Secrets]
+      operationId: listSecretReferences
+      x-soha-implementation-status: implemented
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: secretID
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Visible VM login bindings and initialization operations using fixed secret versions; no secret values.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SecretReferenceUsageListEnvelope"
+        "401":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
+        "404":
+          $ref: "#/components/responses/Error"
   /secrets/{secretID}/versions:
     get:
       tags: [Secrets]
@@ -17740,6 +18746,141 @@ paths:
               schema: { $ref: "#/components/schemas/OperationStatus" }
         "403": { $ref: "#/components/responses/Error" }
         "404": { $ref: "#/components/responses/Error" }
+  /network-access/proxy-instances:
+    get:
+      tags: [Network Access]
+      operationId: listNetworkProxyInstances
+      x-soha-permissions:
+        mode: all
+        keys: [network_access.proxy_instances.view]
+      parameters:
+        - { name: search, in: query, schema: { type: string, maxLength: 200 } }
+        - { name: engine, in: query, schema: { $ref: "#/components/schemas/NetworkProxyEngine" } }
+        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 100 } }
+      responses:
+        "200":
+          description: Registered server proxy instances and observed state.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/NetworkProxyInstanceListEnvelope" }
+        "403": { $ref: "#/components/responses/Error" }
+    post:
+      tags: [Network Access]
+      operationId: createNetworkProxyInstance
+      x-soha-permissions:
+        mode: all
+        keys: [network_access.proxy_instances.create]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/NetworkProxyInstanceInput" }
+      responses:
+        "201":
+          description: Created proxy instance. A separate one-time proxy runtime enrollment is required before it can report state.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/NetworkProxyInstanceEnvelope" }
+        "400": { $ref: "#/components/responses/Error" }
+        "403": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+  /network-access/proxy-instances/{instanceID}:
+    get:
+      tags: [Network Access]
+      operationId: getNetworkProxyInstance
+      x-soha-permissions:
+        mode: all
+        keys: [network_access.proxy_instances.view]
+      parameters:
+        - { name: instanceID, in: path, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
+      responses:
+        "200":
+          description: Proxy instance metadata. Configuration contents and controller credentials are excluded.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/NetworkProxyInstanceEnvelope" }
+        "403": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+  /network-access/proxy-instances/{instanceID}/configuration:
+    put:
+      tags: [Network Access]
+      operationId: updateNetworkProxyConfiguration
+      x-soha-permissions:
+        mode: all
+        keys: [network_access.proxy_instances.update]
+      parameters:
+        - { name: instanceID, in: path, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/NetworkProxyConfigurationInput" }
+      responses:
+        "200":
+          description: Desired revision saved; runtime application is asynchronous. Configuration contents are not returned.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/NetworkProxyInstanceEnvelope" }
+        "400": { $ref: "#/components/responses/Error" }
+        "403": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
+  /network-access/proxy-instances/{instanceID}/traffic:
+    get:
+      tags: [Network Access]
+      operationId: getNetworkProxyTraffic
+      x-soha-permissions:
+        mode: all
+        keys: [network_access.proxy_instances.view]
+      parameters:
+        - { name: instanceID, in: path, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
+        - { name: from, in: query, schema: { type: string, format: date-time } }
+        - { name: to, in: query, schema: { type: string, format: date-time } }
+      responses:
+        "200":
+          description: Bounded samples; speed is derived from adjacent cumulative counters within one runtime uptime epoch.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/NetworkProxyTrafficEnvelope" }
+        "400": { $ref: "#/components/responses/Error" }
+        "403": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+  /network-access/proxy-instances/{instanceID}/connections:
+    get:
+      tags: [Network Access]
+      operationId: getNetworkProxyConnections
+      x-soha-permissions:
+        mode: all
+        keys: [network_access.proxy_connections.view]
+      parameters:
+        - { name: instanceID, in: path, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
+      responses:
+        "200":
+          description: Latest short-lived connection snapshot, or an explicit unsupported/unavailable state.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/NetworkProxyConnectionsEnvelope" }
+        "403": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+  /network-access/proxy-instances/{instanceID}/connections/{connectionID}/close:
+    post:
+      tags: [Network Access]
+      operationId: closeNetworkProxyConnection
+      x-soha-permissions:
+        mode: all
+        keys: [network_access.proxy_connections.close]
+      parameters:
+        - { name: instanceID, in: path, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
+        - { name: connectionID, in: path, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
+      responses:
+        "202":
+          description: Expiring close command queued for the enrolled runtime. The action is audited.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/NetworkProxyCloseCommandEnvelope" }
+        "403": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+        "409": { $ref: "#/components/responses/Error" }
   /network-access/connection-options:
     get:
       tags: [Network Access]
@@ -18458,6 +19599,434 @@ paths:
         "400": { $ref: "#/components/responses/Error" }
         "403": { $ref: "#/components/responses/Error" }
         "404": { $ref: "#/components/responses/Error" }
+  /clusters/{clusterID}/namespaces/{namespaceName}:
+    put:
+      tags:
+        - Platform
+      operationId: updateKubernetesNamespace
+      x-soha-permissions:
+        mode: all
+        keys:
+          - platform.namespaces.update
+      x-soha-implementation-status: implemented
+      parameters:
+        - $ref: "#/components/parameters/ClusterID"
+        - &a1
+          name: namespaceName
+          in: path
+          required: true
+          schema:
+            type: string
+            minLength: 1
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/KubernetesNamespaceInput"
+      responses:
+        "200":
+          description: Kubernetes operation result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/KubernetesNamespaceEnvelope"
+        "400":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
+        "404":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+        "503":
+          $ref: "#/components/responses/Error"
+    delete:
+      tags:
+        - Platform
+      operationId: deleteKubernetesNamespace
+      x-soha-permissions:
+        mode: all
+        keys:
+          - platform.namespaces.delete
+      x-soha-implementation-status: implemented
+      parameters:
+        - $ref: "#/components/parameters/ClusterID"
+        - *a1
+      responses:
+        "204":
+          description: Operation completed.
+        "400":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
+        "404":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+        "503":
+          $ref: "#/components/responses/Error"
+  /clusters/{clusterID}/infrastructure/nodes/{nodeName}:
+    put:
+      tags:
+        - Platform
+      operationId: updateKubernetesNode
+      x-soha-permissions:
+        mode: all
+        keys:
+          - platform.nodes.update
+      x-soha-implementation-status: implemented
+      parameters:
+        - $ref: "#/components/parameters/ClusterID"
+        - $ref: "#/components/parameters/KubernetesNodeName"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/KubernetesNodeUpdateInput"
+      responses:
+        "200":
+          description: Kubernetes operation result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/KubernetesNodeDetailEnvelope"
+        "400":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
+        "404":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+        "503":
+          $ref: "#/components/responses/Error"
+    delete:
+      tags:
+        - Platform
+      operationId: deleteKubernetesNode
+      x-soha-permissions:
+        mode: all
+        keys:
+          - platform.nodes.delete
+      x-soha-implementation-status: implemented
+      parameters:
+        - $ref: "#/components/parameters/ClusterID"
+        - $ref: "#/components/parameters/KubernetesNodeName"
+      responses:
+        "204":
+          description: Operation completed.
+        "400":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
+        "404":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+        "503":
+          $ref: "#/components/responses/Error"
+  /clusters/{clusterID}/infrastructure/nodes/{nodeName}/schedulability:
+    put:
+      tags:
+        - Platform
+      operationId: setKubernetesNodeSchedulability
+      x-soha-permissions:
+        mode: all
+        keys:
+          - platform.nodes.update
+      x-soha-implementation-status: implemented
+      parameters:
+        - $ref: "#/components/parameters/ClusterID"
+        - $ref: "#/components/parameters/KubernetesNodeName"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/KubernetesNodeSchedulabilityInput"
+      responses:
+        "204":
+          description: Operation completed.
+        "400":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
+        "404":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+        "503":
+          $ref: "#/components/responses/Error"
+  /clusters/{clusterID}/infrastructure/nodes/{nodeName}/drain:
+    post:
+      tags:
+        - Platform
+      operationId: drainKubernetesNode
+      x-soha-permissions:
+        mode: all
+        keys:
+          - platform.nodes.drain
+      x-soha-implementation-status: implemented
+      parameters:
+        - $ref: "#/components/parameters/ClusterID"
+        - $ref: "#/components/parameters/KubernetesNodeName"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/KubernetesNodeDrainInput"
+      responses:
+        "204":
+          description: Operation completed.
+        "400":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
+        "404":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+        "503":
+          $ref: "#/components/responses/Error"
+  /clusters/{clusterID}/infrastructure/nodes/{nodeName}/yaml:
+    get:
+      tags:
+        - Platform
+      operationId: getKubernetesNodeYaml
+      x-soha-permissions:
+        mode: all
+        keys:
+          - platform.nodes.view
+      x-soha-implementation-status: implemented
+      parameters:
+        - $ref: "#/components/parameters/ClusterID"
+        - $ref: "#/components/parameters/KubernetesNodeName"
+      responses:
+        "200":
+          description: Kubernetes operation result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/KubernetesResourceYamlEnvelope"
+        "400":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
+        "404":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+        "503":
+          $ref: "#/components/responses/Error"
+    put:
+      tags:
+        - Platform
+      operationId: applyKubernetesNodeYaml
+      x-soha-permissions:
+        mode: all
+        keys:
+          - platform.nodes.update
+      x-soha-implementation-status: implemented
+      parameters:
+        - $ref: "#/components/parameters/ClusterID"
+        - $ref: "#/components/parameters/KubernetesNodeName"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/KubernetesResourceYamlInput"
+      responses:
+        "200":
+          description: Kubernetes operation result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/KubernetesResourceYamlEnvelope"
+        "400":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
+        "404":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+        "503":
+          $ref: "#/components/responses/Error"
+  /clusters/{clusterID}/configuration/configmaps/{name}/data:
+    put:
+      tags:
+        - Platform
+      operationId: updateKubernetesConfigMapData
+      x-soha-permissions:
+        mode: all
+        keys:
+          - platform.configuration.config-maps.update
+      x-soha-implementation-status: implemented
+      parameters:
+        - $ref: "#/components/parameters/ClusterID"
+        - $ref: "#/components/parameters/KubernetesResourceName"
+        - $ref: "#/components/parameters/KubernetesNamespaceQuery"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/KubernetesConfigMapDataInput"
+      responses:
+        "200":
+          description: Kubernetes operation result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/KubernetesConfigMapDetailEnvelope"
+        "400":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
+        "404":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+        "503":
+          $ref: "#/components/responses/Error"
+  /clusters/{clusterID}/configuration/secrets/{name}/detail:
+    get:
+      tags:
+        - Platform
+      operationId: getKubernetesSecretDetail
+      x-soha-permissions:
+        mode: all
+        keys:
+          - platform.configuration.secret-data.view
+          - platform.configuration.secrets.view
+      x-soha-implementation-status: implemented
+      parameters:
+        - $ref: "#/components/parameters/ClusterID"
+        - $ref: "#/components/parameters/KubernetesResourceName"
+        - $ref: "#/components/parameters/KubernetesNamespaceQuery"
+      responses:
+        "200":
+          description: Kubernetes operation result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/KubernetesSecretDetailEnvelope"
+        "400":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
+        "404":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+        "503":
+          $ref: "#/components/responses/Error"
+  /clusters/{clusterID}/configuration/secrets/{name}/data:
+    put:
+      tags:
+        - Platform
+      operationId: updateKubernetesSecretData
+      x-soha-permissions:
+        mode: all
+        keys:
+          - platform.configuration.secret-data.view
+          - platform.configuration.secrets.update
+      x-soha-implementation-status: implemented
+      parameters:
+        - $ref: "#/components/parameters/ClusterID"
+        - $ref: "#/components/parameters/KubernetesResourceName"
+        - $ref: "#/components/parameters/KubernetesNamespaceQuery"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/KubernetesSecretDataInput"
+      responses:
+        "200":
+          description: Kubernetes operation result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/KubernetesSecretDetailEnvelope"
+        "400":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
+        "404":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+        "503":
+          $ref: "#/components/responses/Error"
+  /clusters/{clusterID}/workloads/pods/{podName}:
+    delete:
+      tags:
+        - Platform
+      operationId: deleteKubernetesPod
+      x-soha-permissions:
+        mode: all
+        keys:
+          - platform.pods.delete
+      x-soha-implementation-status: implemented
+      parameters:
+        - $ref: "#/components/parameters/ClusterID"
+        - $ref: "#/components/parameters/KubernetesPodName"
+        - $ref: "#/components/parameters/KubernetesNamespaceQuery"
+      responses:
+        "204":
+          description: Operation completed.
+        "400":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
+        "404":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+        "503":
+          $ref: "#/components/responses/Error"
+  /clusters/{clusterID}/workloads/cronjobs/{cronJobName}/suspend:
+    post:
+      tags:
+        - Platform
+      operationId: setKubernetesCronJobSuspend
+      x-soha-permissions:
+        mode: all
+        keys:
+          - platform.workloads.cron-jobs.suspend
+      x-soha-implementation-status: implemented
+      parameters:
+        - $ref: "#/components/parameters/ClusterID"
+        - $ref: "#/components/parameters/KubernetesCronJobName"
+        - $ref: "#/components/parameters/KubernetesNamespaceQuery"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/KubernetesCronJobSuspendInput"
+      responses:
+        "200":
+          description: Kubernetes operation result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/KubernetesCronJobDetailEnvelope"
+        "400":
+          $ref: "#/components/responses/Error"
+        "403":
+          $ref: "#/components/responses/Error"
+        "404":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+        "503":
+          $ref: "#/components/responses/Error"
 components:
   securitySchemes:
     bearerAuth:
@@ -23728,9 +25297,13 @@ components:
         name: { type: string, minLength: 1, maxLength: 160 }
         kind: { type: string, enum: [inline, http, git, object] }
         version: { type: string, maxLength: 64 }
-        secretRef: { type: string, maxLength: 512 }
+        secretRef:
+          type: string
+          maxLength: 512
+          description: "Gateway execution uses soha://secrets/<id> with an optional /versions/<n>. Legacy secret: references remain readable but require explicit configuration migration before execution."
         config:
           type: object
+          description: External connector config may include importPolicy conforming to knowledge/source-import-policy.schema.json. Core uses this trusted ceiling; fetched ACLs cannot expand it. Omission defaults to the knowledge-base owner. Credentials use secretRef and Gateway authorization, never config values.
           additionalProperties: true
         syncPolicy: { $ref: "#/components/schemas/KnowledgeSyncPolicy" }
       additionalProperties: false
@@ -24096,6 +25669,7 @@ components:
         sourceType: { type: string, enum: [explicit_user, curated_extractor] }
         sourceRefs:
           type: array
+          description: 'Source receipts. Workbench model context supports soha://session/<sessionId>/message/<messageId> and rechecks current ownership and source access. Unsupported historical references remain stored but are withheld from model context.'
           maxItems: 32
           items: { type: string }
         confidence: { type: number, minimum: 0, maximum: 1 }
@@ -24361,14 +25935,53 @@ components:
         createdAt: { type: string, format: date-time }
         updatedAt: { type: string, format: date-time }
       additionalProperties: false
+    PersonalDockerEnvironmentPolicy:
+      type: object
+      description: Administrator-selected registered Agent connection and hard personal-data quota. No user-entered URL, Docker handle, image or credential. Only container templates can use this policy; existing bindings freeze it and cannot silently move or resize their data. Runtime readiness still requires real Agent receipts.
+      required: [agentClusterId, quota, leaseSeconds]
+      properties:
+        agentClusterId: { type: string, format: uuid }
+        quota:
+          $ref: "#/components/schemas/PersonalEnvironmentQuota"
+        leaseSeconds: { type: integer, minimum: 60, maximum: 3600 }
+      additionalProperties: false
+    PersonalVMEnvironmentPolicy:
+      type: object
+      description: Administrator assignment of an existing Soha-managed PVE VM and independent data disk to one user. The server checks administrator VM access update scope and the current approved owner's VM view scope. Binding freezes fresh provider and disk identity; saving or binding does not initialize data or grant runtime readiness. No provider URL, credential, root disk or arbitrary device path is accepted.
+      required: [ownerId, computeRef, provider, dataDiskSerial, dataDiskBytes, quota, leaseSeconds]
+      properties:
+        ownerId: { type: string, format: uuid }
+        computeRef: { type: string, format: uuid, description: Soha VM ID, not a provider VM number. }
+        provider: { type: string, enum: [pve] }
+        dataDiskSerial: { type: string, pattern: '^[A-Za-z0-9_-]{1,20}$' }
+        dataDiskBytes: { type: integer, format: int64, minimum: 1073741824, maximum: 1099511627776, multipleOf: 1073741824, description: Exact independent disk size in whole GiB. }
+        quota:
+          $ref: "#/components/schemas/PersonalEnvironmentQuota"
+        leaseSeconds: { type: integer, minimum: 60, maximum: 3600 }
+      additionalProperties: false
+    PersonalEnvironmentQuota:
+      type: object
+      required: [diskBytes, memoryBytes, cpuUnits, maxProcesses, networkEgress]
+      properties:
+        diskBytes: { type: integer, format: int64, minimum: 16777216, maximum: 1099511627776, description: Hard charged persistent-data bytes; temporary mounts charge memory instead. }
+        memoryBytes: { type: integer, format: int64, minimum: 33554432, maximum: 17179869184 }
+        cpuUnits: { type: integer, format: int64, minimum: 1, maximum: 8000, description: CPU millicores; 1000 is one CPU. }
+        maxProcesses: { type: integer, minimum: 4, maximum: 256 }
+        networkEgress: { type: boolean, const: false, description: Direct network access is not supported by this personal environment policy. }
+      additionalProperties: false
     AIEnvironmentTemplateInput:
       type: object
+      description: Personal policies are mutually exclusive and require matching container or vm backend, an ID of at most 128 characters, and empty legacy resourcePolicy/networkPolicy maps. VM backend requires personalVM; its quota cannot exceed the independent disk size. The server checks current resource scope and explicit owner assignment; saving configuration is not an environment readiness receipt.
       required: [id, name, backend, isolationMode]
       properties:
         id: { type: string, minLength: 1 }
         name: { type: string, minLength: 1 }
-        backend: { type: string, enum: [container, kubernetes] }
+        backend: { type: string, enum: [container, kubernetes, vm] }
         isolationMode: { type: string, enum: [read-only, disposable-write] }
+        personalDocker:
+          $ref: "#/components/schemas/PersonalDockerEnvironmentPolicy"
+        personalVM:
+          $ref: "#/components/schemas/PersonalVMEnvironmentPolicy"
         resourcePolicy:
           type: object
           additionalProperties: true
@@ -24378,12 +25991,17 @@ components:
       additionalProperties: false
     AIEnvironmentTemplate:
       type: object
+      description: Personal policies are mutually exclusive and require matching container or vm backend, an ID of at most 128 characters, and empty legacy resourcePolicy/networkPolicy maps. VM backend requires personalVM; its quota cannot exceed the independent disk size. The server checks current resource scope and explicit owner assignment; saving configuration is not an environment readiness receipt.
       required: [id, name, backend, isolationMode, status, createdAt, updatedAt]
       properties:
         id: { type: string, minLength: 1 }
         name: { type: string, minLength: 1 }
-        backend: { type: string, enum: [container, kubernetes] }
+        backend: { type: string, enum: [container, kubernetes, vm] }
         isolationMode: { type: string, enum: [read-only, disposable-write] }
+        personalDocker:
+          $ref: "#/components/schemas/PersonalDockerEnvironmentPolicy"
+        personalVM:
+          $ref: "#/components/schemas/PersonalVMEnvironmentPolicy"
         resourcePolicy:
           type: object
           additionalProperties: true
@@ -24630,7 +26248,18 @@ components:
         content: { type: string }
         uri: { type: string }
         version: { type: string }
+        deleted:
+          type: boolean
+          description: Explicit source tombstone for this externalId. Missing documents in a partial fetch do not imply deletion. A tombstone has empty content.
         acl: { $ref: "#/components/schemas/KnowledgeAccessScope" }
+      allOf:
+        - if:
+            required: [deleted]
+            properties:
+              deleted: { const: true }
+          then:
+            properties:
+              content: { maxLength: 0 }
       additionalProperties: false
     KnowledgeDocument:
       type: object
@@ -24728,6 +26357,9 @@ components:
         uri: { type: string }
         score: { type: number }
         contentHash: { type: string }
+        documentVersionId: { type: string }
+        indexRevisionId: { type: string }
+        retrievedAt: { type: string, format: date-time }
       additionalProperties: false
     KnowledgeSearchHit:
       type: object
@@ -24758,6 +26390,8 @@ components:
         timingMs: { type: integer, format: int64, minimum: 0 }
         noAnswer: { type: boolean }
         traceId: { type: string }
+        retrievalMode: { type: string, enum: [lexical, hybrid] }
+        degradationReason: { type: string }
       additionalProperties: false
     EvaluationDatasetSample:
       type: object
@@ -25481,10 +27115,32 @@ components:
         reasoningEfforts:
           type: array
           items: { type: string, enum: [low, medium, high] }
+        contextWindowTokens:
+          type: integer
+          format: int64
+          minimum: 1
+          description: Configured model window in tokens. Omitted when any eligible route has no valid capacity; otherwise the smallest eligible route capacity. Never inferred from the model name.
+      additionalProperties: false
+    WorkbenchContextUsage:
+      type: object
+      required: [measurement]
+      description: Latest single model invocation, not cumulative Agent task consumption or selected evidence size. Missing counts and capacity are unknown, not zero. Capacity is snapshotted from the actual resolved route.
+      properties:
+        measurement: { type: string, enum: [reported, estimated, unavailable] }
+        model: { type: string }
+        inputTokens: { type: integer, format: int64, minimum: 0 }
+        outputTokens: { type: integer, format: int64, minimum: 0 }
+        totalTokens: { type: integer, format: int64, minimum: 0 }
+        contextWindowTokens: { type: integer, format: int64, minimum: 1 }
       additionalProperties: false
     WorkbenchSessionMetadata:
       type: object
       properties:
+        conversationKind:
+          type: string
+          enum: [main, side, personal_main, personal_side]
+          readOnly: true
+          description: Server-owned chat role. Older sessions without a role remain side chats. Main chats cannot be archived or deleted through the ordinary session operations.
         modelPreferences:
           $ref: "#/components/schemas/WorkbenchModelPreferences"
         mode:
@@ -25531,6 +27187,340 @@ components:
         createdAt: { type: string, format: date-time }
         updatedAt: { type: string, format: date-time }
       additionalProperties: false
+    PersonalAgentAccess:
+      type: object
+      required: [userId, status, version]
+      properties:
+        userId: { type: string }
+        status:
+          type: string
+          enum: [not_requested, pending, approved, rejected, revoked]
+        version: { type: integer, format: int64, minimum: 0 }
+        requestedAt: { type: string, format: date-time }
+        decidedAt: { type: string, format: date-time }
+        decidedBy: { type: string }
+      additionalProperties: false
+    PersonalAgentAccessDecision:
+      type: object
+      required: [status, version]
+      properties:
+        status: { type: string, enum: [approved, rejected, revoked] }
+        version: { type: integer, format: int64, minimum: 1 }
+      additionalProperties: false
+    PersonalAgentAccessEnvelope:
+      type: object
+      required: [data]
+      properties:
+        data: { $ref: "#/components/schemas/PersonalAgentAccess" }
+      additionalProperties: false
+    PersonalAgentAccessListEnvelope:
+      type: object
+      required: [data]
+      properties:
+        data:
+          type: array
+          items: { $ref: "#/components/schemas/PersonalAgentAccess" }
+      additionalProperties: false
+    PersonalAssistant:
+      type: object
+      required: [id, name, mainSessionId, createdAt, updatedAt]
+      properties:
+        id: { type: string, readOnly: true }
+        name: { type: string, minLength: 1, maxLength: 60 }
+        avatarUrl:
+          description: Bounded raster data URL belonging to this assistant, not the login account. Empty or absent uses the default image.
+          type: string
+          maxLength: 700000
+        avatarPosterUrl:
+          description: Static PNG/JPEG data URL used when motion is disabled or reduced.
+          type: string
+          maxLength: 150000
+        avatarMotion: { type: string, enum: [auto, off] }
+        mainSessionId: { type: string, readOnly: true }
+        createdAt: { type: string, format: date-time, readOnly: true }
+        updatedAt: { type: string, format: date-time, readOnly: true }
+      additionalProperties: false
+    PersonalAssistantAvatarRequest:
+      type: object
+      required: [avatarUrl]
+      properties:
+        avatarUrl:
+          type: string
+          maxLength: 700000
+          pattern: '^(data:image/(png|jpeg|gif|webp);base64,[A-Za-z0-9+/]+={0,2})?$'
+        avatarPosterUrl:
+          type: string
+          maxLength: 150000
+          pattern: '^(data:image/(png|jpeg);base64,[A-Za-z0-9+/]+={0,2})?$'
+        avatarMotion: { type: string, enum: [auto, off], default: auto }
+      additionalProperties: false
+    PersonalEnvironmentActionRequest:
+      type: object
+      required: [action]
+      properties:
+        action: { type: string, enum: [wake, sleep, reconcile] }
+        templateId:
+          description: Required on first wake; may only select the already bound template afterward. Only wake accepts this field.
+          type: string
+          minLength: 1
+          maxLength: 128
+      additionalProperties: false
+    PersonalEnvironmentUsage:
+      type: object
+      required: [diskBytes, memoryBytes, cpuTimeNanos, processes]
+      properties:
+        diskBytes: { type: integer, format: int64, minimum: 0 }
+        memoryBytes: { type: integer, format: int64, minimum: 0 }
+        cpuTimeNanos: { type: integer, format: int64, minimum: 0 }
+        processes: { type: integer, minimum: 0 }
+      additionalProperties: false
+    PersonalEnvironment:
+      type: object
+      required: [assistantId, state, version, dataInitialized]
+      properties:
+        assistantId: { type: string, minLength: 1, readOnly: true }
+        templateId: { type: string, minLength: 1, maxLength: 128, readOnly: true }
+        backend: { type: string, enum: [container, vm], readOnly: true, description: Frozen execution backend of this binding; never inferred from the current template. }
+        provider: { type: string, enum: [docker, pve, kubevirt], readOnly: true }
+        policyRevision: { type: string, minLength: 1, maxLength: 128, readOnly: true, description: Frozen policy identity. legacy-docker-v1 preserves the original stored lease and quota. }
+        computeRef: { type: string, minLength: 1, maxLength: 128, readOnly: true, description: Opaque execution reference; not a physical handle or readiness proof. }
+        computeGeneration: { type: integer, format: int64, minimum: 0, readOnly: true, description: Reserved execution generation; zero means no execution has been reserved. }
+        dataRef: { type: string, minLength: 1, maxLength: 128, readOnly: true, description: Stable logical personal-data identity. Existence requires a fresh authorized receipt. }
+        state:
+          type: string
+          enum: [unprovisioned, pending, ready, sleeping, missing, expired, unknown, quota_exceeded, deleting, deletion_unknown, deleted]
+          readOnly: true
+        version: { type: integer, format: int64, minimum: 0, readOnly: true }
+        dataInitialized:
+          description: A successful past data receipt; does not prove that data currently exists or that the environment is ready.
+          type: boolean
+          readOnly: true
+        quota:
+          $ref: "#/components/schemas/PersonalEnvironmentQuota"
+        usage:
+          $ref: "#/components/schemas/PersonalEnvironmentUsage"
+        observedAt: { type: string, format: date-time, readOnly: true }
+        expiresAt: { type: string, format: date-time, readOnly: true }
+        updatedAt: { type: string, format: date-time, readOnly: true }
+      additionalProperties: false
+    PersonalEnvironmentTemplate:
+      type: object
+      required: [id, name, mode, leaseSeconds, quota]
+      properties:
+        id: { type: string, minLength: 1, maxLength: 128 }
+        name: { type: string, minLength: 1, maxLength: 200 }
+        backend: { type: string, enum: [container, vm] }
+        provider: { type: string, enum: [docker, pve, kubevirt] }
+        policyRevision: { type: string, minLength: 1, maxLength: 128 }
+        mode: { type: string, enum: [observe-only, restricted-write] }
+        leaseSeconds: { type: integer, minimum: 60, maximum: 3600 }
+        quota:
+          $ref: "#/components/schemas/PersonalEnvironmentQuota"
+      additionalProperties: false
+    PersonalEnvironmentTemplateListEnvelope:
+      type: object
+      required: [data]
+      properties:
+        data:
+          type: array
+          maxItems: 100
+          items:
+            $ref: "#/components/schemas/PersonalEnvironmentTemplate"
+      additionalProperties: false
+    PersonalEnvironmentEnvelope:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: "#/components/schemas/PersonalEnvironment"
+      additionalProperties: false
+    PersonalGuestRuntimeInput:
+      type: object
+      additionalProperties: false
+      required: [environmentVersion, idempotencyKey, kind]
+      properties:
+        environmentVersion: { type: integer, format: int64, minimum: 1, maximum: 9007199254740991 }
+        idempotencyKey: { type: string, minLength: 8, maxLength: 128, pattern: "^[a-zA-Z0-9_-]+$" }
+        kind: { type: string, enum: [execute, file_read, file_write, docker, browser] }
+        argv:
+          type: array
+          minItems: 1
+          maxItems: 64
+          items: { type: string, maxLength: 4096 }
+        file:
+          type: object
+          additionalProperties: false
+          required: [path]
+          properties:
+            path: { type: string, minLength: 1, maxLength: 1024 }
+            contentBase64: { type: string, maxLength: 60076 }
+            expectedSHA256: { type: string, pattern: "^[a-f0-9]{64}$" }
+        browser:
+          type: object
+          additionalProperties: false
+          required: [action]
+          properties:
+            action: { type: string, enum: [acquire, snapshot, navigate, click, type, pointer, takeover, return, release] }
+            controlId: { type: string, format: uuid }
+            generation: { type: integer, format: int64, minimum: 1, maximum: 9007199254740991 }
+            url: { type: string, maxLength: 4096 }
+            selector: { type: string, maxLength: 2048 }
+            text: { type: string, maxLength: 4096 }
+            x: { type: integer, minimum: 0, maximum: 799 }
+            y: { type: integer, minimum: 0, maximum: 599 }
+    PersonalGuestRuntime:
+      type: object
+      additionalProperties: false
+      required: [id, kind, status, assistantId, environmentVersion]
+      properties:
+        id: { type: string, format: uuid }
+        kind: { type: string, enum: [execute, file_read, file_write, docker, browser] }
+        status: { type: string, enum: [queued, running, succeeded, failed, canceled, unknown] }
+        assistantId: { type: string, format: uuid }
+        environmentVersion: { type: integer, format: int64, minimum: 1, maximum: 9007199254740991 }
+        output: { type: string, maxLength: 65536 }
+        exitCode: { type: integer, minimum: 0, maximum: 255 }
+        file:
+          type: object
+          additionalProperties: false
+          required: [path, sha256, size]
+          properties:
+            path: { type: string, maxLength: 1024 }
+            contentBase64: { type: string, maxLength: 60076 }
+            sha256: { type: string, pattern: "^[a-f0-9]{64}$" }
+            size: { type: integer, format: int64, minimum: 0, maximum: 45056 }
+        browser:
+          type: object
+          additionalProperties: false
+          required: [controlId, generation, instanceId, width, height]
+          properties:
+            controlId: { type: string, format: uuid }
+            generation: { type: integer, format: int64, minimum: 1, maximum: 9007199254740991 }
+            instanceId: { type: string, format: uuid }
+            url: { type: string, maxLength: 4096 }
+            title: { type: string, maxLength: 512 }
+            text: { type: string, maxLength: 4096 }
+            jpegBase64: { type: string, maxLength: 49152 }
+            width: { type: integer, const: 800 }
+            height: { type: integer, const: 600 }
+    PersonalWorkspaceRuntime:
+      type: object
+      additionalProperties: false
+      required: [assistantId, environmentVersion]
+      properties:
+        assistantId: { type: string, format: uuid }
+        environmentVersion: { type: integer, format: int64, minimum: 1, maximum: 9007199254740991 }
+        latest: { $ref: "#/components/schemas/PersonalGuestRuntime" }
+        browserControl:
+          type: object
+          additionalProperties: false
+          required: [controlId, generation, owner, expiresAt]
+          properties:
+            controlId: { type: string, format: uuid }
+            generation: { type: integer, format: int64, minimum: 1, maximum: 9007199254740991 }
+            owner: { type: string, enum: [user, agent, released] }
+            taskId: { type: string, format: uuid }
+            instanceId: { type: string, format: uuid }
+            expiresAt: { type: string, format: date-time }
+    PersonalWorkspaceRuntimeEnvelope:
+      type: object
+      additionalProperties: false
+      required: [data]
+      properties:
+        data: { $ref: "#/components/schemas/PersonalWorkspaceRuntime" }
+    PersonalGuestRuntimeEnvelope:
+      type: object
+      additionalProperties: false
+      required: [data]
+      properties:
+        data: { $ref: "#/components/schemas/PersonalGuestRuntime" }
+    PersonalGuestToolsInput:
+      type: object
+      additionalProperties: false
+      required: [environmentVersion, idempotencyKey]
+      properties:
+        environmentVersion: { type: integer, format: int64, minimum: 1, maximum: 9007199254740991 }
+        idempotencyKey: { type: string, minLength: 8, maxLength: 128, pattern: "^[a-zA-Z0-9_-]+$" }
+    PersonalGuestPreparationInput:
+      type: object
+      required: [environmentVersion, csrPEM]
+      properties:
+        environmentVersion: { type: integer, format: int64, minimum: 1, maximum: 9007199254740991 }
+        csrPEM: { type: string, minLength: 1, maxLength: 4096, description: Signed Ed25519 CSR containing only a public key. Requested subject and identity never grant authority. }
+      additionalProperties: false
+    PersonalGuestPreparation:
+      type: object
+      required: [bindingId, enrollmentId, challenge, endpoint, certificatePEM, clientCAPEM, expiresAt]
+      properties:
+        bindingId: { type: string, format: uuid }
+        enrollmentId: { type: string, format: uuid }
+        challenge: { type: string, pattern: "^[A-Za-z0-9_-]{43}$", x-soha-sensitive: true, description: One-time 32-byte unpadded base64url token. Must not enter logs, audits, events or command receipts. }
+        endpoint: { type: string, format: uri, maxLength: 512, description: Core-configured HTTPS guest endpoint; never a caller-selected destination. }
+        certificatePEM: { type: string, minLength: 1, maxLength: 8192 }
+        clientCAPEM: { type: string, minLength: 1, maxLength: 8192 }
+        expiresAt: { type: string, format: date-time, description: The bootstrap challenge expiry, not an environment readiness or execution lease. }
+      additionalProperties: false
+    PersonalGuestPreparationEnvelope:
+      type: object
+      required: [data]
+      properties:
+        data: { $ref: "#/components/schemas/PersonalGuestPreparation" }
+      additionalProperties: false
+    PersonalEnvironmentDataExportRequest:
+      type: object
+      required: [assistantId, environmentVersion]
+      properties:
+        assistantId: { type: string, minLength: 1, maxLength: 128 }
+        environmentVersion: { type: integer, format: int64, minimum: 1 }
+      additionalProperties: false
+    PersonalEnvironmentDataDeletionRequest:
+      type: object
+      required: [assistantId, environmentVersion, confirmationName]
+      properties:
+        assistantId: { type: string, minLength: 1, maxLength: 128 }
+        environmentVersion: { type: integer, format: int64, minimum: 1 }
+        confirmationName: { type: string, minLength: 1, maxLength: 60 }
+      additionalProperties: false
+    PersonalAssistantUpdateRequest:
+      type: object
+      required: [name]
+      properties:
+        name: { type: string, minLength: 1, maxLength: 60 }
+      additionalProperties: false
+    PersonalAssistantArtifact:
+      type: object
+      required: [id, artifact, createdAt]
+      properties:
+        id: { type: string, readOnly: true }
+        sessionId: { type: string, readOnly: true }
+        messageId: { type: string, readOnly: true }
+        taskId: { type: string, readOnly: true }
+        artifact:
+          $ref: "#/components/schemas/WorkbenchAnalysisArtifact"
+        createdAt: { type: string, format: date-time, readOnly: true }
+      additionalProperties: false
+    PersonalAssistantArtifactListEnvelope:
+      type: object
+      required: [data]
+      properties:
+        data:
+          type: array
+          maxItems: 50
+          items:
+            $ref: "#/components/schemas/PersonalAssistantArtifact"
+      additionalProperties: false
+    PersonalAssistantEnvelope:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: "#/components/schemas/PersonalAssistant"
+      additionalProperties: false
+    WorkbenchMainSessionRequest:
+      type: object
+      properties:
+        agentProviderId: { type: string, maxLength: 200 }
+      additionalProperties: false
     WorkbenchCreateSessionRequest:
       type: object
       properties:
@@ -25585,9 +27575,11 @@ components:
         role:
           type: string
           enum: [user, assistant, system]
+          x-enum-varnames: [WorkbenchMessageRoleUser, WorkbenchMessageRoleAssistant, WorkbenchMessageRoleSystem]
         content: { type: string }
         metadata:
           type: object
+          description: Background provenance is stored in contextSnapshot (legacy contextEnvelope is readable). contextUsage describes the latest single model call; Native usage is cumulative task consumption. User metadata.images contains WorkbenchImageAttachment items. Completed assistant metadata may contain assistantReaction (one of 👋 👍 ❤️ 😊 🎉 💡 👀 🤔 ✅ 🙏) and server-bound requestMessageId for that reaction. Reactions are social acknowledgements, never approval or execution evidence.
           additionalProperties: {}
         createdAt: { type: string, format: date-time }
       additionalProperties: false
@@ -26197,6 +28189,11 @@ components:
         rootCauseRunId: { type: string }
         createdBy: { type: string }
         status: { type: string }
+        executionOwner: { type: string, enum: [native, external] }
+        phase: { type: string }
+        stopReason: { type: string }
+        eventSequence: { type: integer, minimum: 0 }
+        usageKnown: { type: boolean }
         scope:
           $ref: "#/components/schemas/WorkbenchSessionScope"
         toolset:
@@ -26648,10 +28645,31 @@ components:
         ok:
           type: boolean
       additionalProperties: false
+    WorkbenchAssistantTask:
+      description: An explicit, owner-scoped assistant appearance task executed through chat. Images are bounded inline avatar assets, never arbitrary remote URLs. The instruction remains in content. No account identity or resource permissions change. Undo references a successful profile reply in the same owned session and rejects stale replacements.
+      type: object
+      required: [kind]
+      properties:
+        kind: { type: string, enum: [avatar, undo] }
+        image:
+          $ref: "#/components/schemas/PersonalAssistantAvatarRequest"
+        useCurrentAvatar: { type: boolean }
+        publicModel: { type: string, minLength: 1, maxLength: 128 }
+        messageId: { type: string, minLength: 1, maxLength: 128 }
+      additionalProperties: false
     WorkbenchSendMessageStreamRequest:
       type: object
       required: [content]
       properties:
+        requestId:
+          type: string
+          minLength: 1
+          maxLength: 128
+          description: A stable per-turn idempotency key. Reusing it with different content or selections is rejected.
+        taskIntent:
+          $ref: "#/components/schemas/WorkbenchTaskIntent"
+        assistantTask:
+          $ref: "#/components/schemas/WorkbenchAssistantTask"
         contextSelection:
           $ref: "#/components/schemas/WorkbenchContextSelection"
         knowledgeContext:
@@ -26688,10 +28706,82 @@ components:
           type: object
           additionalProperties: {}
       additionalProperties: false
+    WorkbenchTaskIntent:
+      description: Capability preferences and explicit query parameters for this turn only. Does not change session mode, grant permission, or create scheduled inspections.
+      type: object
+      properties:
+        capabilities:
+          type: array
+          maxItems: 4
+          uniqueItems: true
+          items: { type: string, enum: [root_cause, performance, trace, inspection_review] }
+        dataSourceId:
+          description: Legacy shared selection. A capability-specific data source takes precedence for that capability.
+          type: string
+          maxLength: 256
+        performanceDataSourceId: { type: string, maxLength: 256 }
+        traceDataSourceId: { type: string, maxLength: 256 }
+        rootCauseProfileId: { type: string, maxLength: 256 }
+        metricKey: { type: string, maxLength: 256 }
+        traceId: { type: string, maxLength: 256 }
+        minDurationMs: { type: integer, minimum: 0, maximum: 86400000, x-go-type-skip-optional-pointer: false }
+        inspectionRunIds:
+          type: array
+          maxItems: 20
+          uniqueItems: true
+          items: { type: string, minLength: 1, maxLength: 128 }
+      additionalProperties: false
+    WorkbenchProfessionalCapabilityInput:
+      type: object
+      required: [sessionId, question, scope, intent]
+      properties:
+        sessionId: { type: string, minLength: 1, maxLength: 128 }
+        question: { type: string, minLength: 1, maxLength: 16384 }
+        locale: { type: string, maxLength: 35 }
+        scope: { $ref: "#/components/schemas/WorkbenchSessionScope" }
+        toolset: { $ref: "#/components/schemas/WorkbenchSessionToolset" }
+        intent: { $ref: "#/components/schemas/WorkbenchTaskIntent" }
+      additionalProperties: false
+    AgentRunResumeRequest:
+      type: object
+      properties:
+        input: { type: string, maxLength: 16384 }
+      additionalProperties: false
+    AgentRunEventListEnvelope:
+      type: object
+      required: [data]
+      properties:
+        data: { $ref: "#/components/schemas/AgentRunEventPage" }
+      additionalProperties: false
+    AgentRunEventPage:
+      type: object
+      required: [items, nextSequence, hasMore, resyncRequired]
+      properties:
+        items:
+          type: array
+          items: { $ref: "#/components/schemas/WorkbenchStreamEvent" }
+        nextSequence: { type: integer, minimum: 0 }
+        hasMore: { type: boolean }
+        resyncRequired: { type: boolean }
+      additionalProperties: false
+    WorkbenchMessageSearchHit: {"type":"object","required":["sessionId","sessionTitle","messageId","role","snippet","createdAt"],"properties":{"sessionId":{"type":"string","maxLength":128},"sessionTitle":{"type":"string","maxLength":200},"messageId":{"type":"string","maxLength":128},"role":{"type":"string","enum":["user","assistant"],"x-enum-varnames":["WorkbenchMessageSearchHitRoleUser","WorkbenchMessageSearchHitRoleAssistant"]},"snippet":{"type":"string","maxLength":400},"createdAt":{"type":"string","format":"date-time"}},"additionalProperties":false}
+    WorkbenchMessageSearchPage: {"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WorkbenchMessageSearchHit"}},"nextCursor":{"type":"string","maxLength":512}},"additionalProperties":false}
+    WorkbenchMessageSearchEnvelope: {"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/WorkbenchMessageSearchPage"}},"additionalProperties":false}
+    WorkbenchMessageWindow: {"type":"object","required":["messages"],"properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/WorkbenchMessage"}},"beforeCursor":{"type":"string","maxLength":128},"afterCursor":{"type":"string","maxLength":128}},"additionalProperties":false}
+    WorkbenchMessageWindowEnvelope: {"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/WorkbenchMessageWindow"}},"additionalProperties":false}
+    PersonalFeedSettings: {"type":"object","required":["instructions","searchTool","autoUpdate"],"properties":{"instructions":{"type":"string","maxLength":2000},"searchTool":{"type":"string","maxLength":256},"autoUpdate":{"type":"boolean"}},"additionalProperties":false}
+    PersonalFeedSource: {"type":"object","required":["url","title","excerpt"],"properties":{"url":{"type":"string","format":"uri","maxLength":2048,"pattern":"^https://"},"title":{"type":"string","maxLength":256},"excerpt":{"type":"string","maxLength":4000}},"additionalProperties":false}
+    PersonalFeedItem: {"type":"object","required":["id","title","body","reason","sources","liked","createdAt"],"properties":{"id":{"type":"string","maxLength":128},"title":{"type":"string","maxLength":200},"body":{"type":"string","maxLength":4000},"reason":{"type":"string","maxLength":1000},"sources":{"type":"array","minItems":1,"maxItems":5,"items":{"$ref":"#/components/schemas/PersonalFeedSource"}},"liked":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}},"additionalProperties":false}
+    PersonalFeedSearchTool: {"type":"object","required":["name","title"],"properties":{"name":{"type":"string","maxLength":256},"title":{"type":"string","maxLength":256}},"additionalProperties":false}
+    PersonalFeedPage: {"type":"object","required":["items","settings","state","searchTools"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PersonalFeedItem"}},"settings":{"$ref":"#/components/schemas/PersonalFeedSettings"},"state":{"type":"string","enum":["idle","queued","running","failed"]},"error":{"type":"string","maxLength":1000},"lastUpdatedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":"string","maxLength":128},"searchTools":{"type":"array","items":{"$ref":"#/components/schemas/PersonalFeedSearchTool"}}},"additionalProperties":false}
+    PersonalFeedEnvelope: {"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PersonalFeedPage"}},"additionalProperties":false}
+    PersonalFeedItemEnvelope: {"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PersonalFeedItem"}},"additionalProperties":false}
+    PersonalFeedFeedback: {"type":"object","required":[],"properties":{"liked":{"type":"boolean"},"hidden":{"type":"boolean"}},"additionalProperties":false}
     WorkbenchContextSelection:
-      description: Explicit references and UTF-8 text attachments for this request only. The server rechecks source access and records used content hashes and truncations. Not inherited by subsequent requests.
+      description: Explicit references, UTF-8 text attachments and a bounded inline chat image for this request. Images are ordinary message content and never imply an assistant appearance change. Images are retained with the owned message; references are rechecked on use.
       type: object
       properties:
+        feedItemId: { type: string, minLength: 1, maxLength: 128, description: Owned personal feed post, reloaded and checked by the server before discussion. }
         memoryIds:
           type: array
           maxItems: 20
@@ -26708,6 +28798,23 @@ components:
           maxItems: 8
           items:
             $ref: "#/components/schemas/WorkbenchTextAttachment"
+        images:
+          type: array
+          maxItems: 1
+          items:
+            $ref: "#/components/schemas/WorkbenchImageAttachment"
+      additionalProperties: false
+    WorkbenchImageAttachment:
+      description: Ordinary chat image, preserved without square cropping. Inline PNG/JPEG only, at most 700000 data URL characters and 1024 pixels on each edge. The server verifies MIME, decoded bytes and dimensions before storage or model invocation. No remote URL fetch. Message metadata.images retains the attachment for history and retry.
+      type: object
+      required: [id, name, dataUrl]
+      properties:
+        id: { type: string, minLength: 1, maxLength: 128 }
+        name: { type: string, minLength: 1, maxLength: 256 }
+        dataUrl:
+          type: string
+          maxLength: 700000
+          pattern: '^data:image/(png|jpeg);base64,[A-Za-z0-9+/]+={0,2}$'
       additionalProperties: false
     WorkbenchContextReference:
       type: object
@@ -26881,7 +28988,7 @@ components:
               type: string
             providerKind:
               type: string
-              enum: [internal, hermes, openclaw, general, openai, anthropic, openai-compatible, deepseek, qwen, openrouter, azure-openai, gemini, cohere]
+              enum: [internal, native, hermes, openclaw, general, openai, anthropic, openai-compatible, deepseek, qwen, openrouter, azure-openai, gemini, cohere]
             status:
               type: string
               enum: [queued, running, succeeded, failed, cancelled]
@@ -27023,6 +29130,7 @@ components:
             role:
               type: string
               enum: [assistant]
+              x-enum-varnames: [AgentRunCallbackWorkbenchMessageDeltaEventRoleAssistant]
             contentDelta:
               type: string
       unevaluatedProperties: false
@@ -27038,6 +29146,7 @@ components:
             role:
               type: string
               enum: [assistant]
+              x-enum-varnames: [AgentRunCallbackWorkbenchMessageDeltaEventRoleAssistant]
             content:
               type: string
             metadata:
@@ -32977,12 +35086,14 @@ components:
           type: object
           properties:
             helm: { $ref: "#/components/schemas/HelmExecutionTaskPayload" }
+            sshCommand: { $ref: "#/components/schemas/AgentSSHCommandRequest" }
           additionalProperties: true
           x-go-type: map[string]any
         result:
           type: object
           properties:
             helm: { $ref: "#/components/schemas/HelmExecutionTaskResult" }
+            sshCommand: { $ref: "#/components/schemas/AgentSSHCommandResult" }
           additionalProperties: true
           x-go-type: map[string]any
           x-go-type-skip-optional-pointer: true
@@ -33106,8 +35217,19 @@ components:
         name: { type: string }
         storage: { type: string }
         bus: { type: string }
+        serial:
+          type: string
+          minLength: 1
+          maxLength: 20
+          pattern: '^[A-Za-z0-9_-]+$'
+          description: Immutable guest-visible identity for a newly added PVE disk. Only accepted with add=true; resizing an existing disk preserves its identity. Providers without disk-identity support reject the request before modifying resources.
         sizeGiB: { type: integer, minimum: 1 }
         add: { type: boolean }
+      if: { required: [serial] }
+      then:
+        required: [add]
+        properties:
+          add: { const: true }
       additionalProperties: false
     VirtualMachineNetworkChange:
       type: object
@@ -33206,10 +35328,298 @@ components:
         poolRevision: { type: integer, minimum: 1 }
         idempotencyKey: { type: string, minLength: 8, maxLength: 128 }
       additionalProperties: false
+    VirtualizationCapacityPolicyMode:
+      type: string
+      enum: [unconfigured, observing, enforced]
+      x-enum-varnames: [CapacityPolicyUnconfigured, CapacityPolicyObserving, CapacityPolicyEnforced]
+    VirtualizationOvercommitPolicy:
+      type: object
+      required: [enabled, percent]
+      properties:
+        enabled: { type: boolean }
+        percent: { type: integer, minimum: 100, maximum: 800 }
+      additionalProperties: false
+    VirtualizationMemoryOvercommitPolicy:
+      type: object
+      required: [enabled, percent]
+      properties:
+        enabled: { type: boolean }
+        percent: { type: integer, minimum: 100, maximum: 150 }
+      additionalProperties: false
+    VirtualizationCapacityPolicyInput:
+      type: object
+      required: [expectedRevision, mode, cpu, memory]
+      properties:
+        expectedRevision: { type: integer, minimum: 0 }
+        physicalSourceId:
+          type: string
+          minLength: 1
+          maxLength: 128
+          pattern: "^[A-Za-z0-9][A-Za-z0-9._-]*$"
+          description: Administrator-confirmed identity of one physical PVE source. All aliases must join this identity before admission. Ordinary VM callers cannot choose a source.
+        mode: { type: string, enum: [observing, enforced], x-enum-varnames: [CapacityPolicyInputObserving, CapacityPolicyInputEnforced] }
+        cpu: { $ref: "#/components/schemas/VirtualizationOvercommitPolicy" }
+        memory: { $ref: "#/components/schemas/VirtualizationMemoryOvercommitPolicy" }
+      additionalProperties: false
+    VirtualizationCapacityPolicy:
+      type: object
+      required: [sourceId, revision, mode, cpu, memory]
+      properties:
+        sourceConfirmed: { type: boolean, description: New PVE sources use a strict 100 percent policy and cannot admit until an administrator confirms their physical source identity. }
+        sourceId: { type: string }
+        revision: { type: integer, minimum: 0 }
+        mode: { $ref: "#/components/schemas/VirtualizationCapacityPolicyMode" }
+        cpu: { $ref: "#/components/schemas/VirtualizationOvercommitPolicy" }
+        memory: { $ref: "#/components/schemas/VirtualizationMemoryOvercommitPolicy" }
+        updatedAt: { type: string, format: date-time }
+        updatedBy: { type: string }
+      additionalProperties: false
+    VirtualizationCapacityPolicyEnvelope:
+      type: object
+      required: [data]
+      properties:
+        data: { $ref: "#/components/schemas/VirtualizationCapacityPolicy" }
+      additionalProperties: false
+    VirtualizationCapacityCheckDiagnostic:
+      type: object
+      required: [check, dimension, status, limit, committed, pending, demand, available, reason]
+      properties:
+        check: { type: string, enum: [budget, runtime, storage], x-enum-varnames: [VirtualizationCapacityCheckDiagnosticCheckBudget, VirtualizationCapacityCheckDiagnosticCheckRuntime, VirtualizationCapacityCheckDiagnosticCheckStorage] }
+        dimension: { type: string, enum: [cpu, memory, disk], x-enum-varnames: [VirtualizationCapacityCheckDiagnosticDimensionCpu, VirtualizationCapacityCheckDiagnosticDimensionMemory, VirtualizationCapacityCheckDiagnosticDimensionDisk] }
+        status: { type: string, enum: [available, unavailable, unknown], x-enum-varnames: [VirtualizationCapacityCheckDiagnosticStatusAvailable, VirtualizationCapacityCheckDiagnosticStatusUnavailable, VirtualizationCapacityCheckDiagnosticStatusUnknown] }
+        limit: { type: integer, minimum: 0 }
+        committed: { type: integer, minimum: 0 }
+        pending: { type: integer, minimum: 0 }
+        demand: { type: integer, minimum: 0 }
+        available: { type: integer, minimum: 0 }
+        reason: { type: string }
+      additionalProperties: false
+    VirtualizationCapacityNodeDiagnostic:
+      type: object
+      required: [node, checks]
+      properties:
+        node: { type: string }
+        storage: { type: string }
+        checks:
+          type: array
+          items: { $ref: "#/components/schemas/VirtualizationCapacityCheckDiagnostic" }
+      additionalProperties: false
+    SecretKind:
+      type: string
+      enum: [opaque, ssh_keypair, ssh_public_key, ssh_password]
+      x-enum-varnames: [SecretKindOpaque, SecretKindSSHKeypair, SecretKindSSHPublicKey, SecretKindSSHPassword]
+    SecretPurpose:
+      type: string
+      enum: [vm_cloud_init, vm_auth, vm_exec]
+      x-enum-varnames: [SecretPurposeVMCloudInit, SecretPurposeVMAuth, SecretPurposeVMExec]
+    SecretSSHPublicKey:
+      type: object
+      required: [authorizedKey, algorithm, fingerprint]
+      properties:
+        authorizedKey: { type: string, maxLength: 16384 }
+        algorithm: { type: string }
+        fingerprint: { type: string }
+      additionalProperties: false
+    SecretGenerateSSHKeyRequest:
+      type: object
+      required: [name, scopeType, scopeId, bindings]
+      properties:
+        name: { type: string, minLength: 1, maxLength: 128 }
+        description: { type: string, maxLength: 1024 }
+        scopeType: { $ref: "#/components/schemas/SecretScopeType" }
+        scopeId: { type: string, minLength: 1, maxLength: 128 }
+        bindings:
+          type: array
+          minItems: 1
+          maxItems: 100
+          items: { $ref: "#/components/schemas/SecretBinding" }
+      additionalProperties: false
+    VirtualMachineGuestAccessInput:
+      type: object
+      description: Managed first-boot public-key initialization. Requires a verified cloud-init image and excludes raw cloudInit and native sshkeys/cicustom fields. The server freezes each Secret version; private keys are never sent to the guest.
+      required: [username, publicKeyRefs]
+      properties:
+        username: { type: string, pattern: "^[a-z_][a-z0-9_-]{0,31}$" }
+        publicKeyRefs:
+          type: array
+          minItems: 1
+          maxItems: 16
+          uniqueItems: true
+          items: { type: string, pattern: "^soha://secrets/[A-Za-z0-9._-]+(?:/versions/[1-9][0-9]*)?$" }
+      additionalProperties: false
+    VirtualMachineAccessBindingInput:
+      type: object
+      description: Metadata binding only; it does not install guest keys or alter VM configuration. Host keys must be independently verified by an authorized human before binding.
+      required: [expectedRevision, username, port, address, credentialRef, executionClusterId, executionAgentId, trustedHostKey]
+      properties:
+        expectedRevision: { type: integer, minimum: 0 }
+        username: { type: string, pattern: "^[a-z_][a-z0-9_-]{0,31}$" }
+        port: { type: integer, minimum: 1, maximum: 65535 }
+        address: { type: string, minLength: 1, maxLength: 253 }
+        credentialRef: { type: string, pattern: "^soha://secrets/[A-Za-z0-9._-]+(?:/versions/[1-9][0-9]*)?$" }
+        executionClusterId: { type: string, minLength: 1 }
+        executionAgentId: { type: string, minLength: 1 }
+        trustedHostKey: { type: string, minLength: 1, maxLength: 16384 }
+      additionalProperties: false
+    VirtualMachineAccessBinding:
+      type: object
+      required: [vmId, revision, providerVmId, sourceId, generation, username, port, address, credentialRef, executionClusterId, executionAgentId, hostKeyFingerprint, status]
+      properties:
+        vmId: { type: string }
+        revision: { type: integer, minimum: 1 }
+        providerVmId: { type: string }
+        sourceId: { type: string }
+        generation: { type: string }
+        username: { type: string }
+        port: { type: integer }
+        address: { type: string }
+        credentialRef: { type: string }
+        executionClusterId: { type: string }
+        executionAgentId: { type: string }
+        hostKeyFingerprint: { type: string }
+        status: { type: string, enum: [ready, unavailable, stale], x-enum-varnames: [VirtualMachineAccessBindingStatusReady, VirtualMachineAccessBindingStatusUnavailable, VirtualMachineAccessBindingStatusStale] }
+        reason: { type: string }
+        updatedAt: { type: string, format: date-time }
+      additionalProperties: false
+    VirtualMachineAccessBindingEnvelope:
+      type: object
+      required: [data]
+      properties:
+        data: { $ref: "#/components/schemas/VirtualMachineAccessBinding" }
+      additionalProperties: false
+    VirtualMachineSSHSessionInput:
+      type: object
+      required: [bindingRevision]
+      properties:
+        bindingRevision: { type: integer, minimum: 1 }
+        cols: { type: integer, minimum: 1, maximum: 512, default: 80 }
+        rows: { type: integer, minimum: 1, maximum: 512, default: 24 }
+      additionalProperties: false
+    VirtualMachineSSHSession:
+      type: object
+      required: [id, vmId, bindingRevision, status, expiresAt]
+      properties:
+        id: { type: string }
+        vmId: { type: string }
+        bindingRevision: { type: integer, minimum: 1 }
+        status: { type: string, enum: [pending, active, closed, revoked, unknown], x-enum-varnames: [VirtualMachineSSHSessionStatusPending, VirtualMachineSSHSessionStatusActive, VirtualMachineSSHSessionStatusClosed, VirtualMachineSSHSessionStatusRevoked, VirtualMachineSSHSessionStatusUnknown] }
+        expiresAt: { type: string, format: date-time }
+        reason: { type: string }
+      additionalProperties: false
+    VirtualMachineSSHSessionEnvelope:
+      type: object
+      required: [data]
+      properties:
+        data: { $ref: "#/components/schemas/VirtualMachineSSHSession" }
+      additionalProperties: false
+    VirtualMachineSSHCommandInput:
+      type: object
+      required: [bindingRevision, command, idempotencyKey]
+      properties:
+        bindingRevision: { type: integer, minimum: 1 }
+        command: { type: string, minLength: 1, maxLength: 16384, x-soha-sensitive: true }
+        idempotencyKey: { type: string, minLength: 8, maxLength: 128 }
+        timeoutSeconds: { type: integer, minimum: 1, maximum: 300, default: 60 }
+      additionalProperties: false
+    VirtualMachineSSHCommand:
+      type: object
+      required: [id, vmId, bindingRevision, status, outcome, terminal]
+      properties:
+        id: { type: string }
+        vmId: { type: string }
+        bindingRevision: { type: integer, minimum: 1 }
+        status: { type: string }
+        outcome: { type: string, enum: [unknown, succeeded, failed, canceled], x-enum-varnames: [VirtualMachineSSHCommandOutcomeUnknown, VirtualMachineSSHCommandOutcomeSucceeded, VirtualMachineSSHCommandOutcomeFailed, VirtualMachineSSHCommandOutcomeCanceled] }
+        terminal: { type: boolean }
+        exitCode: { type: integer, minimum: 0, maximum: 255, x-go-type-skip-optional-pointer: false }
+        stdout: { type: string, maxLength: 1048576 }
+        stderr: { type: string, maxLength: 1048576 }
+        outputDigest: { type: string }
+        outputTruncated: { type: boolean }
+        finishedAt: { type: string, format: date-time }
+      additionalProperties: false
+    VirtualMachineSSHCommandEnvelope:
+      type: object
+      required: [data]
+      properties:
+        data: { $ref: "#/components/schemas/VirtualMachineSSHCommand" }
+      additionalProperties: false
+    AgentSSHCommandRequest:
+      type: object
+      required: [session, command, timeoutSeconds]
+      properties:
+        session: { $ref: "#/components/schemas/AgentSSHSessionRequest" }
+        command: { type: string, minLength: 1, maxLength: 16384, x-soha-sensitive: true }
+        timeoutSeconds: { type: integer, minimum: 1, maximum: 300 }
+      additionalProperties: false
+    AgentSSHCommandResult:
+      type: object
+      required: [sessionId, agentId, commandDigest, effect, stopped]
+      properties:
+        sessionId: { type: string }
+        agentId: { type: string }
+        commandDigest: { type: string }
+        effect: { type: string, enum: [not_started, exited, unknown], x-enum-varnames: [AgentSSHCommandResultEffectNotStarted, AgentSSHCommandResultEffectExited, AgentSSHCommandResultEffectUnknown] }
+        stopped: { type: boolean }
+        exitCode: { type: integer, minimum: 0, maximum: 255, x-go-type-skip-optional-pointer: false }
+        stdout: { type: string, maxLength: 1048576 }
+        stderr: { type: string, maxLength: 1048576 }
+        outputTruncated: { type: boolean }
+        outputDigest: { type: string }
+      additionalProperties: false
+    VirtualMachineSSHFrame:
+      type: object
+      required: [type]
+      properties:
+        type: { type: string, enum: [input, resize, output, error, close], x-enum-varnames: [VirtualMachineSSHFrameTypeInput, VirtualMachineSSHFrameTypeResize, VirtualMachineSSHFrameTypeOutput, VirtualMachineSSHFrameTypeError, VirtualMachineSSHFrameTypeClose] }
+        data: { type: string, maxLength: 87384 }
+        dataEncoding: { type: string, enum: [utf8, base64], x-enum-varnames: [VirtualMachineSSHFrameDataEncodingUTF8, VirtualMachineSSHFrameDataEncodingBase64], description: Base64 carries exact terminal bytes including split UTF-8 sequences. Omitted means utf8 for legacy inputs. }
+        exitCode: { type: integer, minimum: 0, maximum: 255, x-go-type-skip-optional-pointer: false }
+        cols: { type: integer, minimum: 1, maximum: 512 }
+        rows: { type: integer, minimum: 1, maximum: 512 }
+        message: { type: string, maxLength: 1024 }
+      additionalProperties: false
+    AgentSSHSessionRequest:
+      type: object
+      required: [sessionId, agentId, executionClusterId, address, port, username, trustedHostKey, credentialKind, lease, controlPlaneEndpoint, expiresAt, cols, rows]
+      properties:
+        sessionId: { type: string }
+        agentId: { type: string }
+        executionClusterId: { type: string, minLength: 1 }
+        address: { type: string }
+        port: { type: integer, minimum: 1, maximum: 65535 }
+        username: { type: string }
+        trustedHostKey: { type: string, maxLength: 16384 }
+        credentialKind: { $ref: "#/components/schemas/SecretKind" }
+        lease: { $ref: "#/components/schemas/SecretLeaseGrant" }
+        controlPlaneEndpoint: { type: string, format: uri }
+        expiresAt: { type: string, format: date-time }
+        cols: { type: integer, minimum: 1, maximum: 512 }
+        rows: { type: integer, minimum: 1, maximum: 512 }
+      additionalProperties: false
+    VMSSHCredentialRedemptionInput:
+      type: object
+      required: [clusterId, agentId, leaseId, token]
+      properties:
+        clusterId: { type: string, minLength: 1 }
+        agentId: { type: string, minLength: 1 }
+        leaseId: { type: string, minLength: 1 }
+        token: { type: string, minLength: 16, maxLength: 256, writeOnly: true }
+      additionalProperties: false
+    AgentSSHCapability:
+      type: object
+      required: [agentId, protocolVersion, available]
+      properties:
+        agentId: { type: string }
+        protocolVersion: { type: integer, const: 1 }
+        available: { type: boolean }
+        commandsAvailable: { type: boolean }
+      additionalProperties: false
     VirtualizationCapacityInput:
       type: object
       required: [connectionId, cpu, memoryMiB, diskGiB]
       properties:
+        startAfterCreate: { type: boolean, default: true, x-go-type-skip-optional-pointer: false }
         connectionId: { type: string, minLength: 1 }
         cpu: { type: integer, minimum: 1, maximum: 65536, description: Dedicated CPU cores for a running VM. }
         memoryMiB: { type: integer, minimum: 1, maximum: 1099511627776, description: Guest memory in MiB; configured hypervisor overhead is added by the server. }
@@ -33224,6 +35634,12 @@ components:
       description: A read-only, expiring placement suggestion for one running VM and root disk. Missing or unsupported inventory remains unknown. Creation must independently require atomic capacity admission; this result is not a reservation or a readiness assessment.
       required: [connectionId, status, reason]
       properties:
+        sourceId: { type: string }
+        policyRevision: { type: integer, minimum: 0 }
+        policyMode: { $ref: "#/components/schemas/VirtualizationCapacityPolicyMode" }
+        diagnostics:
+          type: array
+          items: { $ref: "#/components/schemas/VirtualizationCapacityNodeDiagnostic" }
         connectionId: { type: string }
         provider: { type: string }
         status:
@@ -33247,12 +35663,13 @@ components:
       type: object
       required: [connectionId, name]
       properties:
+        guestAccess: { $ref: "#/components/schemas/VirtualMachineGuestAccessInput" }
         connectionId: { type: string, minLength: 1 }
         name: { type: string, minLength: 1 }
         requireCapacity:
           type: boolean
           default: false
-          description: Require fresh provider capacity and reserve node CPU, memory and storage atomically with this operation. Missing inventory or unsupported placement fails closed. This controls concurrent Soha admission; provider admission and runtime readiness remain authoritative.
+          description: Require fresh provider capacity and reserve node CPU, memory and storage atomically with this operation. Missing inventory or unsupported placement fails closed. An enforced source policy always requires admission, including when this field is false. Unconfigured legacy sources retain the explicit opt-in behavior. Provider admission and runtime readiness remain authoritative.
         architecture: { type: string }
         namespace: { type: string }
         node: { type: string }
@@ -33260,7 +35677,7 @@ components:
         memoryMiB: { type: integer, minimum: 1 }
         bootImageId: { type: string }
         imageId: { type: string }
-        sourceMode: { type: string }
+        sourceMode: { type: string, description: "PVE supports template_clone, vm_clone, iso_install and cloud_image. cloud_image imports a verified catalog QCOW2 volume into this new VM; it does not create or modify a source VM." }
         sourceId: { type: string }
         flavorId: { type: string }
         diskGiB: { type: integer, minimum: 1 }
@@ -33523,6 +35940,9 @@ components:
         cpu: { type: integer, minimum: 0 }
         memoryMiB: { type: integer, minimum: 0 }
         diskGiB: { type: integer, minimum: 0 }
+        requireCapacity:
+          type: boolean
+          description: Require fresh atomic capacity admission for start, reboot or resize even when cluster policy is unconfigured. False never bypasses an enforced policy. New disks require fixed slots, storage and serial identity; multiple storage pools require separate operations.
         disks:
           type: array
           maxItems: 64
@@ -33654,8 +36074,8 @@ components:
         architecture: { type: string }
         sizeBytes: { type: integer, format: int64, minimum: 0 }
         sizeGiB: { type: integer, format: int64, minimum: 0 }
-        sourceKind: { type: string }
-        sourceRef: { type: string }
+        sourceKind: { type: string, description: "PVE cloud_image declares an already staged QCOW2 import volume. cloudInitSupported must be explicitly true for managed guest initialization." }
+        sourceRef: { type: string, description: "For PVE cloud_image use storage:import/<SHA256>.qcow2 sealed with the filesystem immutable flag. The provider verifies immutability, format, digest, absence of backing files and requested root size before dispatch. Catalog creation registers metadata and does not itself upload a file." }
         namespace: { type: string }
         storageClass: { type: string }
         url: { type: string }
@@ -33862,6 +36282,8 @@ components:
           maxLength: 1048576
           description: Sensitive bootstrap content. It is never returned by plan or audit responses.
           x-soha-sensitive: true
+        guestAccess:
+          $ref: "#/components/schemas/VirtualMachineGuestAccessInput"
         cpuCoreCount: { type: integer, minimum: 1 }
         memoryBytes: { type: integer, minimum: 1 }
         diskBytes: { type: integer, minimum: 1 }
@@ -34268,6 +36690,11 @@ components:
           type: string
         status:
           type: string
+        executionOwner: { type: string, enum: [native, external] }
+        phase: { type: string }
+        stopReason: { type: string }
+        eventSequence: { type: integer, minimum: 0 }
+        usageKnown: { type: boolean }
         scope:
           type: object
           additionalProperties: true
@@ -41546,6 +43973,19 @@ components:
         plan: { $ref: "#/components/schemas/CapabilityPlan" }
         aiClientId: { type: string }
         skillId: { type: string }
+        scopeConstraints:
+          type: array
+          maxItems: 20
+          uniqueItems: true
+          description: Immutable exact target constraints for every resolved invocation, approval replay, status read and cancellation. These narrow scope and never grant permission.
+          items: { $ref: "#/components/schemas/CapabilityScopeConstraint" }
+      additionalProperties: false
+    CapabilityScopeConstraint:
+      type: object
+      required: [dimension, value]
+      properties:
+        dimension: { type: string, minLength: 1, maxLength: 64, pattern: '^[A-Za-z][A-Za-z0-9_]{0,63}$' }
+        value: { type: string, minLength: 1, maxLength: 512 }
       additionalProperties: false
     CapabilityTaskRevisionInput:
       description: Retained step IDs inherit their prior SecretRefs when call.secretRefs is omitted; an explicit empty object clears them. All references remain subject to current authorization.
@@ -41566,6 +44006,10 @@ components:
         status: { type: string }
         createdBy: { type: string }
         plan: { $ref: "#/components/schemas/CapabilityPlan" }
+        scopeConstraints:
+          type: array
+          maxItems: 20
+          items: { $ref: "#/components/schemas/CapabilityScopeConstraint" }
         nodes:
           type: array
           items: { $ref: "#/components/schemas/CapabilityTaskNode" }
@@ -41769,10 +44213,11 @@ components:
       type: object
       required: [targetType, targetRef]
       properties:
+        purpose: { $ref: "#/components/schemas/SecretPurpose" }
         targetType:
           type: string
-          enum: [capability, project, connection]
-          x-enum-varnames: [SecretBindingCapability, SecretBindingProject, SecretBindingConnection]
+          enum: [capability, project, connection, vm, vm_create]
+          x-enum-varnames: [SecretBindingCapability, SecretBindingProject, SecretBindingConnection, SecretBindingVM, SecretBindingVMCreate]
         targetRef:
           type: string
           minLength: 1
@@ -41808,10 +44253,41 @@ components:
           type: integer
           minimum: 1
       additionalProperties: false
+    SecretReferenceUsage:
+      type: object
+      required: [targetId, usage, version, status]
+      properties:
+        targetId:
+          type: string
+        vmId:
+          type: string
+        usage:
+          type: string
+          description: login_binding, ssh_session or cloud_init_operation. Historical initialization does not assert that the guest still trusts this key.
+        version:
+          type: integer
+          minimum: 1
+        bindingRevision:
+          type: integer
+          minimum: 1
+        status:
+          type: string
+      additionalProperties: false
+    SecretReferenceUsageListEnvelope:
+      type: object
+      required: [items]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/SecretReferenceUsage"
+      additionalProperties: false
     SecretMetadata:
       type: object
       required: [id, name, scopeType, scopeId, status, currentVersion, bindings, createdBy, createdAt, updatedAt]
       properties:
+        kind: { $ref: "#/components/schemas/SecretKind" }
+        publicKey: { $ref: "#/components/schemas/SecretSSHPublicKey" }
         id:
           type: string
         name:
@@ -41852,6 +44328,8 @@ components:
       else:
         required: [vaultKv2]
       properties:
+        kind: { $ref: "#/components/schemas/SecretKind" }
+        sshPassphrase: { type: string, maxLength: 4096, writeOnly: true, x-soha-sensitive: true }
         name:
           type: string
           minLength: 1
@@ -41908,6 +44386,7 @@ components:
       else:
         required: [vaultKv2]
       properties:
+        sshPassphrase: { type: string, maxLength: 4096, writeOnly: true, x-soha-sensitive: true }
         value:
           type: string
           minLength: 1
@@ -41920,6 +44399,8 @@ components:
       type: object
       required: [secretId, version, status, createdBy, createdAt]
       properties:
+        kind: { $ref: "#/components/schemas/SecretKind" }
+        publicKey: { $ref: "#/components/schemas/SecretSSHPublicKey" }
         secretId:
           type: string
         version:
@@ -42503,6 +44984,7 @@ components:
         rateLimitProfileId:
           type: string
         metadata:
+          description: Optional contextWindowTokens declares this route model window as a positive integer token count. Missing or invalid values mean unknown capacity; model names are never used to guess it.
           type: object
           additionalProperties: true
         createdAt:
@@ -42557,6 +45039,7 @@ components:
         rateLimitProfileId:
           type: string
         metadata:
+          description: Optional contextWindowTokens declares this route model window as a positive integer token count. Missing or invalid values mean unknown capacity; model names are never used to guess it.
           type: object
           additionalProperties: true
       additionalProperties: false