feat(api): manual updates

.stats.yml

@@ -1,2 +1,2 @@
 configured_endpoints: 111
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/gitpod%2Fgitpod-cd6a05ae99d2a050577fa0e729e6ae89b4eacd78f61366a77269398368f8a877.yml
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/gitpod%2Fgitpod-d6a243325df36817d495ce6dd54f80766b77a97e1ca2f6d371c0a68b7d070e0f.yml

src/resources/events.ts

@@ -11,8 +11,32 @@ import { JSONLDecoder } from '../internal/decoders/jsonl';
 
 export class Events extends APIResource {
   /**
-   * ListAuditLogs retrieves a paginated list of audit logs for the specified
-   * organization
+   * Lists audit logs with filtering and pagination options.
+   *
+   * Use this method to:
+   *
+   * - View audit history
+   * - Track user actions
+   * - Monitor system changes
+   *
+   * ### Examples
+   *
+   * - List all logs:
+   *
+   *   ```yaml
+   *   pagination:
+   *     pageSize: 20
+   *   ```
+   *
+   * - Filter by actor:
+   *
+   *   ```yaml
+   *   filter:
+   *     actorIds: ["d2c94c27-3b76-4a42-b88c-95a85e392c68"]
+   *     actorPrincipals: ["PRINCIPAL_USER"]
+   *   pagination:
+   *     pageSize: 20
+   *   ```
    */
   list(
     params: EventListParams,
@@ -28,7 +52,23 @@ export class Events extends APIResource {
   }
 
   /**
-   * WatchEvents streams all requests events to the client
+   * Streams events for all projects, runners, environments, tasks, and services
+   * based on the specified scope.
+   *
+   * Use this method to:
+   *
+   * - Monitor resource changes in real-time
+   * - Track system events
+   * - Receive notifications
+   *
+   * The scope parameter determines which events to watch:
+   *
+   * - Organization scope (default): Watch all organization-wide events including
+   *   projects, runners and environments. Task and service events are not included.
+   *   Use by setting organization=true or omitting the scope.
+   * - Environment scope: Watch events for a specific environment, including its
+   *   tasks, task executions, and services. Use by setting environment_id to the
+   *   UUID of the environment to watch.
    */
   watch(body: EventWatchParams, options?: RequestOptions): APIPromise<JSONLDecoder<EventWatchResponse>> {
     return this._client

src/resources/groups.ts

@@ -6,7 +6,35 @@ import { RequestOptions } from '../internal/request-options';
 
 export class Groups extends APIResource {
   /**
-   * ListGroups lists groups
+   * Lists groups with optional pagination.
+   *
+   * Use this method to:
+   *
+   * - View all groups
+   * - Check group memberships
+   * - Monitor group configurations
+   * - Audit group access
+   *
+   * ### Examples
+   *
+   * - List all groups:
+   *
+   *   Shows all groups with pagination.
+   *
+   *   ```yaml
+   *   pagination:
+   *     pageSize: 20
+   *   ```
+   *
+   * - List with custom page size:
+   *
+   *   Shows groups with specified page size.
+   *
+   *   ```yaml
+   *   pagination:
+   *     pageSize: 50
+   *     token: "next-page-token-from-previous-response"
+   *   ```
    */
   list(params: GroupListParams, options?: RequestOptions): PagePromise<GroupsGroupsPage, Group> {
     const { token, pageSize, ...body } = params;

src/resources/projects/policies.ts

@@ -7,21 +7,75 @@ import { RequestOptions } from '../../internal/request-options';
 
 export class Policies extends APIResource {
   /**
-   * CreateProjectPolicy creates a Project Policy.
+   * Creates a new policy for a project.
+   *
+   * Use this method to:
+   *
+   * - Set up access controls
+   * - Define group permissions
+   * - Configure role-based access
+   *
+   * ### Examples
+   *
+   * - Create admin policy:
+   *
+   *   Grants admin access to a group.
+   *
+   *   ```yaml
+   *   projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+   *   groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
+   *   role: PROJECT_ROLE_ADMIN
+   *   ```
    */
   create(body: PolicyCreateParams, options?: RequestOptions): APIPromise<PolicyCreateResponse> {
     return this._client.post('/gitpod.v1.ProjectService/CreateProjectPolicy', { body, ...options });
   }
 
   /**
-   * UpdateProjectPolicy updates a Project Policy.
+   * Updates an existing project policy.
+   *
+   * Use this method to:
+   *
+   * - Modify access levels
+   * - Change group roles
+   * - Update permissions
+   *
+   * ### Examples
+   *
+   * - Update policy role:
+   *
+   *   Changes a group's access level.
+   *
+   *   ```yaml
+   *   projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+   *   groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
+   *   role: PROJECT_ROLE_EDITOR
+   *   ```
    */
   update(body: PolicyUpdateParams, options?: RequestOptions): APIPromise<PolicyUpdateResponse> {
     return this._client.post('/gitpod.v1.ProjectService/UpdateProjectPolicy', { body, ...options });
   }
 
   /**
-   * ListProjectPolicies lists policies for a project.
+   * Lists policies for a project.
+   *
+   * Use this method to:
+   *
+   * - View access controls
+   * - Check policy configurations
+   * - Audit permissions
+   *
+   * ### Examples
+   *
+   * - List policies:
+   *
+   *   Shows all policies for a project.
+   *
+   *   ```yaml
+   *   projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+   *   pagination:
+   *     pageSize: 20
+   *   ```
    */
   list(
     params: PolicyListParams,
@@ -36,7 +90,24 @@ export class Policies extends APIResource {
   }
 
   /**
-   * DeleteProjectPolicy deletes a Project Policy.
+   * Deletes a project policy.
+   *
+   * Use this method to:
+   *
+   * - Remove access controls
+   * - Revoke permissions
+   * - Clean up policies
+   *
+   * ### Examples
+   *
+   * - Delete policy:
+   *
+   *   Removes a group's access policy.
+   *
+   *   ```yaml
+   *   projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+   *   groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
+   *   ```
    */
   delete(body: PolicyDeleteParams, options?: RequestOptions): APIPromise<unknown> {
     return this._client.post('/gitpod.v1.ProjectService/DeleteProjectPolicy', { body, ...options });

src/resources/projects/projects.ts

@@ -24,28 +24,128 @@ export class Projects extends APIResource {
   policies: PoliciesAPI.Policies = new PoliciesAPI.Policies(this._client);
 
   /**
-   * CreateProject creates a new Project.
+   * Creates a new project with specified configuration.
+   *
+   * Use this method to:
+   *
+   * - Set up development projects
+   * - Configure project environments
+   * - Define project settings
+   * - Initialize project content
+   *
+   * ### Examples
+   *
+   * - Create basic project:
+   *
+   *   Creates a project with minimal configuration.
+   *
+   *   ```yaml
+   *   name: "Web Application"
+   *   environmentClass:
+   *     environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   initializer:
+   *     specs:
+   *       - git:
+   *           remoteUri: "https://github.com/org/repo"
+   *   ```
+   *
+   * - Create project with devcontainer:
+   *
+   *   Creates a project with custom development container.
+   *
+   *   ```yaml
+   *   name: "Backend Service"
+   *   environmentClass:
+   *     environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   initializer:
+   *     specs:
+   *       - git:
+   *           remoteUri: "https://github.com/org/backend"
+   *   devcontainerFilePath: ".devcontainer/devcontainer.json"
+   *   automationsFilePath: ".gitpod/automations.yaml"
+   *   ```
    */
   create(body: ProjectCreateParams, options?: RequestOptions): APIPromise<ProjectCreateResponse> {
     return this._client.post('/gitpod.v1.ProjectService/CreateProject', { body, ...options });
   }
 
   /**
-   * GetProject retrieves a single Project.
+   * Gets details about a specific project.
+   *
+   * Use this method to:
+   *
+   * - View project configuration
+   * - Check project status
+   * - Get project metadata
+   *
+   * ### Examples
+   *
+   * - Get project details:
+   *
+   *   Retrieves information about a specific project.
+   *
+   *   ```yaml
+   *   projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+   *   ```
    */
   retrieve(body: ProjectRetrieveParams, options?: RequestOptions): APIPromise<ProjectRetrieveResponse> {
     return this._client.post('/gitpod.v1.ProjectService/GetProject', { body, ...options });
   }
 
   /**
-   * UpdateProject updates the properties of a Project.
+   * Updates a project's configuration.
+   *
+   * Use this method to:
+   *
+   * - Modify project settings
+   * - Update environment class
+   * - Change project name
+   * - Configure initializers
+   *
+   * ### Examples
+   *
+   * - Update project name:
+   *
+   *   Changes the project's display name.
+   *
+   *   ```yaml
+   *   projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+   *   name: "New Project Name"
+   *   ```
+   *
+   * - Update environment class:
+   *
+   *   Changes the project's environment class.
+   *
+   *   ```yaml
+   *   projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+   *   environmentClass:
+   *     environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   ```
    */
   update(body: ProjectUpdateParams, options?: RequestOptions): APIPromise<ProjectUpdateResponse> {
     return this._client.post('/gitpod.v1.ProjectService/UpdateProject', { body, ...options });
   }
 
   /**
-   * ListProjects lists all projects the caller has access to.
+   * Lists projects with optional filtering.
+   *
+   * Use this method to:
+   *
+   * - View all accessible projects
+   * - Browse project configurations
+   * - Monitor project status
+   *
+   * ### Examples
+   *
+   * - List projects:
+   *
+   *   Shows all projects with pagination.
+   *
+   *   ```yaml
+   *   pagination:
+   *     pageSize: 20
+   *   ```
    */
   list(params: ProjectListParams, options?: RequestOptions): PagePromise<ProjectsProjectsPage, Project> {
     const { token, pageSize, ...body } = params;
@@ -58,14 +158,47 @@ export class Projects extends APIResource {
   }
 
   /**
-   * DeleteProject deletes the specified project.
+   * Deletes a project permanently.
+   *
+   * Use this method to:
+   *
+   * - Remove unused projects
+   * - Clean up test projects
+   * - Delete obsolete configurations
+   *
+   * ### Examples
+   *
+   * - Delete project:
+   *
+   *   Permanently removes a project.
+   *
+   *   ```yaml
+   *   projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+   *   ```
    */
   delete(body: ProjectDeleteParams, options?: RequestOptions): APIPromise<unknown> {
     return this._client.post('/gitpod.v1.ProjectService/DeleteProject', { body, ...options });
   }
 
   /**
-   * CreateProject creates a new Project using an environment as template.
+   * Creates a new project using an existing environment as a template.
+   *
+   * Use this method to:
+   *
+   * - Clone environment configurations
+   * - Create projects from templates
+   * - Share environment setups
+   *
+   * ### Examples
+   *
+   * - Create from environment:
+   *
+   *   Creates a project based on existing environment.
+   *
+   *   ```yaml
+   *   name: "Frontend Project"
+   *   environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
+   *   ```
    */
   createFromEnvironment(
     body: ProjectCreateFromEnvironmentParams,

src/resources/runners/configurations/configurations.ts

@@ -60,8 +60,29 @@ export class Configurations extends APIResource {
   scmIntegrations: ScmIntegrationsAPI.ScmIntegrations = new ScmIntegrationsAPI.ScmIntegrations(this._client);
 
   /**
-   * ValidateRunnerConfiguration validates a runner configuration (e.g. environment
-   * class, SCM integration) with the runner.
+   * Validates a runner configuration.
+   *
+   * Use this method to:
+   *
+   * - Check configuration validity
+   * - Verify integration settings
+   * - Validate environment classes
+   *
+   * ### Examples
+   *
+   * - Validate SCM integration:
+   *
+   *   Checks if an SCM integration is valid.
+   *
+   *   ```yaml
+   *   runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   scmIntegration:
+   *     id: "integration-id"
+   *     scmId: "github"
+   *     host: "github.com"
+   *     oauthClientId: "client_id"
+   *     oauthPlaintextClientSecret: "client_secret"
+   *   ```
    */
   validate(
     body: ConfigurationValidateParams,

src/resources/runners/configurations/environment-classes.ts

@@ -10,7 +10,30 @@ import { RequestOptions } from '../../../internal/request-options';
 
 export class EnvironmentClasses extends APIResource {
   /**
-   * CreateEnvironmentClass creates a new environment class on a runner.
+   * Creates a new environment class for a runner.
+   *
+   * Use this method to:
+   *
+   * - Define compute resources
+   * - Configure environment settings
+   * - Set up runtime options
+   *
+   * ### Examples
+   *
+   * - Create environment class:
+   *
+   *   Creates a new environment configuration.
+   *
+   *   ```yaml
+   *   runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   displayName: "Large Instance"
+   *   description: "8 CPU, 16GB RAM"
+   *   configuration:
+   *     - key: "cpu"
+   *       value: "8"
+   *     - key: "memory"
+   *       value: "16384"
+   *   ```
    */
   create(
     body: EnvironmentClassCreateParams,
@@ -23,7 +46,23 @@ export class EnvironmentClasses extends APIResource {
   }
 
   /**
-   * GetEnvironmentClass returns a single environment class configured for a runner.
+   * Gets details about a specific environment class.
+   *
+   * Use this method to:
+   *
+   * - View class configuration
+   * - Check resource settings
+   * - Verify availability
+   *
+   * ### Examples
+   *
+   * - Get class details:
+   *
+   *   Retrieves information about a specific class.
+   *
+   *   ```yaml
+   *   environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   ```
    */
   retrieve(
     body: EnvironmentClassRetrieveParams,
@@ -36,7 +75,26 @@ export class EnvironmentClasses extends APIResource {
   }
 
   /**
-   * UpdateEnvironmentClass updates an existing environment class on a runner.
+   * Updates an environment class.
+   *
+   * Use this method to:
+   *
+   * - Modify class settings
+   * - Update resource limits
+   * - Change availability
+   *
+   * ### Examples
+   *
+   * - Update class:
+   *
+   *   Changes class configuration.
+   *
+   *   ```yaml
+   *   environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   displayName: "Updated Large Instance"
+   *   description: "16 CPU, 32GB RAM"
+   *   enabled: true
+   *   ```
    */
   update(body: EnvironmentClassUpdateParams, options?: RequestOptions): APIPromise<unknown> {
     return this._client.post('/gitpod.v1.RunnerConfigurationService/UpdateEnvironmentClass', {
@@ -46,8 +104,37 @@ export class EnvironmentClasses extends APIResource {
   }
 
   /**
-   * buf:lint:ignore RPC_REQUEST_RESPONSE_UNIQUE ListEnvironmentClasses returns all
-   * environment classes configured for a runner.
+   * Lists environment classes with optional filtering.
+   *
+   * Use this method to:
+   *
+   * - View available classes
+   * - Filter by capability
+   * - Check enabled status
+   *
+   * ### Examples
+   *
+   * - List all classes:
+   *
+   *   Shows all environment classes.
+   *
+   *   ```yaml
+   *   pagination:
+   *     pageSize: 20
+   *   ```
+   *
+   * - Filter enabled classes:
+   *
+   *   Lists only enabled environment classes.
+   *
+   *   ```yaml
+   *   filter:
+   *     enabled: true
+   *   pagination:
+   *     pageSize: 20
+   *   ```
+   *
+   *   buf:lint:ignore RPC_REQUEST_RESPONSE_UNIQUE
    */
   list(
     params: EnvironmentClassListParams,

src/resources/runners/configurations/host-authentication-tokens.ts

@@ -7,7 +7,29 @@ import { RequestOptions } from '../../../internal/request-options';
 
 export class HostAuthenticationTokens extends APIResource {
   /**
-   * CreateHostAuthenticationToken
+   * Creates a new authentication token for accessing remote hosts.
+   *
+   * Use this method to:
+   *
+   * - Set up SCM authentication
+   * - Configure OAuth credentials
+   * - Manage PAT tokens
+   *
+   * ### Examples
+   *
+   * - Create OAuth token:
+   *
+   *   Creates a new OAuth-based authentication token.
+   *
+   *   ```yaml
+   *   runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   userId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
+   *   host: "github.com"
+   *   token: "gho_xxxxxxxxxxxx"
+   *   source: HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH
+   *   expiresAt: "2024-12-31T23:59:59Z"
+   *   refreshToken: "ghr_xxxxxxxxxxxx"
+   *   ```
    */
   create(
     body: HostAuthenticationTokenCreateParams,
@@ -20,7 +42,23 @@ export class HostAuthenticationTokens extends APIResource {
   }
 
   /**
-   * GetHostAuthenticationToken
+   * Gets details about a specific host authentication token.
+   *
+   * Use this method to:
+   *
+   * - View token information
+   * - Check token expiration
+   * - Verify token validity
+   *
+   * ### Examples
+   *
+   * - Get token details:
+   *
+   *   Retrieves information about a specific token.
+   *
+   *   ```yaml
+   *   id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   ```
    */
   retrieve(
     body: HostAuthenticationTokenRetrieveParams,
@@ -33,7 +71,26 @@ export class HostAuthenticationTokens extends APIResource {
   }
 
   /**
-   * UpdateHostAuthenticationToken
+   * Updates an existing host authentication token.
+   *
+   * Use this method to:
+   *
+   * - Refresh token values
+   * - Update expiration
+   * - Modify token settings
+   *
+   * ### Examples
+   *
+   * - Update token:
+   *
+   *   Updates token value and expiration.
+   *
+   *   ```yaml
+   *   id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   token: "gho_xxxxxxxxxxxx"
+   *   expiresAt: "2024-12-31T23:59:59Z"
+   *   refreshToken: "ghr_xxxxxxxxxxxx"
+   *   ```
    */
   update(body: HostAuthenticationTokenUpdateParams, options?: RequestOptions): APIPromise<unknown> {
     return this._client.post('/gitpod.v1.RunnerConfigurationService/UpdateHostAuthenticationToken', {
@@ -43,7 +100,35 @@ export class HostAuthenticationTokens extends APIResource {
   }
 
   /**
-   * ListHostAuthenticationTokens
+   * Lists host authentication tokens with optional filtering.
+   *
+   * Use this method to:
+   *
+   * - View all tokens
+   * - Filter by runner or user
+   * - Monitor token status
+   *
+   * ### Examples
+   *
+   * - List all tokens:
+   *
+   *   Shows all tokens with pagination.
+   *
+   *   ```yaml
+   *   pagination:
+   *     pageSize: 20
+   *   ```
+   *
+   * - Filter by runner:
+   *
+   *   Lists tokens for a specific runner.
+   *
+   *   ```yaml
+   *   filter:
+   *     runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   pagination:
+   *     pageSize: 20
+   *   ```
    */
   list(
     params: HostAuthenticationTokenListParams,
@@ -58,7 +143,23 @@ export class HostAuthenticationTokens extends APIResource {
   }
 
   /**
-   * DeleteHostAuthenticationToken
+   * Deletes a host authentication token.
+   *
+   * Use this method to:
+   *
+   * - Remove unused tokens
+   * - Revoke access
+   * - Clean up expired tokens
+   *
+   * ### Examples
+   *
+   * - Delete token:
+   *
+   *   Permanently removes a token.
+   *
+   *   ```yaml
+   *   id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   ```
    */
   delete(body: HostAuthenticationTokenDeleteParams, options?: RequestOptions): APIPromise<unknown> {
     return this._client.post('/gitpod.v1.RunnerConfigurationService/DeleteHostAuthenticationToken', {

src/resources/runners/configurations/schema.ts

@@ -6,7 +6,23 @@ import { RequestOptions } from '../../../internal/request-options';
 
 export class Schema extends APIResource {
   /**
-   * GetRunnerConfigurationSchema retrieves the latest Runner configuration schema
+   * Gets the latest runner configuration schema.
+   *
+   * Use this method to:
+   *
+   * - View available settings
+   * - Check configuration options
+   * - Validate configurations
+   *
+   * ### Examples
+   *
+   * - Get schema:
+   *
+   *   Retrieves configuration schema for a runner.
+   *
+   *   ```yaml
+   *   runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   ```
    */
   retrieve(body: SchemaRetrieveParams, options?: RequestOptions): APIPromise<SchemaRetrieveResponse> {
     return this._client.post('/gitpod.v1.RunnerConfigurationService/GetRunnerConfigurationSchema', {

src/resources/runners/configurations/scm-integrations.ts

@@ -7,7 +7,27 @@ import { RequestOptions } from '../../../internal/request-options';
 
 export class ScmIntegrations extends APIResource {
   /**
-   * CreateSCMIntegration creates a new SCM integration on a runner.
+   * Creates a new SCM integration for a runner.
+   *
+   * Use this method to:
+   *
+   * - Configure source control access
+   * - Set up repository integrations
+   * - Enable code synchronization
+   *
+   * ### Examples
+   *
+   * - Create GitHub integration:
+   *
+   *   Sets up GitHub SCM integration.
+   *
+   *   ```yaml
+   *   runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   scmId: "github"
+   *   host: "github.com"
+   *   oauthClientId: "client_id"
+   *   oauthPlaintextClientSecret: "client_secret"
+   *   ```
    */
   create(
     body: ScmIntegrationCreateParams,
@@ -20,7 +40,23 @@ export class ScmIntegrations extends APIResource {
   }
 
   /**
-   * GetSCMIntegration returns a single SCM integration configured for a runner.
+   * Gets details about a specific SCM integration.
+   *
+   * Use this method to:
+   *
+   * - View integration settings
+   * - Check integration status
+   * - Verify configuration
+   *
+   * ### Examples
+   *
+   * - Get integration details:
+   *
+   *   Retrieves information about a specific integration.
+   *
+   *   ```yaml
+   *   id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   ```
    */
   retrieve(
     body: ScmIntegrationRetrieveParams,
@@ -30,7 +66,25 @@ export class ScmIntegrations extends APIResource {
   }
 
   /**
-   * UpdateSCMIntegration updates an existing SCM integration on a runner.
+   * Updates an existing SCM integration.
+   *
+   * Use this method to:
+   *
+   * - Modify integration settings
+   * - Update credentials
+   * - Change configuration
+   *
+   * ### Examples
+   *
+   * - Update integration:
+   *
+   *   Updates OAuth credentials.
+   *
+   *   ```yaml
+   *   id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   oauthClientId: "new_client_id"
+   *   oauthPlaintextClientSecret: "new_client_secret"
+   *   ```
    */
   update(body: ScmIntegrationUpdateParams, options?: RequestOptions): APIPromise<unknown> {
     return this._client.post('/gitpod.v1.RunnerConfigurationService/UpdateSCMIntegration', {
@@ -40,7 +94,26 @@ export class ScmIntegrations extends APIResource {
   }
 
   /**
-   * ListSCMIntegrations returns all SCM integrations configured for a runner.
+   * Lists SCM integrations for a runner.
+   *
+   * Use this method to:
+   *
+   * - View all integrations
+   * - Monitor integration status
+   * - Check available SCMs
+   *
+   * ### Examples
+   *
+   * - List integrations:
+   *
+   *   Shows all SCM integrations.
+   *
+   *   ```yaml
+   *   filter:
+   *     runnerIds: ["d2c94c27-3b76-4a42-b88c-95a85e392c68"]
+   *   pagination:
+   *     pageSize: 20
+   *   ```
    */
   list(
     params: ScmIntegrationListParams,
@@ -55,7 +128,23 @@ export class ScmIntegrations extends APIResource {
   }
 
   /**
-   * DeleteSCMIntegration deletes an existing SCM integration on a runner.
+   * Deletes an SCM integration.
+   *
+   * Use this method to:
+   *
+   * - Remove unused integrations
+   * - Clean up configurations
+   * - Revoke SCM access
+   *
+   * ### Examples
+   *
+   * - Delete integration:
+   *
+   *   Removes an SCM integration.
+   *
+   *   ```yaml
+   *   id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   ```
    */
   delete(body: ScmIntegrationDeleteParams, options?: RequestOptions): APIPromise<unknown> {
     return this._client.post('/gitpod.v1.RunnerConfigurationService/DeleteSCMIntegration', {

src/resources/runners/policies.ts

@@ -7,21 +7,75 @@ import { RequestOptions } from '../../internal/request-options';
 
 export class Policies extends APIResource {
   /**
-   * CreateRunnerPolicy creates a new runner policy.
+   * Creates a new policy for a runner.
+   *
+   * Use this method to:
+   *
+   * - Set up access controls
+   * - Define group permissions
+   * - Configure role-based access
+   *
+   * ### Examples
+   *
+   * - Create admin policy:
+   *
+   *   Grants admin access to a group.
+   *
+   *   ```yaml
+   *   runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
+   *   role: RUNNER_ROLE_ADMIN
+   *   ```
    */
   create(body: PolicyCreateParams, options?: RequestOptions): APIPromise<PolicyCreateResponse> {
     return this._client.post('/gitpod.v1.RunnerService/CreateRunnerPolicy', { body, ...options });
   }
 
   /**
-   * UpdateRunnerPolicy an existing runner policy.
+   * Updates an existing runner policy.
+   *
+   * Use this method to:
+   *
+   * - Modify access levels
+   * - Change group roles
+   * - Update permissions
+   *
+   * ### Examples
+   *
+   * - Update policy role:
+   *
+   *   Changes a group's access level.
+   *
+   *   ```yaml
+   *   runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
+   *   role: RUNNER_ROLE_USER
+   *   ```
    */
   update(body: PolicyUpdateParams, options?: RequestOptions): APIPromise<PolicyUpdateResponse> {
     return this._client.post('/gitpod.v1.RunnerService/UpdateRunnerPolicy', { body, ...options });
   }
 
   /**
-   * ListRunnerPolicies lists runner policies.
+   * Lists policies for a runner.
+   *
+   * Use this method to:
+   *
+   * - View access controls
+   * - Check policy configurations
+   * - Audit permissions
+   *
+   * ### Examples
+   *
+   * - List policies:
+   *
+   *   Shows all policies for a runner.
+   *
+   *   ```yaml
+   *   runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   pagination:
+   *     pageSize: 20
+   *   ```
    */
   list(
     params: PolicyListParams,
@@ -36,7 +90,24 @@ export class Policies extends APIResource {
   }
 
   /**
-   * DeleteRunnerPolicy deletes a runner policy.
+   * Deletes a runner policy.
+   *
+   * Use this method to:
+   *
+   * - Remove access controls
+   * - Revoke permissions
+   * - Clean up policies
+   *
+   * ### Examples
+   *
+   * - Delete policy:
+   *
+   *   Removes a group's access policy.
+   *
+   *   ```yaml
+   *   runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
+   *   ```
    */
   delete(body: PolicyDeleteParams, options?: RequestOptions): APIPromise<unknown> {
     return this._client.post('/gitpod.v1.RunnerService/DeleteRunnerPolicy', { body, ...options });

src/resources/runners/runners.ts

@@ -35,30 +35,135 @@ export class Runners extends APIResource {
   policies: PoliciesAPI.Policies = new PoliciesAPI.Policies(this._client);
 
   /**
-   * CreateRunner creates a new runner with the server. Registrations are very
-   * short-lived and must be renewed every 30 seconds. Runners can be registered for
-   * an entire organisation or a single user.
+   * Creates a new runner registration with the server. Registrations are very
+   * short-lived and must be renewed every 30 seconds.
+   *
+   * Use this method to:
+   *
+   * - Register organization runners
+   * - Set up runner configurations
+   * - Initialize runner credentials
+   * - Configure auto-updates
+   *
+   * ### Examples
+   *
+   * - Create cloud runner:
+   *
+   *   Creates a new runner in AWS EC2.
+   *
+   *   ```yaml
+   *   name: "Production Runner"
+   *   provider: RUNNER_PROVIDER_AWS_EC2
+   *   spec:
+   *     desiredPhase: RUNNER_PHASE_ACTIVE
+   *     configuration:
+   *       region: "us-west"
+   *       releaseChannel: RUNNER_RELEASE_CHANNEL_STABLE
+   *       autoUpdate: true
+   *   ```
+   *
+   * - Create local runner:
+   *
+   *   Creates a new local runner on Linux.
+   *
+   *   ```yaml
+   *   name: "Local Development Runner"
+   *   provider: RUNNER_PROVIDER_LINUX_HOST
+   *   spec:
+   *     desiredPhase: RUNNER_PHASE_ACTIVE
+   *     configuration:
+   *       releaseChannel: RUNNER_RELEASE_CHANNEL_LATEST
+   *       autoUpdate: true
+   *   ```
    */
   create(body: RunnerCreateParams, options?: RequestOptions): APIPromise<RunnerCreateResponse> {
     return this._client.post('/gitpod.v1.RunnerService/CreateRunner', { body, ...options });
   }
 
   /**
-   * GetRunner returns a single runner.
+   * Gets details about a specific runner.
+   *
+   * Use this method to:
+   *
+   * - Check runner status
+   * - View runner configuration
+   * - Monitor runner health
+   * - Verify runner capabilities
+   *
+   * ### Examples
+   *
+   * - Get runner details:
+   *
+   *   Retrieves information about a specific runner.
+   *
+   *   ```yaml
+   *   runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   ```
    */
   retrieve(body: RunnerRetrieveParams, options?: RequestOptions): APIPromise<RunnerRetrieveResponse> {
     return this._client.post('/gitpod.v1.RunnerService/GetRunner', { body, ...options });
   }
 
   /**
-   * UpdateRunner updates an environment runner.
+   * Updates a runner's configuration.
+   *
+   * Use this method to:
+   *
+   * - Modify runner settings
+   * - Update release channels
+   * - Change runner status
+   * - Configure auto-update settings
+   *
+   * ### Examples
+   *
+   * - Update configuration:
+   *
+   *   Changes runner settings.
+   *
+   *   ```yaml
+   *   runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   name: "Updated Runner Name"
+   *   spec:
+   *     configuration:
+   *       releaseChannel: RUNNER_RELEASE_CHANNEL_LATEST
+   *       autoUpdate: true
+   *   ```
    */
   update(body: RunnerUpdateParams, options?: RequestOptions): APIPromise<unknown> {
     return this._client.post('/gitpod.v1.RunnerService/UpdateRunner', { body, ...options });
   }
 
   /**
-   * ListRunners returns all runners registered in the scope.
+   * Lists all registered runners with optional filtering.
+   *
+   * Use this method to:
+   *
+   * - View all available runners
+   * - Filter by runner type
+   * - Monitor runner status
+   * - Check runner availability
+   *
+   * ### Examples
+   *
+   * - List all runners:
+   *
+   *   Shows all runners with pagination.
+   *
+   *   ```yaml
+   *   pagination:
+   *     pageSize: 20
+   *   ```
+   *
+   * - Filter by provider:
+   *
+   *   Lists only AWS EC2 runners.
+   *
+   *   ```yaml
+   *   filter:
+   *     providers: ["RUNNER_PROVIDER_AWS_EC2"]
+   *   pagination:
+   *     pageSize: 20
+   *   ```
    */
   list(params: RunnerListParams, options?: RequestOptions): PagePromise<RunnersRunnersPage, Runner> {
     const { token, pageSize, ...body } = params;
@@ -71,17 +176,46 @@ export class Runners extends APIResource {
   }
 
   /**
-   * DeleteRunner deletes an environment runner.
+   * Deletes a runner permanently.
+   *
+   * Use this method to:
+   *
+   * - Remove unused runners
+   * - Clean up runner registrations
+   * - Delete obsolete runners
+   *
+   * ### Examples
+   *
+   * - Delete runner:
+   *
+   *   Permanently removes a runner.
+   *
+   *   ```yaml
+   *   runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   ```
    */
   delete(body: RunnerDeleteParams, options?: RequestOptions): APIPromise<unknown> {
     return this._client.post('/gitpod.v1.RunnerService/DeleteRunner', { body, ...options });
   }
 
   /**
-   * CheckAuthenticationForHost asks a runner if the user is authenticated against a
-   * particular host, e.g. an SCM system. If not, this function will return a URL
-   * that the user should visit to authenticate, or indicate that Personal Access
-   * Tokens are supported.
+   * Checks if a user is authenticated for a specific host.
+   *
+   * Use this method to:
+   *
+   * - Verify authentication status
+   * - Get authentication URLs
+   * - Check PAT support
+   *
+   * ### Examples
+   *
+   * - Check authentication:
+   *
+   *   Verifies authentication for a host.
+   *
+   *   ```yaml
+   *   host: "github.com"
+   *   ```
    */
   checkAuthenticationForHost(
     body: RunnerCheckAuthenticationForHostParams,
@@ -91,9 +225,25 @@ export class Runners extends APIResource {
   }
 
   /**
-   * CreateRunnerToken returns a token that can be used to authenticate as the
-   * runner. Use this call to renew an outdated token - this does not expire any
-   * previously issued tokens.
+   * Creates a new authentication token for a runner.
+   *
+   * Use this method to:
+   *
+   * - Generate runner credentials
+   * - Renew expired tokens
+   * - Set up runner authentication
+   *
+   * Note: This does not expire previously issued tokens.
+   *
+   * ### Examples
+   *
+   * - Create token:
+   *
+   *   Creates a new token for runner authentication.
+   *
+   *   ```yaml
+   *   runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+   *   ```
    */
   createRunnerToken(
     body: RunnerCreateRunnerTokenParams,
@@ -103,18 +253,30 @@ export class Runners extends APIResource {
   }
 
   /**
-   * ParseContextURL asks a runner to parse a context URL, and return the parsed
-   * result.
+   * Parses a context URL and returns the parsed result.
+   *
+   * Use this method to:
+   *
+   * - Validate context URLs
+   * - Check repository access
+   * - Verify branch existence
+   *
+   * Returns:
+   *
+   * - FAILED_PRECONDITION if authentication is required
+   * - PERMISSION_DENIED if access is not allowed
+   * - INVALID_ARGUMENT if URL is invalid
+   * - NOT_FOUND if repository/branch doesn't exist
+   *
+   * ### Examples
+   *
+   * - Parse URL:
    *
-   * This call returns
+   *   Parses and validates a context URL.
    *
-   * - FAILED_PRECONDITION if the user requires authentication on the runner to
-   *   access the context URL
-   * - PERMISSION_DENIED if the user is not allowed to access the context URL using
-   *   the credentials they have
-   * - INVALID_ARGUMENT if the context URL is invalid
-   * - NOT_FOUND if the repository or branch indicated by the context URL does not
-   *   exist
+   *   ```yaml
+   *   contextUrl: "https://github.com/org/repo/tree/main"
+   *   ```
    */
   parseContextURL(
     body: RunnerParseContextURLParams,

tests/api-resources/projects/projects.test.ts

@@ -23,15 +23,15 @@ describe('resource projects', () => {
   // skipped: tests are disabled for the time being
   test.skip('create: required and optional params', async () => {
     const response = await client.projects.create({
-      environmentClass: { environmentClassId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', localRunner: true },
+      environmentClass: { environmentClassId: 'd2c94c27-3b76-4a42-b88c-95a85e392c68', localRunner: true },
       initializer: {
         specs: [
           {
             contextUrl: { url: 'https://example.com' },
             git: {
               checkoutLocation: 'checkoutLocation',
               cloneTarget: 'cloneTarget',
-              remoteUri: 'remoteUri',
+              remoteUri: 'https://github.com/org/repo',
               targetMode: 'CLONE_TARGET_MODE_UNSPECIFIED',
               upstreamRemoteUri: 'upstreamRemoteUri',
             },
@@ -40,7 +40,7 @@ describe('resource projects', () => {
       },
       automationsFilePath: 'automationsFilePath',
       devcontainerFilePath: 'devcontainerFilePath',
-      name: 'x',
+      name: 'Web Application',
     });
   });