@opengeni/sdk 0.48.0 → 0.57.0

package/src/client.ts

@@ -12,6 +12,95 @@ import {
   streamWorkspaceControlEvents,
   type WorkspaceControlStreamTransport,
 } from "./workspace-control-stream";
+import {
+  streamWorkspaceInteractionRevisions,
+  type WorkspaceInteractionRevisionStreamTransport,
+} from "./interaction-revision-stream";
+import {
+  streamWorkspaceLiveEvents,
+  type WorkspaceLiveStreamOptions,
+  type WorkspaceLiveStreamTransport,
+} from "./workspace-live-stream";
+import {
+  OpenGeniInteractionClient,
+  type AuthRun,
+  type AuthRunListOptions,
+  type AuthRunListResponse,
+  type AuthRunMutationResponse,
+  type AttachedBrowserDevice,
+  type AttachedBrowserDeviceListOptions,
+  type AttachedBrowserDeviceListResponse,
+  type BrowserActionReceipt,
+  type BrowserActionRequest,
+  type BrowserClipboard,
+  type BrowserDiagnosticBatch,
+  type BrowserDiagnosticsOptions,
+  type BrowserDownload,
+  type BrowserDownloadListResponse,
+  type BrowserDownloadSaveRequest,
+  type BrowserDownloadSaveResponse,
+  type BrowserIdentity,
+  type BrowserIdentityListOptions,
+  type BrowserIdentityListResponse,
+  type BrowserIdentityMutationResponse,
+  type BrowserObservation,
+  type BrowserOpenTargetRequest,
+  type BrowserSession,
+  type BrowserSessionAttachment,
+  type BrowserSessionAttachmentRequest,
+  type BrowserSessionHeartbeatResponse,
+  type BrowserSessionLifecycleRequest,
+  type BrowserSessionListResponse,
+  type BrowserSessionMutationResponse,
+  type BrowserTargetListResponse,
+  type BrowserRevisionListResponse,
+  type ComputerActionReceipt,
+  type ComputerActionRequest,
+  type ComputerClipboard,
+  type ComputerObservation,
+  type ComputerSession,
+  type ComputerSessionAttachment,
+  type ComputerSessionAttachmentRequest,
+  type ComputerSessionHeartbeatResponse,
+  type ComputerSessionLifecycleRequest,
+  type ComputerSessionListResponse,
+  type ComputerSessionMutationResponse,
+  type ComputerTargetListResponse,
+  type CreateBrowserIdentityRequest,
+  type CreateBrowserSessionRequest,
+  type CreateComputerSessionRequest,
+  type CreateInteractionInterventionRequest,
+  type CreateNetworkRouteRequest,
+  type CreateSiteAuthConnectionRequest,
+  type ExternalAuthInteractiveRequest,
+  type ExternalAuthInteractiveResponse,
+  type ExternalAuthRunRequest,
+  type ExternalAuthRunResponse,
+  type InteractionIntervention,
+  type InteractionInterventionListOptions,
+  type InteractionInterventionListResponse,
+  type InteractionInterventionMutationResponse,
+  type NetworkRoute,
+  type NetworkRouteListOptions,
+  type NetworkRouteListResponse,
+  type NetworkRouteMutationResponse,
+  type ProtectedAuthFillRequest,
+  type ProtectedAuthFillResponse,
+  type PublishBrowserRevisionRequest,
+  type PublishBrowserRevisionResponse,
+  type ReportAuthRunRequest,
+  type ResolveInteractionInterventionRequest,
+  type SiteAuthConnection,
+  type SiteAuthConnectionListOptions,
+  type SiteAuthConnectionListResponse,
+  type SiteAuthConnectionMutationResponse,
+  type StartAuthRunRequest,
+  type UpdateNetworkRouteRequest,
+  type UpdateBrowserIdentityRequest,
+  type UpdateSiteAuthConnectionRequest,
+  type VerifyAuthRunRequest,
+  type WorkspaceInteractionRevisionEvent,
+} from "./interaction";
 import type {
   AccessContext,
   ActivateCodexRealtimeConnectionRequest,
@@ -33,6 +122,14 @@ import type {
   CodexConnectStart,
   CodexUsage,
   CodexUsageMap,
+  SuperGrokAccount,
+  SuperGrokAccountsResponse,
+  SuperGrokAccountScope,
+  SuperGrokAllocatorUpdate,
+  SuperGrokConnectionStatus,
+  SuperGrokConnectPoll,
+  SuperGrokConnectStart,
+  SuperGrokRotationSettings,
   BillingSummary,
   BillingUsageResponse,
   InsightsRange,
@@ -41,6 +138,29 @@ import type {
   CapabilityCatalogItem,
   CapabilityCatalogResponse,
   CapabilityInstallation,
+  ApiIntegrationPreview,
+  ApiIntegrationOAuthStartRequest,
+  ApiIntegrationUninstallPreview,
+  InstallApiIntegrationRequest,
+  InstalledApiIntegration,
+  IntegrationFacetMutationResult,
+  IntegrationFacetRemovalResult,
+  IntegrationInstanceFacetsResponse,
+  ListIntegrationDefinitionsResponse,
+  ListApiIntegrationsResponse,
+  MutateIntegrationFacetRequest,
+  PreviewApiIntegrationRequest,
+  UninstallApiIntegrationRequest,
+  UninstallApiIntegrationResult,
+  UpsertIntegrationFacetRequest,
+  PreviewPluginRequest,
+  PluginPreview,
+  InstallPluginRequest,
+  InstalledPlugin,
+  ListInstalledPluginsResponse,
+  PluginUninstallPreview,
+  UninstallPluginRequest,
+  UninstallPluginResult,
   AddDocumentRequest,
   CreateKnowledgeDropRequest,
   MoveDocumentRequest,
@@ -54,11 +174,18 @@ import type {
   CreateApiKeyRequest,
   CreateApiKeyResponse,
   CreateCapabilityCatalogItemRequest,
+  InstallSkillRequest,
+  InstallLibrarySkillRequest,
+  InstalledSkill,
+  ListInstalledSkillsResponse,
   CreateCheckoutRequest,
   CreateCheckoutResponse,
   OpenGeniSlackBotInstallRequest,
   OpenGeniSlackBotInstallStart,
   SlackReactionChannelListResponse,
+  FikenInstallRequest,
+  FikenOAuthStartRequest,
+  FikenOAuthStartResponse,
   CreateConnectionRequest,
   CreateDocumentBaseRequest,
   CreateFileUploadRequest,
@@ -91,11 +218,14 @@ import type {
   GetPackResponse,
   GitHubAppInfo,
   GitHubRepositoriesResponse,
+  GoogleDriveBrowseResponse,
   GoogleDriveDisconnectRequest,
+  SaveGoogleDriveIntegrationSourceRequest,
   GoogleDriveLifecycleActionRequest,
   KnowledgeMemory,
   KnowledgeMemorySearchRequest,
   ListApiKeysResponse,
+  ListManagedOrganizationMembershipsResponse,
   ListPacksResponse,
   // Bring-your-own-compute: the Machines dashboard + per-machine metrics (M10).
   MachinesResponse,
@@ -107,27 +237,50 @@ import type {
   SwapActiveSandboxRequest,
   SwapActiveSandboxResponse,
   ListWorkspaceMembersResponse,
+  InstallPackRequest,
+  PackInstallationPreview,
+  ListSlackUserLinkAccessRequestsResponse,
+  PrepareSlackUserLinkAccessRequest,
+  SlackUserLinkAccessMutationRequest,
+  SlackUserLinkAccessRequest,
+  ApproveSlackUserLinkAccessRequest,
   PackInstallation,
+  PackUninstallPreview,
   LatencyMode,
   ReasoningEffort,
   RetainedScreenshotDownload,
   RetainedScreenshotDownloadOptions,
+  RetainedArtifactDownload,
+  RetainedArtifactDownloadOptions,
+  RetainedArtifactReference,
   RetainedArtifactContent,
   RetainedArtifactContentOptions,
   RetainedArtifactMetadata,
+  UpdateVideoGenerationPolicyRequest,
+  VideoArtifactPlaybackSource,
+  VideoGenerationOperationSummary,
+  VideoGenerationPolicy,
+  WorkspaceVideoGenerationSettings,
   RegisterCapabilityPackRequest,
   ResourceRef,
+  PreviewPackInstallationRequest,
+  PreviewSkillImportRequest,
   ScheduledTask,
   ScheduledTaskRun,
   Session,
   SessionListResponse,
+  AgentTopologyPageResponse,
+  UpdateSessionChannelRequest,
   UpdateSessionPinRequest,
+  UninstallPackRequest,
+  UninstallPackResult,
   SessionEvent,
   SessionEventCompactResult,
   SessionEventCompactResultOptions,
   SessionEventListOptions,
   SessionEventPage,
   SessionGoal,
+  SessionGoalRevision,
   SessionHumanInputRequest,
   SessionLineageResponse,
   SessionRealtimeMutationResponse,
@@ -135,6 +288,7 @@ import type {
   SyncSessionRealtimeLedgerResponse,
   RenewSessionRealtimeRequest,
   SessionMcpCredentialUpdateInput,
+  SubmittedTimelineAnnotation,
   UpdateSessionMcpApprovalPolicyRequest,
   UpdateSessionMcpApprovalPolicyResponse,
   SessionQueueSnapshot,
@@ -204,6 +358,7 @@ import type {
   UpdateKnowledgeMemoryRequest,
   UpdateScheduledTaskRequest,
   UpdateSessionGoalRequest,
+  ApplySessionGoalRevisionRequest,
   UpdateSessionRequest,
   UpdateSessionToolPolicyRequest,
   UpdateVariableSetRequest,
@@ -216,6 +371,9 @@ import type {
   VariableSet,
   VariableSetSecret,
   VariableSetVariableMetadata,
+  Channel,
+  CreateChannelRequest,
+  UpdateChannelRequest,
   Rig,
   RigVersion,
   RigChange,
@@ -226,12 +384,20 @@ import type {
   WorkspaceRegisteredPack,
   Workspace,
   ListConnectionsResponse,
+  ListSlackInstallationBindingsResponse,
+  SlackInstallationBinding,
   ConnectionResponse,
   OAuthStartRequest,
   OAuthStartResponse,
   SocialConnection,
   SocialOAuthStartRequest,
+  SkillImportPreview,
+  SkillUninstallPreview,
+  UninstallSkillRequest,
+  UninstallSkillResult,
 } from "./types";
+import { GENERATED_VIDEO_MAX_BYTES } from "./types";
+import { parseRetainedGeneratedImageReference } from "./retained-artifacts";
 import type {
   ActivateWorkspaceInstructionPolicyRequest,
   CreateWorkspaceInstructionPolicyDraftRequest,
@@ -248,6 +414,17 @@ import type {
   WorkspaceInstructionPolicyOnboardingProposalListResponse,
   WorkspaceInstructionPolicyRevision,
 } from "./workspace-instruction-policies";
+import type {
+  ActivateCompanyProfileRevisionRequest,
+  CompanyProfileDiffRequest,
+  CompanyProfileDiffResponse,
+  CompanyProfileListOptions,
+  CompanyProfileListResponse,
+  CompanyProfileMutationResponse,
+  CompanyProfileRevision,
+  RollbackCompanyProfileRequest,
+  UpdateCompanyProfileRequest,
+} from "./company-profile";
 import type {
   WorkspaceStateExportResponse,
   WorkspaceStateGetOptions,
@@ -315,6 +492,7 @@ export type OpenGeniRequestOptions = {
 
 export type SendMessageInput = {
   text: string;
+  annotations?: SubmittedTimelineAnnotation[];
   /** System instructions scoped to this exact turn; never visible timeline text. */
   turnInstructions?: string;
   resources?: ResourceRef[];
@@ -333,6 +511,10 @@ export type SteerMessageResult = {
   accepted: SessionEvent;
   /** The exact turn created for this message in the same server transaction. */
   turn: SessionTurn;
+  /** Number of live attempts durably asked to stop by this atomic Steer. */
+  interruptionCount?: number;
+  /** True when this response came from the command's immutable idempotency receipt. */
+  replay?: boolean;
 };
 
 export type TranscribeAudioInput = {
@@ -375,12 +557,15 @@ export class OpenGeniClient {
   private readonly fetchImpl: FetchLike;
   private readonly readInFlight = new Map<string, Promise<unknown>>();
   private readonly readTrailing = new Map<string, Promise<unknown>>();
+  /** Resource-oriented Browser/Computer facade over this exact authenticated client. */
+  readonly interaction: OpenGeniInteractionClient;
 
   constructor(options: OpenGeniClientOptions) {
     this.baseUrl = options.baseUrl.replace(/\/+$/, "");
     this.options = options;
     // Bind lazily so variable sets that polyfill fetch after module load work.
     this.fetchImpl = options.fetch ?? ((input, init) => fetch(input, init));
+    this.interaction = new OpenGeniInteractionClient(this);
   }
 
   // --- Session lifecycle ---------------------------------------------------
@@ -769,6 +954,32 @@ export class OpenGeniClient {
     return response;
   }
 
+  /** Compact, bounded workspace agent hierarchy page. */
+  async listAgentTopology(
+    workspaceId: string,
+    options: {
+      limit?: number;
+      parentSessionId?: string | null;
+      cursor?: string;
+      search?: string;
+    } = {},
+  ): Promise<AgentTopologyPageResponse> {
+    const search = options.search?.trim();
+    return await this.requestJson<AgentTopologyPageResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/agent-topology`,
+      undefined,
+      {
+        ...(options.limit !== undefined ? { limit: String(options.limit) } : {}),
+        ...(options.parentSessionId === undefined
+          ? {}
+          : { parentSessionId: options.parentSessionId ?? "null" }),
+        ...(options.cursor ? { cursor: options.cursor } : {}),
+        ...(search ? { search } : {}),
+      },
+    );
+  }
+
   /** Set this authenticated member's personal workspace pin for a session. */
   async updateSessionPin(
     workspaceId: string,
@@ -849,6 +1060,22 @@ export class OpenGeniClient {
     );
   }
 
+  /** Mint a short-lived browser token from a connected SuperGrok account. */
+  async negotiateXaiSubscriptionRealtime(
+    workspaceId: string,
+    sessionId: string,
+    request: GatewayRealtimeConnectRequest,
+    options: { signal?: AbortSignal | undefined } = {},
+  ): Promise<GatewayRealtimeConnectResponse> {
+    return await this.requestJson<GatewayRealtimeConnectResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/realtime/supergrok`,
+      request,
+      {},
+      { signal: options.signal },
+    );
+  }
+
   /** Promote a negotiated connection only after its browser data channel is ready. */
   async activateCodexRealtimeConnection(
     workspaceId: string,
@@ -1633,6 +1860,61 @@ export class OpenGeniClient {
     return streamWorkspaceControlEvents(this.workspaceControlStreamTransport(workspaceId), options);
   }
 
+  /**
+   * Multiplex workspace control and interaction invalidations over one HTTP
+   * connection while retaining an independent durable cursor for each domain.
+   */
+  streamWorkspaceLiveEvents(workspaceId: string, options: WorkspaceLiveStreamOptions = {}) {
+    return streamWorkspaceLiveEvents(this.workspaceLiveStreamTransport(workspaceId), options);
+  }
+
+  workspaceLiveStreamTransport(workspaceId: string): WorkspaceLiveStreamTransport {
+    return {
+      openStream: async (controlAfter, interactionAfter, signal) =>
+        await this.openWorkspaceLiveEventStream(workspaceId, {
+          controlAfter,
+          interactionAfter,
+          ...(signal ? { signal } : {}),
+        }),
+    };
+  }
+
+  async openWorkspaceLiveEventStream(
+    workspaceId: string,
+    options: {
+      controlAfter?: number;
+      interactionAfter?: number;
+      signal?: AbortSignal;
+    } = {},
+  ): Promise<ReadableStream<Uint8Array>> {
+    const correlationId = crypto.randomUUID();
+    const response = await this.fetchImpl(
+      this.url(`/v1/workspaces/${workspaceId}/live-events/stream`, {
+        controlAfter: String(options.controlAfter ?? 0),
+        interactionAfter: String(options.interactionAfter ?? 0),
+      }),
+      {
+        method: "GET",
+        headers: {
+          ...this.headers(correlationId),
+          Accept: "text/event-stream",
+        },
+        ...(options.signal ? { signal: options.signal } : {}),
+      },
+    );
+    assertApiContractResponse(response);
+    if (!response.ok) {
+      throw await apiErrorFromResponse(response, {
+        method: "GET",
+        correlationId,
+      });
+    }
+    if (!response.body) {
+      throw new OpenGeniApiError(response.status, "SSE response did not include a readable body");
+    }
+    return response.body;
+  }
+
   workspaceControlStreamTransport(workspaceId: string): WorkspaceControlStreamTransport {
     return {
       openStream: async (after, signal) =>
@@ -1711,6 +1993,26 @@ export class OpenGeniClient {
     );
   }
 
+  async listGoalRevisions(workspaceId: string, sessionId: string): Promise<SessionGoalRevision[]> {
+    return await this.requestJson<SessionGoalRevision[]>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/goal/revisions`,
+    );
+  }
+
+  async applyGoalRevision(
+    workspaceId: string,
+    sessionId: string,
+    revisionId: string,
+    request: ApplySessionGoalRevisionRequest,
+  ): Promise<SessionGoal> {
+    return await this.requestJson<SessionGoal>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/goal/revisions/${revisionId}/apply`,
+      request,
+    );
+  }
+
   async deleteGoal(workspaceId: string, sessionId: string): Promise<void> {
     await this.requestVoid("DELETE", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/goal`);
   }
@@ -2087,13 +2389,11 @@ export class OpenGeniClient {
   }
 
   /** Attach a viewer holder (refcounted liveness — keeps the box warm while
-   *  watched/used), spinning the box up in-process when cold, and mint the scoped
-   *  direct-to-provider URLs for the requested plane(s). `request.desktop:true`
-   *  opts into the un-redacted pixel plane and mints the noVNC URL — that plane
-   *  alone throws `OpenGeniApiError(409)` when the un-redacted/shared
-   *  acknowledgment is missing (the consent gate). A terminal-only attach
-   *  (`desktop` omitted/false) warms the box + mints the pty-ws terminal cell with
-   *  NO consent gate. An omitted `viewerId` mints a fresh one. */
+   *  watched/used), spinning the box up in-process when cold. Exact plane flags
+   *  mint only the requested short-lived credentials and enforce that plane's
+   *  permission. `desktop:true` alone carries the un-redacted/shared consent
+   *  gate. An entirely omitted plane set retains the legacy terminal-only
+   *  meaning; current clients should send all three flags. */
   async attachViewer(
     workspaceId: string,
     sessionId: string,
@@ -2130,1355 +2430,2952 @@ export class OpenGeniClient {
     );
   }
 
-  // --- Access + workspaces -----------------------------------------------------
+  // --- Browser / Computer interaction resources --------------------------------
 
-  /**
-   * The deployment's public client bootstrap config: the host-exposed models
-   * (provider-grouped in `models`, flat in `allowedModels` for back-compat),
-   * reasoning efforts, MCP servers, file-upload limits, and how the client is
-   * expected to authenticate. Drives a composer's model picker without prior
-   * knowledge of the host setup; safe to call before any auth is established.
-   */
-  async getClientConfig(): Promise<ClientConfig> {
-    const config = await this.requestJson<ClientConfig>("GET", "/v1/config/client");
-    if (config.apiContractRevision !== OPENGENI_API_CONTRACT_REVISION) {
-      throw new OpenGeniApiContractMismatchError(
-        OPENGENI_API_CONTRACT_REVISION,
-        String(config.apiContractRevision || "(missing)"),
-      );
-    }
-    return config;
+  streamWorkspaceInteractionRevisions(
+    workspaceId: string,
+    options: StreamSessionEventsOptions = {},
+  ): AsyncGenerator<WorkspaceInteractionRevisionEvent, void, void> {
+    return streamWorkspaceInteractionRevisions(
+      this.workspaceInteractionRevisionStreamTransport(workspaceId),
+      options,
+    );
   }
 
-  /** Authenticated model definitions plus workspace-specific selectability. */
-  async getWorkspaceModelCatalog(workspaceId: string): Promise<WorkspaceModelCatalogResponse> {
-    return await this.requestJson<WorkspaceModelCatalogResponse>(
-      "GET",
-      `/v1/workspaces/${workspaceId}/model-catalog`,
+  workspaceInteractionRevisionStreamTransport(
+    workspaceId: string,
+  ): WorkspaceInteractionRevisionStreamTransport {
+    return {
+      openStream: async (after, signal) =>
+        await this.openWorkspaceInteractionRevisionStream(workspaceId, {
+          after,
+          ...(signal ? { signal } : {}),
+        }),
+    };
+  }
+
+  async openWorkspaceInteractionRevisionStream(
+    workspaceId: string,
+    options: { after?: number; signal?: AbortSignal } = {},
+  ): Promise<ReadableStream<Uint8Array>> {
+    const correlationId = crypto.randomUUID();
+    const response = await this.fetchImpl(
+      this.url(`/v1/workspaces/${workspaceId}/interaction-events/stream`, {
+        after: String(options.after ?? 0),
+      }),
+      {
+        method: "GET",
+        headers: {
+          ...this.headers(correlationId),
+          Accept: "text/event-stream",
+        },
+        ...(options.signal ? { signal: options.signal } : {}),
+      },
     );
+    assertApiContractResponse(response);
+    if (!response.ok) {
+      throw await apiErrorFromResponse(response, {
+        method: "GET",
+        correlationId,
+      });
+    }
+    if (!response.body) {
+      throw new OpenGeniApiError(response.status, "SSE response did not include a readable body");
+    }
+    return response.body;
   }
 
-  /** Authenticated realtime voice models and credential readiness. */
-  async getWorkspaceRealtimeModelCatalog(
+  async listNetworkRoutes(
     workspaceId: string,
-  ): Promise<WorkspaceRealtimeModelCatalogResponse> {
-    return await this.requestJson<WorkspaceRealtimeModelCatalogResponse>(
+    options: NetworkRouteListOptions = {},
+  ): Promise<NetworkRouteListResponse> {
+    return await this.requestJson<NetworkRouteListResponse>(
       "GET",
-      `/v1/workspaces/${workspaceId}/realtime-model-catalog`,
+      `/v1/workspaces/${workspaceId}/network-routes`,
+      undefined,
+      options.includeArchived ? { includeArchived: "true" } : {},
+      options,
     );
   }
 
-  /** The caller's access context: subject, account + workspace grants, defaults. */
-  async getAccessContext(): Promise<AccessContext> {
-    return await this.requestJson<AccessContext>("GET", "/v1/access/me");
+  async getNetworkRoute(
+    workspaceId: string,
+    networkRouteId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<NetworkRoute> {
+    return await this.requestJson<NetworkRoute>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/network-routes/${encodeURIComponent(networkRouteId)}`,
+      undefined,
+      {},
+      options,
+    );
   }
 
-  async listWorkspaces(): Promise<Workspace[]> {
-    return await this.requestJson<Workspace[]>("GET", "/v1/workspaces");
+  async createNetworkRoute(
+    workspaceId: string,
+    request: CreateNetworkRouteRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<NetworkRouteMutationResponse> {
+    return await this.requestJson<NetworkRouteMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/network-routes`,
+      request,
+      {},
+      options,
+    );
   }
 
-  async createWorkspace(request: CreateWorkspaceRequest): Promise<Workspace> {
-    return await this.requestJson<Workspace>("POST", "/v1/workspaces", request);
+  async updateNetworkRoute(
+    workspaceId: string,
+    networkRouteId: string,
+    request: UpdateNetworkRouteRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<NetworkRouteMutationResponse> {
+    return await this.requestJson<NetworkRouteMutationResponse>(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/network-routes/${encodeURIComponent(networkRouteId)}`,
+      request,
+      {},
+      options,
+    );
   }
 
-  async getWorkspace(workspaceId: string): Promise<Workspace> {
-    return await this.requestJson<Workspace>("GET", `/v1/workspaces/${workspaceId}`);
+  async listSiteAuthConnections(
+    workspaceId: string,
+    options: SiteAuthConnectionListOptions = {},
+  ): Promise<SiteAuthConnectionListResponse> {
+    return await this.requestJson<SiteAuthConnectionListResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/site-auth-connections`,
+      undefined,
+      options.includeArchived ? { includeArchived: "true" } : {},
+      options,
+    );
   }
 
-  /** Read-time, secret-safe inventory of policy heads and visible workspace knowledge. */
-  async getWorkspaceState(
+  async getSiteAuthConnection(
     workspaceId: string,
-    options: WorkspaceStateGetOptions = {},
-  ): Promise<WorkspaceStateResponse> {
-    const params = new URLSearchParams();
-    if (options.attemptId) params.set("attemptId", options.attemptId);
-    const query = params.size > 0 ? `?${params.toString()}` : "";
-    return await this.requestJson<WorkspaceStateResponse>(
+    siteAuthConnectionId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<SiteAuthConnection> {
+    return await this.requestJson<SiteAuthConnection>(
       "GET",
-      `/v1/workspaces/${workspaceId}/workspace-state${query}`,
+      `/v1/workspaces/${workspaceId}/site-auth-connections/${encodeURIComponent(siteAuthConnectionId)}`,
+      undefined,
+      {},
+      options,
     );
   }
 
-  /** Download the canonical, explicitly sanitized Workspace State export. */
-  async exportWorkspaceState(
+  async createSiteAuthConnection(
     workspaceId: string,
-    options: WorkspaceStateGetOptions = {},
-  ): Promise<WorkspaceStateExportResponse> {
-    const params = new URLSearchParams();
-    if (options.attemptId) params.set("attemptId", options.attemptId);
-    const query = params.size > 0 ? `?${params.toString()}` : "";
-    return await this.requestJson<WorkspaceStateExportResponse>(
-      "GET",
-      `/v1/workspaces/${workspaceId}/workspace-state/export${query}`,
+    request: CreateSiteAuthConnectionRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<SiteAuthConnectionMutationResponse> {
+    return await this.requestJson<SiteAuthConnectionMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/site-auth-connections`,
+      request,
+      {},
+      options,
     );
   }
 
-  async updateWorkspace(workspaceId: string, request: UpdateWorkspaceRequest): Promise<Workspace> {
-    return await this.requestJson<Workspace>("PATCH", `/v1/workspaces/${workspaceId}`, request);
+  async updateSiteAuthConnection(
+    workspaceId: string,
+    siteAuthConnectionId: string,
+    request: UpdateSiteAuthConnectionRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<SiteAuthConnectionMutationResponse> {
+    return await this.requestJson<SiteAuthConnectionMutationResponse>(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/site-auth-connections/${encodeURIComponent(siteAuthConnectionId)}`,
+      request,
+      {},
+      options,
+    );
   }
 
-  /** Inspect immutable instruction-policy history, active heads, and activation audit evidence. */
-  async listWorkspaceInstructionPolicies(
+  async listAuthRuns(
     workspaceId: string,
-    options: WorkspaceInstructionPolicyListOptions = {},
-  ): Promise<WorkspaceInstructionPolicyListResponse> {
-    const params = new URLSearchParams();
-    if (options.kind !== undefined) params.set("kind", options.kind);
-    if (options.scope !== undefined) params.set("scope", options.scope);
-    if (options.roleKey !== undefined) params.set("roleKey", options.roleKey);
-    if (options.afterRevision !== undefined) {
-      params.set("afterRevision", String(options.afterRevision));
-    }
-    if (options.limit !== undefined) params.set("limit", String(options.limit));
-    const query = params.toString();
-    return await this.requestJson<WorkspaceInstructionPolicyListResponse>(
+    options: AuthRunListOptions = {},
+  ): Promise<AuthRunListResponse> {
+    return await this.requestJson<AuthRunListResponse>(
       "GET",
-      `/v1/workspaces/${workspaceId}/instruction-policies${query ? `?${query}` : ""}`,
+      `/v1/workspaces/${workspaceId}/auth-runs`,
+      undefined,
+      {
+        ...(options.browserSessionId ? { browserSessionId: options.browserSessionId } : {}),
+        ...(options.siteAuthConnectionId
+          ? { siteAuthConnectionId: options.siteAuthConnectionId }
+          : {}),
+        ...(options.includeSettled ? { includeSettled: "true" } : {}),
+      },
+      options,
     );
   }
 
-  async getWorkspaceInstructionPolicyRevision(
+  async getAuthRun(
     workspaceId: string,
-    revisionId: string,
-  ): Promise<WorkspaceInstructionPolicyRevision> {
-    return await this.requestJson<WorkspaceInstructionPolicyRevision>(
+    authRunId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<AuthRun> {
+    return await this.requestJson<AuthRun>(
       "GET",
-      `/v1/workspaces/${workspaceId}/instruction-policies/${encodeURIComponent(revisionId)}`,
+      `/v1/workspaces/${workspaceId}/auth-runs/${encodeURIComponent(authRunId)}`,
+      undefined,
+      {},
+      options,
     );
   }
 
-  async createWorkspaceInstructionPolicyDraft(
+  async startBrowserAuthRun(
     workspaceId: string,
-    request: CreateWorkspaceInstructionPolicyDraftRequest,
-  ): Promise<WorkspaceInstructionPolicyRevision> {
-    return await this.requestJson<WorkspaceInstructionPolicyRevision>(
+    browserSessionId: string,
+    request: StartAuthRunRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<AuthRunMutationResponse> {
+    return await this.requestJson<AuthRunMutationResponse>(
       "POST",
-      `/v1/workspaces/${workspaceId}/instruction-policies/drafts`,
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/auth-runs`,
       request,
+      {},
+      options,
     );
   }
 
-  /** List the newest immutable onboarding proposals and their inactive policy drafts. */
-  async listWorkspaceInstructionPolicyOnboardingProposals(
-    workspaceId: string,
-    options: WorkspaceInstructionPolicyOnboardingProposalListOptions = {},
-  ): Promise<WorkspaceInstructionPolicyOnboardingProposalListResponse> {
-    const params = new URLSearchParams();
-    if (options.limit !== undefined) params.set("limit", String(options.limit));
-    const query = params.toString();
-    return await this.requestJson<WorkspaceInstructionPolicyOnboardingProposalListResponse>(
-      "GET",
-      `/v1/workspaces/${workspaceId}/instruction-policies/onboarding-proposals${query ? `?${query}` : ""}`,
-    );
-  }
-
-  /** Create one draft-only proposal against an exact active-policy baseline. */
-  async createWorkspaceInstructionPolicyOnboardingProposal(
+  async reportBrowserAuthRun(
     workspaceId: string,
-    request: CreateWorkspaceInstructionPolicyOnboardingProposalRequest,
-  ): Promise<WorkspaceInstructionPolicyOnboardingProposal> {
-    return await this.requestJson<WorkspaceInstructionPolicyOnboardingProposal>(
+    browserSessionId: string,
+    authRunId: string,
+    request: ReportAuthRunRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<AuthRunMutationResponse> {
+    return await this.requestJson<AuthRunMutationResponse>(
       "POST",
-      `/v1/workspaces/${workspaceId}/instruction-policies/onboarding-proposals`,
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/auth-runs/${encodeURIComponent(authRunId)}/report`,
       request,
+      {},
+      options,
     );
   }
 
-  /** Import the stored legacy workspace override as an inactive charter draft. */
-  async importLegacyWorkspaceInstructionPolicyDraft(
+  async protectedBrowserAuthFill(
     workspaceId: string,
-    request: ImportLegacyWorkspaceInstructionPolicyDraftRequest = {},
-  ): Promise<WorkspaceInstructionPolicyRevision> {
-    return await this.requestJson<WorkspaceInstructionPolicyRevision>(
+    browserSessionId: string,
+    authRunId: string,
+    request: ProtectedAuthFillRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<ProtectedAuthFillResponse> {
+    return await this.requestJson<ProtectedAuthFillResponse>(
       "POST",
-      `/v1/workspaces/${workspaceId}/instruction-policies/import-legacy`,
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/auth-runs/${encodeURIComponent(authRunId)}/protected-fill`,
       request,
+      {},
+      options,
     );
   }
 
-  async diffWorkspaceInstructionPolicyRevisions(
+  async advanceExternalBrowserAuthRun(
     workspaceId: string,
-    request: WorkspaceInstructionPolicyDiffRequest,
-  ): Promise<WorkspaceInstructionPolicyDiffResponse> {
-    const params = new URLSearchParams({
-      fromRevisionId: request.fromRevisionId,
-      toRevisionId: request.toRevisionId,
-    });
-    return await this.requestJson<WorkspaceInstructionPolicyDiffResponse>(
-      "GET",
-      `/v1/workspaces/${workspaceId}/instruction-policies/diff?${params}`,
+    browserSessionId: string,
+    authRunId: string,
+    request: ExternalAuthRunRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<ExternalAuthRunResponse> {
+    return await this.requestJson<ExternalAuthRunResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/auth-runs/${encodeURIComponent(authRunId)}/external-auth`,
+      request,
+      {},
+      options,
     );
   }
 
-  async activateWorkspaceInstructionPolicyRevision(
+  async openExternalBrowserAuthFlow(
     workspaceId: string,
-    revisionId: string,
-    request: ActivateWorkspaceInstructionPolicyRequest,
-  ): Promise<WorkspaceInstructionPolicyActivationResponse> {
-    return await this.requestJson<WorkspaceInstructionPolicyActivationResponse>(
+    browserSessionId: string,
+    authRunId: string,
+    request: ExternalAuthInteractiveRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<ExternalAuthInteractiveResponse> {
+    return await this.requestJson<ExternalAuthInteractiveResponse>(
       "POST",
-      `/v1/workspaces/${workspaceId}/instruction-policies/${encodeURIComponent(revisionId)}/activate`,
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/auth-runs/${encodeURIComponent(authRunId)}/external-auth/interactive`,
       request,
+      {},
+      options,
     );
   }
 
-  async rollbackWorkspaceInstructionPolicyRevision(
+  async verifyBrowserAuthRun(
     workspaceId: string,
-    request: RollbackWorkspaceInstructionPolicyRequest,
-  ): Promise<WorkspaceInstructionPolicyActivationResponse> {
-    return await this.requestJson<WorkspaceInstructionPolicyActivationResponse>(
+    browserSessionId: string,
+    authRunId: string,
+    request: VerifyAuthRunRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<AuthRunMutationResponse> {
+    return await this.requestJson<AuthRunMutationResponse>(
       "POST",
-      `/v1/workspaces/${workspaceId}/instruction-policies/rollback`,
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/auth-runs/${encodeURIComponent(authRunId)}/verify`,
       request,
+      {},
+      options,
     );
   }
 
-  async listPreferenceRegistry(
+  async listInteractionInterventions(
     workspaceId: string,
-    options: PreferenceRegistryListOptions = {},
-  ): Promise<PreferenceRegistryListResponse> {
-    const params = new URLSearchParams();
-    if (options.scope) params.set("scope", options.scope);
-    if (options.status) params.set("status", options.status);
-    if (options.limit !== undefined) params.set("limit", String(options.limit));
-    const query = params.toString();
-    return await this.requestJson<PreferenceRegistryListResponse>(
+    options: InteractionInterventionListOptions = {},
+  ): Promise<InteractionInterventionListResponse> {
+    return await this.requestJson<InteractionInterventionListResponse>(
       "GET",
-      `/v1/workspaces/${workspaceId}/preferences${query ? `?${query}` : ""}`,
+      `/v1/workspaces/${workspaceId}/interaction-interventions`,
+      undefined,
+      {
+        ...(options.resourceKind ? { resourceKind: options.resourceKind } : {}),
+        ...(options.resourceId ? { resourceId: options.resourceId } : {}),
+        ...(options.includeSettled ? { includeSettled: "true" } : {}),
+      },
+      options,
     );
   }
 
-  async getPreferenceRegistry(
+  async getInteractionIntervention(
     workspaceId: string,
-    preferenceId: string,
-  ): Promise<PreferenceRegistryDetailResponse> {
-    return await this.requestJson<PreferenceRegistryDetailResponse>(
+    interventionId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<InteractionIntervention> {
+    return await this.requestJson<InteractionIntervention>(
       "GET",
-      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}`,
+      `/v1/workspaces/${workspaceId}/interaction-interventions/${encodeURIComponent(interventionId)}`,
+      undefined,
+      {},
+      options,
     );
   }
 
-  async createPreferenceRegistryProposal(
+  async createInteractionIntervention(
     workspaceId: string,
-    request: CreatePreferenceRegistryProposalRequest,
-  ): Promise<PreferenceRegistryRecord> {
-    return await this.requestJson<PreferenceRegistryRecord>(
+    request: CreateInteractionInterventionRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<InteractionInterventionMutationResponse> {
+    return await this.requestJson<InteractionInterventionMutationResponse>(
       "POST",
-      `/v1/workspaces/${workspaceId}/preferences/proposals`,
+      `/v1/workspaces/${workspaceId}/interaction-interventions`,
       request,
+      {},
+      options,
     );
   }
 
-  async activatePreferenceRegistryRevision(
+  async resolveInteractionIntervention(
     workspaceId: string,
-    preferenceId: string,
-    request: ActivatePreferenceRegistryRevisionRequest,
-  ): Promise<PreferenceRegistryMutationResponse> {
-    return await this.requestJson<PreferenceRegistryMutationResponse>(
+    interventionId: string,
+    request: ResolveInteractionInterventionRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<InteractionInterventionMutationResponse> {
+    return await this.requestJson<InteractionInterventionMutationResponse>(
       "POST",
-      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/activate`,
+      `/v1/workspaces/${workspaceId}/interaction-interventions/${encodeURIComponent(interventionId)}/resolve`,
       request,
+      {},
+      options,
     );
   }
 
-  async correctPreferenceRegistry(
+  async listAttachedBrowsers(
     workspaceId: string,
-    preferenceId: string,
-    request: CorrectPreferenceRegistryRequest,
-  ): Promise<PreferenceRegistryMutationResponse> {
-    return await this.requestJson<PreferenceRegistryMutationResponse>(
-      "POST",
-      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/correct`,
-      request,
+    options: AttachedBrowserDeviceListOptions = {},
+  ): Promise<AttachedBrowserDeviceListResponse> {
+    return await this.requestJson<AttachedBrowserDeviceListResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/attached-browsers`,
+      undefined,
+      options.includeDisconnected ? { includeDisconnected: "true" } : {},
+      options,
     );
   }
 
-  async changePreferenceRegistryScope(
+  async getAttachedBrowser(
     workspaceId: string,
-    preferenceId: string,
-    request: ChangePreferenceRegistryScopeRequest,
-  ): Promise<PreferenceRegistryMutationResponse> {
-    return await this.requestJson<PreferenceRegistryMutationResponse>(
-      "POST",
-      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/scope`,
-      request,
+    deviceId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<AttachedBrowserDevice> {
+    return await this.requestJson<AttachedBrowserDevice>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/attached-browsers/${encodeURIComponent(deviceId)}`,
+      undefined,
+      {},
+      options,
     );
   }
 
-  async deactivatePreferenceRegistry(
+  async listBrowserIdentities(
     workspaceId: string,
-    preferenceId: string,
-    request: DeactivatePreferenceRegistryRequest,
-  ): Promise<PreferenceRegistryMutationResponse> {
-    return await this.requestJson<PreferenceRegistryMutationResponse>(
-      "POST",
-      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/deactivate`,
-      request,
+    options: BrowserIdentityListOptions = {},
+  ): Promise<BrowserIdentityListResponse> {
+    return await this.requestJson<BrowserIdentityListResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/browser-identities`,
+      undefined,
+      options.includeArchived ? { includeArchived: "true" } : {},
+      options,
     );
   }
 
-  async supersedePreferenceRegistry(
+  async getBrowserIdentity(
     workspaceId: string,
-    preferenceId: string,
-    request: SupersedePreferenceRegistryRequest,
-  ): Promise<PreferenceRegistryMutationResponse> {
-    return await this.requestJson<PreferenceRegistryMutationResponse>(
+    identityId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserIdentity> {
+    return await this.requestJson<BrowserIdentity>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/browser-identities/${encodeURIComponent(identityId)}`,
+      undefined,
+      {},
+      options,
+    );
+  }
+
+  async createBrowserIdentity(
+    workspaceId: string,
+    request: CreateBrowserIdentityRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserIdentityMutationResponse> {
+    return await this.requestJson<BrowserIdentityMutationResponse>(
       "POST",
-      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/supersede`,
+      `/v1/workspaces/${workspaceId}/browser-identities`,
       request,
+      {},
+      options,
     );
   }
 
-  async rejectPreferenceRegistryProposal(
+  async updateBrowserIdentity(
     workspaceId: string,
-    preferenceId: string,
-    request: RejectPreferenceRegistryProposalRequest,
-  ): Promise<PreferenceRegistryMutationResponse> {
-    return await this.requestJson<PreferenceRegistryMutationResponse>(
-      "POST",
-      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/reject`,
+    identityId: string,
+    request: UpdateBrowserIdentityRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserIdentityMutationResponse> {
+    return await this.requestJson<BrowserIdentityMutationResponse>(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/browser-identities/${encodeURIComponent(identityId)}`,
       request,
+      {},
+      options,
     );
   }
 
-  async getPreferenceRegistrySummary(workspaceId: string): Promise<PreferenceRegistrySnapshot> {
-    return await this.requestJson<PreferenceRegistrySnapshot>(
+  async listBrowserRevisions(
+    workspaceId: string,
+    identityId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserRevisionListResponse> {
+    return await this.requestJson<BrowserRevisionListResponse>(
       "GET",
-      `/v1/workspaces/${workspaceId}/preferences/summary`,
+      `/v1/workspaces/${workspaceId}/browser-identities/${encodeURIComponent(identityId)}/revisions`,
+      undefined,
+      {},
+      options,
     );
   }
 
-  async getPreferenceRegistryFullContent(
+  /** Workspace-wide BrowserSession inventory. Associations express relevance,
+   *  not access: peers and child agents intentionally remain discoverable. */
+  async listBrowserSessions(
     workspaceId: string,
-    retrievalHandle: string,
-  ): Promise<PreferenceRegistryFullContent> {
-    return await this.requestJson<PreferenceRegistryFullContent>(
-      "POST",
-      `/v1/workspaces/${workspaceId}/preferences/full-content`,
-      { retrievalHandle },
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserSessionListResponse> {
+    return await this.requestJson<BrowserSessionListResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/browser-sessions`,
+      undefined,
+      {},
+      options,
     );
   }
 
-  /**
-   * Delete a workspace and everything in it. Refused (409) for the account's
-   * only workspace and while it still has a running session. Irreversible.
-   */
-  async deleteWorkspace(workspaceId: string): Promise<void> {
-    await this.requestVoid("DELETE", `/v1/workspaces/${workspaceId}`);
+  async getBrowserSession(
+    workspaceId: string,
+    browserSessionId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserSession> {
+    return await this.requestJson<BrowserSession>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}`,
+      undefined,
+      {},
+      options,
+    );
   }
 
-  // --- Members ("People with access") -------------------------------------------
+  async readBrowserClipboard(
+    workspaceId: string,
+    browserSessionId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserClipboard> {
+    return await this.requestJson<BrowserClipboard>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/clipboard`,
+      undefined,
+      {},
+      options,
+    );
+  }
 
-  /** The workspace's members (user + api_key subjects). */
-  async listWorkspaceMembers(workspaceId: string): Promise<WorkspaceMember[]> {
-    const response = await this.requestJson<ListWorkspaceMembersResponse>(
+  async listBrowserDownloads(
+    workspaceId: string,
+    browserSessionId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserDownloadListResponse> {
+    return await this.requestJson<BrowserDownloadListResponse>(
       "GET",
-      `/v1/workspaces/${workspaceId}/members`,
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/downloads`,
+      undefined,
+      {},
+      options,
     );
-    return response.members;
   }
 
-  /**
-   * Add an already-registered user by email. 404s when no user with that email
-   * exists (email invites for unknown users are deferred).
-   */
-  async addWorkspaceMember(
+  async getBrowserDownload(
     workspaceId: string,
-    request: AddWorkspaceMemberRequest,
-  ): Promise<WorkspaceMember> {
-    return await this.requestJson<WorkspaceMember>(
-      "POST",
-      `/v1/workspaces/${workspaceId}/members`,
-      request,
+    browserSessionId: string,
+    downloadId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserDownload> {
+    return await this.requestJson<BrowserDownload>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/downloads/${encodeURIComponent(downloadId)}`,
+      undefined,
+      {},
+      options,
     );
   }
 
-  async updateWorkspaceMember(
+  async saveBrowserDownload(
     workspaceId: string,
-    subjectId: string,
-    request: UpdateWorkspaceMemberRequest,
-  ): Promise<WorkspaceMember> {
-    return await this.requestJson<WorkspaceMember>(
-      "PATCH",
-      `/v1/workspaces/${workspaceId}/members/${encodeURIComponent(subjectId)}`,
+    browserSessionId: string,
+    downloadId: string,
+    request: BrowserDownloadSaveRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserDownloadSaveResponse> {
+    return await this.requestJson<BrowserDownloadSaveResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/downloads/${encodeURIComponent(downloadId)}/save`,
       request,
+      {},
+      options,
     );
   }
 
-  /**
-   * Remove a member. Refused (409) for your own membership and for the last
-   * member who can still manage the workspace.
-   */
-  async removeWorkspaceMember(workspaceId: string, subjectId: string): Promise<void> {
-    await this.requestVoid(
-      "DELETE",
-      `/v1/workspaces/${workspaceId}/members/${encodeURIComponent(subjectId)}`,
+  async createBrowserSession(
+    workspaceId: string,
+    request: CreateBrowserSessionRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserSessionMutationResponse> {
+    return await this.requestJson<BrowserSessionMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/browser-sessions`,
+      request,
+      {},
+      options,
     );
   }
 
-  // --- Scheduled tasks (write + runs) -------------------------------------------
+  async listBrowserTargets(
+    workspaceId: string,
+    browserSessionId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserTargetListResponse> {
+    return await this.requestJson<BrowserTargetListResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/targets`,
+      undefined,
+      {},
+      options,
+    );
+  }
 
-  async createScheduledTask(
+  async openBrowserTarget(
     workspaceId: string,
-    request: CreateScheduledTaskRequest,
-  ): Promise<ScheduledTask> {
-    return await this.requestJson<ScheduledTask>(
+    browserSessionId: string,
+    request: BrowserOpenTargetRequest = {},
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserObservation> {
+    return await this.requestJson<BrowserObservation>(
       "POST",
-      `/v1/workspaces/${workspaceId}/scheduled-tasks`,
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/targets`,
       request,
+      {},
+      options,
     );
   }
 
-  async updateScheduledTask(
+  async selectBrowserTarget(
     workspaceId: string,
-    taskId: string,
-    request: UpdateScheduledTaskRequest,
-  ): Promise<ScheduledTask> {
-    return await this.requestJson<ScheduledTask>(
-      "PATCH",
-      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}`,
-      request,
+    browserSessionId: string,
+    targetId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserObservation> {
+    return await this.requestJson<BrowserObservation>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/targets/${encodeURIComponent(targetId)}/select`,
+      {},
+      {},
+      options,
     );
   }
 
-  async pauseScheduledTask(workspaceId: string, taskId: string): Promise<ScheduledTask> {
-    return await this.requestJson<ScheduledTask>(
-      "POST",
-      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}/pause`,
+  async closeBrowserTarget(
+    workspaceId: string,
+    browserSessionId: string,
+    targetId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserTargetListResponse> {
+    return await this.requestJson<BrowserTargetListResponse>(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/targets/${encodeURIComponent(targetId)}`,
+      undefined,
+      {},
+      options,
     );
   }
 
-  async resumeScheduledTask(workspaceId: string, taskId: string): Promise<ScheduledTask> {
-    return await this.requestJson<ScheduledTask>(
-      "POST",
-      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}/resume`,
+  async observeBrowserTarget(
+    workspaceId: string,
+    browserSessionId: string,
+    targetId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserObservation> {
+    return await this.requestJson<BrowserObservation>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/targets/${encodeURIComponent(targetId)}/observation`,
+      undefined,
+      {},
+      options,
     );
   }
 
-  /**
-   * Fire the task immediately (manual trigger), independent of its schedule.
-   * Pass a stable `triggerId` to make a retried trigger idempotent — the same
-   * token charges once and starts one run. Omit it and each call is distinct.
-   */
-  async triggerScheduledTask(
+  async actInBrowser(
     workspaceId: string,
-    taskId: string,
-    options: { triggerId?: string } = {},
-  ): Promise<ScheduledTask> {
-    return await this.requestJson<ScheduledTask>(
+    browserSessionId: string,
+    request: BrowserActionRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserActionReceipt> {
+    return await this.requestJson<BrowserActionReceipt>(
       "POST",
-      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}/trigger`,
-      options.triggerId ? { triggerId: options.triggerId } : undefined,
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/actions`,
+      request,
+      {},
+      options,
     );
   }
 
-  async deleteScheduledTask(workspaceId: string, taskId: string): Promise<void> {
-    await this.requestJson<unknown>(
-      "DELETE",
-      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}`,
+  async getBrowserActionReceipt(
+    workspaceId: string,
+    browserSessionId: string,
+    operationId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserActionReceipt> {
+    return await this.requestJson<BrowserActionReceipt>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/operations/${encodeURIComponent(operationId)}`,
+      undefined,
+      {},
+      options,
     );
   }
 
-  async listScheduledTaskRuns(
+  async listBrowserDiagnostics(
     workspaceId: string,
-    taskId: string,
-    options: { limit?: number } = {},
-  ): Promise<ScheduledTaskRun[]> {
-    return await this.requestJson<ScheduledTaskRun[]>(
+    browserSessionId: string,
+    targetId: string,
+    options: BrowserDiagnosticsOptions = {},
+  ): Promise<BrowserDiagnosticBatch> {
+    return await this.requestJson<BrowserDiagnosticBatch>(
       "GET",
-      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}/runs`,
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/targets/${encodeURIComponent(targetId)}/diagnostics`,
       undefined,
       {
+        ...(options.kinds?.length ? { kinds: options.kinds.join(",") } : {}),
+        ...(options.after !== undefined ? { after: String(options.after) } : {}),
         ...(options.limit !== undefined ? { limit: String(options.limit) } : {}),
       },
+      options.signal ? { signal: options.signal } : {},
     );
   }
 
-  // --- VariableSets --------------------------------------------------------------
-  // Generic reads return name/version metadata only. Plaintext uses one
-  // dedicated permissioned endpoint.
-
-  async listVariableSets(workspaceId: string): Promise<VariableSet[]> {
-    return await this.requestJson<VariableSet[]>(
-      "GET",
-      `/v1/workspaces/${workspaceId}/variable-sets`,
-    );
-  }
-
-  async createVariableSet(
+  async attachBrowserSession(
     workspaceId: string,
-    request: CreateVariableSetRequest,
-  ): Promise<VariableSet> {
-    return await this.requestJson<VariableSet>(
+    browserSessionId: string,
+    request: BrowserSessionAttachmentRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserSessionAttachment> {
+    return await this.requestJson<BrowserSessionAttachment>(
       "POST",
-      `/v1/workspaces/${workspaceId}/variable-sets`,
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/attachments`,
       request,
+      {},
+      options,
     );
   }
 
-  async getVariableSet(workspaceId: string, variableSetId: string): Promise<VariableSet> {
-    return await this.requestJson<VariableSet>(
-      "GET",
-      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}`,
+  async heartbeatBrowserSession(
+    workspaceId: string,
+    browserSessionId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserSessionHeartbeatResponse> {
+    return await this.requestJson<BrowserSessionHeartbeatResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/heartbeat`,
+      {},
+      {},
+      options,
     );
   }
 
-  async getVariableSetVariable(
+  async publishBrowserRevision(
     workspaceId: string,
-    variableSetId: string,
-    name: string,
-  ): Promise<VariableSetSecret> {
-    return await this.requestJson<VariableSetSecret>(
-      "GET",
-      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}/variables/${encodeURIComponent(name)}`,
+    browserSessionId: string,
+    request: PublishBrowserRevisionRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<PublishBrowserRevisionResponse> {
+    return await this.requestJson<PublishBrowserRevisionResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/revisions`,
+      request,
+      {},
+      options,
     );
   }
 
-  async updateVariableSet(
+  async suspendBrowserSession(
     workspaceId: string,
-    variableSetId: string,
-    request: UpdateVariableSetRequest,
-  ): Promise<VariableSet> {
-    return await this.requestJson<VariableSet>(
-      "PATCH",
-      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}`,
+    browserSessionId: string,
+    request: BrowserSessionLifecycleRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserSessionMutationResponse> {
+    return await this.requestJson<BrowserSessionMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/suspend`,
       request,
+      {},
+      options,
     );
   }
 
-  async deleteVariableSet(workspaceId: string, variableSetId: string): Promise<void> {
-    await this.requestJson<unknown>(
-      "DELETE",
-      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}`,
+  async resumeBrowserSession(
+    workspaceId: string,
+    browserSessionId: string,
+    request: BrowserSessionLifecycleRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserSessionMutationResponse> {
+    return await this.requestJson<BrowserSessionMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/resume`,
+      request,
+      {},
+      options,
     );
   }
 
-  /** Create or rotate a variable. Generic reads never return its value. */
-  async setVariableSetVariable(
+  async endBrowserSession(
     workspaceId: string,
-    variableSetId: string,
-    name: string,
-    value: string,
-  ): Promise<VariableSetVariableMetadata> {
-    return await this.requestJson<VariableSetVariableMetadata>(
-      "PUT",
-      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}/variables/${encodeURIComponent(name)}`,
-      { value },
+    browserSessionId: string,
+    request: BrowserSessionLifecycleRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserSessionMutationResponse> {
+    return await this.requestJson<BrowserSessionMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/browser-sessions/${encodeURIComponent(browserSessionId)}/end`,
+      request,
+      {},
+      options,
     );
   }
 
-  async deleteVariableSetVariable(
+  /** Workspace-wide ComputerSession inventory. Associations express
+   * relevance, not access; peer sessions intentionally remain discoverable. */
+  async listComputerSessions(
     workspaceId: string,
-    variableSetId: string,
-    name: string,
-  ): Promise<void> {
-    await this.requestJson<unknown>(
-      "DELETE",
-      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}/variables/${encodeURIComponent(name)}`,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<ComputerSessionListResponse> {
+    return await this.requestJson<ComputerSessionListResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/computer-sessions`,
+      undefined,
+      {},
+      options,
     );
   }
 
-  // --- Rigs ------------------------------------------------------------------
-  // Workspace-scoped, versioned sandbox machine definitions. rigs:use gates read
-  // + proposeRigChange; rigs:manage gates create / update / delete / activate.
-
-  async listRigs(workspaceId: string): Promise<Rig[]> {
-    return await this.requestJson<Rig[]>("GET", `/v1/workspaces/${workspaceId}/rigs`);
-  }
-
-  async createRig(workspaceId: string, request: CreateRigRequest): Promise<Rig> {
-    return await this.requestJson<Rig>("POST", `/v1/workspaces/${workspaceId}/rigs`, request);
+  async getComputerSession(
+    workspaceId: string,
+    computerSessionId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<ComputerSession> {
+    return await this.requestJson<ComputerSession>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/computer-sessions/${encodeURIComponent(computerSessionId)}`,
+      undefined,
+      {},
+      options,
+    );
   }
 
-  async getRig(workspaceId: string, rigId: string): Promise<Rig> {
-    return await this.requestJson<Rig>("GET", `/v1/workspaces/${workspaceId}/rigs/${rigId}`);
+  async readComputerClipboard(
+    workspaceId: string,
+    computerSessionId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<ComputerClipboard> {
+    return await this.requestJson<ComputerClipboard>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/computer-sessions/${encodeURIComponent(computerSessionId)}/clipboard`,
+      undefined,
+      {},
+      options,
+    );
   }
 
-  async updateRig(workspaceId: string, rigId: string, request: UpdateRigRequest): Promise<Rig> {
-    return await this.requestJson<Rig>(
-      "PATCH",
-      `/v1/workspaces/${workspaceId}/rigs/${rigId}`,
+  async createComputerSession(
+    workspaceId: string,
+    request: CreateComputerSessionRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<ComputerSessionMutationResponse> {
+    return await this.requestJson<ComputerSessionMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/computer-sessions`,
       request,
+      {},
+      options,
     );
   }
 
-  async deleteRig(workspaceId: string, rigId: string): Promise<void> {
-    await this.requestJson<unknown>("DELETE", `/v1/workspaces/${workspaceId}/rigs/${rigId}`);
+  async listComputerTargets(
+    workspaceId: string,
+    computerSessionId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<ComputerTargetListResponse> {
+    return await this.requestJson<ComputerTargetListResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/computer-sessions/${encodeURIComponent(computerSessionId)}/targets`,
+      undefined,
+      {},
+      options,
+    );
   }
 
-  async listRigVersions(workspaceId: string, rigId: string): Promise<RigVersion[]> {
-    return await this.requestJson<RigVersion[]>(
+  async observeComputerTarget(
+    workspaceId: string,
+    computerSessionId: string,
+    targetId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<ComputerObservation> {
+    return await this.requestJson<ComputerObservation>(
       "GET",
-      `/v1/workspaces/${workspaceId}/rigs/${rigId}/versions`,
+      `/v1/workspaces/${workspaceId}/computer-sessions/${encodeURIComponent(computerSessionId)}/targets/${encodeURIComponent(targetId)}/observation`,
+      undefined,
+      {},
+      options,
     );
   }
 
-  /** Roll the active version to an existing one (rollback / promote-activate). */
-  async activateRigVersion(
+  async actInComputer(
     workspaceId: string,
-    rigId: string,
-    versionId: string,
-  ): Promise<RigVersion> {
-    return await this.requestJson<RigVersion>(
+    computerSessionId: string,
+    request: ComputerActionRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<ComputerActionReceipt> {
+    return await this.requestJson<ComputerActionReceipt>(
       "POST",
-      `/v1/workspaces/${workspaceId}/rigs/${rigId}/versions/${versionId}/activate`,
+      `/v1/workspaces/${workspaceId}/computer-sessions/${encodeURIComponent(computerSessionId)}/actions`,
+      request,
+      {},
+      options,
     );
   }
 
-  async listRigChanges(workspaceId: string, rigId: string): Promise<RigChange[]> {
-    return await this.requestJson<RigChange[]>(
+  async getComputerActionReceipt(
+    workspaceId: string,
+    computerSessionId: string,
+    operationId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<ComputerActionReceipt> {
+    return await this.requestJson<ComputerActionReceipt>(
       "GET",
-      `/v1/workspaces/${workspaceId}/rigs/${rigId}/changes`,
+      `/v1/workspaces/${workspaceId}/computer-sessions/${encodeURIComponent(computerSessionId)}/operations/${encodeURIComponent(operationId)}`,
+      undefined,
+      {},
+      options,
     );
   }
 
-  /** Propose a change against the rig's active version (rigs:use). */
-  async proposeRigChange(
+  async attachComputerSession(
     workspaceId: string,
-    rigId: string,
-    request: ProposeRigChangeRequest,
-  ): Promise<RigChange> {
-    return await this.requestJson<RigChange>(
+    computerSessionId: string,
+    request: ComputerSessionAttachmentRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<ComputerSessionAttachment> {
+    return await this.requestJson<ComputerSessionAttachment>(
       "POST",
-      `/v1/workspaces/${workspaceId}/rigs/${rigId}/changes`,
+      `/v1/workspaces/${workspaceId}/computer-sessions/${encodeURIComponent(computerSessionId)}/attachments`,
       request,
+      {},
+      options,
     );
   }
 
-  async getRigChange(workspaceId: string, rigId: string, changeId: string): Promise<RigChange> {
-    return await this.requestJson<RigChange>(
-      "GET",
-      `/v1/workspaces/${workspaceId}/rigs/${rigId}/changes/${changeId}`,
+  async heartbeatComputerSession(
+    workspaceId: string,
+    computerSessionId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<ComputerSessionHeartbeatResponse> {
+    return await this.requestJson<ComputerSessionHeartbeatResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/computer-sessions/${encodeURIComponent(computerSessionId)}/heartbeat`,
+      {},
+      {},
+      options,
     );
   }
 
-  /**
-   * Re-run verification for a change (rigs:use). Verification is asynchronous:
-   * this returns the change immediately with status `verifying`; poll
-   * `getRigChange`/`listRigChanges` for the terminal outcome + logs.
-   */
-  async verifyRigChange(workspaceId: string, rigId: string, changeId: string): Promise<RigChange> {
-    return await this.requestJson<RigChange>(
+  async endComputerSession(
+    workspaceId: string,
+    computerSessionId: string,
+    request: ComputerSessionLifecycleRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<ComputerSessionMutationResponse> {
+    return await this.requestJson<ComputerSessionMutationResponse>(
       "POST",
-      `/v1/workspaces/${workspaceId}/rigs/${rigId}/changes/${changeId}/verify`,
+      `/v1/workspaces/${workspaceId}/computer-sessions/${encodeURIComponent(computerSessionId)}/end`,
+      request,
+      {},
+      options,
     );
   }
 
+  // --- Access + workspaces -----------------------------------------------------
+
   /**
-   * Promote a verified `definition_edit` change into a new active rig version
-   * (rigs:manage). Only valid once the change's verification passed; returns the
-   * newly minted version.
+   * The deployment's public client bootstrap config: the host-exposed models
+   * (provider-grouped in `models`, flat in `allowedModels` for back-compat),
+   * reasoning efforts, MCP servers, file-upload limits, and how the client is
+   * expected to authenticate. Drives a composer's model picker without prior
+   * knowledge of the host setup; safe to call before any auth is established.
    */
-  async promoteRigChange(
+  async getClientConfig(): Promise<ClientConfig> {
+    const config = await this.requestJson<ClientConfig>("GET", "/v1/config/client");
+    if (config.apiContractRevision !== OPENGENI_API_CONTRACT_REVISION) {
+      throw new OpenGeniApiContractMismatchError(
+        OPENGENI_API_CONTRACT_REVISION,
+        String(config.apiContractRevision || "(missing)"),
+      );
+    }
+    return config;
+  }
+
+  /** Authenticated model definitions plus workspace-specific selectability. */
+  async getWorkspaceModelCatalog(workspaceId: string): Promise<WorkspaceModelCatalogResponse> {
+    return await this.requestJson<WorkspaceModelCatalogResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/model-catalog`,
+    );
+  }
+
+  /** Authenticated realtime voice models and credential readiness. */
+  async getWorkspaceRealtimeModelCatalog(
     workspaceId: string,
-    rigId: string,
-    changeId: string,
-  ): Promise<RigVersion> {
-    return await this.requestJson<RigVersion>(
-      "POST",
-      `/v1/workspaces/${workspaceId}/rigs/${rigId}/changes/${changeId}/promote`,
+  ): Promise<WorkspaceRealtimeModelCatalogResponse> {
+    return await this.requestJson<WorkspaceRealtimeModelCatalogResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/realtime-model-catalog`,
     );
   }
 
-  /**
-   * Re-run the active version's checks in a clean throwaway sandbox (rigs:use).
-   * Asynchronous — returns the version id being verified; the outcome lands on
-   * the version's audit trail.
-   */
-  async verifyRig(workspaceId: string, rigId: string): Promise<{ ok: boolean; versionId: string }> {
-    return await this.requestJson<{ ok: boolean; versionId: string }>(
-      "POST",
-      `/v1/workspaces/${workspaceId}/rigs/${rigId}/verify`,
+  /** The caller's access context: subject, account + workspace grants, defaults. */
+  async getAccessContext(): Promise<AccessContext> {
+    return await this.requestJson<AccessContext>("GET", "/v1/access/me");
+  }
+
+  /** Active organization memberships proven by the current managed-human session. */
+  async listOrganizationMemberships(): Promise<ListManagedOrganizationMembershipsResponse> {
+    return await this.requestJson<ListManagedOrganizationMembershipsResponse>(
+      "GET",
+      "/v1/organization-memberships",
     );
   }
 
-  /** @deprecated use listVariableSets */
-  async listEnvironments(workspaceId: string): Promise<VariableSet[]> {
-    return await this.listVariableSets(workspaceId);
+  async listWorkspaces(): Promise<Workspace[]> {
+    return await this.requestJson<Workspace[]>("GET", "/v1/workspaces");
   }
 
-  /** @deprecated use createVariableSet */
-  async createEnvironment(
-    workspaceId: string,
-    request: CreateVariableSetRequest,
-  ): Promise<VariableSet> {
-    return await this.createVariableSet(workspaceId, request);
+  async createWorkspace(request: CreateWorkspaceRequest): Promise<Workspace> {
+    return await this.requestJson<Workspace>("POST", "/v1/workspaces", request);
   }
 
-  /** @deprecated use getVariableSet */
-  async getEnvironment(workspaceId: string, environmentId: string): Promise<VariableSet> {
-    return await this.getVariableSet(workspaceId, environmentId);
+  async getWorkspace(workspaceId: string): Promise<Workspace> {
+    return await this.requestJson<Workspace>("GET", `/v1/workspaces/${workspaceId}`);
   }
 
-  /** @deprecated use updateVariableSet */
-  async updateEnvironment(
+  /** Read-time, secret-safe inventory of policy heads and visible workspace knowledge. */
+  async getWorkspaceState(
     workspaceId: string,
-    environmentId: string,
-    request: UpdateVariableSetRequest,
-  ): Promise<VariableSet> {
-    return await this.updateVariableSet(workspaceId, environmentId, request);
+    options: WorkspaceStateGetOptions = {},
+  ): Promise<WorkspaceStateResponse> {
+    const params = new URLSearchParams();
+    if (options.attemptId) params.set("attemptId", options.attemptId);
+    const query = params.size > 0 ? `?${params.toString()}` : "";
+    return await this.requestJson<WorkspaceStateResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/workspace-state${query}`,
+    );
   }
 
-  /** @deprecated use deleteVariableSet */
-  async deleteEnvironment(workspaceId: string, environmentId: string): Promise<void> {
-    await this.deleteVariableSet(workspaceId, environmentId);
+  /** Download the canonical, explicitly sanitized Workspace State export. */
+  async exportWorkspaceState(
+    workspaceId: string,
+    options: WorkspaceStateGetOptions = {},
+  ): Promise<WorkspaceStateExportResponse> {
+    const params = new URLSearchParams();
+    if (options.attemptId) params.set("attemptId", options.attemptId);
+    const query = params.size > 0 ? `?${params.toString()}` : "";
+    return await this.requestJson<WorkspaceStateExportResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/workspace-state/export${query}`,
+    );
   }
 
-  /** @deprecated use setVariableSetVariable */
-  async setEnvironmentVariable(
+  async updateWorkspace(workspaceId: string, request: UpdateWorkspaceRequest): Promise<Workspace> {
+    return await this.requestJson<Workspace>("PATCH", `/v1/workspaces/${workspaceId}`, request);
+  }
+
+  /** Inspect immutable instruction-policy history, active heads, and activation audit evidence. */
+  async listWorkspaceInstructionPolicies(
     workspaceId: string,
-    environmentId: string,
-    name: string,
-    value: string,
-  ): Promise<VariableSetVariableMetadata> {
-    return await this.setVariableSetVariable(workspaceId, environmentId, name, value);
+    options: WorkspaceInstructionPolicyListOptions = {},
+  ): Promise<WorkspaceInstructionPolicyListResponse> {
+    const params = new URLSearchParams();
+    if (options.kind !== undefined) params.set("kind", options.kind);
+    if (options.scope !== undefined) params.set("scope", options.scope);
+    if (options.roleKey !== undefined) params.set("roleKey", options.roleKey);
+    if (options.afterRevision !== undefined) {
+      params.set("afterRevision", String(options.afterRevision));
+    }
+    if (options.limit !== undefined) params.set("limit", String(options.limit));
+    const query = params.toString();
+    return await this.requestJson<WorkspaceInstructionPolicyListResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/instruction-policies${query ? `?${query}` : ""}`,
+    );
   }
 
-  /** @deprecated use deleteVariableSetVariable */
-  async deleteEnvironmentVariable(
+  async getWorkspaceInstructionPolicyRevision(
     workspaceId: string,
-    environmentId: string,
-    name: string,
-  ): Promise<void> {
-    await this.deleteVariableSetVariable(workspaceId, environmentId, name);
+    revisionId: string,
+  ): Promise<WorkspaceInstructionPolicyRevision> {
+    return await this.requestJson<WorkspaceInstructionPolicyRevision>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/instruction-policies/${encodeURIComponent(revisionId)}`,
+    );
   }
 
-  // --- Files -----------------------------------------------------------------------
+  async createWorkspaceInstructionPolicyDraft(
+    workspaceId: string,
+    request: CreateWorkspaceInstructionPolicyDraftRequest,
+  ): Promise<WorkspaceInstructionPolicyRevision> {
+    return await this.requestJson<WorkspaceInstructionPolicyRevision>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/instruction-policies/drafts`,
+      request,
+    );
+  }
 
-  /** Step 1 of the upload flow: returns the pre-signed PUT target. */
-  async beginFileUpload(
+  /** List the newest immutable onboarding proposals and their inactive policy drafts. */
+  async listWorkspaceInstructionPolicyOnboardingProposals(
     workspaceId: string,
-    request: CreateFileUploadRequest,
-    options: OpenGeniRequestOptions = {},
-  ): Promise<CreateFileUploadResponse> {
-    return await this.requestJson<CreateFileUploadResponse>(
+    options: WorkspaceInstructionPolicyOnboardingProposalListOptions = {},
+  ): Promise<WorkspaceInstructionPolicyOnboardingProposalListResponse> {
+    const params = new URLSearchParams();
+    if (options.limit !== undefined) params.set("limit", String(options.limit));
+    const query = params.toString();
+    return await this.requestJson<WorkspaceInstructionPolicyOnboardingProposalListResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/instruction-policies/onboarding-proposals${query ? `?${query}` : ""}`,
+    );
+  }
+
+  /** Create one draft-only proposal against an exact active-policy baseline. */
+  async createWorkspaceInstructionPolicyOnboardingProposal(
+    workspaceId: string,
+    request: CreateWorkspaceInstructionPolicyOnboardingProposalRequest,
+  ): Promise<WorkspaceInstructionPolicyOnboardingProposal> {
+    return await this.requestJson<WorkspaceInstructionPolicyOnboardingProposal>(
       "POST",
-      `/v1/workspaces/${workspaceId}/files/uploads`,
+      `/v1/workspaces/${workspaceId}/instruction-policies/onboarding-proposals`,
       request,
-      {},
-      options,
     );
   }
 
-  /** Step 3 of the upload flow: server verifies the object and marks it ready. */
-  async completeFileUpload(
+  /** Import the stored legacy workspace override as an inactive charter draft. */
+  async importLegacyWorkspaceInstructionPolicyDraft(
     workspaceId: string,
-    uploadId: string,
-    options: OpenGeniRequestOptions = {},
-  ): Promise<FileAsset> {
-    const response = await this.requestJson<CompleteFileUploadResponse>(
+    request: ImportLegacyWorkspaceInstructionPolicyDraftRequest = {},
+  ): Promise<WorkspaceInstructionPolicyRevision> {
+    return await this.requestJson<WorkspaceInstructionPolicyRevision>(
       "POST",
-      `/v1/workspaces/${workspaceId}/files/uploads/${uploadId}/complete`,
-      undefined,
-      {},
-      options,
+      `/v1/workspaces/${workspaceId}/instruction-policies/import-legacy`,
+      request,
     );
-    return response.file;
   }
 
-  /**
-   * The whole upload flow as one call: begin -> PUT the bytes to the signed
-   * URL (with its required headers; no API auth is sent to object storage)
-   * -> complete. Returns the ready `FileAsset`.
-   */
-  async uploadFile(workspaceId: string, input: UploadFileInput): Promise<FileAsset> {
-    if (
-      input.timeoutMs !== undefined &&
-      (!Number.isFinite(input.timeoutMs) || input.timeoutMs <= 0)
-    ) {
-      throw new Error("File upload timeout must be a positive number");
-    }
-    const withTimeout = async <T>(
-      timeoutMs: number,
-      operation: (signal: AbortSignal) => Promise<T>,
-    ): Promise<T> => {
-      const controller = new AbortController();
-      let timeout: ReturnType<typeof setTimeout> | undefined;
-      const timedOut = new Promise<never>((_resolve, reject) => {
-        timeout = setTimeout(() => {
-          controller.abort();
-          reject(new Error("File upload timed out. Retry the upload."));
-        }, timeoutMs);
-      });
-      try {
-        return await Promise.race([operation(controller.signal), timedOut]);
-      } finally {
-        if (timeout !== undefined) clearTimeout(timeout);
-      }
-    };
-    // Snapshot mutable inputs before hashing so the digest always describes the
-    // exact bytes later sent to object storage. Copy Uint8Array views into a
-    // Blob so byte offsets/shared buffers can't leak surrounding bytes.
-    const body: Blob | ArrayBuffer | string =
-      input.data instanceof Uint8Array
-        ? new Blob([input.data.slice()])
-        : input.data instanceof ArrayBuffer
-          ? input.data.slice(0)
-          : input.data;
-    const sizeBytes =
-      typeof body === "string"
-        ? new TextEncoder().encode(body).byteLength
-        : body instanceof Blob
-          ? body.size
-          : body.byteLength;
-    const sha256 = input.sha256 ?? (await sha256ForUpload(body));
-    const upload = await withTimeout(
-      30_000,
-      async (signal) =>
-        await this.beginFileUpload(
-          workspaceId,
-          {
-            filename: input.filename,
-            contentType: input.contentType,
-            sizeBytes,
-            sha256,
-          },
-          { signal },
-        ),
+  async diffWorkspaceInstructionPolicyRevisions(
+    workspaceId: string,
+    request: WorkspaceInstructionPolicyDiffRequest,
+  ): Promise<WorkspaceInstructionPolicyDiffResponse> {
+    const params = new URLSearchParams({
+      fromRevisionId: request.fromRevisionId,
+      toRevisionId: request.toRevisionId,
+    });
+    return await this.requestJson<WorkspaceInstructionPolicyDiffResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/instruction-policies/diff?${params}`,
     );
-    // Give large valid uploads enough time at a conservative 256 KiB/s while
-    // still bounding an object-storage request that never settles.
-    const transferTimeoutMs =
-      input.timeoutMs ?? Math.max(120_000, Math.ceil(sizeBytes / (256 * 1024)) * 1_000);
-    const putResponse = await withTimeout(
-      transferTimeoutMs,
-      async (signal) =>
-        await this.fetchImpl(upload.putUrl, {
-          method: "PUT",
-          // Signed object-storage URLs carry their own short-lived authority.
-          // Browser cookies and HTTP auth must never accompany this cross-origin
-          // request: credentialed fetches are incompatible with wildcard CORS and
-          // can leak ambient credentials to a caller-selected storage endpoint.
-          credentials: "omit",
-          // The backend's requiredHeaders already carry the canonical lowercase
-          // `content-type` for every storage backend (Azure/S3/GCS). Do NOT also set
-          // a `Content-Type` key here: WHATWG Headers treats the two casings as the
-          // same header and comma-joins their values (e.g. "text/plain, text/plain"),
-          // which the object store persists verbatim and COMPLETE then rejects (422),
-          // and which breaks S3's presigned-URL signature.
-          headers: { ...upload.requiredHeaders },
-          body,
-          signal,
-        }),
+  }
+
+  async activateWorkspaceInstructionPolicyRevision(
+    workspaceId: string,
+    revisionId: string,
+    request: ActivateWorkspaceInstructionPolicyRequest,
+  ): Promise<WorkspaceInstructionPolicyActivationResponse> {
+    return await this.requestJson<WorkspaceInstructionPolicyActivationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/instruction-policies/${encodeURIComponent(revisionId)}/activate`,
+      request,
     );
-    if (!putResponse.ok) {
-      throw await apiErrorFromResponse(putResponse, { method: "PUT" });
-    }
-    return await withTimeout(
-      30_000,
-      async (signal) => await this.completeFileUpload(workspaceId, upload.uploadId, { signal }),
+  }
+
+  async rollbackWorkspaceInstructionPolicyRevision(
+    workspaceId: string,
+    request: RollbackWorkspaceInstructionPolicyRequest,
+  ): Promise<WorkspaceInstructionPolicyActivationResponse> {
+    return await this.requestJson<WorkspaceInstructionPolicyActivationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/instruction-policies/rollback`,
+      request,
     );
   }
 
-  async getFile(workspaceId: string, fileId: string): Promise<FileAsset> {
-    return await this.requestJson<FileAsset>(
+  /** Read the current organization profile plus immutable revision and activation history. */
+  async listCompanyProfile(
+    workspaceId: string,
+    options: CompanyProfileListOptions = {},
+  ): Promise<CompanyProfileListResponse> {
+    const params = new URLSearchParams();
+    if (options.afterRevision !== undefined)
+      params.set("afterRevision", String(options.afterRevision));
+    if (options.limit !== undefined) params.set("limit", String(options.limit));
+    const query = params.toString();
+    return await this.requestJson<CompanyProfileListResponse>(
       "GET",
-      `/v1/workspaces/${workspaceId}/files/${fileId}`,
+      `/v1/workspaces/${workspaceId}/company-profile${query ? `?${query}` : ""}`,
     );
   }
 
-  /** Read provider-neutral retained evidence metadata; never returns a storage location. */
-  async getRetainedArtifact(
+  async getCompanyProfileRevision(
     workspaceId: string,
-    artifactId: string,
-  ): Promise<RetainedArtifactMetadata> {
-    return await this.requestJson<RetainedArtifactMetadata>(
+    revisionId: string,
+  ): Promise<CompanyProfileRevision> {
+    return await this.requestJson<CompanyProfileRevision>(
       "GET",
-      `/v1/workspaces/${workspaceId}/artifacts/${artifactId}`,
+      `/v1/workspaces/${workspaceId}/company-profile/revisions/${encodeURIComponent(revisionId)}`,
     );
   }
 
-  /**
-   * Read at most one authenticated retained-evidence range from the API. This
-   * deliberately does not use the ordinary signed file-download URL.
-   */
-  async getRetainedArtifactContent(
+  async updateCompanyProfile(
     workspaceId: string,
-    artifactId: string,
-    options: RetainedArtifactContentOptions = {},
-  ): Promise<RetainedArtifactContent> {
-    return await this.getRetainedArtifactContentAtPath(
-      `/v1/workspaces/${workspaceId}/artifacts/${artifactId}/content`,
-      options,
+    request: UpdateCompanyProfileRequest,
+  ): Promise<CompanyProfileMutationResponse> {
+    return await this.requestJson<CompanyProfileMutationResponse>(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/company-profile`,
+      request,
     );
   }
 
-  async getSessionRetainedArtifact(
+  async diffCompanyProfileRevisions(
     workspaceId: string,
-    sessionId: string,
-    artifactId: string,
-  ): Promise<RetainedArtifactMetadata> {
-    return await this.requestJson<RetainedArtifactMetadata>(
+    request: CompanyProfileDiffRequest,
+  ): Promise<CompanyProfileDiffResponse> {
+    const params = new URLSearchParams(request);
+    return await this.requestJson<CompanyProfileDiffResponse>(
       "GET",
-      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/artifacts/${artifactId}`,
+      `/v1/workspaces/${workspaceId}/company-profile/diff?${params}`,
     );
   }
 
-  async getSessionRetainedArtifactContent(
+  async activateCompanyProfileRevision(
     workspaceId: string,
-    sessionId: string,
-    artifactId: string,
-    options: RetainedArtifactContentOptions = {},
-  ): Promise<RetainedArtifactContent> {
-    return await this.getRetainedArtifactContentAtPath(
-      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/artifacts/${artifactId}/content`,
-      options,
+    revisionId: string,
+    request: ActivateCompanyProfileRevisionRequest,
+  ): Promise<CompanyProfileMutationResponse> {
+    return await this.requestJson<CompanyProfileMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/company-profile/revisions/${encodeURIComponent(revisionId)}/activate`,
+      request,
     );
   }
 
-  /** Assemble one retained screenshot from bounded authenticated API ranges. */
-  async downloadRetainedScreenshot(
+  async rollbackCompanyProfile(
     workspaceId: string,
-    sessionId: string,
-    artifactId: string,
-    options: RetainedScreenshotDownloadOptions = {},
-  ): Promise<RetainedScreenshotDownload> {
-    const maxRetries = options.maxRetries ?? 2;
-    if (!Number.isInteger(maxRetries) || maxRetries < 0 || maxRetries > 3) {
-      throw new RangeError("retained screenshot maxRetries must be an integer from 0 to 3");
-    }
-    const metadata = await this.getSessionRetainedArtifact(workspaceId, sessionId, artifactId);
-    if (!metadata.available) return { metadata, bytes: null };
-    if (
-      metadata.kind !== "computer_screenshot" ||
-      metadata.contentType !== "image/png" ||
-      !metadata.dimensions ||
-      metadata.originalBytes <= 0 ||
-      metadata.originalBytes > COMPUTER_SCREENSHOT_MAX_BYTES
-    ) {
-      throw new OpenGeniApiError(502, "retained screenshot metadata is invalid");
-    }
-    const bytes = new Uint8Array(metadata.originalBytes);
-    const pageBytes = Math.min(metadata.retrieval.maxRangeBytes, RETAINED_OUTPUT_MAX_PAGE_BYTES);
-    if (!Number.isSafeInteger(pageBytes) || pageBytes <= 0) {
-      throw new OpenGeniApiError(502, "retained screenshot range metadata is invalid");
-    }
-    for (let start = 0; start < bytes.byteLength; start += pageBytes) {
-      options.signal?.throwIfAborted();
-      const end = Math.min(start + pageBytes, bytes.byteLength) - 1;
-      let page: RetainedArtifactContent | null = null;
-      for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
-        try {
-          page = await this.getSessionRetainedArtifactContent(workspaceId, sessionId, artifactId, {
-            range: `bytes=${start}-${end}`,
-            ...(options.signal ? { signal: options.signal } : {}),
-          });
-          break;
-        } catch (error) {
-          options.signal?.throwIfAborted();
-          if (
-            attempt >= maxRetries ||
-            (error instanceof OpenGeniApiError && error.status >= 400 && error.status < 500)
-          ) {
-            throw error;
-          }
-        }
-      }
-      if (!page) throw new OpenGeniApiError(502, "retained screenshot range retry exhausted");
-      const expectedLength = end - start + 1;
-      if (
-        page.status !== 206 ||
-        page.contentType !== metadata.contentType ||
-        page.contentLength !== expectedLength ||
-        page.contentRange !== `bytes ${start}-${end}/${metadata.originalBytes}`
-      ) {
-        throw new OpenGeniApiError(502, "retained screenshot range response is invalid");
-      }
-      bytes.set(page.bytes, start);
-    }
-    if ((await sha256Hex(bytes)) !== metadata.sha256) {
-      throw new OpenGeniApiError(502, "retained screenshot checksum mismatch");
-    }
-    return { metadata, bytes };
+    request: RollbackCompanyProfileRequest,
+  ): Promise<CompanyProfileMutationResponse> {
+    return await this.requestJson<CompanyProfileMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/company-profile/rollback`,
+      request,
+    );
+  }
+
+  async listPreferenceRegistry(
+    workspaceId: string,
+    options: PreferenceRegistryListOptions = {},
+  ): Promise<PreferenceRegistryListResponse> {
+    const params = new URLSearchParams();
+    if (options.scope) params.set("scope", options.scope);
+    if (options.status) params.set("status", options.status);
+    if (options.limit !== undefined) params.set("limit", String(options.limit));
+    const query = params.toString();
+    return await this.requestJson<PreferenceRegistryListResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/preferences${query ? `?${query}` : ""}`,
+    );
+  }
+
+  async getPreferenceRegistry(
+    workspaceId: string,
+    preferenceId: string,
+  ): Promise<PreferenceRegistryDetailResponse> {
+    return await this.requestJson<PreferenceRegistryDetailResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}`,
+    );
+  }
+
+  async createPreferenceRegistryProposal(
+    workspaceId: string,
+    request: CreatePreferenceRegistryProposalRequest,
+  ): Promise<PreferenceRegistryRecord> {
+    return await this.requestJson<PreferenceRegistryRecord>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/proposals`,
+      request,
+    );
+  }
+
+  async activatePreferenceRegistryRevision(
+    workspaceId: string,
+    preferenceId: string,
+    request: ActivatePreferenceRegistryRevisionRequest,
+  ): Promise<PreferenceRegistryMutationResponse> {
+    return await this.requestJson<PreferenceRegistryMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/activate`,
+      request,
+    );
+  }
+
+  async correctPreferenceRegistry(
+    workspaceId: string,
+    preferenceId: string,
+    request: CorrectPreferenceRegistryRequest,
+  ): Promise<PreferenceRegistryMutationResponse> {
+    return await this.requestJson<PreferenceRegistryMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/correct`,
+      request,
+    );
+  }
+
+  async changePreferenceRegistryScope(
+    workspaceId: string,
+    preferenceId: string,
+    request: ChangePreferenceRegistryScopeRequest,
+  ): Promise<PreferenceRegistryMutationResponse> {
+    return await this.requestJson<PreferenceRegistryMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/scope`,
+      request,
+    );
+  }
+
+  async deactivatePreferenceRegistry(
+    workspaceId: string,
+    preferenceId: string,
+    request: DeactivatePreferenceRegistryRequest,
+  ): Promise<PreferenceRegistryMutationResponse> {
+    return await this.requestJson<PreferenceRegistryMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/deactivate`,
+      request,
+    );
+  }
+
+  async supersedePreferenceRegistry(
+    workspaceId: string,
+    preferenceId: string,
+    request: SupersedePreferenceRegistryRequest,
+  ): Promise<PreferenceRegistryMutationResponse> {
+    return await this.requestJson<PreferenceRegistryMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/supersede`,
+      request,
+    );
+  }
+
+  async rejectPreferenceRegistryProposal(
+    workspaceId: string,
+    preferenceId: string,
+    request: RejectPreferenceRegistryProposalRequest,
+  ): Promise<PreferenceRegistryMutationResponse> {
+    return await this.requestJson<PreferenceRegistryMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/reject`,
+      request,
+    );
+  }
+
+  async getPreferenceRegistrySummary(workspaceId: string): Promise<PreferenceRegistrySnapshot> {
+    return await this.requestJson<PreferenceRegistrySnapshot>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/preferences/summary`,
+    );
+  }
+
+  async getPreferenceRegistryFullContent(
+    workspaceId: string,
+    retrievalHandle: string,
+  ): Promise<PreferenceRegistryFullContent> {
+    return await this.requestJson<PreferenceRegistryFullContent>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/full-content`,
+      { retrievalHandle },
+    );
+  }
+
+  /**
+   * Delete a workspace and everything in it. Refused (409) for the account's
+   * only workspace and while it still has a running session. Irreversible.
+   */
+  async deleteWorkspace(workspaceId: string): Promise<void> {
+    await this.requestVoid("DELETE", `/v1/workspaces/${workspaceId}`);
+  }
+
+  // --- Members ("People with access") -------------------------------------------
+
+  /** The workspace's members (user + api_key subjects). */
+  async listWorkspaceMembers(workspaceId: string): Promise<WorkspaceMember[]> {
+    const response = await this.requestJson<ListWorkspaceMembersResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/members`,
+    );
+    return response.members;
+  }
+
+  /**
+   * Add an already-registered user by email. 404s when no user with that email
+   * exists (email invites for unknown users are deferred).
+   */
+  async addWorkspaceMember(
+    workspaceId: string,
+    request: AddWorkspaceMemberRequest,
+  ): Promise<WorkspaceMember> {
+    return await this.requestJson<WorkspaceMember>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/members`,
+      request,
+    );
+  }
+
+  async updateWorkspaceMember(
+    workspaceId: string,
+    subjectId: string,
+    request: UpdateWorkspaceMemberRequest,
+  ): Promise<WorkspaceMember> {
+    return await this.requestJson<WorkspaceMember>(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/members/${encodeURIComponent(subjectId)}`,
+      request,
+    );
+  }
+
+  /**
+   * Remove a member. Refused (409) for your own membership and for the last
+   * member who can still manage the workspace.
+   */
+  async removeWorkspaceMember(workspaceId: string, subjectId: string): Promise<void> {
+    await this.requestVoid(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/members/${encodeURIComponent(subjectId)}`,
+    );
+  }
+
+  /** Exchange one signed Slack bearer for durable, token-free continuation state. */
+  async prepareSlackUserLinkAccess(
+    workspaceId: string,
+    request: PrepareSlackUserLinkAccessRequest,
+  ): Promise<SlackUserLinkAccessRequest> {
+    return await this.requestJson<SlackUserLinkAccessRequest>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/integrations/slack/user-link-intents`,
+      request,
+    );
+  }
+
+  async getSlackUserLinkAccess(
+    workspaceId: string,
+    requestId: string,
+  ): Promise<SlackUserLinkAccessRequest> {
+    return await this.requestJson<SlackUserLinkAccessRequest>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/integrations/slack/user-link-intents/${requestId}`,
+    );
+  }
+
+  async requestSlackUserLinkWorkspaceAccess(
+    workspaceId: string,
+    requestId: string,
+    request: SlackUserLinkAccessMutationRequest,
+  ): Promise<SlackUserLinkAccessRequest> {
+    return await this.requestJson<SlackUserLinkAccessRequest>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/integrations/slack/user-link-intents/${requestId}/request-access`,
+      request,
+    );
+  }
+
+  async cancelSlackUserLinkAccess(
+    workspaceId: string,
+    requestId: string,
+    request: SlackUserLinkAccessMutationRequest,
+  ): Promise<SlackUserLinkAccessRequest> {
+    return await this.requestJson<SlackUserLinkAccessRequest>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/integrations/slack/user-link-intents/${requestId}/cancel`,
+      request,
+    );
+  }
+
+  async listSlackUserLinkAccessRequests(
+    workspaceId: string,
+  ): Promise<SlackUserLinkAccessRequest[]> {
+    const response = await this.requestJson<ListSlackUserLinkAccessRequestsResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/members/access-requests/slack`,
+    );
+    return response.requests;
+  }
+
+  async approveSlackUserLinkAccessRequest(
+    workspaceId: string,
+    requestId: string,
+    request: ApproveSlackUserLinkAccessRequest,
+  ): Promise<SlackUserLinkAccessRequest> {
+    return await this.requestJson<SlackUserLinkAccessRequest>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/members/access-requests/slack/${requestId}/approve`,
+      request,
+    );
+  }
+
+  async denySlackUserLinkAccessRequest(
+    workspaceId: string,
+    requestId: string,
+    request: SlackUserLinkAccessMutationRequest,
+  ): Promise<SlackUserLinkAccessRequest> {
+    return await this.requestJson<SlackUserLinkAccessRequest>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/members/access-requests/slack/${requestId}/deny`,
+      request,
+    );
+  }
+
+  // --- Scheduled tasks (write + runs) -------------------------------------------
+
+  async createScheduledTask(
+    workspaceId: string,
+    request: CreateScheduledTaskRequest,
+  ): Promise<ScheduledTask> {
+    return await this.requestJson<ScheduledTask>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks`,
+      request,
+    );
+  }
+
+  async updateScheduledTask(
+    workspaceId: string,
+    taskId: string,
+    request: UpdateScheduledTaskRequest,
+  ): Promise<ScheduledTask> {
+    return await this.requestJson<ScheduledTask>(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}`,
+      request,
+    );
+  }
+
+  async pauseScheduledTask(workspaceId: string, taskId: string): Promise<ScheduledTask> {
+    return await this.requestJson<ScheduledTask>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}/pause`,
+    );
+  }
+
+  async resumeScheduledTask(workspaceId: string, taskId: string): Promise<ScheduledTask> {
+    return await this.requestJson<ScheduledTask>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}/resume`,
+    );
+  }
+
+  /**
+   * Fire the task immediately (manual trigger), independent of its schedule.
+   * Pass a stable `triggerId` to make a retried trigger idempotent — the same
+   * token charges once and starts one run. Omit it and each call is distinct.
+   */
+  async triggerScheduledTask(
+    workspaceId: string,
+    taskId: string,
+    options: { triggerId?: string } = {},
+  ): Promise<ScheduledTask> {
+    return await this.requestJson<ScheduledTask>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}/trigger`,
+      options.triggerId ? { triggerId: options.triggerId } : undefined,
+    );
+  }
+
+  async deleteScheduledTask(workspaceId: string, taskId: string): Promise<void> {
+    await this.requestJson<unknown>(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}`,
+    );
+  }
+
+  async listScheduledTaskRuns(
+    workspaceId: string,
+    taskId: string,
+    options: { limit?: number } = {},
+  ): Promise<ScheduledTaskRun[]> {
+    return await this.requestJson<ScheduledTaskRun[]>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/scheduled-tasks/${taskId}/runs`,
+      undefined,
+      {
+        ...(options.limit !== undefined ? { limit: String(options.limit) } : {}),
+      },
+    );
+  }
+
+  // --- VariableSets --------------------------------------------------------------
+  // Generic reads return name/version metadata only. Plaintext uses one
+  // dedicated permissioned endpoint.
+
+  async listVariableSets(workspaceId: string): Promise<VariableSet[]> {
+    return await this.requestJson<VariableSet[]>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/variable-sets`,
+    );
+  }
+
+  async createVariableSet(
+    workspaceId: string,
+    request: CreateVariableSetRequest,
+  ): Promise<VariableSet> {
+    return await this.requestJson<VariableSet>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/variable-sets`,
+      request,
+    );
+  }
+
+  async getVariableSet(workspaceId: string, variableSetId: string): Promise<VariableSet> {
+    return await this.requestJson<VariableSet>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}`,
+    );
+  }
+
+  async getVariableSetVariable(
+    workspaceId: string,
+    variableSetId: string,
+    name: string,
+  ): Promise<VariableSetSecret> {
+    return await this.requestJson<VariableSetSecret>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}/variables/${encodeURIComponent(name)}`,
+    );
+  }
+
+  async updateVariableSet(
+    workspaceId: string,
+    variableSetId: string,
+    request: UpdateVariableSetRequest,
+  ): Promise<VariableSet> {
+    return await this.requestJson<VariableSet>(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}`,
+      request,
+    );
+  }
+
+  async deleteVariableSet(workspaceId: string, variableSetId: string): Promise<void> {
+    await this.requestJson<unknown>(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}`,
+    );
+  }
+
+  /** Create or rotate a variable. Generic reads never return its value. */
+  async setVariableSetVariable(
+    workspaceId: string,
+    variableSetId: string,
+    name: string,
+    value: string,
+  ): Promise<VariableSetVariableMetadata> {
+    return await this.requestJson<VariableSetVariableMetadata>(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}/variables/${encodeURIComponent(name)}`,
+      { value },
+    );
+  }
+
+  async deleteVariableSetVariable(
+    workspaceId: string,
+    variableSetId: string,
+    name: string,
+  ): Promise<void> {
+    await this.requestJson<unknown>(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/variable-sets/${variableSetId}/variables/${encodeURIComponent(name)}`,
+    );
+  }
+
+  // --- Channels --------------------------------------------------------------
+  // Workspace-shared rail organization for root sessions. sessions:read gates
+  // list; sessions:create gates create / update / delete; sessions:control
+  // gates re-filing a session.
+
+  async listChannels(workspaceId: string): Promise<Channel[]> {
+    return await this.requestJson<Channel[]>("GET", `/v1/workspaces/${workspaceId}/channels`);
+  }
+
+  async createChannel(workspaceId: string, request: CreateChannelRequest): Promise<Channel> {
+    return await this.requestJson<Channel>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/channels`,
+      request,
+    );
+  }
+
+  async updateChannel(
+    workspaceId: string,
+    channelId: string,
+    request: UpdateChannelRequest,
+  ): Promise<Channel> {
+    return await this.requestJson<Channel>(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/channels/${channelId}`,
+      request,
+    );
+  }
+
+  async deleteChannel(workspaceId: string, channelId: string): Promise<void> {
+    await this.requestJson<unknown>(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/channels/${channelId}`,
+    );
+  }
+
+  /** Re-file a session into a channel (null = back to the unfiled inbox). */
+  async updateSessionChannel(
+    workspaceId: string,
+    sessionId: string,
+    request: UpdateSessionChannelRequest,
+  ): Promise<Session> {
+    return await this.requestJson<Session>(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/channel`,
+      request,
+    );
+  }
+
+  // --- Rigs ------------------------------------------------------------------
+  // Workspace-scoped, versioned sandbox machine definitions. rigs:use gates read
+  // + proposeRigChange; rigs:manage gates create / update / delete / activate.
+
+  async listRigs(workspaceId: string): Promise<Rig[]> {
+    return await this.requestJson<Rig[]>("GET", `/v1/workspaces/${workspaceId}/rigs`);
+  }
+
+  async createRig(workspaceId: string, request: CreateRigRequest): Promise<Rig> {
+    return await this.requestJson<Rig>("POST", `/v1/workspaces/${workspaceId}/rigs`, request);
+  }
+
+  async getRig(workspaceId: string, rigId: string): Promise<Rig> {
+    return await this.requestJson<Rig>("GET", `/v1/workspaces/${workspaceId}/rigs/${rigId}`);
+  }
+
+  async updateRig(workspaceId: string, rigId: string, request: UpdateRigRequest): Promise<Rig> {
+    return await this.requestJson<Rig>(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}`,
+      request,
+    );
+  }
+
+  async deleteRig(workspaceId: string, rigId: string): Promise<void> {
+    await this.requestJson<unknown>("DELETE", `/v1/workspaces/${workspaceId}/rigs/${rigId}`);
+  }
+
+  async listRigVersions(workspaceId: string, rigId: string): Promise<RigVersion[]> {
+    return await this.requestJson<RigVersion[]>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/versions`,
+    );
+  }
+
+  /** Roll the active version to an existing one (rollback / promote-activate). */
+  async activateRigVersion(
+    workspaceId: string,
+    rigId: string,
+    versionId: string,
+  ): Promise<RigVersion> {
+    return await this.requestJson<RigVersion>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/versions/${versionId}/activate`,
+    );
+  }
+
+  async listRigChanges(workspaceId: string, rigId: string): Promise<RigChange[]> {
+    return await this.requestJson<RigChange[]>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/changes`,
+    );
+  }
+
+  /** Propose a change against the rig's active version (rigs:use). */
+  async proposeRigChange(
+    workspaceId: string,
+    rigId: string,
+    request: ProposeRigChangeRequest,
+  ): Promise<RigChange> {
+    return await this.requestJson<RigChange>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/changes`,
+      request,
+    );
+  }
+
+  async getRigChange(workspaceId: string, rigId: string, changeId: string): Promise<RigChange> {
+    return await this.requestJson<RigChange>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/changes/${changeId}`,
+    );
+  }
+
+  /**
+   * Re-run verification for a change (rigs:use). Verification is asynchronous:
+   * this returns the change immediately with status `verifying`; poll
+   * `getRigChange`/`listRigChanges` for the terminal outcome + logs.
+   */
+  async verifyRigChange(workspaceId: string, rigId: string, changeId: string): Promise<RigChange> {
+    return await this.requestJson<RigChange>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/changes/${changeId}/verify`,
+    );
+  }
+
+  /**
+   * Promote a verified `definition_edit` change into a new active rig version
+   * (rigs:manage). Only valid once the change's verification passed; returns the
+   * newly minted version.
+   */
+  async promoteRigChange(
+    workspaceId: string,
+    rigId: string,
+    changeId: string,
+  ): Promise<RigVersion> {
+    return await this.requestJson<RigVersion>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/changes/${changeId}/promote`,
+    );
+  }
+
+  /**
+   * Re-run the active version's checks in a clean throwaway sandbox (rigs:use).
+   * Asynchronous — returns the version id being verified; the outcome lands on
+   * the version's audit trail.
+   */
+  async verifyRig(workspaceId: string, rigId: string): Promise<{ ok: boolean; versionId: string }> {
+    return await this.requestJson<{ ok: boolean; versionId: string }>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/rigs/${rigId}/verify`,
+    );
+  }
+
+  /** @deprecated use listVariableSets */
+  async listEnvironments(workspaceId: string): Promise<VariableSet[]> {
+    return await this.listVariableSets(workspaceId);
+  }
+
+  /** @deprecated use createVariableSet */
+  async createEnvironment(
+    workspaceId: string,
+    request: CreateVariableSetRequest,
+  ): Promise<VariableSet> {
+    return await this.createVariableSet(workspaceId, request);
+  }
+
+  /** @deprecated use getVariableSet */
+  async getEnvironment(workspaceId: string, environmentId: string): Promise<VariableSet> {
+    return await this.getVariableSet(workspaceId, environmentId);
+  }
+
+  /** @deprecated use updateVariableSet */
+  async updateEnvironment(
+    workspaceId: string,
+    environmentId: string,
+    request: UpdateVariableSetRequest,
+  ): Promise<VariableSet> {
+    return await this.updateVariableSet(workspaceId, environmentId, request);
+  }
+
+  /** @deprecated use deleteVariableSet */
+  async deleteEnvironment(workspaceId: string, environmentId: string): Promise<void> {
+    await this.deleteVariableSet(workspaceId, environmentId);
+  }
+
+  /** @deprecated use setVariableSetVariable */
+  async setEnvironmentVariable(
+    workspaceId: string,
+    environmentId: string,
+    name: string,
+    value: string,
+  ): Promise<VariableSetVariableMetadata> {
+    return await this.setVariableSetVariable(workspaceId, environmentId, name, value);
+  }
+
+  /** @deprecated use deleteVariableSetVariable */
+  async deleteEnvironmentVariable(
+    workspaceId: string,
+    environmentId: string,
+    name: string,
+  ): Promise<void> {
+    await this.deleteVariableSetVariable(workspaceId, environmentId, name);
+  }
+
+  // --- Files -----------------------------------------------------------------------
+
+  /** Step 1 of the upload flow: returns the pre-signed PUT target. */
+  async beginFileUpload(
+    workspaceId: string,
+    request: CreateFileUploadRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<CreateFileUploadResponse> {
+    return await this.requestJson<CreateFileUploadResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/files/uploads`,
+      request,
+      {},
+      options,
+    );
+  }
+
+  /** Step 3 of the upload flow: server verifies the object and marks it ready. */
+  async completeFileUpload(
+    workspaceId: string,
+    uploadId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<FileAsset> {
+    const response = await this.requestJson<CompleteFileUploadResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/files/uploads/${uploadId}/complete`,
+      undefined,
+      {},
+      options,
+    );
+    return response.file;
+  }
+
+  /**
+   * The whole upload flow as one call: begin -> PUT the bytes to the signed
+   * URL (with its required headers; no API auth is sent to object storage)
+   * -> complete. Returns the ready `FileAsset`.
+   */
+  async uploadFile(workspaceId: string, input: UploadFileInput): Promise<FileAsset> {
+    if (
+      input.timeoutMs !== undefined &&
+      (!Number.isFinite(input.timeoutMs) || input.timeoutMs <= 0)
+    ) {
+      throw new Error("File upload timeout must be a positive number");
+    }
+    const withTimeout = async <T>(
+      timeoutMs: number,
+      operation: (signal: AbortSignal) => Promise<T>,
+    ): Promise<T> => {
+      const controller = new AbortController();
+      let timeout: ReturnType<typeof setTimeout> | undefined;
+      const timedOut = new Promise<never>((_resolve, reject) => {
+        timeout = setTimeout(() => {
+          controller.abort();
+          reject(new Error("File upload timed out. Retry the upload."));
+        }, timeoutMs);
+      });
+      try {
+        return await Promise.race([operation(controller.signal), timedOut]);
+      } finally {
+        if (timeout !== undefined) clearTimeout(timeout);
+      }
+    };
+    // Snapshot mutable inputs before hashing so the digest always describes the
+    // exact bytes later sent to object storage. Copy Uint8Array views into a
+    // Blob so byte offsets/shared buffers can't leak surrounding bytes.
+    const body: Blob | ArrayBuffer | string =
+      input.data instanceof Uint8Array
+        ? new Blob([input.data.slice()])
+        : input.data instanceof ArrayBuffer
+          ? input.data.slice(0)
+          : input.data;
+    const sizeBytes =
+      typeof body === "string"
+        ? new TextEncoder().encode(body).byteLength
+        : body instanceof Blob
+          ? body.size
+          : body.byteLength;
+    const sha256 = input.sha256 ?? (await sha256ForUpload(body));
+    const upload = await withTimeout(
+      30_000,
+      async (signal) =>
+        await this.beginFileUpload(
+          workspaceId,
+          {
+            filename: input.filename,
+            contentType: input.contentType,
+            sizeBytes,
+            sha256,
+          },
+          { signal },
+        ),
+    );
+    // Give large valid uploads enough time at a conservative 256 KiB/s while
+    // still bounding an object-storage request that never settles.
+    const transferTimeoutMs =
+      input.timeoutMs ?? Math.max(120_000, Math.ceil(sizeBytes / (256 * 1024)) * 1_000);
+    const putResponse = await withTimeout(
+      transferTimeoutMs,
+      async (signal) =>
+        await this.fetchImpl(upload.putUrl, {
+          method: "PUT",
+          // Signed object-storage URLs carry their own short-lived authority.
+          // Browser cookies and HTTP auth must never accompany this cross-origin
+          // request: credentialed fetches are incompatible with wildcard CORS and
+          // can leak ambient credentials to a caller-selected storage endpoint.
+          credentials: "omit",
+          // The backend's requiredHeaders already carry the canonical lowercase
+          // `content-type` for every storage backend (Azure/S3/GCS). Do NOT also set
+          // a `Content-Type` key here: WHATWG Headers treats the two casings as the
+          // same header and comma-joins their values (e.g. "text/plain, text/plain"),
+          // which the object store persists verbatim and COMPLETE then rejects (422),
+          // and which breaks S3's presigned-URL signature.
+          headers: { ...upload.requiredHeaders },
+          body,
+          signal,
+        }),
+    );
+    if (!putResponse.ok) {
+      throw await apiErrorFromResponse(putResponse, { method: "PUT" });
+    }
+    return await withTimeout(
+      30_000,
+      async (signal) => await this.completeFileUpload(workspaceId, upload.uploadId, { signal }),
+    );
+  }
+
+  async getFile(workspaceId: string, fileId: string): Promise<FileAsset> {
+    return await this.requestJson<FileAsset>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/files/${fileId}`,
+    );
+  }
+
+  /** Read provider-neutral retained evidence metadata; never returns a storage location. */
+  async getRetainedArtifact(
+    workspaceId: string,
+    artifactId: string,
+  ): Promise<RetainedArtifactMetadata> {
+    return await this.requestJson<RetainedArtifactMetadata>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/artifacts/${artifactId}`,
+    );
+  }
+
+  /**
+   * Read at most one authenticated retained-evidence range from the API. This
+   * deliberately does not use the ordinary signed file-download URL.
+   */
+  async getRetainedArtifactContent(
+    workspaceId: string,
+    artifactId: string,
+    options: RetainedArtifactContentOptions = {},
+  ): Promise<RetainedArtifactContent> {
+    return await this.getRetainedArtifactContentAtPath(
+      `/v1/workspaces/${workspaceId}/artifacts/${artifactId}/content`,
+      options,
+    );
+  }
+
+  async getSessionRetainedArtifact(
+    workspaceId: string,
+    sessionId: string,
+    artifactId: string,
+  ): Promise<RetainedArtifactMetadata> {
+    return await this.requestJson<RetainedArtifactMetadata>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/artifacts/${artifactId}`,
+    );
+  }
+
+  async getSessionRetainedArtifactContent(
+    workspaceId: string,
+    sessionId: string,
+    artifactId: string,
+    options: RetainedArtifactContentOptions = {},
+  ): Promise<RetainedArtifactContent> {
+    return await this.getRetainedArtifactContentAtPath(
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/artifacts/${artifactId}/content`,
+      options,
+    );
+  }
+
+  /** Assemble one permanent generated-image receipt from bounded authenticated ranges. */
+  async downloadRetainedArtifact(
+    workspaceId: string,
+    artifact: RetainedArtifactReference,
+    options: RetainedArtifactDownloadOptions = {},
+  ): Promise<RetainedArtifactDownload> {
+    assertRetainedGeneratedImageReceipt(workspaceId, artifact);
+    const bytes = await this.downloadRetainedArtifactBytes(artifact, options);
+    return { artifact, bytes };
+  }
+
+  /** Mint a short-lived, zero-copy browser source for a validated generated image. */
+  async createRetainedArtifactDownloadUrl(
+    workspaceId: string,
+    artifact: RetainedArtifactReference,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<FileDownloadUrlResponse> {
+    assertRetainedGeneratedImageReceipt(workspaceId, artifact);
+    const download = await this.createFileDownloadUrl(workspaceId, artifact.artifactId, options);
+    assertSafeArtifactDownloadUrl(download);
+    return download;
+  }
+
+  /** Assemble one retained screenshot from bounded authenticated API ranges. */
+  async downloadRetainedScreenshot(
+    workspaceId: string,
+    sessionId: string,
+    artifactId: string,
+    options: RetainedScreenshotDownloadOptions = {},
+  ): Promise<RetainedScreenshotDownload> {
+    const metadata = await this.getSessionRetainedArtifact(workspaceId, sessionId, artifactId);
+    if (!metadata.available) return { metadata, bytes: null };
+    if (
+      metadata.kind !== "computer_screenshot" ||
+      metadata.contentType !== "image/png" ||
+      !metadata.dimensions ||
+      metadata.originalBytes <= 0 ||
+      metadata.originalBytes > COMPUTER_SCREENSHOT_MAX_BYTES
+    ) {
+      throw new OpenGeniApiError(502, "retained screenshot metadata is invalid");
+    }
+    const bytes = await this.downloadRetainedArtifactBytes(metadata, options);
+    return { metadata, bytes };
+  }
+
+  private async downloadRetainedArtifactBytes(
+    artifact: RetainedArtifactReference,
+    options: RetainedArtifactDownloadOptions,
+  ): Promise<Uint8Array> {
+    const maxRetries = options.maxRetries ?? 2;
+    if (!Number.isInteger(maxRetries) || maxRetries < 0 || maxRetries > 3) {
+      throw new RangeError("retained artifact maxRetries must be an integer from 0 to 3");
+    }
+    const bytes = new Uint8Array(artifact.originalBytes);
+    const pageBytes = Math.min(artifact.retrieval.maxRangeBytes, RETAINED_OUTPUT_MAX_PAGE_BYTES);
+    if (!Number.isSafeInteger(pageBytes) || pageBytes <= 0) {
+      throw new OpenGeniApiError(502, "retained artifact range metadata is invalid");
+    }
+    for (let start = 0; start < bytes.byteLength; start += pageBytes) {
+      options.signal?.throwIfAborted();
+      const end = Math.min(start + pageBytes, bytes.byteLength) - 1;
+      let page: RetainedArtifactContent | null = null;
+      for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+        try {
+          page = await this.getRetainedArtifactContentAtPath(artifact.retrieval.path, {
+            range: `bytes=${start}-${end}`,
+            ...(options.signal ? { signal: options.signal } : {}),
+          });
+          break;
+        } catch (error) {
+          options.signal?.throwIfAborted();
+          if (
+            attempt >= maxRetries ||
+            (error instanceof OpenGeniApiError && error.status >= 400 && error.status < 500)
+          ) {
+            throw error;
+          }
+        }
+      }
+      if (!page) throw new OpenGeniApiError(502, "retained artifact range retry exhausted");
+      const expectedLength = end - start + 1;
+      if (
+        page.status !== 206 ||
+        page.contentType !== artifact.contentType ||
+        page.contentLength !== expectedLength ||
+        page.contentRange !== `bytes ${start}-${end}/${artifact.originalBytes}`
+      ) {
+        throw new OpenGeniApiError(502, "retained artifact range response is invalid");
+      }
+      bytes.set(page.bytes, start);
+    }
+    if ((await sha256Hex(bytes)) !== artifact.sha256) {
+      throw new OpenGeniApiError(502, "retained artifact checksum mismatch");
+    }
+    return bytes;
+  }
+
+  private async getRetainedArtifactContentAtPath(
+    path: string,
+    options: RetainedArtifactContentOptions,
+  ): Promise<RetainedArtifactContent> {
+    if (options.range && (options.range.length > 128 || /[^\x20-\x7e]/.test(options.range))) {
+      throw new RangeError("retained artifact range must be at most 128 printable ASCII bytes");
+    }
+    const correlationId = crypto.randomUUID();
+    const response = await this.fetchImpl(this.url(path), {
+      method: "GET",
+      headers: {
+        ...this.headers(correlationId),
+        Accept: "application/octet-stream",
+        ...(options.range ? { Range: options.range } : {}),
+      },
+      ...(options.signal ? { signal: options.signal } : {}),
+    });
+    try {
+      assertApiContractResponse(response);
+    } catch (error) {
+      await cancelResponseBody(response, "retained artifact API contract mismatch");
+      throw error;
+    }
+    if (!response.ok) {
+      throw await apiErrorFromResponse(response, {
+        method: "GET",
+        correlationId,
+      });
+    }
+    if (response.status !== 200 && response.status !== 206) {
+      await cancelResponseBody(response, "unexpected retained artifact response status");
+      throw new OpenGeniApiError(response.status, "unexpected retained artifact response status");
+    }
+    if (response.headers.get("accept-ranges") !== "bytes") {
+      await cancelResponseBody(response, "retained artifact response omitted byte-range support");
+      throw new OpenGeniApiError(502, "retained artifact response omitted byte-range support");
+    }
+    let declaredLength: number | null;
+    try {
+      declaredLength = parseBoundedContentLength(response.headers.get("content-length"));
+    } catch (error) {
+      await cancelResponseBody(response, "invalid retained artifact content-length");
+      throw error;
+    }
+    const bytes = await readBoundedResponseBytes(
+      response,
+      RETAINED_OUTPUT_MAX_PAGE_BYTES,
+      declaredLength,
+    );
+    return {
+      bytes,
+      status: response.status,
+      contentType: response.headers.get("content-type") ?? "application/octet-stream",
+      contentLength: bytes.byteLength,
+      contentRange: response.headers.get("content-range"),
+      acceptRanges: "bytes",
+    };
+  }
+
+  /** Mint a short-lived signed download URL for a ready file. */
+  async createFileDownloadUrl(
+    workspaceId: string,
+    fileId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<FileDownloadUrlResponse> {
+    return await this.requestJson<FileDownloadUrlResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/files/${fileId}/download-url`,
+      undefined,
+      {},
+      options,
+    );
+  }
+
+  // --- Video generation ---------------------------------------------------------------
+
+  /** Read the effective workspace policy and executable Seedance capabilities. */
+  async getVideoGenerationSettings(
+    workspaceId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<WorkspaceVideoGenerationSettings> {
+    return await this.requestJson<WorkspaceVideoGenerationSettings>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/video-generation`,
+      undefined,
+      {},
+      options,
+    );
+  }
+
+  /** Replace the enabled video models/default under optimistic policy revision control. */
+  async updateVideoGenerationPolicy(
+    workspaceId: string,
+    request: UpdateVideoGenerationPolicyRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<VideoGenerationPolicy> {
+    return await this.requestJson<VideoGenerationPolicy>(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/video-generation/policy`,
+      request,
+      {},
+      options,
+    );
+  }
+
+  /** Read durable progress for one accepted video generation operation. */
+  async getVideoGenerationOperation(
+    workspaceId: string,
+    operationId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<VideoGenerationOperationSummary> {
+    return await this.requestJson<VideoGenerationOperationSummary>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/video-generation/operations/${operationId}`,
+      undefined,
+      {},
+      options,
+    );
+  }
+
+  /** Mint a short-lived zero-copy URL for native Range-based video playback. */
+  async createVideoArtifactPlaybackSource(
+    workspaceId: string,
+    artifactId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<VideoArtifactPlaybackSource> {
+    const source = await this.requestJson<VideoArtifactPlaybackSource>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/artifacts/${artifactId}/playback-source`,
+      undefined,
+      {},
+      options,
+    );
+    assertSafeVideoArtifactPlaybackSource(source, artifactId);
+    return source;
+  }
+
+  // --- Documents ----------------------------------------------------------------------
+
+  async createDocumentBase(
+    workspaceId: string,
+    request: CreateDocumentBaseRequest,
+  ): Promise<DocumentBase> {
+    return await this.requestJson<DocumentBase>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/document-bases`,
+      request,
+    );
+  }
+
+  async listDocumentBases(workspaceId: string): Promise<DocumentBase[]> {
+    return await this.requestJson<DocumentBase[]>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/document-bases`,
+    );
+  }
+
+  async getDocumentBase(workspaceId: string, baseId: string): Promise<DocumentBase> {
+    return await this.requestJson<DocumentBase>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/document-bases/${baseId}`,
+    );
+  }
+
+  /** Index an uploaded file into the base. The file must be `ready`. */
+  async addDocument(
+    workspaceId: string,
+    baseId: string,
+    request: AddDocumentRequest,
+  ): Promise<Document> {
+    return await this.requestJson<Document>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents`,
+      request,
+    );
+  }
+
+  async listDocuments(workspaceId: string, baseId: string): Promise<Document[]> {
+    return await this.requestJson<Document[]>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents`,
+    );
+  }
+
+  /**
+   * Drop raw text or an already-uploaded file into the workspace's Default
+   * base. When curation is enabled, it may name, summarize, categorize, and
+   * (confidence permitting) file the document into the best-matching base;
+   * provider=none leaves caller metadata and Default placement unchanged.
+   */
+  async createKnowledgeDrop(
+    workspaceId: string,
+    request: CreateKnowledgeDropRequest,
+  ): Promise<Document> {
+    return await this.requestJson<Document>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/knowledge/drops`,
+      request,
+    );
+  }
+
+  /**
+   * Move a document (and its indexed chunks) to another base. With no
+   * targetBaseId, applies the document's stored curation suggestion.
+   */
+  async moveDocument(
+    workspaceId: string,
+    documentId: string,
+    request: MoveDocumentRequest = {},
+  ): Promise<Document> {
+    return await this.requestJson<Document>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/documents/${documentId}/move`,
+      request,
+    );
+  }
+
+  /** Retry indexing for a failed document. */
+  async reindexDocument(
+    workspaceId: string,
+    baseId: string,
+    documentId: string,
+  ): Promise<Document> {
+    return await this.requestJson<Document>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents/${documentId}/reindex`,
+    );
+  }
+
+  /**
+   * Delete a document from a base. Removes the document row and its indexed
+   * chunks while leaving the uploaded file asset available for other uses.
+   */
+  async deleteDocument(workspaceId: string, baseId: string, documentId: string): Promise<void> {
+    await this.requestVoid(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents/${documentId}`,
+    );
+  }
+
+  async searchDocuments(
+    workspaceId: string,
+    baseId: string,
+    request: Omit<DocumentSearchRequest, "baseIds">,
+  ): Promise<DocumentSearchResponse> {
+    return await this.requestJson<DocumentSearchResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/document-bases/${baseId}/search`,
+      request,
+    );
+  }
+
+  async searchKnowledge(
+    workspaceId: string,
+    request: DocumentSearchRequest,
+  ): Promise<DocumentSearchResponse> {
+    return await this.requestJson<DocumentSearchResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/knowledge/search`,
+      request,
+    );
+  }
+
+  async listKnowledgeMemories(
+    workspaceId: string,
+    request: KnowledgeMemorySearchRequest = {},
+  ): Promise<KnowledgeMemory[]> {
+    const params = new URLSearchParams();
+    if (request.query) params.set("query", request.query);
+    if (request.status) params.set("status", request.status);
+    if (request.kind) params.set("kind", request.kind);
+    if (request.scope) params.set("scope", request.scope);
+    if (request.limit) params.set("limit", String(request.limit));
+    const query = params.toString();
+    return await this.requestJson<KnowledgeMemory[]>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/knowledge/memories${query ? `?${query}` : ""}`,
+    );
+  }
+
+  async getKnowledgeMemory(workspaceId: string, memoryId: string): Promise<KnowledgeMemory> {
+    return await this.requestJson<KnowledgeMemory>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/knowledge/memories/${memoryId}`,
+    );
+  }
+
+  async createKnowledgeMemory(
+    workspaceId: string,
+    request: CreateKnowledgeMemoryRequest,
+  ): Promise<KnowledgeMemory> {
+    return await this.requestJson<KnowledgeMemory>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/knowledge/memories`,
+      request,
+    );
+  }
+
+  async updateKnowledgeMemory(
+    workspaceId: string,
+    memoryId: string,
+    request: UpdateKnowledgeMemoryRequest,
+  ): Promise<KnowledgeMemory> {
+    return await this.requestJson<KnowledgeMemory>(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/knowledge/memories/${memoryId}`,
+      request,
+    );
+  }
+
+  /** Hybrid (semantic + keyword) search over the workspace's agent-visible memory. */
+  async searchWorkspaceMemories(
+    workspaceId: string,
+    request: WorkspaceMemorySearchRequest,
+  ): Promise<WorkspaceMemorySearchResponse> {
+    return await this.requestJson<WorkspaceMemorySearchResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/knowledge/memories/search`,
+      request,
+    );
+  }
+
+  /** Deep-merge a settings patch into the workspace (preserves unknown keys). */
+  async updateWorkspaceSettings(
+    workspaceId: string,
+    request: UpdateWorkspaceSettingsRequest,
+  ): Promise<Workspace> {
+    return await this.requestJson<Workspace>(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/settings`,
+      request,
+    );
+  }
+
+  async setWorkspaceDefaultRig(
+    workspaceId: string,
+    request: SetWorkspaceDefaultRigRequest,
+  ): Promise<Workspace> {
+    return await this.requestJson<Workspace>(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/default-rig`,
+      request,
+    );
+  }
+
+  // --- Capability packs ------------------------------------------------------------------
+
+  /** Built-in + registered packs, with the workspace's installations. */
+  async listPacks(workspaceId: string): Promise<ListPacksResponse> {
+    return await this.requestJson<ListPacksResponse>("GET", `/v1/workspaces/${workspaceId}/packs`);
+  }
+
+  /** Register (or replace) a workspace-scoped pack from a manifest. */
+  async registerPack(
+    workspaceId: string,
+    manifest: RegisterCapabilityPackRequest,
+  ): Promise<WorkspaceRegisteredPack> {
+    return await this.requestJson<WorkspaceRegisteredPack>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/packs`,
+      manifest,
+    );
   }
 
-  private async getRetainedArtifactContentAtPath(
-    path: string,
-    options: RetainedArtifactContentOptions,
-  ): Promise<RetainedArtifactContent> {
-    if (options.range && (options.range.length > 128 || /[^\x20-\x7e]/.test(options.range))) {
-      throw new RangeError("retained artifact range must be at most 128 printable ASCII bytes");
-    }
-    const correlationId = crypto.randomUUID();
-    const response = await this.fetchImpl(this.url(path), {
-      method: "GET",
-      headers: {
-        ...this.headers(correlationId),
-        Accept: "application/octet-stream",
-        ...(options.range ? { Range: options.range } : {}),
-      },
-      ...(options.signal ? { signal: options.signal } : {}),
-    });
-    try {
-      assertApiContractResponse(response);
-    } catch (error) {
-      await cancelResponseBody(response, "retained artifact API contract mismatch");
-      throw error;
-    }
-    if (!response.ok) {
-      throw await apiErrorFromResponse(response, {
-        method: "GET",
-        correlationId,
-      });
-    }
-    if (response.status !== 200 && response.status !== 206) {
-      await cancelResponseBody(response, "unexpected retained artifact response status");
-      throw new OpenGeniApiError(response.status, "unexpected retained artifact response status");
-    }
-    if (response.headers.get("accept-ranges") !== "bytes") {
-      await cancelResponseBody(response, "retained artifact response omitted byte-range support");
-      throw new OpenGeniApiError(502, "retained artifact response omitted byte-range support");
-    }
-    let declaredLength: number | null;
-    try {
-      declaredLength = parseBoundedContentLength(response.headers.get("content-length"));
-    } catch (error) {
-      await cancelResponseBody(response, "invalid retained artifact content-length");
-      throw error;
-    }
-    const bytes = await readBoundedResponseBytes(
-      response,
-      RETAINED_OUTPUT_MAX_PAGE_BYTES,
-      declaredLength,
+  async getPack(workspaceId: string, packId: string): Promise<GetPackResponse> {
+    return await this.requestJson<GetPackResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/packs/${encodeURIComponent(packId)}`,
     );
-    return {
-      bytes,
-      status: response.status,
-      contentType: response.headers.get("content-type") ?? "application/octet-stream",
-      contentLength: bytes.byteLength,
-      contentRange: response.headers.get("content-range"),
-      acceptRanges: "bytes",
-    };
   }
 
-  /** Mint a short-lived signed download URL for a ready file. */
-  async createFileDownloadUrl(
+  async enablePack(
     workspaceId: string,
-    fileId: string,
-  ): Promise<FileDownloadUrlResponse> {
-    return await this.requestJson<FileDownloadUrlResponse>(
+    packId: string,
+    request: EnablePackRequest = {},
+  ): Promise<PackInstallation> {
+    return await this.requestJson<PackInstallation>(
       "POST",
-      `/v1/workspaces/${workspaceId}/files/${fileId}/download-url`,
+      `/v1/workspaces/${workspaceId}/packs/${encodeURIComponent(packId)}/enable`,
+      request,
     );
   }
 
-  // --- Documents ----------------------------------------------------------------------
-
-  async createDocumentBase(
+  /** Resolve pinned components, Variable Set, and Rig requirements before installation. */
+  async previewPackInstallation(
     workspaceId: string,
-    request: CreateDocumentBaseRequest,
-  ): Promise<DocumentBase> {
-    return await this.requestJson<DocumentBase>(
+    packId: string,
+    request: PreviewPackInstallationRequest = {},
+  ): Promise<PackInstallationPreview> {
+    return await this.requestJson<PackInstallationPreview>(
       "POST",
-      `/v1/workspaces/${workspaceId}/document-bases`,
+      `/v1/workspaces/${workspaceId}/packs/${encodeURIComponent(packId)}/installation-preview`,
       request,
     );
   }
 
-  async listDocumentBases(workspaceId: string): Promise<DocumentBase[]> {
-    return await this.requestJson<DocumentBase[]>(
-      "GET",
-      `/v1/workspaces/${workspaceId}/document-bases`,
+  /** Install, update, or repair a Pack from an exact previewed manifest. */
+  async installPack(
+    workspaceId: string,
+    packId: string,
+    request: InstallPackRequest,
+  ): Promise<PackInstallation> {
+    return await this.requestJson<PackInstallation>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/packs/${encodeURIComponent(packId)}/install`,
+      request,
     );
   }
 
-  async getDocumentBase(workspaceId: string, baseId: string): Promise<DocumentBase> {
-    return await this.requestJson<DocumentBase>(
+  /** Preview which Pack-owned components will be retained by other owners. */
+  async previewPackUninstall(workspaceId: string, packId: string): Promise<PackUninstallPreview> {
+    return await this.requestJson<PackUninstallPreview>(
       "GET",
-      `/v1/workspaces/${workspaceId}/document-bases/${baseId}`,
+      `/v1/workspaces/${workspaceId}/packs/${encodeURIComponent(packId)}/uninstall-preview`,
     );
   }
 
-  /** Index an uploaded file into the base. The file must be `ready`. */
-  async addDocument(
+  /** Safely release Pack ownership and disable only now-ownerless components. */
+  async uninstallPack(
     workspaceId: string,
-    baseId: string,
-    request: AddDocumentRequest,
-  ): Promise<Document> {
-    return await this.requestJson<Document>(
-      "POST",
-      `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents`,
+    packId: string,
+    request: UninstallPackRequest,
+  ): Promise<UninstallPackResult> {
+    return await this.requestJson<UninstallPackResult>(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/packs/${encodeURIComponent(packId)}/installation`,
       request,
     );
   }
 
-  async listDocuments(workspaceId: string, baseId: string): Promise<Document[]> {
-    return await this.requestJson<Document[]>(
+  /** Unregister a workspace-scoped pack (built-in packs cannot be deleted). */
+  async deletePack(workspaceId: string, packId: string): Promise<void> {
+    await this.requestVoid(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/packs/${encodeURIComponent(packId)}`,
+    );
+  }
+
+  async listPackInstallations(workspaceId: string): Promise<PackInstallation[]> {
+    return await this.requestJson<PackInstallation[]>(
       "GET",
-      `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents`,
+      `/v1/workspaces/${workspaceId}/packs/installations`,
     );
   }
 
-  /**
-   * Drop raw text or an already-uploaded file into the workspace's Default
-   * base. When curation is enabled, it may name, summarize, categorize, and
-   * (confidence permitting) file the document into the best-matching base;
-   * provider=none leaves caller metadata and Default placement unchanged.
-   */
-  async createKnowledgeDrop(
+  // --- Capabilities -------------------------------------------------------------------------
+
+  async listCapabilities(workspaceId: string): Promise<CapabilityCatalogResponse> {
+    return await this.requestJson<CapabilityCatalogResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/capabilities`,
+    );
+  }
+
+  /** Add a manual capability catalog item (e.g. a remote MCP server). */
+  async createCapability(
     workspaceId: string,
-    request: CreateKnowledgeDropRequest,
-  ): Promise<Document> {
-    return await this.requestJson<Document>(
+    request: CreateCapabilityCatalogItemRequest,
+  ): Promise<CapabilityCatalogItem> {
+    return await this.requestJson<CapabilityCatalogItem>(
       "POST",
-      `/v1/workspaces/${workspaceId}/knowledge/drops`,
+      `/v1/workspaces/${workspaceId}/capabilities`,
       request,
     );
   }
 
-  /**
-   * Move a document (and its indexed chunks) to another base. With no
-   * targetBaseId, applies the document's stored curation suggestion.
-   */
-  async moveDocument(
+  async enableCapability(
     workspaceId: string,
-    documentId: string,
-    request: MoveDocumentRequest = {},
-  ): Promise<Document> {
-    return await this.requestJson<Document>(
+    capabilityId: string,
+    request: EnableCapabilityRequest = {},
+  ): Promise<CapabilityInstallation> {
+    return await this.requestJson<CapabilityInstallation>(
       "POST",
-      `/v1/workspaces/${workspaceId}/documents/${documentId}/move`,
+      `/v1/workspaces/${workspaceId}/capabilities/${encodeURIComponent(capabilityId)}/enable`,
       request,
     );
   }
 
-  /** Retry indexing for a failed document. */
-  async reindexDocument(
+  async disableCapability(
     workspaceId: string,
-    baseId: string,
-    documentId: string,
-  ): Promise<Document> {
-    return await this.requestJson<Document>(
+    capabilityId: string,
+  ): Promise<CapabilityInstallation> {
+    return await this.requestJson<CapabilityInstallation>(
       "POST",
-      `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents/${documentId}/reindex`,
+      `/v1/workspaces/${workspaceId}/capabilities/${encodeURIComponent(capabilityId)}/disable`,
     );
   }
 
-  /**
-   * Delete a document from a base. Removes the document row and its indexed
-   * chunks while leaving the uploaded file asset available for other uses.
-   */
-  async deleteDocument(workspaceId: string, baseId: string, documentId: string): Promise<void> {
-    await this.requestVoid(
-      "DELETE",
-      `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents/${documentId}`,
+  /** Search the official MCP registry for installable capabilities. */
+  async discoverMcpCapabilities(
+    workspaceId: string,
+    options: { query?: string; limit?: number } = {},
+  ): Promise<DiscoverMcpCapabilitiesResponse> {
+    return await this.requestJson<DiscoverMcpCapabilitiesResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/capabilities/discovery/mcp-registry`,
+      undefined,
+      {
+        ...(options.query !== undefined ? { query: options.query } : {}),
+        ...(options.limit !== undefined ? { limit: String(options.limit) } : {}),
+      },
     );
   }
 
-  async searchDocuments(
+  /** List installed protocol-neutral OpenAPI and GraphQL Integrations. */
+  async listApiIntegrations(workspaceId: string): Promise<ListApiIntegrationsResponse> {
+    return await this.requestJson<ListApiIntegrationsResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/integrations`,
+    );
+  }
+
+  /** List curated provider definitions without exposing deployment OAuth credentials. */
+  async listIntegrationDefinitions(
     workspaceId: string,
-    baseId: string,
-    request: Omit<DocumentSearchRequest, "baseIds">,
-  ): Promise<DocumentSearchResponse> {
-    return await this.requestJson<DocumentSearchResponse>(
+  ): Promise<ListIntegrationDefinitionsResponse> {
+    return await this.requestJson<ListIntegrationDefinitionsResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/integrations/definitions`,
+    );
+  }
+
+  /** Detect and compile an Integration without mutating workspace state. */
+  async previewApiIntegration(
+    workspaceId: string,
+    request: PreviewApiIntegrationRequest,
+  ): Promise<ApiIntegrationPreview> {
+    return await this.requestJson<ApiIntegrationPreview>(
       "POST",
-      `/v1/workspaces/${workspaceId}/document-bases/${baseId}/search`,
+      `/v1/workspaces/${workspaceId}/integrations/preview`,
       request,
     );
   }
 
-  async searchKnowledge(
+  /** Start a signed PKCE OAuth flow for a built-in Google or Microsoft definition. */
+  async startApiIntegrationOAuth(
     workspaceId: string,
-    request: DocumentSearchRequest,
-  ): Promise<DocumentSearchResponse> {
-    return await this.requestJson<DocumentSearchResponse>(
+    request: ApiIntegrationOAuthStartRequest,
+  ): Promise<OAuthStartResponse> {
+    return await this.requestJson<OAuthStartResponse>(
       "POST",
-      `/v1/workspaces/${workspaceId}/knowledge/search`,
+      `/v1/workspaces/${workspaceId}/integrations/oauth/start`,
       request,
     );
   }
 
-  async listKnowledgeMemories(
+  /** Install only the exact immutable revision and digest accepted in preview. */
+  async installApiIntegration(
     workspaceId: string,
-    request: KnowledgeMemorySearchRequest = {},
-  ): Promise<KnowledgeMemory[]> {
-    const params = new URLSearchParams();
-    if (request.query) params.set("query", request.query);
-    if (request.status) params.set("status", request.status);
-    if (request.kind) params.set("kind", request.kind);
-    if (request.scope) params.set("scope", request.scope);
-    if (request.limit) params.set("limit", String(request.limit));
-    const query = params.toString();
-    return await this.requestJson<KnowledgeMemory[]>(
+    request: InstallApiIntegrationRequest,
+  ): Promise<InstalledApiIntegration> {
+    return await this.requestJson<InstalledApiIntegration>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/integrations/install`,
+      request,
+    );
+  }
+
+  async previewApiIntegrationUninstall(
+    workspaceId: string,
+    capabilityId: string,
+    instanceKey: string,
+  ): Promise<ApiIntegrationUninstallPreview> {
+    return await this.requestJson<ApiIntegrationUninstallPreview>(
       "GET",
-      `/v1/workspaces/${workspaceId}/knowledge/memories${query ? `?${query}` : ""}`,
+      `/v1/workspaces/${workspaceId}/integrations/${encodeURIComponent(capabilityId)}/instances/${encodeURIComponent(instanceKey)}/uninstall-preview`,
     );
   }
 
-  async getKnowledgeMemory(workspaceId: string, memoryId: string): Promise<KnowledgeMemory> {
-    return await this.requestJson<KnowledgeMemory>(
+  /** Remove one Integration instance without deleting its Connection or sibling instances. */
+  async uninstallApiIntegration(
+    workspaceId: string,
+    capabilityId: string,
+    instanceKey: string,
+    request: UninstallApiIntegrationRequest,
+  ): Promise<UninstallApiIntegrationResult> {
+    return await this.requestJson<UninstallApiIntegrationResult>(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/integrations/${encodeURIComponent(capabilityId)}/instances/${encodeURIComponent(instanceKey)}`,
+      request,
+    );
+  }
+
+  /** List immutable provider facets and their exact per-account bindings. */
+  async listIntegrationFacets(
+    workspaceId: string,
+    capabilityId: string,
+    instanceKey: string,
+  ): Promise<IntegrationInstanceFacetsResponse> {
+    return await this.requestJson<IntegrationInstanceFacetsResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/integrations/${encodeURIComponent(capabilityId)}/instances/${encodeURIComponent(instanceKey)}/facets`,
+    );
+  }
+
+  /** Configure or OCC-update one adapter-owned facet on an Integration instance. */
+  async configureIntegrationFacet(
+    workspaceId: string,
+    capabilityId: string,
+    instanceKey: string,
+    facetKey: string,
+    request: UpsertIntegrationFacetRequest,
+  ): Promise<IntegrationFacetMutationResult> {
+    return await this.requestJson<IntegrationFacetMutationResult>(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/integrations/${encodeURIComponent(capabilityId)}/instances/${encodeURIComponent(instanceKey)}/facets/${encodeURIComponent(facetKey)}`,
+      request,
+    );
+  }
+
+  /** Browse source metadata through one exact Google Drive Integration instance. */
+  async browseGoogleDriveFacetSource(
+    workspaceId: string,
+    capabilityId: string,
+    instanceKey: string,
+    facetKey: string,
+    options: {
+      parentId?: string | undefined;
+      pageToken?: string | undefined;
+    } = {},
+  ): Promise<GoogleDriveBrowseResponse> {
+    const query = new URLSearchParams();
+    if (options.parentId) query.set("parentId", options.parentId);
+    if (options.pageToken) query.set("pageToken", options.pageToken);
+    const suffix = query.size > 0 ? `?${query}` : "";
+    return await this.requestJson<GoogleDriveBrowseResponse>(
       "GET",
-      `/v1/workspaces/${workspaceId}/knowledge/memories/${memoryId}`,
+      `/v1/workspaces/${workspaceId}/integrations/${encodeURIComponent(capabilityId)}/instances/${encodeURIComponent(instanceKey)}/facets/${encodeURIComponent(facetKey)}/browse${suffix}`,
     );
   }
 
-  async createKnowledgeMemory(
+  /** Verify and bind document sources to one exact Google Drive Integration instance. */
+  async saveGoogleDriveFacetSource(
     workspaceId: string,
-    request: CreateKnowledgeMemoryRequest,
-  ): Promise<KnowledgeMemory> {
-    return await this.requestJson<KnowledgeMemory>(
-      "POST",
-      `/v1/workspaces/${workspaceId}/knowledge/memories`,
+    capabilityId: string,
+    instanceKey: string,
+    facetKey: string,
+    request: SaveGoogleDriveIntegrationSourceRequest,
+  ): Promise<IntegrationFacetMutationResult> {
+    return await this.requestJson<IntegrationFacetMutationResult>(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/integrations/${encodeURIComponent(capabilityId)}/instances/${encodeURIComponent(instanceKey)}/facets/${encodeURIComponent(facetKey)}/source`,
       request,
     );
   }
 
-  async updateKnowledgeMemory(
+  async pauseIntegrationFacet(
     workspaceId: string,
-    memoryId: string,
-    request: UpdateKnowledgeMemoryRequest,
-  ): Promise<KnowledgeMemory> {
-    return await this.requestJson<KnowledgeMemory>(
-      "PATCH",
-      `/v1/workspaces/${workspaceId}/knowledge/memories/${memoryId}`,
+    capabilityId: string,
+    instanceKey: string,
+    facetKey: string,
+    request: MutateIntegrationFacetRequest,
+  ): Promise<IntegrationFacetMutationResult> {
+    return await this.mutateIntegrationFacetLifecycle(
+      workspaceId,
+      capabilityId,
+      instanceKey,
+      facetKey,
+      "pause",
       request,
     );
   }
 
-  /** Hybrid (semantic + keyword) search over the workspace's agent-visible memory. */
-  async searchWorkspaceMemories(
+  async resumeIntegrationFacet(
     workspaceId: string,
-    request: WorkspaceMemorySearchRequest,
-  ): Promise<WorkspaceMemorySearchResponse> {
-    return await this.requestJson<WorkspaceMemorySearchResponse>(
-      "POST",
-      `/v1/workspaces/${workspaceId}/knowledge/memories/search`,
+    capabilityId: string,
+    instanceKey: string,
+    facetKey: string,
+    request: MutateIntegrationFacetRequest,
+  ): Promise<IntegrationFacetMutationResult> {
+    return await this.mutateIntegrationFacetLifecycle(
+      workspaceId,
+      capabilityId,
+      instanceKey,
+      facetKey,
+      "resume",
       request,
     );
   }
 
-  /** Deep-merge a settings patch into the workspace (preserves unknown keys). */
-  async updateWorkspaceSettings(
+  async removeIntegrationFacet(
     workspaceId: string,
-    request: UpdateWorkspaceSettingsRequest,
-  ): Promise<Workspace> {
-    return await this.requestJson<Workspace>(
-      "PATCH",
-      `/v1/workspaces/${workspaceId}/settings`,
+    capabilityId: string,
+    instanceKey: string,
+    facetKey: string,
+    request: MutateIntegrationFacetRequest,
+  ): Promise<IntegrationFacetRemovalResult> {
+    return await this.requestJson<IntegrationFacetRemovalResult>(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/integrations/${encodeURIComponent(capabilityId)}/instances/${encodeURIComponent(instanceKey)}/facets/${encodeURIComponent(facetKey)}`,
       request,
     );
   }
 
-  async setWorkspaceDefaultRig(
+  private async mutateIntegrationFacetLifecycle(
     workspaceId: string,
-    request: SetWorkspaceDefaultRigRequest,
-  ): Promise<Workspace> {
-    return await this.requestJson<Workspace>(
-      "PUT",
-      `/v1/workspaces/${workspaceId}/default-rig`,
+    capabilityId: string,
+    instanceKey: string,
+    facetKey: string,
+    action: "pause" | "resume",
+    request: MutateIntegrationFacetRequest,
+  ): Promise<IntegrationFacetMutationResult> {
+    return await this.requestJson<IntegrationFacetMutationResult>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/integrations/${encodeURIComponent(capabilityId)}/instances/${encodeURIComponent(instanceKey)}/facets/${encodeURIComponent(facetKey)}/${action}`,
       request,
     );
   }
 
-  // --- Capability packs ------------------------------------------------------------------
-
-  /** Built-in + registered packs, with the workspace's installations. */
-  async listPacks(workspaceId: string): Promise<ListPacksResponse> {
-    return await this.requestJson<ListPacksResponse>("GET", `/v1/workspaces/${workspaceId}/packs`);
-  }
-
-  /** Register (or replace) a workspace-scoped pack from a manifest. */
-  async registerPack(
-    workspaceId: string,
-    manifest: RegisterCapabilityPackRequest,
-  ): Promise<WorkspaceRegisteredPack> {
-    return await this.requestJson<WorkspaceRegisteredPack>(
+  async previewPlugin(workspaceId: string, request: PreviewPluginRequest): Promise<PluginPreview> {
+    return await this.requestJson<PluginPreview>(
       "POST",
-      `/v1/workspaces/${workspaceId}/packs`,
-      manifest,
+      `/v1/workspaces/${workspaceId}/plugins/preview`,
+      request,
     );
   }
 
-  async getPack(workspaceId: string, packId: string): Promise<GetPackResponse> {
-    return await this.requestJson<GetPackResponse>(
+  async listInstalledPlugins(workspaceId: string): Promise<ListInstalledPluginsResponse> {
+    return await this.requestJson<ListInstalledPluginsResponse>(
       "GET",
-      `/v1/workspaces/${workspaceId}/packs/${encodeURIComponent(packId)}`,
+      `/v1/workspaces/${workspaceId}/plugins`,
     );
   }
 
-  async enablePack(
+  async installPlugin(
     workspaceId: string,
-    packId: string,
-    request: EnablePackRequest = {},
-  ): Promise<PackInstallation> {
-    return await this.requestJson<PackInstallation>(
+    request: InstallPluginRequest,
+  ): Promise<InstalledPlugin> {
+    return await this.requestJson<InstalledPlugin>(
       "POST",
-      `/v1/workspaces/${workspaceId}/packs/${encodeURIComponent(packId)}/enable`,
+      `/v1/workspaces/${workspaceId}/plugins/install`,
       request,
     );
   }
 
-  /** Unregister a workspace-scoped pack (built-in packs cannot be deleted). */
-  async deletePack(workspaceId: string, packId: string): Promise<void> {
-    await this.requestVoid(
-      "DELETE",
-      `/v1/workspaces/${workspaceId}/packs/${encodeURIComponent(packId)}`,
+  async previewPluginUninstall(
+    workspaceId: string,
+    pluginKey: string,
+  ): Promise<PluginUninstallPreview> {
+    return await this.requestJson<PluginUninstallPreview>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/plugins/${encodeURIComponent(pluginKey)}/uninstall-preview`,
     );
   }
 
-  async listPackInstallations(workspaceId: string): Promise<PackInstallation[]> {
-    return await this.requestJson<PackInstallation[]>(
-      "GET",
-      `/v1/workspaces/${workspaceId}/packs/installations`,
+  async uninstallPlugin(
+    workspaceId: string,
+    pluginKey: string,
+    request: UninstallPluginRequest,
+  ): Promise<UninstallPluginResult> {
+    return await this.requestJson<UninstallPluginResult>(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/plugins/${encodeURIComponent(pluginKey)}`,
+      request,
     );
   }
 
-  // --- Capabilities -------------------------------------------------------------------------
-
-  async listCapabilities(workspaceId: string): Promise<CapabilityCatalogResponse> {
-    return await this.requestJson<CapabilityCatalogResponse>(
-      "GET",
-      `/v1/workspaces/${workspaceId}/capabilities`,
+  /** Resolve one public skills.sh or GitHub Skill folder to an immutable review preview. */
+  async previewSkillImport(
+    workspaceId: string,
+    request: PreviewSkillImportRequest,
+  ): Promise<SkillImportPreview> {
+    return await this.requestJson<SkillImportPreview>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/skills/preview`,
+      request,
     );
   }
 
-  /** Add a manual capability catalog item (e.g. a remote MCP server). */
-  async createCapability(
-    workspaceId: string,
-    request: CreateCapabilityCatalogItemRequest,
-  ): Promise<CapabilityCatalogItem> {
-    return await this.requestJson<CapabilityCatalogItem>(
+  /** Install only the exact commit and full-content digest accepted during preview. */
+  async installSkill(workspaceId: string, request: InstallSkillRequest): Promise<InstalledSkill> {
+    return await this.requestJson<InstalledSkill>(
       "POST",
-      `/v1/workspaces/${workspaceId}/capabilities`,
+      `/v1/workspaces/${workspaceId}/skills/install`,
       request,
     );
   }
 
-  async enableCapability(
+  /** List Skills from the authoritative Plugin/Skill-Facet installation ledger. */
+  async listInstalledSkills(workspaceId: string): Promise<ListInstalledSkillsResponse> {
+    return await this.requestJson<ListInstalledSkillsResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/skills`,
+    );
+  }
+
+  /** Install one exact reviewed curated-library Skill through the Skill domain. */
+  async installLibrarySkill(
     workspaceId: string,
-    capabilityId: string,
-    request: EnableCapabilityRequest = {},
-  ): Promise<CapabilityInstallation> {
-    return await this.requestJson<CapabilityInstallation>(
+    libraryId: string,
+    request: InstallLibrarySkillRequest,
+  ): Promise<InstalledSkill> {
+    return await this.requestJson<InstalledSkill>(
       "POST",
-      `/v1/workspaces/${workspaceId}/capabilities/${encodeURIComponent(capabilityId)}/enable`,
+      `/v1/workspaces/${workspaceId}/skills/library/${encodeURIComponent(libraryId)}/install`,
       request,
     );
   }
 
-  async disableCapability(
+  async previewSkillUninstall(
     workspaceId: string,
     capabilityId: string,
-  ): Promise<CapabilityInstallation> {
-    return await this.requestJson<CapabilityInstallation>(
-      "POST",
-      `/v1/workspaces/${workspaceId}/capabilities/${encodeURIComponent(capabilityId)}/disable`,
+  ): Promise<SkillUninstallPreview> {
+    return await this.requestJson<SkillUninstallPreview>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/skills/${encodeURIComponent(capabilityId)}/uninstall-preview`,
     );
   }
 
-  /** Search the official MCP registry for installable capabilities. */
-  async discoverMcpCapabilities(
+  /** Remove the direct owner under an optimistic installation-version fence. */
+  async uninstallSkill(
     workspaceId: string,
-    options: { query?: string; limit?: number } = {},
-  ): Promise<DiscoverMcpCapabilitiesResponse> {
-    return await this.requestJson<DiscoverMcpCapabilitiesResponse>(
-      "GET",
-      `/v1/workspaces/${workspaceId}/capabilities/discovery/mcp-registry`,
-      undefined,
-      {
-        ...(options.query !== undefined ? { query: options.query } : {}),
-        ...(options.limit !== undefined ? { limit: String(options.limit) } : {}),
-      },
+    capabilityId: string,
+    request: UninstallSkillRequest,
+  ): Promise<UninstallSkillResult> {
+    return await this.requestJson<UninstallSkillResult>(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/skills/${encodeURIComponent(capabilityId)}`,
+      request,
     );
   }
 
@@ -3492,6 +5389,15 @@ export class OpenGeniClient {
     return response.connections;
   }
 
+  /** List the secret-free Slack team -> OpenGeni tenant routing authority. */
+  async listSlackInstallationBindings(workspaceId: string): Promise<SlackInstallationBinding[]> {
+    const response = await this.requestJson<ListSlackInstallationBindingsResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/connections/slack-bot/bindings`,
+    );
+    return response.bindings;
+  }
+
   async createConnection(
     workspaceId: string,
     request: CreateConnectionRequest,
@@ -3504,6 +5410,34 @@ export class OpenGeniClient {
     return response.connection;
   }
 
+  /**
+   * Verify a pasted Fiken personal API token and store it as the
+   * workspace-shared Fiken connection (or rewrite an existing one in place).
+   */
+  async installFikenConnection(
+    workspaceId: string,
+    request: FikenInstallRequest,
+  ): Promise<ConnectionMetadata> {
+    const response = await this.requestJson<ConnectionResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/connections/fiken/install`,
+      request,
+    );
+    return response.connection;
+  }
+
+  /** Start the Fiken OAuth flow for the workspace-shared Fiken connection. */
+  async startFikenOAuth(
+    workspaceId: string,
+    request: FikenOAuthStartRequest = {},
+  ): Promise<FikenOAuthStartResponse> {
+    return await this.requestJson<FikenOAuthStartResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/connections/fiken/oauth/start`,
+      request,
+    );
+  }
+
   /** Start the public Slack installation flow for the workspace-shared OpenGeni bot. */
   async startOpenGeniSlackBotInstall(
     workspaceId: string,
@@ -3634,8 +5568,16 @@ export class OpenGeniClient {
   // --- GitHub ----------------------------------------------------------------------------------
 
   /** GitHub App server configuration plus truthful workspace binding status. */
-  async getGitHubApp(workspaceId: string): Promise<GitHubAppInfo> {
-    return await this.requestJson<GitHubAppInfo>("GET", `/v1/workspaces/${workspaceId}/github/app`);
+  async getGitHubApp(
+    workspaceId: string,
+    options: { returnPath?: string } = {},
+  ): Promise<GitHubAppInfo> {
+    return await this.requestJson<GitHubAppInfo>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/github/app`,
+      undefined,
+      options.returnPath ? { returnPath: options.returnPath } : undefined,
+    );
   }
 
   /** Build the GitHub owner-consent entry URL for fresh workspace-bound state. */
@@ -3955,7 +5897,99 @@ export class OpenGeniClient {
     );
   }
 
-  protected async requestJson<T>(
+  // --- SuperGrok/xAI connected subscriptions ------------------------------------------------------
+
+  async supergrokStatus(workspaceId: string): Promise<SuperGrokConnectionStatus> {
+    return await this.requestJson<SuperGrokConnectionStatus>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/supergrok/status`,
+    );
+  }
+
+  async supergrokConnectStart(
+    workspaceId: string,
+    scope: SuperGrokAccountScope = "workspace",
+  ): Promise<SuperGrokConnectStart> {
+    return await this.requestJson<SuperGrokConnectStart>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/supergrok/connect/start`,
+      { scope },
+    );
+  }
+
+  async supergrokConnectPoll(workspaceId: string, state: string): Promise<SuperGrokConnectPoll> {
+    return await this.requestJson<SuperGrokConnectPoll>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/supergrok/connect/poll`,
+      { state },
+    );
+  }
+
+  async listSuperGrokAccounts(workspaceId: string): Promise<SuperGrokAccountsResponse> {
+    return await this.requestJson<SuperGrokAccountsResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/supergrok/accounts`,
+    );
+  }
+
+  async activateSuperGrokAccount(
+    workspaceId: string,
+    accountId: string,
+  ): Promise<{ activated: boolean; accountId: string }> {
+    return await this.requestJson<{ activated: boolean; accountId: string }>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/supergrok/accounts/${accountId}/activate`,
+      {},
+    );
+  }
+
+  async setSuperGrokRotationSettings(
+    workspaceId: string,
+    patch: { rotationEnabled: boolean },
+  ): Promise<SuperGrokRotationSettings> {
+    return await this.requestJson<SuperGrokRotationSettings>(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/supergrok/settings`,
+      patch,
+    );
+  }
+
+  async setSuperGrokAccountAllocator(
+    workspaceId: string,
+    accountId: string,
+    input: { enabled: boolean; expectedVersion: number },
+  ): Promise<SuperGrokAllocatorUpdate> {
+    return await this.requestJson<SuperGrokAllocatorUpdate>(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/supergrok/accounts/${accountId}/allocator`,
+      input,
+    );
+  }
+
+  async renameSuperGrokAccount(
+    workspaceId: string,
+    accountId: string,
+    label: string | null,
+  ): Promise<SuperGrokAccount> {
+    return await this.requestJson<SuperGrokAccount>(
+      "PATCH",
+      `/v1/workspaces/${workspaceId}/supergrok/accounts/${accountId}`,
+      { label },
+    );
+  }
+
+  async disconnectSuperGrokAccount(
+    workspaceId: string,
+    accountId: string,
+  ): Promise<{ disconnected: boolean; newActiveId: string | null }> {
+    return await this.requestJson<{
+      disconnected: boolean;
+      newActiveId: string | null;
+    }>("DELETE", `/v1/workspaces/${workspaceId}/supergrok/accounts/${accountId}`, {});
+  }
+
+  /** Contract-checked JSON transport shared by opt-in typed SDK clients. */
+  async requestJson<T>(
     method: string,
     path: string,
     body?: unknown,
@@ -3996,6 +6030,35 @@ export class OpenGeniClient {
     }
   }
 
+  /** Authenticated, contract-checked response for bounded streaming downloads. */
+  protected async requestResponse(
+    method: string,
+    path: string,
+    query: Record<string, string> = {},
+    options: OpenGeniRequestOptions = {},
+  ): Promise<Response> {
+    const correlationId = crypto.randomUUID();
+    let response: Response;
+    try {
+      response = await this.fetchImpl(this.url(path, query), {
+        method,
+        headers: {
+          ...this.headers(correlationId),
+          Accept: "application/octet-stream",
+        },
+        ...(options.signal ? { signal: options.signal } : {}),
+      });
+    } catch (error) {
+      if (isMutationMethod(method)) throw mutationTransportError(correlationId);
+      throw error;
+    }
+    assertApiContractResponse(response);
+    if (!response.ok) {
+      throw await apiErrorFromResponse(response, { method, correlationId });
+    }
+    return response;
+  }
+
   /** Like `requestJson` for endpoints that respond with no body (204). */
   private async requestVoid(method: string, path: string, body?: unknown): Promise<void> {
     const correlationId = crypto.randomUUID();
@@ -4235,6 +6298,55 @@ async function cancelResponseBody(response: Response, reason: string): Promise<v
   await response.body?.cancel(reason).catch(() => undefined);
 }
 
+function assertRetainedGeneratedImageReceipt(
+  workspaceId: string,
+  artifact: RetainedArtifactReference,
+): void {
+  if (!parseRetainedGeneratedImageReference(artifact, workspaceId)) {
+    throw new OpenGeniApiError(502, "retained generated image receipt is invalid");
+  }
+}
+
+function assertSafeArtifactDownloadUrl(value: FileDownloadUrlResponse): void {
+  if (
+    !value ||
+    typeof value.url !== "string" ||
+    typeof value.expiresAt !== "string" ||
+    !Number.isFinite(Date.parse(value.expiresAt))
+  ) {
+    throw new OpenGeniApiError(502, "retained artifact download URL is invalid");
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(value.url);
+  } catch {
+    throw new OpenGeniApiError(502, "retained artifact download URL is invalid");
+  }
+  if (!["http:", "https:"].includes(parsed.protocol) || parsed.username || parsed.password) {
+    throw new OpenGeniApiError(502, "retained artifact download URL is unsafe");
+  }
+}
+
+function assertSafeVideoArtifactPlaybackSource(
+  value: VideoArtifactPlaybackSource,
+  expectedArtifactId: string,
+): void {
+  if (
+    !value ||
+    value.schemaVersion !== 1 ||
+    value.artifactId !== expectedArtifactId ||
+    value.contentType !== "video/mp4" ||
+    value.acceptRanges !== "bytes" ||
+    !Number.isSafeInteger(value.sizeBytes) ||
+    value.sizeBytes <= 0 ||
+    value.sizeBytes > GENERATED_VIDEO_MAX_BYTES ||
+    !/^[0-9a-f]{64}$/.test(value.sha256)
+  ) {
+    throw new OpenGeniApiError(502, "generated-video playback source is invalid");
+  }
+  assertSafeArtifactDownloadUrl({ url: value.url, expiresAt: value.expiresAt });
+}
+
 function parseBoundedContentLength(value: string | null): number | null {
   if (value === null) return null;
   if (!/^\d+$/.test(value)) {