unfazed 0.6.0 → 0.8.0

package/schema/schema.graphqls

@@ -1,8 +1,13 @@
+"Incremental fragment delivery over multipart/mixed (deferSpec=20220824)."
+directive @defer(if: Boolean = true, label: String) on FRAGMENT_SPREAD | INLINE_FRAGMENT
+
 scalar File
 scalar JSON
 
 type Function {
   id: ID!
+  "The owning identity. A listing also includes the functions of agents the caller claimed (and, for the operator, every tenant's), so a client that must act only on its own functions keeps those whose ownerId equals whoami.userID. Returned only with a function the caller can already see."
+  ownerId: ID!
   name: String!
   filename: String!
   sizeBytes: Int!
@@ -11,6 +16,25 @@ type Function {
   bundled: Boolean!
 }
 
+"Durable registration metadata. A published resource can still be awaiting job cleanup; settled distinguishes that case. No worker credentials or source paths are exposed."
+type FunctionRegistration {
+  id: ID!
+  name: String!
+  createdAt: String!
+  "pending, published, failed, cancelled, rejected or unavailable."
+  state: String!
+  phase: String!
+  code: String
+  settled: Boolean!
+  canResume: Boolean!
+  cancelRequested: Boolean!
+}
+
+type FunctionRegistrationPage {
+  items: [FunctionRegistration!]!
+  nextCursor: ID
+}
+
 enum DeploymentKind {
   STATIC
   SERVICE
@@ -58,6 +82,7 @@ enum DeploymentEventType {
   SERVICE_VM_STARTED
   SERVICE_VM_STOPPED
   SERVICE_CRON_TRIGGERED
+  SERVICE_VM_CRASHED
 }
 
 enum DeploymentEventSeverity {
@@ -67,23 +92,84 @@ enum DeploymentEventSeverity {
 }
 
 type Workspace {
+  "Write-only secrets are returned with null values, as in workspaceEnv."
+  environment: [WorkspaceEnvVar!]
+  "Value-free connections shared with this workspace's project."
+  sharedConnections: [IntegrationConnection!]
   id: ID!
   name: String!
   "Who owns this source. The listing includes the sources of agents the caller claimed, so this is how a client tells its own from an agent's: it matches one of whoami.linkedAgents[].agentID for the latter. Operations that require a DIRECTLY owned source — alias adoption targets — must filter on it."
   ownerId: ID!
   "The owner-defined project this app is grouped under (dashboard organization only); null when ungrouped."
   projectId: ID
+  "The containing project, when visible to the caller; null when ungrouped."
+  project: Project
   gitSource: GitSource
+  "Platform git for this app; null where the installation runs no platform git."
+  platformGit: WorkspacePlatformGit
+  "Every environment of this workspace's git repo — the main app first — including this workspace. Empty when the workspace is not git-linked."
+  repoEnvironments: [RepoEnvironment!]!
+  "The apps this workspace serves right now, by alias: everything deleteWorkspace withDeployments would take offline, and the exact list its confirmAliases must name. Domains are listed for the app's owner only."
+  liveApps: [LiveApp!]!
+  "Apps deleted with deleteApp while the workspace is git-linked. Pushes and syncs skip them while unfazed.json apps[] still declares them; removing them from apps[] clears this, and syncRepo restoreApps brings one back."
+  deletedApps: [DeletedApp!]!
   createdAt: String!
   updatedAt: String!
 }
 
+"An app (alias) a workspace or an API client serves right now, with the custom domains routing to it."
+type LiveApp {
+  alias: String!
+  "The deployment serving the alias."
+  deploymentID: ID!
+  "Custom domains that stop serving with the app; empty for a caller who does not own it."
+  domains: [String!]!
+}
+
+"An app deleted with deleteApp from a git-linked workspace (Workspace.deletedApps)."
+type DeletedApp {
+  alias: String!
+  deletedAt: String!
+  "The newest commit whose import skipped the app because unfazed.json apps[] still declared it; null until one did."
+  skippedCommit: String
+  skippedAt: String
+}
+
+"An app's platform git, as the caller sees it."
+type WorkspacePlatformGit {
+  "The git server, e.g. https://git.unfz.to. A person signs git in to it once with <url>/install.sh."
+  url: String!
+  "The app's repository by alias, e.g. https://git.unfz.to/<alias>.git, while the app deploys from it; null otherwise."
+  cloneURL: String
+  "Whether the caller may turn it on (enablePlatformGit): the app's owner and the platform operator. Team members may not, though they clone and push once it is on."
+  canEnable: Boolean!
+  "Whether apps without a repository get platform git by themselves at their next change (a file write or a deploy) once they serve."
+  byDefault: Boolean!
+  "Why this app does not get platform git by itself (its owner turned it off, or what enablePlatformGit would refuse); null when it will, or has it."
+  offReason: String
+}
+
+"One environment of a git-linked repo: the main app, or a sibling workspace that deploys another branch to its own aliases."
+type RepoEnvironment {
+  workspace: Workspace!
+  "The environment name, e.g. staging; null for the main app."
+  name: String
+  branch: String!
+  lastImportStatus: String!
+  "Where the environment is opened: its serving app, else its latest deployment attempt; null before the first one exists."
+  deployment: Deployment
+}
+
 "A project groups an owner's apps under a human-chosen name. Purely a dashboard organization layer: it does not affect app URLs or aliases, and is never exposed to agents."
 type Project {
   id: ID!
   name: String!
-  "The owning identity (github:<login>); the dashboard uses it to tell own projects from team-shared ones."
+  "The owning identity. Visibility through a team does not grant ownership."
   owner: String!
+  "Display name of the owning human account, resolving a linked agent to its claimer. Unclaimed agents display as Unclaimed account."
+  ownerName: String!
+  "Whether the caller may rename, delete or share this project."
+  canManage: Boolean!
   createdAt: String!
   updatedAt: String!
 }
@@ -136,13 +222,14 @@ type TeamSharedProject {
 
 type TeamMember {
   userID: String!
-  "Bare github login for display."
+  "The member's handle (a GitHub login, a display name, or the words Google account), never an email address (docs/access-control.md)."
   name: String!
   role: String!
   addedAt: String!
 }
 
 type TeamInvite {
+  "Stable opaque recipient key for cancellation. An email invitation key is not an account ID, even after sign-in."
   userID: String!
   name: String!
   invitedBy: String!
@@ -154,7 +241,7 @@ type TeamEvent {
   at: String!
   actor: String!
   actorName: String!
-  "created | renamed | invited | invite_cancelled | invite_declined | joined | member_removed | member_left"
+  "created | renamed | invited | invite_bound | invite_cancelled | invite_declined | joined | member_removed | member_left"
   action: String!
   subject: String
   subjectName: String
@@ -184,12 +271,13 @@ input TeamIDInput {
 
 input TeamInviteInput {
   teamID: ID!
-  "GitHub login to invite, with or without a leading @."
+  "GitHub login (optional leading @) or Gmail/Google Workspace email. Google invitations appear after the recipient signs in with that verified address; no email is sent."
   login: String!
 }
 
 input TeamMemberInput {
   teamID: ID!
+  "Account ID for member operations; use TeamInvite.userID unchanged when cancelling an invitation."
   userID: String!
 }
 
@@ -202,13 +290,125 @@ type TeamPayload {
   team: Team!
 }
 
-"A BYO custom domain attached to an app's alias. The edge issues its TLS cert (Let's Encrypt) once active; requests to the domain serve the app."
+"A BYO custom domain attached to an app's alias. The edge issues its TLS cert once active; requests to the domain serve the app."
 type CustomDomain {
   domain: String!
   alias: String!
   "True once the platform allows the edge to issue a cert and route the domain."
   active: Boolean!
   createdAt: String!
+  "The DNS records to create for this domain: where to point it, plus any verification record the edge still asks for. A record with recommended=false is an alternative to a recommended one, not an addition."
+  dnsRecords: [DNSRecord!]!
+  "The domain's hostname at the edge (Cloudflare for SaaS) as of the platform's last check; null while the platform does not manage one."
+  status: CustomDomainStatus
+  "How far the domain is from serving, in one word and one sentence, as of the platform's last check."
+  activation: CustomDomainActivation!
+}
+
+"A custom domain's activation state."
+enum CustomDomainState {
+  "Cloudflare is verifying the domain or issuing its certificate: usually 1–5 minutes, during which it answers the domain with \"error code: 1014\". Nothing to do unless it lasts longer than 15 minutes."
+  ACTIVATING
+  "Cloudflare has not seen the domain point at the platform for longer than activation takes, or it stopped pointing there: create or fix its CNAME."
+  DNS_MISSING
+  "Served over HTTPS."
+  ACTIVE
+  "Refused, timed out, or still not active long after activation should have finished; the message says why."
+  FAILED
+}
+
+"How far a custom domain is from serving."
+type CustomDomainActivation {
+  state: CustomDomainState!
+  "One sentence for a person or an agent: what is happening, and what to do if anything."
+  message: String!
+  "When the current activation step started (RFC 3339); null once active or when unknown."
+  since: String
+}
+
+"How far a custom domain is from serving over HTTPS at the edge."
+type CustomDomainStatus {
+  "The edge's hostname status, e.g. pending, active, blocked; \"registering\" before the hostname exists."
+  status: String!
+  "The certificate's status, e.g. initializing, pending_validation, pending_issuance, active; empty before the hostname exists."
+  sslStatus: String!
+  "True once the hostname and its certificate are both active."
+  live: Boolean!
+  "Why the domain is not live yet: verification and certificate validation errors from the edge, and the platform's own when it could not register the domain."
+  errors: [String!]!
+}
+
+"""
+A hostname of the caller's that serves an app besides its own <alias> URL:
+a custom domain attached to the app's alias, or the domain of a site an
+integration publishes the app to.
+"""
+type AppDomain {
+  "The hostname, e.g. app.example.com."
+  domain: String!
+  "Serves the app over HTTPS now."
+  live: Boolean!
+  "How far the domain is from serving (a published site's domain is ACTIVE)."
+  state: CustomDomainState!
+  "What a domain that is not live yet waits for; null once it is live."
+  pending: AppDomainPending @deprecated(reason: "Use state.")
+}
+
+enum AppDomainPending {
+  "Its DNS: the records its owner creates at their DNS provider (Configuration → Domains lists them)."
+  DNS
+  "Its certificate, being issued now that the DNS resolves."
+  CERTIFICATE
+}
+
+"A DNS record a custom domain's owner creates at their DNS provider."
+type DNSRecord {
+  "Record type: CNAME, A, or TXT."
+  type: String!
+  "The record's hostname: the custom domain itself, or a verification name under it."
+  name: String!
+  "What the record points at, or the TXT value."
+  content: String!
+  "True when the record must be proxied by Cloudflare; false when it need not be (the note says whether it must be DNS only)."
+  proxied: Boolean!
+  "True for a record to create; false for an alternative to it."
+  recommended: Boolean!
+  "When this record applies."
+  note: String!
+}
+
+"""
+A provider a person can sign in with, as their account settings show it. The
+dashboard renders the list as given; it knows no provider by name. Linking
+and unlinking are same-origin form posts to linkURL and unlinkURL.
+"""
+type SignInMethod {
+  provider: String!
+  label: String!
+  iconURL: String!
+  "Whether a sign-in from this provider reaches the account."
+  linked: Boolean!
+  "The linked login or address, as the provider last reported it."
+  handle: String
+  "Whether unlinking is offered: never for the account's only sign-in."
+  canUnlink: Boolean!
+  linkURL: String!
+  unlinkURL: String!
+}
+
+"""
+A computer whose git is signed in to platform git with this account
+(git-credential-unfazed, approved in the browser). Signing it out is a
+same-origin form post to signOutURL.
+"""
+type GitSignIn {
+  id: ID!
+  "What the computer called itself when it asked; not verified."
+  name: String!
+  createdAt: String!
+  "When it last renewed its git token (about hourly while git is used)."
+  lastUsedAt: String!
+  signOutURL: String!
 }
 
 "A public key that may authenticate to the box SSH gateway. Public keys are not secrets, so the fingerprint and type are shown in full."
@@ -244,6 +444,19 @@ input RemoveCustomDomainInput {
   domain: String!
 }
 
+input MoveCustomDomainInput {
+  domain: String!
+  "The alias of the app the domain serves from now on."
+  alias: String!
+}
+
+"An app a custom domain may move to (moveCustomDomain)."
+type CustomDomainMoveTarget {
+  alias: String!
+  "The app's name."
+  name: String!
+}
+
 type GitSource {
   provider: String!
   repo: String!
@@ -259,8 +472,10 @@ type GitSource {
   lastImportError: String
   webhookURL: String
   webhookSecret: String
-  "When set, the auto-deploy webhook has been registered on the GitHub repo (RFC3339)."
+  "When set, the auto-deploy webhook has been registered on the source repo (RFC3339)."
   webhookInstalledAt: String
+  "The environment this link deploys (e.g. staging); null for the repo's main app."
+  environment: String
 }
 
 type GitHubTokenStatus {
@@ -339,6 +554,22 @@ type AppEnvScope {
 }
 
 type Deployment {
+  "Whether the caller may create a guest feedback link for this app."
+  canShareReview: Boolean!
+  "Whether the app keeps its own platform git history (appCommits); false while platform git is off and for apps linked to another repository."
+  gitHistory: Boolean!
+  "The caller's custom hostnames serving this app (AppDomain), custom domains oldest first, then published sites'. Empty for a release that does not hold its alias. Custom domains are the app owner's: team members see none of them."
+  domains: [AppDomain!]!
+  workspace: Workspace
+  "Runs visible to the caller in this deployment's workspace."
+  runs(limit: Int = 20, offset: Int = 0): RunPage
+  "Effective environment for this app alias; secret values stay write-only."
+  environment: [WorkspaceEnvVar!]
+  releases: [DeploymentRelease!]
+  events(limit: Int = 20, offset: Int = 0): DeploymentEventPage
+  "Null for deployments that are not services. Errors stay within this field."
+  runtimeStatus: ServiceRuntimeStatus
+  runtimeLogs(tailBytes: Int = 16384): ServiceRuntimeLogs
   id: ID!
   workspaceID: ID!
   kind: DeploymentKind!
@@ -375,6 +606,20 @@ type Deployment {
   worker: DeploymentWorker
 }
 
+"A release summary. History cannot recursively expand the same history."
+type DeploymentRelease {
+  id: ID!
+  aliasHeld: Boolean!
+  aliasRevision: String!
+  status: DeploymentStatus!
+  error: String
+  serviceMode: ServiceMode!
+  previewUrl: String!
+  gitCommit: String
+  size: String!
+  createdAt: String!
+}
+
 "The authoritative runtime target assigned to a current deployment."
 type DeploymentWorker {
   id: String!
@@ -412,6 +657,42 @@ type ServiceRuntimeStatus {
   lastStoppedAt: String
   restartCount: Int!
   lastError: String
+  """
+  The app's recent crashes on its server: its VM stopped without being asked
+  to. Null when it has had none since that server's runtime last started.
+  """
+  crashes: ServiceCrashes
+  "True when the app's server tracks its crashes, so a null crashes means none; false for a server runtime that predates crash tracking, and for boxes."
+  crashesTracked: Boolean!
+}
+
+"Recent crashes of a service on the server that runs it."
+type ServiceCrashes {
+  "At least 3 crashes within the last hour."
+  looping: Boolean!
+  lastHour: Int!
+  last24h: Int!
+  "Crashes since the server's runtime last started."
+  total: Int!
+  "Newest first, at most 5; only the newest carries logTail."
+  recent: [ServiceCrash!]!
+}
+
+"One unexpected stop of a service's VM."
+type ServiceCrash {
+  at: String!
+  vmID: String
+  "running (the VM was serving) or starting (the app failed before it was ready)."
+  phase: String!
+  "app_exit, app_signal, out_of_memory, kernel_panic, guest_stopped, unknown, health_check, host_killed or vm_error."
+  cause: String!
+  "The app process's exit status (128+signal when a signal ended it), when its VM reported it."
+  exitCode: Int
+  signal: String
+  "One line saying what happened."
+  message: String!
+  "The last lines of the VM's console before it stopped (the app's output, secrets redacted)."
+  logTail: String
 }
 
 type ServiceRuntimeLogs {
@@ -445,6 +726,8 @@ type IntegrationKind {
   kind: String!
   label: String!
   iconURL: String
+  "Lowercase catalog grouping labels: ai, database, observability, …"
+  tags: [String!]!
   # who supplies the backend: "platform" (unfazed runs it) or "user" (BYO)
   provenance: String!
   # how the owner connects: "none" (no connection), "fields" (a form), "link" (an auth flow)
@@ -458,7 +741,55 @@ type IntegrationKind {
   "Safe isolation mode selected when bindIntegration omits mode; null for providers without app runtime."
   defaultMode: String
   runtime: IntegrationRuntime!
+  "Tools and skills this provider contributes to a bound app's bot tasks. No credentials or server endpoints."
+  agent: IntegrationAgent!
   surfaces: [IntegrationSurface!]!
+  "True when the provider can read what one scoped binding's per-app resource consumed (integrationBindingUsage)."
+  reportsUsage: Boolean!
+  "Choices the owner makes when binding this kind to an app (bindIntegration options), e.g. what a git environment's database starts with. Empty for most kinds."
+  bindOptions: [IntegrationBindOption!]!
+}
+"A provider-declared choice made once, at bind time, about how the app's resource is created. A resource that already exists is kept whatever the choice."
+type IntegrationBindOption {
+  name: String!
+  label: String!
+  description: String!
+  "Which apps the option exists for: app (every app) or environment (only a git environment of another app). Elsewhere bindIntegration refuses it."
+  appliesTo: String!
+  "The value recorded when bindIntegration omits the option."
+  default: String!
+  choices: [IntegrationBindChoice!]!
+}
+type IntegrationBindChoice {
+  value: String!
+  label: String!
+  description: String!
+  "What the owner must know before choosing this value (e.g. that it copies production data); null when nothing."
+  warning: String
+}
+"One bind option value of a binding."
+type IntegrationBindOptionValue {
+  name: String!
+  value: String!
+  "True when the binding predates the option: nothing was chosen or recorded, and value is what such bindings were created with."
+  legacy: Boolean!
+}
+input IntegrationBindOptionInput {
+  name: String!
+  value: String!
+}
+type IntegrationAgent {
+  revision: String!
+  servers: [IntegrationAgentServer!]!
+  skills: [String!]!
+}
+type IntegrationAgentServer {
+  name: String!
+  description: String!
+  transport: String!
+  auth: String!
+  readTools: [String!]!
+  writeTools: [String!]!
 }
 type IntegrationSurface {
   id: String!
@@ -501,6 +832,18 @@ type IntegrationConnection {
   grantedProjectIDs: [ID!]!
   createdAt: String!
   updatedAt: String!
+  "OAuth state of the kind's MCP server (null for kinds without one): runs get the server only while it is active."
+  authorization: IntegrationConnectionAuthorization
+}
+"The owner's OAuth grant for a connection's MCP server. The platform is the OAuth client; tokens stay on the control plane."
+type IntegrationConnectionAuthorization {
+  "required (no usable grant), active, or failed (the server refused a refresh; authorize again)"
+  status: String!
+  "The protected resource: the MCP endpoint the grant is for."
+  resource: String!
+  scopes: [String!]!
+  authorizedAt: String
+  error: String
 }
 type IntegrationFieldValue {
   name: String!
@@ -524,17 +867,59 @@ type IntegrationBinding {
   status: String!
   "Set when the binding rides a GRANTED connection: the lender's identity. The lender can always see and sever such bindings."
   connectionOwner: String
+  "True when integrationBindingUsage can answer for this binding: an active scoped binding of a usage-reporting kind. Passthrough bindings never report usage — a shared credential's spend belongs to no one app."
+  reportsUsage: Boolean!
+  "The binding's bind options: chosen or defaulted at bind time, or, for a binding recorded before an option existed, the value such bindings were created with (legacy). Empty for most kinds."
+  options: [IntegrationBindOptionValue!]!
+  "Warnings of the recorded options, e.g. that the environment's database is a copy of production data with every setting stored in it. Empty for most bindings."
+  warnings: [String!]!
+  "True when the signed-in caller can mint this binding's one-time .env reveal now (revealIntegrationEnv): the binding is active and carries credentials, the caller owns the app, and no reveal was ever issued for it (bindings older than 30 days never qualify)."
+  revealAvailable: Boolean!
+}
+"What one binding's per-app resource consumed, read from the provider's own accounting and cached for about a minute. Figures, labels and units are the provider's and are shown as-is."
+type IntegrationUsage {
+  bindingID: ID!
+  kind: String!
+  "Start of the window the figures cover (RFC3339); null means since the resource was created."
+  periodStart: String
+  "End of the window (RFC3339); null means now."
+  periodEnd: String
+  metrics: [IntegrationUsageMetric!]!
+  "Optional https link to this app's resource in the provider's console."
+  consoleURL: String
+  "When unfazed read these figures from the provider (RFC3339)."
+  fetchedAt: String!
+  "Why the figures are unavailable (the provider failed, timed out or reported malformed data); null on success. Never carries credential values."
+  error: String
+}
+type IntegrationUsageMetric {
+  "Stable machine name, e.g. compute_hours."
+  name: String!
+  label: String!
+  value: Float!
+  "Display unit; may be empty for plain counts."
+  unit: String!
+  "Optional cap configured for this app, in the same unit."
+  limit: Float
 }
 type IntegrationConnectionPayload {
   connection: IntegrationConnection!
 }
 type IntegrationBindingPayload {
   binding: IntegrationBinding!
-  "One-time command (curl) that prints THIS binding's freshly minted credentials as .env lines, exactly once. Present only in the bind response for credential-carrying bindings; it can never be re-issued — only its hash is stored."
+  "One-time command (curl) that prints THIS binding's credentials as .env lines, exactly once. Present in the bind response for an active credential-carrying binding whose single reveal was not issued yet; a binding that becomes active later gets it once from revealIntegrationEnv. Never issued twice — only its hash is stored."
   revealCommand: String
   "RFC3339 time the unused reveal stops working."
   revealExpiresAt: String
 }
+"The single one-time .env reveal of one binding, minted by revealIntegrationEnv."
+type IntegrationEnvReveal {
+  binding: IntegrationBinding!
+  "One-time command (curl) that prints THIS binding's credentials as .env lines. Whoever runs it consumes it; it is never issued again for this binding."
+  revealCommand: String!
+  "RFC3339 time the unused reveal stops working."
+  revealExpiresAt: String!
+}
 "Account-level non-secret event routing. Credential/runtime grants never use this type."
 type IntegrationSubscription {
   id: ID!
@@ -609,6 +994,142 @@ input BindIntegrationInput {
   alias: String!
   "Optional provider-supported isolation mode. Omit to use the provider's safe default (scoped for Postgres)."
   mode: String
+  "Choices for the kind's bindOptions, by name. Omitted options take their default; an option the app does not take (e.g. an environment-only option on a main app) is refused."
+  options: [IntegrationBindOptionInput!]
+}
+"The account's chosen model-provider connection for one harness (docs/run-design.md phase 12 step 2). connectionName and kind are omitted when the referenced connection was since deleted."
+type RunHarnessSetting {
+  harness: String!
+  connectionID: ID!
+  connectionName: String
+  kind: String
+  model: String
+  updatedAt: String!
+}
+type RunHarnessSettingPayload {
+  setting: RunHarnessSetting!
+}
+"A named run bundle (docs/run-design.md phase 12 step 3): base harness, optional provider connection + model, extra env. A preset picks a CONNECTION, never carries a key; an env value may reference a workspace name as \"$NAME\", resolved when a run is created."
+type RunPreset {
+  name: String!
+  description: String!
+  harness: String!
+  connectionID: ID
+  "Set when the referenced connection still exists: its display name and kind."
+  connectionName: String
+  kind: String
+  model: String
+  env: [RunPresetEnv!]!
+  createdAt: String!
+  updatedAt: String!
+}
+type RunPresetEnv {
+  name: String!
+  value: String!
+}
+type RunPresetPayload {
+  preset: RunPreset!
+}
+input RunPresetEnvInput {
+  name: String!
+  value: String!
+}
+input SaveRunPresetInput {
+  name: String!
+  description: String
+  harness: String!
+  connectionID: ID
+  model: String
+  env: [RunPresetEnvInput!]
+}
+input DeleteRunPresetInput {
+  name: String!
+}
+"An account-level run trigger (docs/run-design.md phase 13): an inbound webhook event becomes an agent run. The secret authenticates deliveries; it is returned only by runTriggerSecret."
+type RunTrigger {
+  id: ID!
+  name: String!
+  enabled: Boolean!
+  "\"webhook\" (generic HMAC/bearer) or \"github\" (X-Hub-Signature-256)."
+  source: String!
+  "Event names that fire (github: X-GitHub-Event); empty fires on every event."
+  filter: [String!]!
+  template: RunTriggerTemplate!
+  cooldownSeconds: Int!
+  "Allow parallel firings; off = one at a time, later firings queue (owner decision D3)."
+  allowParallel: Boolean!
+  "The POST endpoint to configure at the sender: /hooks/runs/{id}."
+  hookPath: String!
+  "Recent firings, newest first."
+  firings: [RunTriggerFiring!]!
+  "Firings waiting for a slot (cooldown or a still-running previous firing)."
+  queued: Int!
+  createdAt: String!
+  updatedAt: String!
+}
+type RunTriggerTemplate {
+  workspaceID: ID!
+  alias: String
+  harness: String
+  preset: String
+  "May hold {{event.<dotted.path>}} placeholders, interpolated from the JSON payload."
+  prompt: String!
+  access: String
+  maxSeconds: Int
+  metadata: JSON
+}
+type RunTriggerFiring {
+  id: ID!
+  at: String!
+  "started | queued | skipped | failed | expired"
+  status: String!
+  summary: String
+  runID: ID
+  reason: String
+}
+type RunTriggerPayload {
+  trigger: RunTrigger!
+}
+input RunTriggerTemplateInput {
+  workspaceID: ID!
+  alias: String
+  harness: String
+  preset: String
+  prompt: String!
+  access: String
+  maxSeconds: Int
+  metadata: JSON
+}
+input SaveRunTriggerInput {
+  "Empty creates; a set id updates that trigger."
+  id: ID
+  name: String!
+  enabled: Boolean!
+  source: String!
+  "Empty keeps the existing secret (a fresh one is generated on create); set replaces it."
+  secret: String
+  filter: [String!]
+  template: RunTriggerTemplateInput!
+  cooldownSeconds: Int
+  allowParallel: Boolean
+}
+input RunTriggerIDInput {
+  id: ID!
+}
+input SetRunHarnessProviderInput {
+  harness: String!
+  connectionID: ID!
+  model: String
+}
+input ClearRunHarnessProviderInput {
+  harness: String!
+}
+"One of the caller's own connections eligible to back a harness: its kind implements harness credentials and actually serves this one."
+type RunHarnessProviderChoice {
+  harness: String!
+  connectionID: ID!
+  name: String!
+  kind: String!
 }
 input IntegrationIDInput {
   id: ID!
@@ -681,6 +1202,8 @@ type DeploymentEventPage {
 type Invocation {
   id: ID!
   functionID: ID!
+  "True while the original invocation is unfinished. Query functionInvocation with this ID; do not start a new invocation to check its outcome."
+  pending: Boolean!
   ok: Boolean!
   result: JSON
   stdout: String!
@@ -696,7 +1219,7 @@ enum CurrentActorKind {
   OWNER
   "An automated caller using a self-registered bearer token. Subject to free-tier usage/resource limits; a user can claim it to link it to their account."
   AGENT
-  "A human signed in via GitHub OAuth, who manages their linked agents and apps."
+  "A human signed in via an enabled identity provider, who manages their linked agents and apps."
   USER
 }
 
@@ -714,20 +1237,115 @@ type CurrentActorResources {
 }
 
 """
-Per-owner compute usage for the current calendar month (docs/run-design.md,
-"Metering (phase 0, ships alone)"): VM-seconds and MiB-seconds accrued across
-every VM the runner has booted for this owner (service, box), keyed on the raw
-owner id. No pricing, no currency — a price is a presentation decision made
-later, on top of these raw numbers. Populated for both humans (session
-callers) and agents, unlike `usage`/`resources` above, which are agent-only.
+Recorded compute for the caller's raw owner ID in the current UTC calendar
+month. Linked API identities retain separate ownership and are not included.
+This is metering, not an invoice: no prices or charges are calculated. Running
+VMs may await an hourly checkpoint; builds, storage, network and provider API
+usage are not included. Null means the ledger could not be read.
 """
 type CurrentActorCompute {
   seconds: Float!
   mibSeconds: Float!
   since: String!
   until: String!
+  "When this ledger snapshot was read, in UTC."
+  generatedAt: String!
+  "Latest recorded activity in the period, not a completeness watermark."
+  lastRecordedAt: String
+  "Corrupt, conflicting, or memory-less records make this report incomplete."
+  incomplete: Boolean!
+  byMode: [ComputeModeUsage!]!
 }
 
+type ComputeModeUsage {
+  mode: String!
+  seconds: Float!
+  mibSeconds: Float!
+}
+
+"An agent (docs/agents-design.md): a long-lived worker with a name and a job whose setup a run inherits. It owns a hidden workspace with its computer, a BOX deployment, in it."
+type Agent {
+  id: ID!
+  ownerId: ID!
+  name: String!
+  "The one-line role under the name."
+  job: String!
+  "Standing rules the harness is given on every run; never sent as a task."
+  description: String!
+  "The agent's own workspace (hidden from the apps lists): its env and secrets, the home of its computer."
+  workspaceID: ID!
+  "The alias of the agent's computer (its SSH user name); null until it exists."
+  boxAlias: String
+  "The agent's computer: the newest BOX deployment in its workspace (BUILDING while it starts, FAILED when its build failed)."
+  computer: Deployment
+  "The harness a run of this agent uses; null means the node's first catalogue entry."
+  harness: String
+  "The provider connection backing its runs; null means the account's per-harness setting."
+  connectionID: ID
+  "Set when the referenced connection still exists: its display name and kind."
+  connectionName: String
+  kind: String
+  model: String
+  "read-only or read-write: what a run of this agent may do."
+  access: String!
+  "\"human\" routes the harness's guarded actions to a person; empty keeps the harness's defaults."
+  approval: String!
+  "The workspaces the agent works on; the first supplies a run's files and env until runs execute on the agent's computer."
+  scopeWorkspaceIDs: [ID!]!
+  "Remembered \"always\" answers to permission questions of this agent's runs: a tool name, a whole MCP server (mcp__postgres), or a tool with an input prefix (Bash(git push:*))."
+  allowedTools: [String!]!
+  "Derived on the server from the newest run and the computer, so every surface agrees."
+  state: AgentState!
+  "One line about the state: the current task, the pending question, or what failed."
+  stateDetail: String!
+  "The agent's newest run, whoever messaged it."
+  lastRun: Run
+  createdAt: String!
+  updatedAt: String!
+}
+"What an agent is doing: STARTING (computer being made), IDLE, WORKING (a run in flight), NEEDS_YOU (a run waits for an answer), ASLEEP (computer stopped), FAILED (the computer or the last run)."
+enum AgentState {
+  STARTING
+  IDLE
+  WORKING
+  NEEDS_YOU
+  ASLEEP
+  FAILED
+}
+type AgentPayload {
+  agent: Agent!
+}
+input CreateAgentInput {
+  name: String!
+  job: String
+  description: String
+  harness: String
+  connectionID: ID
+  model: String
+  access: String
+  approval: String
+  scopeWorkspaceIDs: [ID!]
+  "The computer's size; omitted uses the platform defaults."
+  boxResources: BoxResourcesInput
+}
+input UpdateAgentInput {
+  id: ID!
+  name: String
+  job: String
+  description: String
+  harness: String
+  connectionID: ID
+  model: String
+  access: String
+  approval: String
+  "Replaces the scope when given; an empty list clears it."
+  scopeWorkspaceIDs: [ID!]
+  "Replaces the remembered permission rules when given; an empty list forgets them all."
+  allowedTools: [String!]
+}
+input DeleteAgentInput {
+  id: ID!
+}
 enum RunStatus {
   QUEUED
   RUNNING
@@ -753,13 +1371,22 @@ that executed one task and was destroyed when it exited. Deployments answer
 "what is running"; runs answer "what happened".
 """
 type Run {
+  "Source workspace and its current alias holders, when still visible."
+  source: RunSource
+  events(limit: Int = 100): [RunEvent!]
+  console(tailBytes: Int = 16384): RunConsole
+  transcript(tailBytes: Int = 16384): RunTranscript
   id: ID!
   workspaceID: ID!
+  "The agent this run is a task of (docs/agents-design.md); null for a plain app run."
+  agentID: ID
   ownerId: ID!
   status: RunStatus!
   rawStatus: String!
   command: String
   harness: String
+  "The preset this run was created from (display-only; resolved at creation)."
+  preset: String
   prompt: String
   setup: [String!]!
   skills: [String!]!
@@ -800,6 +1427,19 @@ type Run {
   settledAt: String
 }
 
+"A terminal source summary: run navigation cannot recursively expand runs."
+type RunSource {
+  id: ID!
+  name: String!
+  deployments: [RunSourceDeployment!]!
+}
+
+type RunSourceDeployment {
+  id: ID!
+  alias: String
+  createdAt: String!
+}
+
 "One bound integration's contribution to a run. env is the credential set injected: empty (none), read-only or read-write."
 type RunIntegration {
   kind: String!
@@ -892,6 +1532,8 @@ type CurrentActorAgent {
   claimedAt: String
   "Deployments owned by this linked agent. Resolved lazily — only fetched when selected."
   deployments: [Deployment!]!
+  "Every app this agent serves right now, across its workspaces: what deleteLinkedAgent takes offline, and the exact list its confirmAliases must name."
+  liveApps: [LiveApp!]!
 }
 
 type CurrentActor {
@@ -914,11 +1556,160 @@ type CurrentActor {
   linkedAgents: [CurrentActorAgent!]!
 }
 
+"The authenticated account. Nested fields can be delivered independently with @defer."
+type Viewer {
+  availableIntegrations: [IntegrationKind!]
+  integrationConnections: [IntegrationConnection!]
+  integrationSubscriptions: [IntegrationSubscription!]
+  integrationBindings: [IntegrationBinding!]
+  customDomains: [CustomDomain!]
+}
+
+
+"Current app placement without assessing destinations or granting placement authority."
+type PlacementDisplay {
+  current: PlacementCurrent
+  target: PlacementServer
+  blockers: [PlacementBlocker!]!
+}
+"Public metadata for the exact server currently assigned to the app."
+type PlacementServer {
+  id: ID!
+  "CONTROL_PLANE or WORKER."
+  kind: String!
+  name: String!
+  "Empty when the server has no configured region."
+  region: String!
+  incarnation: String!
+}
+
+"Read-only placement metadata. Blockers are observations, never permission to move data."
+type PlacementCatalog {
+  current: PlacementCurrent
+  targets: [PlacementTarget!]!
+  "Regions advertised by the caller's targets, before the optional region filter."
+  regions: [String!]!
+  blockers: [PlacementBlocker!]!
+  "Where a new app would land. Set only when no current app is selected."
+  newApps: PlacementDecision
+}
+"Where a new app lands. The first release starts on the control plane; a WORKER choice then moves the app there with its App State through the ordinary placement move. Existing apps keep their server."
+type PlacementDecision {
+  serverID: String!
+  serverName: String!
+  "CONTROL_PLANE or WORKER."
+  kind: String!
+  region: String!
+  "request, account_default, default or platform."
+  source: String!
+  "The server that was asked for when the app cannot use it; empty otherwise."
+  requested: String!
+  "Why the app stays on the control plane, e.g. worker_disconnected or static_on_control_plane; empty when it lands as chosen."
+  code: String!
+  message: String!
+}
+type PlacementTarget {
+  id: ID!
+  "CONTROL_PLANE or WORKER."
+  kind: String!
+  name: String!
+  "Empty when the server has no configured region."
+  region: String!
+  "Exact installation identity; empty when it is unknown for the default server."
+  incarnation: String!
+  status: String!
+  connected: Boolean!
+  "An authenticated session on a settled runtime release; not a data-admission grant."
+  ready: Boolean!
+  deployBlockers: [PlacementBlocker!]!
+  moveBlockers: [PlacementBlocker!]!
+}
+type PlacementBlocker { code: String!, message: String! }
+type PlacementCurrent {
+  deploymentID: ID!
+  alias: String!
+  aliasRevision: String!
+  "Empty if the exact current placement is unknown."
+  targetID: String!
+  incarnation: String!
+  state: String!
+  blockers: [PlacementBlocker!]!
+}
+input PlacementTargetsInput {
+  workspaceID: ID
+  alias: String
+  deploymentID: ID
+  "Filter exact servers by region; this does not select a regional scheduler."
+  region: String
+}
+
+type PlacementMoveApp { deploymentID: ID!, workspaceID: ID!, alias: String! }
+type PlacementMovePlan {
+  deploymentID: ID!
+  "Public retry key; empty for an older operator-created move."
+  idempotencyKey: String!
+  planDigest: String!
+  targetID: String!
+  targetIncarnation: String!
+  affectedApps: [PlacementMoveApp!]!
+  resourceCount: Int!
+}
+type PlacementMove {
+  id: ID!
+  phase: String!
+  complete: Boolean!
+  running: Boolean!
+  resumable: Boolean!
+  plan: PlacementMovePlan!
+}
+input PlacementMovePlanInput {
+  deploymentID: ID!
+  targetID: String!
+  targetIncarnation: String!
+  idempotencyKey: String!
+}
+input BeginPlacementMoveInput {
+  deploymentID: ID!
+  targetID: String!
+  targetIncarnation: String!
+  idempotencyKey: String!
+  planDigest: String!
+}
+input PlacementMoveStatusInput {
+  deploymentID: ID!
+  idempotencyKey: String
+  moveID: ID
+}
+input RunPlacementMoveInput {
+  deploymentID: ID!
+  idempotencyKey: String
+  moveID: ID!
+}
+
 type Query {
+  "Read-only exact server-move plan for a current app. Ordinary apps need no operator enrollment: App State follows compute and external connections stay unchanged. Existing managed-data pilots retain their shared-data group. Does not reserve or start a move."
+  placementMovePlan(input: PlacementMovePlanInput!): PlacementMovePlan!
+  "Saved move by key/ID; with neither selector, the app's incomplete move. Null is absence, never evidence that a timed-out operation rolled back."
+  placementMove(input: PlacementMoveStatusInput!): PlacementMove
+
+  "Authoritative current server for a visible app, without assessing destination eligibility."
+  deploymentPlacement(deploymentID: ID!): PlacementDisplay
+  "Servers for the caller or an owned app/workspace. Shared-project access alone does not expose another owner's servers. Historical releases have no current placement."
+  placementTargets(input: PlacementTargetsInput): PlacementCatalog!
+  "Where a new app would land for the caller, or for the owner of an owned workspace. Read-only."
+  newAppPlacement(workspaceID: ID): PlacementDecision!
+
+  viewer: Viewer
   whoami: CurrentActor!
   functions: [Function!]!
   functionsPage(input: PageInput): FunctionPage!
   function(id: ID!): Function
+  "Read the caller's saved invocation without executing it again. Requires deploy scope, as invoking does."
+  functionInvocation(id: ID!): Invocation!
+  "Read one visible registration without contacting a worker or starting work."
+  functionRegistration(id: ID!): FunctionRegistration!
+  "Discover saved registrations, including a lost initial response. Ordered by immutable ID; limit 1–100."
+  functionRegistrations(after: ID, limit: Int = 20): FunctionRegistrationPage!
   "Sources visible to the current account: directly owned plus those of linked claimed agents for a user; own for an agent; all for the operator. The same scope as deployments, so an agent's apps can be grouped into the caller's projects."
   workspaces: [Workspace!]!
   "Paginated sources visible to the current account, with the same ownership scope as workspaces."
@@ -932,8 +1723,14 @@ type Query {
   myTeamInvites: [TeamInviteForMe!]!
   "The signed-in owner's BYO custom domains, oldest first."
   customDomains: [CustomDomain!]!
+  "The apps a custom domain of yours may move to (moveCustomDomain), by alias."
+  customDomainMoveTargets(domain: String!): [CustomDomainMoveTarget!]!
   "The signed-in account's SSH public keys — the keys that may open its boxes."
   sshKeys: [SSHKey!]!
+  "The sign-in providers the platform offers, and which of them are linked to the signed-in account."
+  signInMethods: [SignInMethod!]!
+  "Computers whose git is signed in to platform git with the signed-in account, newest first."
+  gitSignIns: [GitSignIn!]!
   "Integration types available to connect (postgres, redis, …)."
   availableIntegrations: [IntegrationKind!]!
   "The signed-in owner's connected backends."
@@ -942,6 +1739,8 @@ type Query {
   projectSharedConnections(projectID: ID!): [IntegrationConnection!]!
   "The signed-in owner's app bindings (which app uses which backend)."
   integrationBindings: [IntegrationBinding!]!
+  "Usage of one binding's per-app resource, read live from its provider (bounded, cached ~60s). Fails for a binding that does not report usage (see IntegrationBinding.reportsUsage); a provider failure is returned in error, not as a GraphQL error."
+  integrationBindingUsage(id: ID!): IntegrationUsage!
   "Account-level event subscriptions, including disabled state."
   integrationSubscriptions: [IntegrationSubscription!]!
   "Secret-free configuration effective for this app's next deploy or lifecycle event."
@@ -950,6 +1749,10 @@ type Query {
   publishDomainProbe(bindingID: ID!): PublishDomainProbe!
   workspaceFiles(workspaceID: ID!): [WorkspaceFile!]!
   workspaceFilesPage(input: ListWorkspaceFilesInput!): WorkspaceFilePage!
+  "History of an app with platform git: its branch's commits, newest first (limit default 20, max 100); before continues from a page's nextBefore."
+  appCommits(workspaceID: ID!, limit: Int, before: String): AppCommitPage!
+  "One commit of an app with platform git with its diff against its first parent."
+  appCommit(workspaceID: ID!, sha: String!): AppCommitDiff!
   readWorkspaceFile(input: ReadWorkspaceFileInput!): WorkspaceFileContent
   workspaceEnv(workspaceID: ID!): [WorkspaceEnvVar!]!
   workspaceEnvPage(input: ListWorkspaceEnvInput!): WorkspaceEnvPage!
@@ -974,10 +1777,25 @@ type Query {
   deploymentEventsPage(input: ListDeploymentEventsInput!): DeploymentEventPage!
   "The harness presets a run may name: what each is and which workspace secrets it needs. Empty when this node's box image carries no catalogue."
   runHarnesses: [RunHarness!]!
+  "The caller's chosen model-provider connection per harness. A run of that harness receives its env unless the workspace sets the same name."
+  runHarnessSettings: [RunHarnessSetting!]!
+  "The caller's named run presets, sorted by name."
+  runPresets: [RunPreset!]!
+  "The caller's run triggers, sorted by name."
+  runTriggers: [RunTrigger!]!
+  "One trigger's shared secret — shown to its owner to configure the sending side."
+  runTriggerSecret(input: RunTriggerIDInput!): String!
+  "The caller's own connections eligible to back each harness in the catalogue, computed server-side (kind implements harness credentials and actually serves that harness)."
+  runHarnessProviderChoices: [RunHarnessProviderChoice!]!
+  "The models a connection's provider offers for a harness, fetched live from the provider (e.g. GET /v1/models); empty when the kind cannot list models (no remote catalogue, or an oauth-only credential with no API access) — the caller falls back to free text."
+  runHarnessProviderModels(harness: String!, connectionID: ID!): [String!]!
   "One agent run visible to the caller; not-found otherwise."
   run(id: ID!): Run!
   "The caller's agent runs, newest first."
   runs(input: ListRunsInput): RunPage!
+  "Agents the caller may see (docs/agents-design.md): its own and those of identities it claimed; a claimed identity sees only its own, never its claimer's. Oldest first."
+  agents: [Agent!]!
+  agent(id: ID!): Agent!
   "A run's own history, oldest first (at most limit, default 100)."
   runEvents(runID: ID!, limit: Int): [RunEvent!]!
   "The live console tail of a RUNNING run (tailBytes, default 16384)."
@@ -994,8 +1812,19 @@ type Query {
 }
 
 type Mutation {
+  "Persist the exact previewed move before execution. Retry with the same key/digest after a lost response."
+  beginPlacementMove(input: BeginPlacementMoveInput!): PlacementMove!
+  "Execute or resume the saved move. On interruption, read status and retry this same ID; cancellation does not undo it."
+  runPlacementMove(input: RunPlacementMoveInput!): PlacementMove!
+
   "Start an agent run; returns once its VM has started (RUNNING) or FAILED with error."
   createRun(input: CreateRunInput!): Run!
+  "Create an agent: the record, its own hidden workspace, and its computer (a BOX deployment, sized like any box). A name is enough; the rest defaults. Requires a claimed account, like a box."
+  createAgent(input: CreateAgentInput!): AgentPayload!
+  "Change an agent's setup; omitted fields stay as they are. Owner only."
+  updateAgent(input: UpdateAgentInput!): AgentPayload!
+  "Delete an agent: its active runs are cancelled, its computer and disk deleted, its workspace removed. The agent itself cannot be restored; its computer's files and disk are kept by the platform for 30 days for investigation, then erased. Owner only."
+  deleteAgent(input: DeleteAgentInput!): DeleteResultPayload!
   "Stop an agent run (idempotent on an already-cancelled run)."
   cancelRun(id: ID!): Run!
   "Answer a BLOCKED run's pending question; the run resumes."
@@ -1003,7 +1832,11 @@ type Mutation {
   "Continue a finished run: a new run in the same workspace with the parent's context prepended to the prompt."
   followUpRun(input: FollowUpRunInput!): Run!
   registerFunction(input: RegisterFunctionInput!): Function!
+  "Reconcile the original registration, preserving its source and worker identity. May finalize an interrupted preparation as failed; never retries a completed failed execution. Requires deploy scope."
+  resumeFunctionRegistration(id: ID!): FunctionRegistration!
   invokeFunction(input: InvokeFunctionInput!): Invocation!
+  "Permanently delete a published function: it stops being invocable and its stored source and bundle are removed. Saved invocation results are not affected. Unpublished registrations are not deleted. Requires deploy scope. Not idempotent: once deleted, the ID reports function was not found like any unknown ID, so a client retrying its own delete may treat that error as already deleted."
+  deleteFunction(input: DeleteFunctionInput!): DeleteResultPayload!
   createWorkspace(input: CreateWorkspaceInput!): CreateWorkspacePayload!
   "Rename an app (its workspace). Does not change its alias or public URL."
   renameWorkspace(input: RenameWorkspaceInput!): Workspace!
@@ -1041,10 +1874,28 @@ type Mutation {
   connectIntegration(input: ConnectIntegrationInput!): IntegrationConnectionPayload!
   "Start the link flow for a link integration (e.g. Telegram); returns a URL to open."
   startIntegrationLink(kind: String!): IntegrationLinkPayload!
+  "Begin the owner's OAuth authorization of a connection's MCP server: open the returned URL in a browser signed in to this account; the callback completes it."
+  startConnectionAuthorization(input: IntegrationIDInput!): IntegrationLinkPayload!
+  "Choose which of the caller's own connections backs a harness; refused when the caller does not own the connection or it does not serve this harness."
+  setRunHarnessProvider(input: SetRunHarnessProviderInput!): RunHarnessSettingPayload!
+  "Create or replace (by name) one of the caller's run presets. A preset naming a connection is refused unless the caller owns it and it serves the preset's harness."
+  saveRunPreset(input: SaveRunPresetInput!): RunPresetPayload!
+  "Forget a preset by name; runs already created from it are untouched."
+  deleteRunPreset(input: DeleteRunPresetInput!): DeleteResultPayload!
+  "Create or update a run trigger. The template's workspace must be visible to the caller; a named preset must exist."
+  saveRunTrigger(input: SaveRunTriggerInput!): RunTriggerPayload!
+  "Forget a trigger and its queued firings."
+  deleteRunTrigger(input: RunTriggerIDInput!): DeleteResultPayload!
+  "Forget the caller's chosen provider for a harness; it falls back to no credential."
+  clearRunHarnessProvider(input: ClearRunHarnessProviderInput!): DeleteResultPayload!
+  "Revoke (best effort, at the server) and forget a connection's OAuth grant; runs stop getting the server."
+  revokeConnectionAuthorization(input: IntegrationIDInput!): DeleteResultPayload!
   "Delete a connected backend by id. Active bindings must be unbound first; detached bindings retain it until rollback/provider cleanup completes."
   deleteIntegrationConnection(input: IntegrationIDInput!): DeleteResultPayload!
   "Bind a backend to ONE app. Scoped providers first create a distinct per-app resource and credential; the app receives only that credential on its next deploy."
   bindIntegration(input: BindIntegrationInput!): IntegrationBindingPayload!
+  "Mint the single one-time .env reveal of an ACTIVE credential-carrying binding that never had one — typically a binding whose provider finished provisioning after bindIntegration returned. Only the app's owner may call it; it is refused while the binding is still provisioning and once a reveal was issued for the binding."
+  revealIntegrationEnv(input: IntegrationIDInput!): IntegrationEnvReveal!
   "Attach a custom hostname (a zone already in the connected account) to a publish binding's site. Replaces the previously attached hostname, if any."
   setPublishDomain(input: PublishDomainInput!): IntegrationBindingPayload!
   "Detach the publish binding's custom hostname. The site stays reachable at its provider URL."
@@ -1076,6 +1927,8 @@ type Mutation {
   addCustomDomain(input: AddCustomDomainInput!): CustomDomain!
   "Detach a custom domain; the app keeps serving on its alias/URL."
   removeCustomDomain(input: RemoveCustomDomainInput!): DeleteResultPayload!
+  "Move a custom domain to another of your apps without activating it again: its Cloudflare hostname and certificate are kept and re-pointed, so it never answers \"error code: 1014\". The previous app answers it until Cloudflare has switched, usually within seconds. Only between apps of the domain's own account."
+  moveCustomDomain(input: MoveCustomDomainInput!): CustomDomain!
   writeWorkspaceTextFile(input: WriteWorkspaceTextFileInput!): WorkspaceFilePayload!
   writeWorkspaceBase64File(input: WriteWorkspaceBase64FileInput!): WorkspaceFilePayload!
   uploadWorkspaceFile(input: UploadWorkspaceFileInput!): WorkspaceFilePayload!
@@ -1098,31 +1951,44 @@ type Mutation {
   adoptDeploymentAlias(input: AdoptDeploymentAliasInput!): CreateDeploymentPayload!
   "Deploy a workspace's CURRENT files, detecting the kind from them (a root server.ts/index.html or an unfazed.json). The recovery path after a failed import: add/fix unfazed.json (or an entry), then deploy — no git re-fetch. Errors with what to add if the files still aren't deployable."
   deployWorkspace(input: DeployWorkspaceInput!): CreateDeploymentPayload!
-  "Import and deploy a GitHub repo into a new workspace. Kind/runtime are detected from the repo root (server.ts/go.mod+main.go -> SERVICE, index.html -> STATIC) unless a root unfazed.json overrides it. For a monorepo, a root unfazed.json `apps` array deploys SEVERAL apps from one push — each {alias, rootDir} builds that subdirectory as its own app (apps[] is repo config, not an input here; the same applies to syncRepo and webhook pushes). Returns immediately with an IMPORTING status; the fetch+build runs in the background."
+  "Import and deploy a Git repo into a new workspace using the selected provider (GitHub by default). Kind/runtime are detected from the repo root (server.ts/go.mod+main.go -> SERVICE, index.html -> STATIC) unless a root unfazed.json overrides it. For a monorepo, a root unfazed.json `apps` array deploys SEVERAL apps from one push — each {alias, rootDir} builds that subdirectory as its own app (apps[] is repo config, not an input here; the same applies to syncRepo and webhook pushes). Returns immediately with an IMPORTING status; the fetch+build runs in the background."
   importRepo(input: ImportRepoInput!): ImportRepoPayload!
-  "Link a GitHub repo to an EXISTING workspace (one with no source yet) and import it. The workspace keeps its id, env, and secrets. If unfazed.json apps[] omits the supplied/stored current alias, that alias, its current deployment, and its App State are retired."
+  "Link a Git repo from the selected provider to an EXISTING workspace (one with no source yet) and import it. The workspace keeps its id, env, and secrets. If unfazed.json apps[] omits the supplied/stored current alias, that alias, its current deployment, and its App State are retired."
   connectRepo(input: ConnectRepoInput!): ImportRepoPayload!
   syncRepo(input: SyncRepoInput!): ImportRepoPayload!
+  "Give an app with platform git back the files of an earlier commit: one new commit by the caller on its branch, deployed like a push when the app deploys every push. Requires deploy scope."
+  restoreAppVersion(input: RestoreAppVersionInput!): RestoreAppVersionPayload!
+  "Move an app with platform git to a NEW private GitHub repository, created with the caller's own GitHub credential: its whole history (every branch and tag, commits untouched) is pushed there, GitHub's push webhook is installed, and the app deploys from GitHub from then on — nothing redeploys. The platform repository is kept, read-only. Only the app's owner may move it. Idempotent: an app that moved answers with its repository, and a retry finishes a move that failed part-way. Requires deploy scope."
+  moveAppToGitHub(input: MoveAppToGitHubInput!): MoveAppToGitHubPayload!
+  "Give an app with no linked repository its own git repository on the platform now (MCP enable_platform_git; apps get one by themselves at their next change once they serve): its current files become the first commit on main, by the caller, and every later push to main deploys it like a linked repository's. Only the app's owner may turn it on. Refused, with what to fix, when the first push would change what runs: a box, a VM size, schedule or health path set at deploy time instead of in unfazed.json, several aliases without unfazed.json apps[], or files a git import leaves out (.env, .git, node_modules). Idempotent. Requires deploy scope."
+  enablePlatformGit(input: EnablePlatformGitInput!): EnablePlatformGitPayload!
   unlinkRepo(input: UnlinkRepoInput!): DeleteResultPayload!
   installRepoWebhook(input: InstallRepoWebhookInput!): ImportRepoPayload!
   setRepoDeployAlias(input: SetRepoDeployAliasInput!): ImportRepoPayload!
+  "Create an environment (e.g. staging) of a git-linked app: a sibling workspace that deploys another branch of the same repo to its own aliases. Plain env is copied, secrets are not."
+  addRepoEnvironment(input: AddRepoEnvironmentInput!): AddRepoEnvironmentPayload!
+  "Replace the encrypted repository token; empty removes it. Does not deploy. GitHub then uses the account token. Other providers use anonymous access."
+  setRepoToken(workspaceID: ID!, token: String!): ImportRepoPayload!
   setGitHubToken(input: SetGitHubTokenInput!): GitHubTokenStatus!
   deleteGitHubToken: GitHubTokenStatus!
   restartService(input: ServiceControlInput!): ServiceRuntimeStatus!
   stopService(input: ServiceControlInput!): ServiceRuntimeStatus!
-  "Permanently delete a deployment and its files snapshot, stopping a running service VM first. Alias-keyed app state is freed once no other deployment uses the alias; the alias's app-scoped env and secrets are reclaimed on that condition plus two more — the alias really was deployed once, and no git source redeploys it — so deleting a failed first build keeps the env staged for the retry. That reclaim is not reversible: secret values are never returned by the API."
+  "Delete ONE app of a workspace and nothing else: every deployment of the alias in that workspace (its VM stopped, its URL and custom domains stop serving), its App State, its app-scoped env and secrets, and its integration bindings. The workspace, its files and defaults, and its other apps keep serving. In a git-linked workspace pushes and syncs skip the alias while unfazed.json apps[] still declares it (Workspace.deletedApps) — remove it from apps[], or bring it back with syncRepo restoreApps. Refused while a git import of the workspace runs. Owner only. The app is kept by the platform for 30 days, so support (the platform operator) can restore it exactly as it was within that time; then it is erased for good. Secret values are never returned."
+  deleteApp(input: DeleteAppInput!): DeleteAppPayload!
+  "Delete a deployment and its files snapshot, stopping a running service VM first. Alias-keyed app state goes with it once no other deployment uses the alias; the alias's app-scoped env and secrets go with it on that condition plus two more — the alias really was deployed once, and no git source redeploys it — so deleting a failed first build keeps the env staged for the retry. What is deleted is kept by the platform for 30 days, so support (the platform operator) can restore it within that time; then it is erased for good. Secret values are never returned by the API."
   deleteDeployment(input: DeleteDeploymentInput!): DeleteResultPayload!
   "Roll an alias back to a PRIOR release: atomically repoint it to the given deployment and bring that snapshot back (always_on restarts warm; on_demand cold-starts on the next request). Also reverts to that release's env/secrets snapshot. Pass the id and opaque aliasRevision of the aliasHeld release you observed; the rollback fails if either changed since deploymentReleases."
   rollbackDeployment(input: RollbackDeploymentInput!): Deployment!
+  "Delete a workspace: its files, env and secrets, and any persistent box disk; with withDeployments, every app it serves too (confirmAliases). Kept by the platform for 30 days, so support (the platform operator) can restore it exactly as it was within that time; then it is erased for good."
   deleteWorkspace(input: DeleteWorkspaceInput!): DeleteResultPayload!
   setAppState(input: SetAppStateInput!): AppStateValue!
   deleteAppState(input: DeleteAppStateInput!): DeleteResultPayload!
   "Rename a linked (claimed) agent. Allowed for the agent's claimer or the operator."
-  renameAgent(input: RenameAgentInput!): CurrentActorAgent!
-  "Delete a linked (claimed) agent: revoke its token AND delete every workspace and deployment it owns (stopping service VMs). Irreversible."
-  deleteAgent(input: DeleteAgentInput!): DeleteResultPayload!
+  renameLinkedAgent(input: RenameLinkedAgentInput!): CurrentActorAgent!
+  "Delete a linked (claimed) agent: revoke its token AND delete everything it owns — its apps and releases (stopping service VMs), its agents and its integration connections. A binding of those connections on another account's app goes too: that app keeps its running release but gets no env from the integration at its next deploy, and the result names it. Allowed for the agent's claimer or the operator, with their own sign-in (not a run, script or job). The agent itself cannot be restored; what its apps held is kept by the platform for 30 days for investigation, then erased."
+  deleteLinkedAgent(input: DeleteLinkedAgentInput!): DeleteLinkedAgentPayload!
   "Issue a fresh access token for a linked (claimed) agent, keeping its identity so it can still redeploy the aliases it owns. Self-registration cannot do this: it always mints a NEW agent, and the platform refuses to let a different owner near an existing alias. Every previous token of the agent stops working immediately, so write the returned value wherever the agent reads it. The token is returned once and is never retrievable again. Allowed for the agent's claimer or the operator."
-  rotateAgentToken(input: RotateAgentTokenInput!): AgentTokenPayload!
+  rotateLinkedAgentToken(input: RotateLinkedAgentTokenInput!): LinkedAgentTokenPayload!
   "Issue a one-time code to connect the caller's Telegram to deploy notifications. Returns a t.me deep link to open the bot with the code prefilled; the code expires and is single-use."
   createTelegramLinkCode: TelegramLinkPayload!
 }
@@ -1138,21 +2004,40 @@ type TelegramLinkPayload {
   botUsername: String!
 }
 
-input RenameAgentInput {
+input RenameLinkedAgentInput {
   agentID: ID!
   name: String!
 }
 
-input DeleteAgentInput {
+input DeleteLinkedAgentInput {
   agentID: ID!
+  "Exactly the aliases of the agent's liveApps, in any order: every app this delete takes offline. A missing or extra alias refuses the delete and changes nothing."
+  confirmAliases: [String!]
+}
+
+"What deleting a linked agent changed outside the agent's own things. A delete that stopped part-way answers with ok false and the error beside it, and still names the apps it detached; deleting again finishes and names them again."
+type DeleteLinkedAgentPayload {
+  ok: Boolean!
+  "Apps of other accounts (yours, a teammate's) that had one of the agent's connections bound. Each keeps its running release but gets no env from that integration at its next deploy; the provider resource is released once no retained release uses it."
+  affectedApps: [LinkedAgentAffectedApp!]!
+  "Affected apps you cannot see, counted but not named."
+  hiddenAffectedApps: Int!
 }
 
-input RotateAgentTokenInput {
+"An app that lost a binding of a deleted agent's connection."
+type LinkedAgentAffectedApp {
+  workspaceID: ID!
+  alias: String!
+  "The integration kind of the binding it lost."
+  kind: String!
+}
+
+input RotateLinkedAgentTokenInput {
   agentID: ID!
 }
 
 "A newly issued agent credential. Shown once: only its hash is stored."
-type AgentTokenPayload {
+type LinkedAgentTokenPayload {
   "The agent this token authenticates as — unchanged by rotation."
   agentID: ID!
   "The bearer token. Copy it now; it cannot be read again."
@@ -1171,10 +2056,16 @@ input RegisterFunctionInput {
 }
 
 input InvokeFunctionInput {
+  "Optional UUID identifying one invocation across retries. A changed function revision or payload conflicts. Servers unable to guarantee replay safety reject this field before execution."
+  invocationID: ID
   functionID: ID!
   payload: JSON
 }
 
+input DeleteFunctionInput {
+  functionID: ID!
+}
+
 input PageInput {
   limit: Int
   offset: Int
@@ -1198,12 +2089,16 @@ input WriteWorkspaceTextFileInput {
   workspaceID: ID!
   path: String!
   text: String!
+  "On an app with platform git: the message of the commit this write makes; default names the file. Ignored on other apps."
+  commitMessage: String
 }
 
 input WriteWorkspaceBase64FileInput {
   workspaceID: ID!
   path: String!
   contentBase64: String!
+  "On an app with platform git: the message of the commit this write makes; default names the file. Ignored on other apps."
+  commitMessage: String
 }
 
 input UploadWorkspaceFileInput {
@@ -1214,6 +2109,30 @@ input UploadWorkspaceFileInput {
 
 type WorkspaceFilePayload {
   file: WorkspaceFile!
+  "The commit the write made on an app with platform git; null on any other app, and for an upload."
+  commit: FileCommit
+}
+
+"The commit a file write made on an app with platform git."
+type FileCommit {
+  "The commit; with committed false, the branch head that already held exactly these files. Null while it waits."
+  sha: String
+  branch: String!
+  message: String!
+  "False when git already held exactly these files: no commit was made."
+  committed: Boolean!
+  "True while the commit waits for the git server: the app's files have the write, and its commit lands in order. Should a push change the same files meanwhile, a git.conflict event says so."
+  waiting: Boolean!
+  "The app's commits waiting, while this one does."
+  waitingCount: Int!
+  "Whether the branch head, this write included, is imported and deployed like a push."
+  deploys: Boolean!
+  "Paths a push changed too since the write was made: the head keeps the pushed version (sha is the merge). Empty otherwise."
+  conflicts: [String!]!
+  "The write as it was made, the merge's second parent, when there are conflicts."
+  writeSHA: String
+  "True while platform git is paused (its commit queue is being recovered): the app's files have the write, and they are committed as they are once it is back. Nothing to retry."
+  paused: Boolean!
 }
 
 input ReadWorkspaceFileInput {
@@ -1350,15 +2269,17 @@ input CreateDeploymentInput {
   cronPath: String
   "BOX only: optional VM size. Omit for the platform defaults."
   boxResources: BoxResourcesInput
+  "Server for a NEW app: a server id or name from placementTargets, or control-plane. Omit for the default server. An existing app keeps its server (use a placement move); static sites stay on the control plane."
+  server: String
 }
 
 "A box's requested VM size. Omitted fields use the platform default."
 input BoxResourcesInput {
-  "RAM in MiB (default 2048, min 512, max 16384)."
+  "RAM in MiB (default 4096, min 512, max 16384)."
   memMiB: Int
-  "vCPU count (default 2, max 8)."
+  "vCPU count (default 4, max 16)."
   vcpus: Int
-  "Persistent disk in GiB (default 8, max 64). Applies only when the disk is first created; an existing disk keeps its size."
+  "Persistent disk in GiB (default 32, max 128). Sets the size when the disk is first created; a later redeploy asking for more grows the existing disk before the box boots (it never shrinks, and the effective size may be lower than requested)."
   diskGiB: Int
 }
 
@@ -1380,6 +2301,8 @@ input DeployWorkspaceInput {
   serviceMode: ServiceMode
   "STATIC only; overrides the detected SPA fallback."
   spaMode: Boolean
+  "Server for a NEW app (see CreateDeploymentInput.server); overrides unfazed.json server."
+  server: String
 }
 
 type CreateDeploymentPayload {
@@ -1387,6 +2310,11 @@ type CreateDeploymentPayload {
 }
 
 input ImportRepoInput {
+  "Git provider, default github. Forgejo accepts any public HTTPS instance."
+  provider: String
+  serverURL: String
+  "Optional repository token, encrypted per workspace; never returned."
+  token: String
   repo: String!
   ref: String
   alias: String
@@ -1397,6 +2325,9 @@ input ImportRepoInput {
 }
 
 input ConnectRepoInput {
+  provider: String
+  serverURL: String
+  token: String
   workspaceID: ID!
   repo: String!
   ref: String
@@ -1409,6 +2340,8 @@ input ConnectRepoInput {
 input SyncRepoInput {
   workspaceID: ID!
   force: Boolean
+  "Apps deleted with deleteApp that unfazed.json apps[] still declares (Workspace.deletedApps): their deletion is lifted and this sync, forced, deploys them again. Owner only."
+  restoreApps: [String!]
 }
 
 input UnlinkRepoInput {
@@ -1425,6 +2358,26 @@ input SetRepoDeployAliasInput {
   alias: String!
 }
 
+input AddRepoEnvironmentInput {
+  "The main app's git-linked workspace."
+  workspaceID: ID!
+  "Environment name such as staging: 1-20 lowercase letters, digits or dashes. Every alias of the environment ends with -<name>."
+  name: String!
+  "The branch the environment deploys on every push."
+  branch: String!
+  "Single-app alias; defaults to <main alias>-<name>."
+  alias: String
+}
+
+type AddRepoEnvironmentPayload {
+  workspace: Workspace!
+  gitSource: GitSource
+  "The main app's secret names that were not copied; set them on the environment."
+  skippedSecrets: [String!]!
+  "Why the environment's push webhook could not be installed automatically."
+  webhookError: String
+}
+
 input SetGitHubTokenInput {
   token: String!
 }
@@ -1446,9 +2399,14 @@ input ListDeploymentsInput {
 }
 
 input CreateRunInput {
-  workspaceID: ID!
+  "The workspace whose env, secrets and files the run gets. Optional for an agent's run: the agent's first scoped workspace, else its own."
+  workspaceID: ID
+  "Make this run a task of an agent: it inherits the agent's harness, provider and model, access and approval wherever this input leaves them empty."
+  agentID: ID
   prompt: String
   harness: String
+  "A run preset name: its harness applies when harness is empty, its connection/model override the account's harness setting, its extra env merges below the workspace's own."
+  preset: String
   command: String
   "Shell commands run in /work before the harness; the first failure fails the run."
   setup: [String!]
@@ -1483,6 +2441,7 @@ input FollowUpRunInput {
 
 input ListRunsInput {
   workspaceID: ID
+  agentID: ID
   status: RunStatus
   limit: Int
   offset: Int
@@ -1515,8 +2474,32 @@ input RollbackDeploymentInput {
 
 input DeleteWorkspaceInput {
   workspaceID: ID!
-  "Also delete every deployment snapshotted from the workspace (stopping service VMs) instead of refusing while any exist."
+  "Also delete every deployment snapshotted from the workspace (stopping service VMs) instead of refusing while any exist. This takes down EVERY app the workspace serves, so confirmAliases must name exactly those apps (Workspace.liveApps)."
   withDeployments: Boolean
+  "With withDeployments: exactly the aliases of Workspace.liveApps, in any order — every app this delete takes offline. A missing or extra alias refuses the delete and deletes nothing; the error lists the live apps. To delete one app, use deleteApp."
+  confirmAliases: [String!]
+}
+
+input DeleteAppInput {
+  workspaceID: ID!
+  "The app to delete: an alias of the workspace."
+  alias: String!
+}
+
+"What deleteApp removed."
+type DeleteAppPayload {
+  ok: Boolean!
+  alias: String!
+  "Deployment records deleted: the live release, retained releases and failed or building attempts."
+  deployments: Int!
+  "Custom domains that served the app and stopped. Their records stay with the alias in this workspace, so a restored app serves them again; removeCustomDomain removes one for good."
+  domains: [String!]!
+  "App-scoped env, secret and REMOVE entries removed."
+  envEntries: Int!
+  "Whether pushes and syncs of this git-linked workspace now skip the alias while unfazed.json apps[] declares it."
+  skippedOnSync: Boolean!
+  "The workspace's apps that are still live, untouched."
+  otherApps: [String!]!
 }
 
 input SetAppStateInput {
@@ -1530,3 +2513,618 @@ input DeleteAppStateInput {
   alias: String!
   key: String!
 }
+
+"Application feedback shared by the on-page toolbar, dashboard and agents."
+type ReviewAttachment {
+  id: ID!
+  filename: String!
+  mimeType: String!
+  size: Int!
+}
+type ReviewMessage {
+  id: ID!
+  author: String!
+  "Current authenticated profile picture, empty for guests and accounts without one."
+  avatarURL: String!
+  guest: Boolean!
+  body: String!
+  deleted: Boolean!
+  "Whether the current viewer may delete this message."
+  canDelete: Boolean!
+  createdAt: String!
+  attachments: [ReviewAttachment!]!
+}
+type ReviewThread {
+  id: ID!
+  "Permanent discussion number within this app generation, including resolved discussions."
+  number: Int!
+  workspaceID: ID!
+  alias: String!
+  deploymentID: ID!
+  page: String!
+  title: String!
+  selector: String!
+  selectedText: String!
+  x: Float!
+  y: Float!
+  viewportWidth: Int!
+  viewportHeight: Int!
+  userAgent: String!
+  resolved: Boolean!
+  createdAt: String!
+  messages: [ReviewMessage!]!
+}
+type ReviewPage { threads: [ReviewThread!]! total: Int! canManage: Boolean! }
+type ReviewLink { id: ID! url: String createdAt: String! expiresAt: String! revoked: Boolean! }
+type ReviewFile { filename: String! mimeType: String! contentBase64: String! }
+type ReviewNotificationConnection { id: ID! name: String! }
+type ReviewNotificationChannel {
+  kind: String!
+  label: String!
+  iconURL: String!
+  connectMethod: String!
+  connections: [ReviewNotificationConnection!]!
+}
+type ReviewNotificationSettings {
+  enabled: Boolean!
+  appEnabled: Boolean!
+  connected: Boolean!
+  connectionID: String!
+  channels: [ReviewNotificationChannel!]!
+}
+input ReviewAttachmentInput { filename: String! contentBase64: String! }
+input ReviewCommentInput {
+  deploymentID: ID!
+  threadID: ID
+  body: String!
+  page: String
+  title: String
+  selector: String
+  selectedText: String
+  x: Float
+  y: Float
+  viewportWidth: Int
+  viewportHeight: Int
+  userAgent: String
+  requestID: ID
+  attachments: [ReviewAttachmentInput!]
+}
+extend type Query {
+  "Personal feedback notification settings. Omit deploymentID for the account-wide switch."
+  reviewNotificationSettings(deploymentID: ID): ReviewNotificationSettings!
+  reviewThreads(deploymentID: ID!, offset: Int, limit: Int): ReviewPage!
+  reviewThread(deploymentID: ID!, threadID: ID!): ReviewThread!
+  reviewLinks(deploymentID: ID!): [ReviewLink!]!
+  reviewAttachment(deploymentID: ID!, threadID: ID!, attachmentID: ID!): ReviewFile!
+}
+extend type Mutation {
+  "Set the account-wide feedback switch, or one app override when deploymentID is present. Defaults are on; delivery is at most once an hour per account."
+  setReviewNotificationSettings(deploymentID: ID, connectionID: ID, enabled: Boolean!): ReviewNotificationSettings!
+  "Create a revocable 30-day guest link, or a one-hour personal toolbar session."
+  createReviewLink(deploymentID: ID!, personal: Boolean = false): ReviewLink!
+  revokeReviewLink(deploymentID: ID!, linkID: ID!): Boolean!
+  addReviewComment(input: ReviewCommentInput!): ReviewThread!
+  "Delete one comment and its attachments. Authors may delete their own; the app owner may moderate all comments."
+	deleteReviewComment(deploymentID: ID!, threadID: ID!, messageID: ID!): Boolean!
+  resolveReviewThread(deploymentID: ID!, threadID: ID!, resolved: Boolean!): ReviewThread!
+}
+
+"A commit of an app's platform git repository."
+type AppCommit {
+  sha: String!
+  "The commit message (its first 64 KiB)."
+  message: String!
+  authorName: String!
+  authorEmail: String!
+  "When the change was authored (RFC3339)."
+  authoredAt: String!
+  "Paths changed against the first parent (every path of a first commit)."
+  filesChanged: Int!
+  "Aliases whose live release runs this commit."
+  deployedTo: [String!]!
+}
+
+type AppCommitPage {
+  branch: String!
+  "The branch head; null while the branch has no commits."
+  head: String
+  commits: [AppCommit!]!
+  "Pass as before for the older commits; null on the last page."
+  nextBefore: String
+  "Whether pushes (and restores) deploy the app."
+  autoDeploy: Boolean!
+  "File writes whose commits have not landed yet: the app's files have them, and they land in order as soon as the git server takes them."
+  waitingCommits: Int!
+  "When the oldest waiting write was made (RFC3339); null when none waits."
+  waitingSince: String
+  "The commit every live alias of the app runs, whether or not it is on this page."
+  deployed: [AppDeployedCommit!]!
+}
+
+"The commit one live alias runs (AppCommitPage.deployed)."
+type AppDeployedCommit {
+  alias: String!
+  sha: String!
+  "The release serving the alias."
+  deploymentID: ID!
+}
+
+type AppCommitFile {
+  path: String!
+  "added, modified, deleted or type changed."
+  status: String!
+}
+
+type AppCommitDiff {
+  commit: AppCommit!
+  files: [AppCommitFile!]!
+  "Unified diff against the first parent, at most 64 KiB (16 KiB per file); lines starting with … say what was left out."
+  patch: String!
+  truncated: Boolean!
+  additions: Int!
+  deletions: Int!
+}
+
+input RestoreAppVersionInput {
+  workspaceID: ID!
+  "Full 40-character sha of the commit whose files the app gets back."
+  sha: String!
+  "When set, refuse (changing nothing) unless the branch head is still this commit."
+  expectedHead: String
+  "Message of the new commit; default Restore <short sha> (<its message>)."
+  message: String
+}
+
+input MoveAppToGitHubInput {
+  workspaceID: ID!
+  "GitHub account or organization to create the repository in; default the caller's own GitHub account."
+  owner: String
+  "Name of the new repository; default the app's alias."
+  repo: String
+  "When set, refuse (changing nothing) unless the branch head is still this commit."
+  expectedHead: String
+}
+
+input EnablePlatformGitInput {
+  workspaceID: ID!
+}
+
+type EnablePlatformGitPayload {
+  "The app's source, now deploying from its platform repository."
+  workspace: Workspace!
+  "The repository by alias (https://git.unfz.to/<alias>.git)."
+  cloneURL: String!
+  "The repository by workspace ID, which never changes."
+  stableCloneURL: String!
+  branch: String!
+  "The commit holding the app's files; null for an app without files, whose first push fills it."
+  commitSHA: String
+  "False when the repository already held exactly these files."
+  committed: Boolean!
+}
+
+type MoveAppToGitHubPayload {
+  "owner/name of the GitHub repository."
+  repository: String!
+  repoURL: String!
+  "False when an earlier attempt of this move created the repository, or the caller named an empty one."
+  created: Boolean!
+  "The app had moved before: nothing was done."
+  alreadyMoved: Boolean!
+  "The branch head the app deploys, on GitHub too."
+  head: String!
+  "Whether every push to the branch on GitHub deploys the app."
+  webhookInstalled: Boolean!
+  "The platform repository, kept read-only."
+  platformCloneURL: String!
+  "What else happened, such as a push that landed during the move."
+  note: String
+}
+
+type RestoreAppVersionPayload {
+  "The new commit; with committed false, the head that already holds that version."
+  sha: String!
+  committed: Boolean!
+  "Whether the new commit is deployed like a push. The deploy is an import queued behind the restore: its deployment is the one whose gitCommit is sha (deploymentsPage with the workspace, then waitForDeployment)."
+  deploys: Boolean!
+  message: String!
+  "The app's branch."
+  branch: String!
+  "The alias a push deploys to, when the link names one; null otherwise (unfazed.json apps[] deploys each of its aliases)."
+  deployAlias: String
+  "The commit restored from (the sha asked for)."
+  restoredFrom: String!
+  "The branch head the new commit was made on; null with committed false."
+  parent: String
+}
+
+enum WorkflowRunStatus { PENDING RUNNING COMPLETED FAILED CANCELLED }
+
+type WorkflowValue { text: String! bytes: Int! truncated: Boolean! error: Boolean! }
+type WorkflowError { message: String! stack: String code: String truncated: Boolean! }
+type WorkflowAttribute { key: String! value: String! }
+
+type WorkflowRunSummary {
+  runID: ID! workflowName: String! displayName: String! module: String!
+  status: WorkflowRunStatus! deploymentID: String!
+  createdAt: String! startedAt: String completedAt: String updatedAt: String! expiredAt: String
+  errorCode: String attributes: [WorkflowAttribute!]!
+}
+type WorkflowRunPage { runs: [WorkflowRunSummary!]! nextCursor: String hasMore: Boolean! }
+
+type WorkflowStep {
+  stepID: ID! stepName: String! displayName: String! module: String!
+  status: String! attempt: Int!
+  createdAt: String! startedAt: String completedAt: String updatedAt: String! retryAfter: String
+}
+type WorkflowStepPage { steps: [WorkflowStep!]! nextCursor: String hasMore: Boolean! }
+type WorkflowWait { correlationID: ID! status: String! createdAt: String! resumeAt: String completedAt: String }
+type WorkflowHook {
+  hookID: ID! kind: String! status: String! createdAt: String!
+  receivedCount: Int! lastReceivedAt: String disposedAt: String
+}
+type WorkflowStreamInfo { name: String! tailIndex: Int done: Boolean }
+type WorkflowEvent {
+  eventID: ID! eventType: String! correlationID: String createdAt: String!
+  info: JSON! infoTruncated: Boolean!
+}
+type WorkflowEventPage { events: [WorkflowEvent!]! nextCursor: String hasMore: Boolean! }
+
+type WorkflowRun {
+  run: WorkflowRunSummary!
+  input: WorkflowValue output: WorkflowValue error: WorkflowError
+  steps: [WorkflowStep!]! stepsNextCursor: String stepsHasMore: Boolean!
+  waits: [WorkflowWait!]! hooks: [WorkflowHook!]! streams: [WorkflowStreamInfo!]!
+  eventsScanned: Int! eventsComplete: Boolean!
+  waitsTruncated: Boolean! hooksTruncated: Boolean!
+}
+type WorkflowStepDetail {
+  step: WorkflowStep! input: WorkflowValue output: WorkflowValue error: WorkflowError
+  events: [WorkflowEvent!]! eventsHasMore: Boolean!
+}
+type WorkflowEventDetail { event: WorkflowEvent! data: WorkflowValue }
+type WorkflowStreamChunk { index: Int! bytes: Int! encoding: String! text: String! truncated: Boolean! }
+type WorkflowStreamPage {
+  name: String! chunks: [WorkflowStreamChunk!]! nextCursor: String hasMore: Boolean!
+  done: Boolean! tailIndex: Int!
+}
+type WorkflowInfo { version: Int! package: String! workflow: String! specVersion: Int workflows: [WorkflowName!]! }
+type WorkflowName { name: String! displayName: String! module: String! }
+
+"The app's queue counters, read from its data node (docs/workflow-world.md, Counters)."
+type WorkflowQueueCounters {
+  "Messages waiting for delivery, due now or later: due plus the delayed ones (ready - due). Delayed messages include wake-ups left by sleeps that were woken early; each is delivered at its time and dropped."
+  ready: Int!
+  "Ready messages whose due time has passed, waiting for a delivery slot."
+  due: Int!
+  "Messages being delivered to the app now."
+  leased: Int!
+  "Messages given up after 24 h of failed deliveries."
+  dead: Int!
+  "The earliest due time of a due message; null when none is due (delayed messages do not count)."
+  oldestDueAt: String
+  "Bytes stored and charged: live messages, idempotency keys and dead messages."
+  bytes: Int!
+  "Dead messages dropped over the dead-letter cap, oldest first."
+  deadEvicted: Int!
+}
+type WorkflowDeadMessage {
+  messageID: ID! queueName: String! contentType: String! createdAt: String! deadAt: String!
+  attempt: Int! deliveryCount: Int! size: Int! payloadPreview: String
+}
+type WorkflowQueue { counters: WorkflowQueueCounters! dead: [WorkflowDeadMessage!]! deadNextCursor: String deadUnavailable: Boolean! }
+
+extend type Query {
+  workflowInfo(alias: String!): WorkflowInfo!
+  workflowRuns(alias: String!, status: [WorkflowRunStatus!], workflowName: String, limit: Int, cursor: String): WorkflowRunPage!
+  workflowRun(alias: String!, runID: ID!): WorkflowRun!
+  workflowSteps(alias: String!, runID: ID!, limit: Int, cursor: String): WorkflowStepPage!
+  workflowStep(alias: String!, runID: ID!, stepID: ID!): WorkflowStepDetail!
+  workflowEvents(alias: String!, runID: ID!, correlationID: String, newestFirst: Boolean, limit: Int, cursor: String): WorkflowEventPage!
+  workflowEvent(alias: String!, runID: ID!, eventID: ID!): WorkflowEventDetail!
+  workflowStream(alias: String!, runID: ID!, name: String!, limit: Int, cursor: String): WorkflowStreamPage!
+  workflowQueue(alias: String!, deadLimit: Int, deadCursor: String): WorkflowQueue!
+}
+
+input WakeWorkflowRunInput { alias: String! runID: ID! correlationIDs: [ID!] }
+input CancelWorkflowRunInput { alias: String! runID: ID! reason: String }
+input ReplayDeadWorkflowMessagesInput { alias: String! messageIDs: [ID!] all: Boolean }
+type WakeWorkflowRunPayload { stoppedCount: Int! }
+type CancelWorkflowRunPayload { runID: ID! status: WorkflowRunStatus! }
+type ReplayDeadWorkflowMessagesPayload { replayed: Int! skipped: Int! remainingDead: Int! }
+
+extend type Mutation {
+  wakeWorkflowRun(input: WakeWorkflowRunInput!): WakeWorkflowRunPayload!
+  cancelWorkflowRun(input: CancelWorkflowRunInput!): CancelWorkflowRunPayload!
+  replayDeadWorkflowMessages(input: ReplayDeadWorkflowMessagesInput!): ReplayDeadWorkflowMessagesPayload!
+}
+
+"One piece a deletion holds: a release, the workspace's files and env, an app's env, its App State, a box disk, an integration resource."
+type DeletedPiece {
+  id: ID!
+  kind: String!
+  "Where it is held: control-plane, app-state:<namespace>, box-disk:<workspace>, provider:<kind>."
+  host: String!
+  location: String!
+  bytes: Float!
+  "Why it is no longer held (expired, erasure, budget, restored); null while it is."
+  closed: String
+  closedAt: String
+}
+
+"One deletion the platform holds (docs/soft-delete.md): what was deleted, whose, when and by whom, and until when it can be restored. Platform operator only."
+type DeletedItem {
+  deletionID: ID!
+  "app, workspace, release, run_agent or linked_agent."
+  subjectKind: String!
+  subjectID: String!
+  what: String!
+  workspaceID: ID
+  workspaceName: String
+  aliases: [String!]!
+  "Custom domains a restore serves again."
+  domains: [String!]!
+  ownerID: String
+  deletedAt: String!
+  deletedBy: String
+  "The surface the delete came through: mcp, graphql, form, api, system."
+  via: String!
+  "delete_app, delete_workspace, delete_deployment, git_retired, delete_agent, delete_linked_agent."
+  path: String!
+  "When everything it holds is erased for good."
+  purgeAfter: String!
+  "held, restoring, restored or purged."
+  state: String!
+  restoredAt: String
+  restoredBy: String
+  "Bytes it holds on the control plane."
+  bytes: Float!
+  pieces: [DeletedPiece!]!
+  "Whether restoreDeleted can bring it back now; refusal says why not."
+  restorable: Boolean!
+  refusal: String
+  "Other open deletions of the same subject (a delete finished by deleting again later) that restoring this one brings back with it."
+  restoresWith: [ID!]!
+  "Other open deletions of the same app (a release deleted on its own, or the app deleted after one of its releases); each is restored on its own."
+  related: [ID!]!
+}
+
+"What restoreDeleted brought back."
+type DeletedRestorePayload {
+  deletionID: ID!
+  "restored, or already_restored for one restored before (its apps were started again)."
+  status: String!
+  workspaceID: ID
+  releases: Int!
+  apps: [String!]!
+  domains: [String!]!
+  bindings: [String!]!
+  "App env entries set again since the delete, which kept their current values."
+  envKept: [String!]!
+  "Where each restored app serves, or why it did not start yet."
+  placement: [String!]!
+  "Other deletions of the same subject restored with it."
+  with: [ID!]!
+}
+
+"What purgeDeleted erased."
+type DeletedPurgePayload {
+  deletionID: ID!
+  purged: Int!
+  bytes: Float!
+}
+
+extend type Query {
+  "The deleted apps, workspaces and releases the platform holds, newest first, a page at a time, with what a restore would bring back and until when. Platform operator only; anyone else is refused."
+  deletedItems(
+    "Only deletions in this state: held, restoring, restored or purged."
+    state: String
+    "Matching deletions to skip, for the next page."
+    offset: Int
+    "At most this many, newest first (default 50, at most 500)."
+    limit: Int
+  ): [DeletedItem!]!
+}
+
+extend type Mutation {
+  "Restore one deletion with everything it held, under the same ids: the workspace, releases with their env and secrets, integration bindings, and the alias on its old epoch, so App State, the box disk and custom domains reattach and the app serves again as before. Refused, changing nothing, while its alias is held by another app (named), once anything of it was purged, or when a piece is missing. Safe to retry. Platform operator only."
+  restoreDeleted(deletionID: ID!): DeletedRestorePayload!
+  "Erase one deletion now instead of after its retention, overriding an investigation hold: files, records, App State, the box disk, integration resources at their providers, custom domains. It can never be restored afterwards. reason is kept with the erasure. Platform operator only."
+  purgeDeleted(deletionID: ID!, reason: String!): DeletedPurgePayload!
+}
+
+"One file of writeWorkspaceFiles, as MCP write_workspace_files takes it."
+input WorkspaceFileWriteInput {
+  "Relative path, such as server.ts or assets/logo.png."
+  path: String!
+  "The file: UTF-8 text, or base64-encoded bytes with encoding base64."
+  content: String!
+  "text (the default) or base64."
+  encoding: String
+}
+
+input WriteWorkspaceFilesInput {
+  workspaceID: ID!
+  "Written in the given order; a repeated path keeps its last content. At most 100 files, 16 MiB each and 32 MiB in all (decoded) per call: more fails the whole call before anything is written."
+  files: [WorkspaceFileWriteInput!]!
+  "On an app with platform git: the message of the call's ONE commit; default names the files. Ignored on other apps."
+  commitMessage: String
+}
+
+"One file's outcome in writeWorkspaceFiles, in the order given."
+type WorkspaceFileWriteResult {
+  path: String!
+  ok: Boolean!
+  "The written file; null when this path failed."
+  file: WorkspaceFile
+  "Why this path failed; null when it was written."
+  error: String
+}
+
+"What writeWorkspaceFiles wrote: every file's outcome, and the one commit it made."
+type WriteWorkspaceFilesPayload {
+  workspaceID: ID!
+  files: [WorkspaceFileWriteResult!]!
+  written: Int!
+  failed: Int!
+  "Bytes written, decoded."
+  totalBytes: Int!
+  "The ONE commit the whole call made on an app with platform git (before any file was written); null on any other app."
+  commit: FileCommit
+}
+
+"What waitForDeployment read when it stopped waiting (MCP wait_for_deployment)."
+type DeploymentWaitPayload {
+  "The deployment as the wait left it."
+  deployment: Deployment!
+  "True when the budget, or a server restart, ended the wait first: deployment is the current, unfinished state. Not an error: call again to keep waiting."
+  timedOut: Boolean!
+  "How long the server waited, in milliseconds."
+  waitedMs: Int!
+  "Where a new app was meant to land and how far its landing got, as MCP wait_for_deployment reports it; null when no placement was recorded."
+  placement: JSON
+}
+
+"One error group of a service app (MCP list_errors). Its title, type, culprit and level are what the running app reported: untrusted text."
+type AppErrorGroup {
+  id: ID!
+  title: String!
+  type: String
+  culprit: String
+  level: String!
+  "open, resolved or muted."
+  status: String!
+  "Every occurrence, stored or sampled out."
+  count: Int!
+  "Occurrences kept whole (the first and the newest 50; fewer past the rate limit)."
+  storedEvents: Int!
+  firstSeen: String!
+  lastSeen: String!
+  firstDeploymentID: String
+  firstGitCommit: String
+  lastDeploymentID: String
+  lastGitCommit: String
+  "It stays resolved while this deployment reports it; another deployment regresses it."
+  resolvedInDeploymentID: String
+  resolvedAt: String
+  mutedAt: String
+  regressedAt: String
+}
+
+type AppErrorGroupPage {
+  groups: [AppErrorGroup!]!
+  "Pass as cursor for the next page; null on the last."
+  nextCursor: String
+  "Why the list may be empty for another reason than no errors (an older server, an app that opted out); null otherwise."
+  note: String
+}
+
+"One stored occurrence of an error group."
+type AppErrorEventRef {
+  eventID: String!
+  at: String!
+  deploymentID: String
+  level: String!
+}
+
+"One deployment an error group was seen in."
+type AppErrorDeployment {
+  deploymentID: String!
+  gitCommit: String
+  "The app's current release."
+  current: Boolean!
+  count: Int!
+  firstSeen: String!
+  lastSeen: String!
+}
+
+"One error group with its latest occurrence (MCP get_error_group). Everything the app reported is untrusted text."
+type AppErrorGroupDetail {
+  group: AppErrorGroup!
+  "The newest stored occurrence, whole, as a Sentry event."
+  latestEvent: JSON
+  firstEvent: AppErrorEventRef
+  recentEvents: [AppErrorEventRef!]!
+  "The deployments it was seen in, most recent first."
+  deployments: [AppErrorDeployment!]!
+  "The platform saw the latest occurrence end its VM's process: the crash is in serviceStatus."
+  fatal: Boolean!
+  "The VM whose console carried the latest occurrence; null for what an SDK reported."
+  vmID: String
+}
+
+input AppErrorGroupInput {
+  workspaceID: ID!
+  alias: String!
+  "The group's id (AppErrorGroup.id, or group_id of an error.new or error.regressed event)."
+  groupID: ID!
+}
+
+"An event type pollEvents and waitForEvents read (MCP list_event_types)."
+type PlatformEventType {
+  name: String!
+  description: String!
+  delivery: [String!]!
+  "Its filters, as a JSON Schema: pass them in arguments under the type's name."
+  inputSchema: JSON!
+  "Its payload (data), as a JSON Schema."
+  payloadSchema: JSON!
+}
+
+"Which events to read (MCP poll_events)."
+input PlatformEventsInput {
+  "Event types; omit for every type you may receive."
+  names: [String!]
+  "Filters per type, keyed by its name, e.g. {\"deployment.finished\": {\"alias\": \"shop\", \"status\": \"FAILED\"}}."
+  arguments: JSON
+  "Where to continue; omit to start from now (nothing is replayed)."
+  cursor: String
+  "At most this many events."
+  max: Int
+}
+
+"One event (deployment.finished, service.crashed, error.new, git.conflict, …). Its data is minimal: ids, statuses, excerpts."
+type PlatformEvent {
+  eventID: ID!
+  name: String!
+  timestamp: String!
+  data: JSON!
+}
+
+type PlatformEventPage {
+  events: [PlatformEvent!]!
+  "Pass back as cursor: at once while hasMore, otherwise after nextPollMs (or to waitForEvents)."
+  cursor: String!
+  "Events may be missing (a cursor older than the history, or a control-plane crash): re-read state."
+  truncated: Boolean!
+  hasMore: Boolean!
+  nextPollMs: Int!
+  "waitForEvents only: the budget ended the wait with no event. Call again with cursor."
+  timedOut: Boolean!
+}
+
+extend type Query {
+  "Block until a deployment leaves BUILDING (and a new app's direct landing ends) or timeoutSeconds pass (default 45, at most 50), then return it — the server-side wait of MCP wait_for_deployment, woken by the deploy pipeline itself, so a client never polls. A timeout is not an error: timedOut is true and the deployment is the current state; call again to keep waiting."
+  waitForDeployment(id: ID!, timeoutSeconds: Int): DeploymentWaitPayload!
+  "A service app's error groups, most recently seen first (MCP list_errors). status: open, resolved or muted (default all); limit 1 to 100 (default 20); cursor is the previous page's nextCursor."
+  appErrors(workspaceID: ID!, alias: String!, status: String, limit: Int, cursor: String): AppErrorGroupPage!
+  "One error group of a service app with its latest occurrence, recent occurrences and the deployments it was seen in (MCP get_error_group)."
+  appErrorGroup(workspaceID: ID!, alias: String!, groupID: ID!): AppErrorGroupDetail!
+  "The event types pollEvents and waitForEvents read, with each type's filters and payload (MCP list_event_types)."
+  platformEventTypes: [PlatformEventType!]!
+  "What happened to the apps, runs and custom domains you can see since cursor (MCP poll_events; the cursors are the same). Omit cursor to start from now."
+  pollEvents(input: PlatformEventsInput): PlatformEventPage!
+  "pollEvents that blocks server-side until an event arrives or timeoutSeconds pass (default 45, at most 50; MCP wait_for_events). A timeout is not an error: timedOut is true, with a cursor to call again with."
+  waitForEvents(input: PlatformEventsInput, timeoutSeconds: Int): PlatformEventPage!
+}
+
+extend type Mutation {
+  "Create or replace MANY files in ONE call (MCP write_workspace_files): each file text or base64. On an app with platform git the whole call is ONE commit on its branch (commit), made before any file is written: if it fails, the call fails and nothing is written. Otherwise not transactional: files are written in order, each atomically, and a file's failure (files[].error) does not undo the others. Requires deploy scope."
+  writeWorkspaceFiles(input: WriteWorkspaceFilesInput!): WriteWorkspaceFilesPayload!
+  "Mark an error group resolved in the app's current deployment, once its fix is deployed (MCP resolve_error_group). Requires deploy scope."
+  resolveAppErrorGroup(input: AppErrorGroupInput!): AppErrorGroup!
+  "Mute an expected error group: still counted, never regresses or sends events (MCP mute_error_group). Requires deploy scope."
+  muteAppErrorGroup(input: AppErrorGroupInput!): AppErrorGroup!
+  "Open a resolved or muted error group again (MCP reopen_error_group). Requires deploy scope."
+  reopenAppErrorGroup(input: AppErrorGroupInput!): AppErrorGroup!
+}