@wix/auto_sdk_containers_projects 1.0.5 → 1.0.7

package/build/internal/cjs/index.typings.d.ts

@@ -1,5 +1,10 @@
 import { NonNullablePaths } from '@wix/sdk-types';
 
+/**
+ * A project represents an app that a user builds with the Wix AI coding agent.
+ * A project belongs to the Wix site it's created on. The user's chat with the coding agent about a
+ * project is held in [conversations](https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-chat/introduction).
+ */
 interface Project {
     /**
      * Project ID.
@@ -8,137 +13,144 @@ interface Project {
      */
     _id?: string | null;
     /**
-     * Display name for the project.
+     * Project name, shown to the user.
      * @maxLength 200
      */
     name?: string;
-    /** Current status of the project. */
+    /** Project status. */
     status?: ProjectStatusWithLiterals;
     /**
-     * ID of the template used to create this project.
+     * ID of the template that the project was created from.
      * @format GUID
      * @immutable
      */
     templateId?: string | null;
     /**
-     * ID of the git-code-store project (and backing dev-center app) for this project. Set on creation.
+     * ID of the project's source code project. Set automatically when the project is created.
      * @format GUID
      * @readonly
      */
     codeStoreProjectId?: string | null;
     /**
-     * The user id of the owner of this project
+     * ID of the user who created the project.
      * @format GUID
      * @readonly
      */
     ownerUserId?: string | null;
     /**
-     * Revision number, which increments by 1 each time the Project is updated.
+     * Revision number, which increments by 1 each time the project is updated.
+     * To prevent conflicting changes,
+     * the current revision must be passed when updating the project.
+     *
+     * Ignored when creating a project.
      * @readonly
      */
     revision?: string | null;
     /**
-     * Date and time the Project was created.
+     * Date and time the project was created.
      * @readonly
      */
     _createdDate?: Date | null;
     /**
-     * Date and time the Project was last updated.
+     * Date and time the project was last updated.
      * @readonly
      */
     _updatedDate?: Date | null;
     /**
-     * Transient lock marking that a sandbox is currently being created for this project.
-     * Used to serialize concurrent dev-machine creation; liveness of the sandbox itself is resolved via ListSandboxes.
+     * Whether a remote development environment is being created for the project.
      * @readonly
      */
     sandboxStatus?: SandboxStatusWithLiterals;
     /**
-     * Meta site IDs (MSIDs) of the Wix sites this project is related to.
-     * Optional — a project is not required to be tied to a site; may relate to many sites.
-     * Preserve the deployed input contract; see containers-projects/SDK_COMPATIBILITY.md.
+     * IDs of the Wix sites that the project relates to.
+     *
+     * A project can relate to any number of sites, including none.
      * @format GUID
      */
     metaSiteIds?: string[];
     /**
-     * Platform this project targets (iOS/Android). Supplied by the client at creation; immutable after.
+     * Platform that the project's app targets. Set when the project is created and can't be changed.
      * @immutable
      */
     platform?: PlatformWithLiterals;
     /**
-     * Optional app icon URL supplied by the client from Wix Media Manager.
+     * URL of the app's icon.
      * @maxLength 2000
      */
     appIconUrl?: string | null;
     /**
-     * The Himalaya release the editor is currently on — the "head" the client previews and the next
-     * edit (design save or AI edit) branches from. Server-managed: set to the new draft after each
-     * edit, and to the chosen release by RestoreRelease. Unset means "newest release by date" (the
-     * pre-head default), so existing projects keep working until their first edit/restore sets it.
-     * Not a GUID — a Himalaya release id (e.g. `rel-<hash>` / `<sha>-<hash>`).
+     * ID of the release that the project is currently on.
+     *
+     * Your app previews this release, and the next design save or edit by the coding agent branches
+     * from it. Set automatically after each design save or edit, and by
+     * [Restore Release](https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/restore-release).
+     * When empty, the project is on its newest release.
      * @maxLength 200
      * @readonly
      */
     headReleaseId?: string | null;
 }
+/**
+ * Project status. The status changes in one direction only: `PLANNING`, then `PLAN_READY`, then
+ * `BUILDING`.
+ */
 declare enum ProjectStatus {
-    /** Project created; client (via containers-plans) is doing most of the work. */
+    /** The user and the coding agent are planning the app. New projects start with this status. */
     PLANNING = "PLANNING",
-    /** Generation job created; project moves onward to machine startup. */
+    /** The coding agent is building the app, or has built it. The user can continue to request changes. */
     BUILDING = "BUILDING",
-    /** Plan finalized; project is about to create the initial generation job. */
+    /** The plan is finalized, and the first build of the app is about to start. */
     PLAN_READY = "PLAN_READY"
 }
 /** @enumType */
 type ProjectStatusWithLiterals = ProjectStatus | 'PLANNING' | 'BUILDING' | 'PLAN_READY';
 declare enum SandboxStatus {
-    /** No sandbox creation in progress. */
+    /** No remote development environment is being created. */
     NONE = "NONE",
-    /** A caller is currently creating a sandbox for this project (creation lock held). */
+    /** A remote development environment is being created. */
     CREATING = "CREATING"
 }
 /** @enumType */
 type SandboxStatusWithLiterals = SandboxStatus | 'NONE' | 'CREATING';
 declare enum Platform {
+    /** Native iOS app. Used by older projects. */
     IOS = "IOS",
+    /** Native Android app. Used by older projects. */
     ANDROID = "ANDROID",
     /**
-     * Himalaya Mobile (Wix SDUI/OTA content package): mobile apps built headlessly on the
-     * on-demand remote machine via the himi CLI, instead of native iOS/Android pods.
+     * Mobile app built from content that's updated over the air, instead of native iOS or Android
+     * code. Most new projects use this platform.
      */
     HIMALAYA_MOBILE = "HIMALAYA_MOBILE"
 }
 /** @enumType */
 type PlatformWithLiterals = Platform | 'IOS' | 'ANDROID' | 'HIMALAYA_MOBILE';
+/** Details of a request to start a project's remote development environment. */
 interface ProjectStartRequested {
     /**
-     * ID of the Project to start.
+     * ID of the project to start.
      * @format GUID
      */
     projectId?: string;
 }
+/** Details of a request to resume a project. */
 interface ProjectResumeRequested {
     /**
-     * ID of the Project to resume.
+     * ID of the project to resume.
      * @format GUID
      */
     projectId?: string;
 }
-/**
- * Emitted when the project transitions PLANNING -> PLAN_READY (on plan finalization). The project
- * self-consumes this event to start the app generation: mint the agent session, attach it to the
- * finalized conversation, create the initial generation job, and move to BUILDING. The finalized
- * plan is read back from containers-plans by project id when the job is built.
- */
+/** Details of a project whose plan is finalized. */
 interface ProjectPlanReady {
     /**
-     * ID of the Project whose plan is ready.
+     * ID of the project whose plan is finalized.
      * @format GUID
      */
     projectId?: string;
     /**
-     * ID of the conversation that led to this plan being finalized. The minted agent session id is
-     * attached to this conversation so the build can --resume it. Propagated from PlanFinalized.
+     * ID of the conversation in which the plan was finalized. The coding agent continues the build in
+     * this conversation.
      * @format GUID
      */
     conversationId?: string;
@@ -357,40 +369,40 @@ interface AccountInfo {
     siteId?: string | null;
 }
 interface CreateProjectRequest {
-    /** Project to be created. */
+    /** Project to create. */
     project: Project;
 }
 interface CreateProjectResponse {
-    /** The created Project. */
+    /** Created project. */
     project?: Project;
 }
 interface GetProjectRequest {
     /**
-     * ID of the Project to retrieve.
+     * ID of the project to retrieve.
      * @format GUID
      */
     projectId: string;
 }
 interface GetProjectResponse {
-    /** The requested Project. */
+    /** Retrieved project. */
     project?: Project;
 }
 interface UpdateProjectRequest {
-    /** Project to be updated, may be partial. */
+    /** Project to update. */
     project: Project;
     /**
-     * Set of fields to update.
+     * Set of fields to update. Fields not in the mask are ignored.
      * @internal
      */
     fieldMask?: string[];
 }
 interface UpdateProjectResponse {
-    /** Updated Project. */
+    /** Updated project. */
     project?: Project;
 }
 interface DeleteProjectRequest {
     /**
-     * Id of the Project to delete.
+     * ID of the project to delete.
      * @format GUID
      */
     projectId: string;
@@ -399,60 +411,60 @@ interface DeleteProjectResponse {
 }
 interface StartProjectRequest {
     /**
-     * ID of the Project to start.
+     * ID of the project to start.
      * @format GUID
      */
     projectId?: string;
 }
 interface StartProjectResponse {
-    /** The Project for which start was requested. */
+    /** Project whose environment is starting. */
     project?: Project;
 }
 interface ResumeProjectRequest {
     /**
-     * ID of the Project to resume.
+     * ID of the project to resume.
      * @format GUID
      */
     projectId: string;
 }
 interface ResumeProjectResponse {
-    /** The Project for which resume was requested. */
+    /** Resumed project. The project is returned unchanged; its environment starts in the background. */
     project?: Project;
 }
 interface RegenerateProjectNameRequest {
     /**
-     * ID of the Project to generate a new name for.
+     * ID of the project to generate a name for.
      * @format GUID
      */
     projectId: string;
     /**
-     * The user's free-text renaming instruction, passed to the name-generation prompt.
+     * User's instruction for the new name. For example, `Make it shorter and more playful`.
      * @maxLength 4000
      */
     prompt: string;
 }
 interface RegenerateProjectNameResponse {
     /**
-     * The generated display name, at most 30 characters. Not persisted.
+     * Suggested project name. Not saved.
      * @maxLength 30
      */
     name?: string;
 }
 interface RegenerateProjectIconRequest {
     /**
-     * ID of the Project to generate a new icon for.
+     * ID of the project to generate an icon for.
      * @format GUID
      */
     projectId: string;
     /**
-     * The user's free-text icon instruction, passed to the icon-generation prompt.
+     * User's instruction for the new icon. For example, `Use a minimal coffee cup`.
      * @maxLength 4000
      */
     prompt: string;
 }
 interface RegenerateProjectIconResponse {
     /**
-     * The generated icon URL. Not persisted.
+     * URL of the suggested icon. Not saved.
      * @format WEB_URL
      */
     iconUrl?: string;
@@ -477,9 +489,9 @@ interface CursorPaging {
     cursor?: string | null;
 }
 interface ListProjectsForCurrentUserResponse {
-    /** Projects owned by the current user. */
+    /** Projects that the current user owns. */
     projects?: Project[];
-    /** Paging metadata for cursor-based pagination. */
+    /** Paging metadata. */
     pagingMetadata?: CursorPagingMetadata;
 }
 interface CursorPagingMetadata {
@@ -509,101 +521,94 @@ interface Cursors {
 }
 interface SaveProjectDesignRequest {
     /**
-     * Project whose design is being saved. The caller must own it.
+     * ID of the project whose design to save.
      * @format GUID
      */
     projectId: string;
     /**
-     * The Himalaya release ID currently displayed by the client. The saved draft branches from
-     * exactly this release, even when a newer release exists for the app.
+     * ID of the release that the user is currently viewing.
+     *
+     * The new draft release branches from this release, even if a newer release exists.
      * @maxLength 100
      */
     baseReleaseId: string;
     /**
-     * The complete edited design-token document, as a JSON object string — not a flattened set of
-     * preview overrides. The caller is responsible for preserving unknown groups and light/dark
-     * values it did not change.
+     * Complete design-token document, as a string that contains a single JSON object.
+     *
+     * Specify the whole document, not only the values that changed. Keep any token groups and light or
+     * dark mode values that you didn't change.
      * @maxLength 65536
      */
     tokensJson: string;
     /**
-     * Short-lived, app-scoped Himalaya control credential the client obtained from Himalaya's owner
-     * embed-token endpoint. Forwarded to Himalaya for this call only — never logged, persisted, or
-     * echoed back in any response, error, or event.
+     * Short-lived control credential for the project's app releases.
      *
-     * The app this call writes to is NOT taken from this request. It is composed from the owner
-     * prefix this credential carries plus project_id; see HimalayaAppSlug.
+     * Used for this call only. It isn't stored or returned.
      * @maxLength 4096
      */
     himalayaControlToken: string;
     /**
-     * Client assertion of the canonical app returned by authenticated Himalaya lookup. Catalyst
-     * resolves and validates the same value; it is never used as an unchecked write target.
+     * Canonical slug of the project's app, exactly as returned in `canonicalApp` by
+     * [Get Himalaya Authorization](https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/get-himalaya-authorization).
+     * This isn't the app's ID.
+     *
+     * Required when the project's `platform` is `HIMALAYA_MOBILE`. The value is verified on the server.
      * @maxLength 200
      */
     canonicalApp?: string;
     /**
-     * Conversation this design is saved from. When set, a CHECKPOINT message marking the saved
-     * version is posted into it (best-effort). Optional — an older client that omits it still saves
-     * the design; it just produces no checkpoint. Verified to belong to this project server-side.
+     * ID of the [conversation](https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-chat/introduction) that the design is saved from.
      *
-     * Deliberately NOT (.wix.api.format) = GUID: posting the checkpoint is best-effort and must never
-     * fail the save. A malformed/unexpected id is handled downstream (the ownership lookup rejects it
-     * and the checkpoint is skipped) rather than hard-failing SaveProjectDesign at the request boundary.
+     * When specified, a `CHECKPOINT` message that marks the saved version is added to the conversation.
+     * The conversation must belong to the project.
      * @maxLength 100
      */
     conversationId?: string;
 }
 interface SaveProjectDesignResponse {
     /**
-     * The saved draft release. Always a draft, so the app's live release is untouched.
+     * ID of the saved draft release.
      * @maxLength 100
      */
     himalayaReleaseId?: string;
     /**
-     * Short-lived credential for previewing the saved draft release. Response-only: never persisted
-     * or placed in a preview URL by this service.
+     * Short-lived token for previewing the saved draft release.
      * @maxLength 4096
      */
     previewToken?: string;
-    /** When preview_token expires. */
+    /** Date and time the preview token expires. */
     previewTokenExpiresAt?: Date | null;
 }
 interface RestoreReleaseRequest {
     /**
-     * Project whose head is being moved. The caller must own it.
+     * ID of the project to restore a release for.
      * @format GUID
      */
     projectId: string;
     /**
-     * The Himalaya release to make the project's editable head. Not a GUID — a Himalaya release id
-     * (e.g. `rel-<hash>` / `<sha>-<hash>`), taken from the project's own release ledger.
+     * ID of the release to restore. For example, `rel-4f9c2a1b7d3e`.
      * @maxLength 200
      */
     releaseId: string;
     /**
-     * Short-lived, app-scoped Himalaya control credential (the same the client obtains from Himalaya's
-     * owner embed-token endpoint and sends on SaveProjectDesign). When present, the server verifies
-     * release_id belongs to this project's Himalaya app before moving head. Optional for back-compat:
-     * an older client that omits it skips that check (the release still comes from the project's own
-     * ledger). Forwarded to Himalaya for the ledger read only — never logged, persisted, or echoed.
+     * Short-lived control credential for the project's app releases.
+     *
+     * When specified, the release is checked to belong to the project before it's restored. Used for
+     * this call only. It isn't stored or returned.
      * @maxLength 4096
      */
     himalayaControlToken?: string;
     /**
-     * Conversation this restore is made from. When set, a CHECKPOINT message marking the restored
-     * version is posted into it (best-effort). Optional — a client that omits it still restores; it
-     * just produces no checkpoint. Verified to belong to this project server-side.
+     * ID of the [conversation](https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-chat/introduction) that the release is restored from.
      *
-     * Deliberately NOT (.wix.api.format) = GUID: posting the checkpoint is best-effort and must never
-     * fail the restore. A malformed id is handled downstream (the ownership lookup rejects it and the
-     * checkpoint is skipped) rather than hard-failing RestoreRelease at the request boundary.
+     * When specified, a `CHECKPOINT` message that marks the restored version is added to the
+     * conversation. The conversation must belong to the project.
      * @maxLength 100
      */
     conversationId?: string;
 }
 interface RestoreReleaseResponse {
-    /** The project after the restore, with head_release_id set to the restored release. */
+    /** Updated project. `headReleaseId` is set to the restored release. */
     project?: Project;
 }
 interface ListProjectsRequest {
@@ -611,71 +616,77 @@ interface ListProjectsRequest {
     paging?: CursorPaging;
 }
 interface ListProjectsResponse {
-    /** Projects in the current site. */
+    /** Projects of the current site. */
     projects?: Project[];
-    /** Paging metadata for cursor-based pagination. */
+    /** Paging metadata. */
     pagingMetadata?: CursorPagingMetadata;
 }
 interface GetHimalayaAuthorizationRequest {
     /**
-     * Site-tenanted Containers project being authorized.
+     * ID of the project to check.
      * @format GUID
      */
     projectId: string;
 }
 interface GetHimalayaAuthorizationResponse {
-    /** Version of the authorization capability contract. */
+    /** Version of the response format. Currently always `1`. */
     authorizationVersion?: number;
     /**
-     * Trusted MetaSite selected from request identity context.
+     * ID of the Wix site that the check was made for.
      * @format GUID
      */
     metaSiteId?: string;
     /**
-     * Site-tenanted Containers project authorized by the lookup.
+     * Project ID.
      * @format GUID
      */
     projectId?: string;
     /**
-     * Verified canonical Himalaya app slug.
+     * Canonical slug of the project's app.
+     *
+     * Specify this value in `canonicalApp` when you call
+     * [Save Project Design](https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/save-project-design).
      * @maxLength 200
      */
     canonicalApp?: string;
-    /** Whether a fresh worker launch is currently authorized. */
+    /** Whether the current user can start new work by the coding agent on the project. */
     workerLaunch?: boolean;
-    /** Whether a fresh design save is currently authorized. */
+    /** Whether the current user can save the project's design. */
     saveDesign?: boolean;
 }
 /**
- * Creates a new Project from a template.
- * Looks up the template to find its backing source code, creates a dev-center app,
- * registers an AppProject, clones the template's git repository into a new
- * code-store project, and persists the Project.
- * @param project - Project to be created.
+ * Creates a project from a template.
+ *
+ * The project is created with `PLANNING` status.
+ * @param project - Project to create.
  * @internal
  * @documentationMaturity preview
  * @requiredField project
  * @requiredField project.platform
  * @requiredField project.templateId
  * @permissionId containers:projects:v1:project:create_project
- * @returns The created Project.
+ * @returns Created project.
  * @fqn wix.containers.projects.v1.ContainersProjects.CreateProject
  */
 declare function createProject(project: NonNullablePaths<Project, `platform` | `templateId`, 0>): Promise<NonNullablePaths<Project, `name` | `status` | `sandboxStatus` | `metaSiteIds` | `platform`, 0>>;
 /**
- * Retrieves a Project by ID.
- * @param projectId - ID of the Project to retrieve.
+ * Retrieves a project.
+ * @param projectId - ID of the project to retrieve.
  * @public
  * @documentationMaturity preview
  * @requiredField projectId
  * @permissionId containers:projects:v1:project:get_project
  * @applicableIdentity APP
- * @returns The requested Project.
+ * @returns Retrieved project.
  * @fqn wix.containers.projects.v1.ContainersProjects.GetProject
  */
 declare function getProject(projectId: string): Promise<NonNullablePaths<Project, `name` | `status` | `sandboxStatus` | `metaSiteIds` | `platform`, 0>>;
 /**
- * Updates an existing Project.
+ * Updates a project.
+ *
+ * Each time the project is updated, `revision` increments by 1. The current `revision` must be
+ * passed when updating the project. This ensures you're working with the latest project and
+ * prevents unintended overwrites.
  * @param _id - Project ID.
  * @internal
  * @documentationMaturity preview
@@ -683,7 +694,7 @@ declare function getProject(projectId: string): Promise<NonNullablePaths<Project
  * @requiredField project
  * @requiredField project.revision
  * @permissionId containers:projects:v1:project:update_project
- * @returns Updated Project.
+ * @returns Updated project.
  * @fqn wix.containers.projects.v1.ContainersProjects.UpdateProject
  */
 declare function updateProject(_id: string, project: NonNullablePaths<UpdateProject, `revision`, 0>): Promise<NonNullablePaths<Project, `name` | `status` | `sandboxStatus` | `metaSiteIds` | `platform`, 0>>;
@@ -695,82 +706,86 @@ interface UpdateProject {
      */
     _id?: string | null;
     /**
-     * Display name for the project.
+     * Project name, shown to the user.
      * @maxLength 200
      */
     name?: string;
-    /** Current status of the project. */
+    /** Project status. */
     status?: ProjectStatusWithLiterals;
     /**
-     * ID of the template used to create this project.
+     * ID of the template that the project was created from.
      * @format GUID
      * @immutable
      */
     templateId?: string | null;
     /**
-     * ID of the git-code-store project (and backing dev-center app) for this project. Set on creation.
+     * ID of the project's source code project. Set automatically when the project is created.
      * @format GUID
      * @readonly
      */
     codeStoreProjectId?: string | null;
     /**
-     * The user id of the owner of this project
+     * ID of the user who created the project.
      * @format GUID
      * @readonly
      */
     ownerUserId?: string | null;
     /**
-     * Revision number, which increments by 1 each time the Project is updated.
+     * Revision number, which increments by 1 each time the project is updated.
+     * To prevent conflicting changes,
+     * the current revision must be passed when updating the project.
+     *
+     * Ignored when creating a project.
      * @readonly
      */
     revision?: string | null;
     /**
-     * Date and time the Project was created.
+     * Date and time the project was created.
      * @readonly
      */
     _createdDate?: Date | null;
     /**
-     * Date and time the Project was last updated.
+     * Date and time the project was last updated.
      * @readonly
      */
     _updatedDate?: Date | null;
     /**
-     * Transient lock marking that a sandbox is currently being created for this project.
-     * Used to serialize concurrent dev-machine creation; liveness of the sandbox itself is resolved via ListSandboxes.
+     * Whether a remote development environment is being created for the project.
      * @readonly
      */
     sandboxStatus?: SandboxStatusWithLiterals;
     /**
-     * Meta site IDs (MSIDs) of the Wix sites this project is related to.
-     * Optional — a project is not required to be tied to a site; may relate to many sites.
-     * Preserve the deployed input contract; see containers-projects/SDK_COMPATIBILITY.md.
+     * IDs of the Wix sites that the project relates to.
+     *
+     * A project can relate to any number of sites, including none.
      * @format GUID
      */
     metaSiteIds?: string[];
     /**
-     * Platform this project targets (iOS/Android). Supplied by the client at creation; immutable after.
+     * Platform that the project's app targets. Set when the project is created and can't be changed.
      * @immutable
      */
     platform?: PlatformWithLiterals;
     /**
-     * Optional app icon URL supplied by the client from Wix Media Manager.
+     * URL of the app's icon.
      * @maxLength 2000
      */
     appIconUrl?: string | null;
     /**
-     * The Himalaya release the editor is currently on — the "head" the client previews and the next
-     * edit (design save or AI edit) branches from. Server-managed: set to the new draft after each
-     * edit, and to the chosen release by RestoreRelease. Unset means "newest release by date" (the
-     * pre-head default), so existing projects keep working until their first edit/restore sets it.
-     * Not a GUID — a Himalaya release id (e.g. `rel-<hash>` / `<sha>-<hash>`).
+     * ID of the release that the project is currently on.
+     *
+     * Your app previews this release, and the next design save or edit by the coding agent branches
+     * from it. Set automatically after each design save or edit, and by
+     * [Restore Release](https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/restore-release).
+     * When empty, the project is on its newest release.
      * @maxLength 200
      * @readonly
      */
     headReleaseId?: string | null;
 }
 /**
- * Deletes a Project.
- * @param projectId - Id of the Project to delete.
+ * Deletes a project.
+ * @param projectId - ID of the project to delete.
  * @internal
  * @documentationMaturity preview
  * @requiredField projectId
@@ -779,8 +794,16 @@ interface UpdateProject {
  */
 declare function deleteProject(projectId: string): Promise<void>;
 /**
- * Requests Project resume by starting or reusing its configured remote machine asynchronously.
- * @param projectId - ID of the Project to resume.
+ * Resumes work on a project by starting its remote development environment, or by reusing an
+ * environment that's already running.
+ *
+ * Call this method when a user returns to a project with `BUILDING` status, before they send new
+ * requests to the coding agent. The environment starts in the background, and the method returns
+ * the project without waiting for it. The API doesn't report when the environment is ready. The
+ * coding agent picks up new work as soon as it is.
+ *
+ * The project's `status` must be `BUILDING`.
+ * @param projectId - ID of the project to resume.
  * @public
  * @documentationMaturity preview
  * @requiredField projectId
@@ -790,12 +813,11 @@ declare function deleteProject(projectId: string): Promise<void>;
  */
 declare function resumeProject(projectId: string): Promise<NonNullablePaths<ResumeProjectResponse, `project.name` | `project.status` | `project.sandboxStatus` | `project.metaSiteIds` | `project.platform`, 1>>;
 /**
- * Generates a candidate display name for a Project from a user instruction, via the published
- * "Regenerate app name" Prompt Hub prompt. The current name and the project's description are
- * resolved server-side; the caller supplies only the instruction. Does not persist the result —
- * the caller saves an accepted name with UpdateProject.
- * @param projectId - ID of the Project to generate a new name for.
- * @param prompt - The user's free-text renaming instruction, passed to the name-generation prompt.
+ * Generates a suggested name for a project, based on the user's instruction.
+ *
+ * The suggested name isn't saved. To save it, call Update Project.
+ * @param projectId - ID of the project to generate a name for.
+ * @param prompt - User's instruction for the new name. For example, `Make it shorter and more playful`.
  * @internal
  * @documentationMaturity preview
  * @requiredField projectId
@@ -805,11 +827,12 @@ declare function resumeProject(projectId: string): Promise<NonNullablePaths<Resu
  */
 declare function regenerateProjectName(projectId: string, prompt: string): Promise<NonNullablePaths<RegenerateProjectNameResponse, `name`, 0>>;
 /**
- * Generates a candidate icon for a Project from a user instruction. The current project name,
- * icon, app description, and brand colors are resolved server-side. Does not persist the result —
- * the caller saves an accepted icon with UpdateProject.
- * @param projectId - ID of the Project to generate a new icon for.
- * @param prompt - The user's free-text icon instruction, passed to the icon-generation prompt.
+ * Generates a suggested icon for a project, based on the user's instruction.
+ *
+ * The icon is based on the project's current name, icon, description, and brand colors. The
+ * suggested icon isn't saved. To save it, call Update Project.
+ * @param projectId - ID of the project to generate an icon for.
+ * @param prompt - User's instruction for the new icon. For example, `Use a minimal coffee cup`.
  * @internal
  * @documentationMaturity preview
  * @requiredField projectId
@@ -819,17 +842,26 @@ declare function regenerateProjectName(projectId: string, prompt: string): Promi
  */
 declare function regenerateProjectIcon(projectId: string, prompt: string): Promise<NonNullablePaths<RegenerateProjectIconResponse, `iconUrl`, 0>>;
 /**
- * Persists a complete design-token document as a new Himalaya draft release, branched from the
- * release the client currently has displayed.
+ * Saves a project's design as a new draft release.
+ *
+ * Specify the complete design-token document in `tokensJson`, and the release that the user is
+ * currently viewing in `baseReleaseId`. The new draft release branches from `baseReleaseId`, even
+ * if a newer release exists. Saving a design doesn't change the project's live app.
+ *
+ * The response includes the ID of the new release and a short-lived token for previewing it. After
+ * the save, the project's `headReleaseId` is set to the new release.
+ *
+ * To record the saved version in a conversation, specify the conversation's ID in `conversationId`.
+ * A `CHECKPOINT` message is then added to the conversation. If the checkpoint can't be added, the
+ * design is still saved.
  *
- * Synchronous: the Himalaya write completes before this call returns. Never touches the project's
- * sandbox, runs a build, or activates the app — the saved release stays a draft, so what the live
- * app serves is unaffected. Persists no entity of its own. When `conversation_id` is supplied it
- * posts a CHECKPOINT message for the saved release into that conversation (best-effort — a chat
- * failure never fails the save); omit it to skip the checkpoint.
- * @param projectId - Project whose design is being saved. The caller must own it.
- * @param baseReleaseId - The Himalaya release ID currently displayed by the client. The saved draft branches from
- * exactly this release, even when a newer release exists for the app.
+ * For projects whose `platform` is `HIMALAYA_MOBILE`, call
+ * [Get Himalaya Authorization](https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/get-himalaya-authorization)
+ * first, and specify the returned `canonicalApp`.
+ * @param projectId - ID of the project whose design to save.
+ * @param baseReleaseId - ID of the release that the user is currently viewing.
+ *
+ * The new draft release branches from this release, even if a newer release exists.
  * @public
  * @documentationMaturity preview
  * @requiredField baseReleaseId
@@ -843,53 +875,53 @@ declare function regenerateProjectIcon(projectId: string, prompt: string): Promi
 declare function saveProjectDesign(projectId: string, baseReleaseId: string, options?: NonNullablePaths<SaveProjectDesignOptions, `himalayaControlToken` | `tokensJson`, 0>): Promise<NonNullablePaths<SaveProjectDesignResponse, `himalayaReleaseId` | `previewToken`, 0>>;
 interface SaveProjectDesignOptions {
     /**
-     * The complete edited design-token document, as a JSON object string — not a flattened set of
-     * preview overrides. The caller is responsible for preserving unknown groups and light/dark
-     * values it did not change.
+     * Complete design-token document, as a string that contains a single JSON object.
+     *
+     * Specify the whole document, not only the values that changed. Keep any token groups and light or
+     * dark mode values that you didn't change.
      * @maxLength 65536
      */
     tokensJson: string;
     /**
-     * Short-lived, app-scoped Himalaya control credential the client obtained from Himalaya's owner
-     * embed-token endpoint. Forwarded to Himalaya for this call only — never logged, persisted, or
-     * echoed back in any response, error, or event.
+     * Short-lived control credential for the project's app releases.
      *
-     * The app this call writes to is NOT taken from this request. It is composed from the owner
-     * prefix this credential carries plus project_id; see HimalayaAppSlug.
+     * Used for this call only. It isn't stored or returned.
      * @maxLength 4096
      */
     himalayaControlToken: string;
     /**
-     * Client assertion of the canonical app returned by authenticated Himalaya lookup. Catalyst
-     * resolves and validates the same value; it is never used as an unchecked write target.
+     * Canonical slug of the project's app, exactly as returned in `canonicalApp` by
+     * [Get Himalaya Authorization](https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/get-himalaya-authorization).
+     * This isn't the app's ID.
+     *
+     * Required when the project's `platform` is `HIMALAYA_MOBILE`. The value is verified on the server.
      * @maxLength 200
      */
     canonicalApp?: string;
     /**
-     * Conversation this design is saved from. When set, a CHECKPOINT message marking the saved
-     * version is posted into it (best-effort). Optional — an older client that omits it still saves
-     * the design; it just produces no checkpoint. Verified to belong to this project server-side.
+     * ID of the [conversation](https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-chat/introduction) that the design is saved from.
      *
-     * Deliberately NOT (.wix.api.format) = GUID: posting the checkpoint is best-effort and must never
-     * fail the save. A malformed/unexpected id is handled downstream (the ownership lookup rejects it
-     * and the checkpoint is skipped) rather than hard-failing SaveProjectDesign at the request boundary.
+     * When specified, a `CHECKPOINT` message that marks the saved version is added to the conversation.
+     * The conversation must belong to the project.
      * @maxLength 100
      */
     conversationId?: string;
 }
 /**
- * Restores an earlier version by pointing the project's editable head at `release_id`: the client
- * then previews that release and the next edit (design save or AI edit) branches from it. Pure
- * project state — sets `head_release_id` and nothing in Himalaya: it does NOT activate the release,
- * so the live app end-users run is untouched (a later publish/build is what carries head live).
+ * Restores an earlier version of a project.
+ *
+ * Sets the project's `headReleaseId` to the release specified in `releaseId`. Your app then
+ * previews that release, and the next design save or edit by the coding agent branches from it.
+ * Restoring a release doesn't change the project's live app.
+ *
+ * Only the project's owner can restore a release.
  *
- * `release_id` is a Himalaya release id the caller already holds from the project's own release
- * ledger, scoped to this project's app; the server stores it as head without re-reading Himalaya.
- * When `conversation_id` is supplied, a CHECKPOINT message for the restored release is posted into
- * it (best-effort — a chat failure never fails the restore); omit it to skip the checkpoint.
- * @param projectId - Project whose head is being moved. The caller must own it.
- * @param releaseId - The Himalaya release to make the project's editable head. Not a GUID — a Himalaya release id
- * (e.g. `rel-<hash>` / `<sha>-<hash>`), taken from the project's own release ledger.
+ * To confirm that the release belongs to the project before it's restored, specify
+ * `himalayaControlToken`. To record the restored version in a conversation, specify the
+ * conversation's ID in `conversationId`. A `CHECKPOINT` message is then added to the conversation.
+ * If the checkpoint can't be added, the release is still restored.
+ * @param projectId - ID of the project to restore a release for.
+ * @param releaseId - ID of the release to restore. For example, `rel-4f9c2a1b7d3e`.
  * @public
  * @documentationMaturity preview
  * @requiredField projectId
@@ -901,31 +933,26 @@ interface SaveProjectDesignOptions {
 declare function restoreRelease(projectId: string, releaseId: string, options?: RestoreReleaseOptions): Promise<NonNullablePaths<RestoreReleaseResponse, `project.name` | `project.status` | `project.sandboxStatus` | `project.metaSiteIds` | `project.platform`, 1>>;
 interface RestoreReleaseOptions {
     /**
-     * Short-lived, app-scoped Himalaya control credential (the same the client obtains from Himalaya's
-     * owner embed-token endpoint and sends on SaveProjectDesign). When present, the server verifies
-     * release_id belongs to this project's Himalaya app before moving head. Optional for back-compat:
-     * an older client that omits it skips that check (the release still comes from the project's own
-     * ledger). Forwarded to Himalaya for the ledger read only — never logged, persisted, or echoed.
+     * Short-lived control credential for the project's app releases.
+     *
+     * When specified, the release is checked to belong to the project before it's restored. Used for
+     * this call only. It isn't stored or returned.
      * @maxLength 4096
      */
     himalayaControlToken?: string;
     /**
-     * Conversation this restore is made from. When set, a CHECKPOINT message marking the restored
-     * version is posted into it (best-effort). Optional — a client that omits it still restores; it
-     * just produces no checkpoint. Verified to belong to this project server-side.
+     * ID of the [conversation](https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-chat/introduction) that the release is restored from.
      *
-     * Deliberately NOT (.wix.api.format) = GUID: posting the checkpoint is best-effort and must never
-     * fail the restore. A malformed id is handled downstream (the ownership lookup rejects it and the
-     * checkpoint is skipped) rather than hard-failing RestoreRelease at the request boundary.
+     * When specified, a `CHECKPOINT` message that marks the restored version is added to the
+     * conversation. The conversation must belong to the project.
      * @maxLength 100
      */
     conversationId?: string;
 }
 /**
- * Lists the Projects of the current site — the MetaSite in the call scope — regardless of who owns
- * them. Anyone with access to the site sees the site's projects; other sites in the same account are
- * separate tenants and never appear here. The dashboard uses this; ListProjectsForCurrentUser stays
- * owner-scoped for callers that still depend on it.
+ * Retrieves the projects of the current site, regardless of who created them.
+ *
+ * Projects of other sites in the same account aren't included.
  * @internal
  * @documentationMaturity preview
  * @permissionId containers:projects:v1:project:list_projects
@@ -937,9 +964,15 @@ interface ListProjectsOptions {
     paging?: CursorPaging;
 }
 /**
- * Repeats authenticated Himalaya authorization for the current collaborator. This response is
- * a capability check only; every worker/design mutation performs a fresh check.
- * @param projectId - Site-tenanted Containers project being authorized.
+ * Checks whether the current user can work on a project's app.
+ *
+ * Supported for projects whose `platform` is `HIMALAYA_MOBILE`. The response returns the canonical
+ * slug of the project's app in `canonicalApp`. Specify this value when you call
+ * [Save Project Design](https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/save-project-design).
+ *
+ * The response is a check only and doesn't grant access. Each later change to the project is
+ * authorized again.
+ * @param projectId - ID of the project to check.
  * @public
  * @documentationMaturity preview
  * @requiredField projectId