Update docs (#1663)

docs/go/primitives/app-structure.md

@@ -17,7 +17,7 @@ It's simple to integrate Encore applications with pre-existing systems you might
 
 Encore is not opinionated about monoliths vs. microservices. It does however let you build microservices applications with a monolith-style developer experience. For example, you automatically get IDE auto-complete when making [API calls between services](/docs/go/primitives/api-calls), along with cross-service type-safety.
 
-When using Encore Cloud Platform to create an environment on AWS/GCP, Encore enables you to configure if you want to combine multiple services into one process or keep them separate. This can be useful for improved efficiency at smaller scales, and for co-locating services for increased performance. Learn more in the [environments documentation](/docs/platform/deploy/environments#process-allocation).
+When using Encore Cloud to create an environment on AWS/GCP, Encore enables you to configure if you want to combine multiple services into one process or keep them separate. This can be useful for improved efficiency at smaller scales, and for co-locating services for increased performance. Learn more in the [environments documentation](/docs/platform/deploy/environments#process-allocation).
 
 ## Creating services
 

docs/go/primitives/secrets.md

@@ -87,7 +87,7 @@ When you store a secret Encore stores it encrypted using Google Cloud Platform's
 ### Overriding local secrets
 
 When setting secrets via the `encore secret set` command, they are automatically synced to all developers
-working on the same application, courtesy of the Encore Platform.
+working on the same application, courtesy of Encore Cloud.
 
 In some cases, however, you want to override a secret only for your local machine.
 This can be done by creating a file named `.secrets.local.cue` in the root of your Encore application,

docs/go/quick-start.mdx

@@ -184,8 +184,8 @@ $ encore build docker MY-IMAGE:TAG
 This will compile your application using the host machine and then produce a Docker image containing the compiled application.
 You can now deploy this anywhere you like. Learn more in the [self-host docs](/docs/go/self-host/docker-build).
 
-### Deploy using Encore Cloud Platform
-Optionally, you can use [Encore Cloud Platform](https://encore.dev/use-cases/devops-automation) to automatically deploy your application.
+### Deploy using Encore Cloud
+Optionally, you can use [Encore Cloud](https://encore.dev/use-cases/devops-automation) to automatically deploy your application.
 It comes with built-in free development hosting, and for production offers fully automated deployment to your own cloud on AWS or GCP.
 
 🥐 To deploy, simply push your changes to Encore:

docs/go/self-host/self-host.md

@@ -7,7 +7,7 @@ lang: go
 
 Encore supports building Docker images directly from the CLI, which can then be self-hosted on your own infrastructure of choice.
 
-This can be a good choice if Encore's cloud platform isn't a good fit for your use case, or if you want to [migrate away](/docs/go/migration/migrate-away).
+This can be a good choice if Encore Cloud isn't a good fit for your use case, or if you want to [migrate away](/docs/go/migration/migrate-away).
 
 ## Building your own Docker image
 

docs/platform/deploy/deploying.md

@@ -1,58 +1,95 @@
 ---
 seotitle: Deploying your Encore application is as simple as git push
 seodesc: Learn how to deploy your backend application built with Encore with a single command, while Encore manages your entire CI/CD process.
-title: Deploying Applications with Encore
-subtitle: Encore comes with built-in CI/CD and integrates with GitHub
+title: Deploying Applications with Encore Cloud
+subtitle: Encore Cloud automates the deployment and infrastructure provisioning process
 lang: platform
 ---
 
-Encore simplifies the deployment process, making it as straightforward as a `git push`. Encore's built-in integration with Git and GitHub, automated CI/CD pipeline, and automatic provisioning of [Preview Environments](/docs/platform/deploy/preview-environments) and [cloud infrastructure](/docs/platform/infrastructure/infra), is designed to speed up development and remove manual steps.
+Encore Cloud simplifies the deployment and infrastructure provisioning process, making it as straightforward as pushing to a git repository, removing the need for manual steps.
 
-## Setting Up Your Encore Application
+## Deploying your application
 
-1. **Create your Application**: If you haven't already, create an application using the Encore CLI. This automatically creates a new git repository managed by Encore.
+### Step 1: Pre-requisites
+
+Before deploying, ensure that you have created an **Encore application** and an **Encore Cloud account**.
+
+If you haven't created one yet, you can do so by running the following command:
 
 ```shell
 $ encore app create
 ```
 
-2. **Integrate with GitHub (Optional)**: If you prefer to use GitHub, you can [integrate your app with GitHub](/docs/platform/integrations/github). This way, you can push code to GitHub, which triggers Encore's deployment process. This is especially handy for teams as it enables collaborative development, version control, and other GitHub functionality.
+You will be asked to create a free Encore Cloud account first and can then create a new Encore application.
+
+### Step 2: Integrate with GitHub (Optional)
+
+When you create an Encore application while logged into your Encore Cloud account in the CLI, Encore will automatically create a new Encore managed git repository.
+If you are just trying out Encore Cloud, you can use this and skip the rest of this step.
+
+For production applications, we recommend integrating with GitHub instead of the built-in Encore managed git:
+
+**Integrating with GitHub:** Open your app in the **[Encore Cloud dashboard](https://app.encore.cloud/) > (Select your app) > App Settings > Integrations > GitHub**.
+Click the **Connect Account to GitHub** button, which will open GitHub where you can grant access either to all repositories or only the specific one(s) you want to link with Encore Cloud.
+
+For more information and details on how to configure different repository structures, [see the full docs on integrating with GitHub](/docs/platform/integrations/github).
+
+Once you have integrated with GitHub, you can push code to GitHub to trigger Encore Cloud's deployment process. If you use Encore Cloud Pro, you will also get automatic [Preview Environments](/docs/platform/deploy/preview-environments) for each pull request.
+
+### Step 3: Connect your AWS / GCP account (Optional)
 
-## Deploying Your Application
+If you want to deploy to your own cloud on AWS or GCP, you first need to connect your cloud account to Encore Cloud.
 
-With Encore, deploys are triggered simply by pushing changes to the connected Git repository.
+If you are just trying out Encore Cloud, you can skip this step and Encore Cloud will automatically deploy to an environment using Encore Cloud's free development hosting, subject to the [fair use limits](/docs/platform/management/usage).
 
-- If you are using Encore's Git, run the following command to deploy your application:
+**Connect your cloud account:** Open your app in the **[Encore Cloud dashboard](https://app.encore.cloud/) > (Select your app) > App Settings > Integrations > Connect Cloud**.
+
+Learn more in the [connecting your AWS or GCP account docs](/docs/platform/infrastructure/own-cloud).
+
+### Step 4: Deploying Your Application
+
+To deploy your application, simply push your code to the connected Git repository.
+
+- **If you are using Encore Cloud's managed git**: Run the following command to deploy your application:
 
 ```shell
 $ git add -A .
 $ git commit -m 'Commit message'
 $ git push encore
 ```
 
-- If you are using GitHub, a standard `git push` to your repository will work:
+- **If you are using GitHub:** Just a standard `git push` to your repository will work:
 
 ```shell
 $ git add -A .
 $ git commit -m 'Commit message'
 $ git push origin
 ```
 
-In both scenarios, this will trigger Encore's built-in CI/CD pipeline. This includes building your application, running tests, provisioning the necessary infrastructure, and deploying your application.
+In both scenarios, this will trigger Encore Cloud's deployment process, consisting of the following phases:
+* A build & test phase
+* An infrastructure provisioning phase
+* A deployment phase
 
-### Configure deploy trigger
+These phases are combined into a unified entity called a *Rollout*.
+A rollout represents the coordinated process of rolling out a specific version of an Encore application.
+(We use the term *rollout* to disambiguate from the *deployment phase*.)
 
-When using GitHub, you can configure Encore to automatically trigger deploys when you push to a specific branch name.
+Once you've pushed your code, you can monitor the progress in the **[Encore Cloud dashboard](https://app.encore.cloud/) > (Select your app) > Deployments**.
 
-To configure which branch name is used to trigger deploys, open your app in the [Encore Cloud dashboard](https://app.encore.cloud) and go to the **Overview** page for your intended environment. Click on **Settings** and then in the section **Branch Push** configure the `Branch name`  and hit save.
+### Integrating using Encore Cloud's API
+
+You can also trigger a deployment using Encore Cloud's API, learn more in the [API reference](/docs/platform/integrations/api-reference).
 
-### Preview Environments
+## Configuring deploy trigger
 
-When you connect your GitHub account and push changes to a pull request, Encore will automatically create a [Preview Environment](/docs/platform/deploy/preview-environments). This is a fully functional, isolated environment where you can test your application as it would run in production. This environment runs in Encore's free development cloud, giving you an efficient way to validate your changes before they are merged and deployed to the [primary environment](/docs/platform/deploy/environments#primary-environment).
+When using GitHub, you can configure Encore Cloud to automatically trigger deploys when you push to a specific branch name.
+
+To configure which branch name is used to trigger deploys, open your app in the [Encore Cloud dashboard](https://app.encore.cloud) and go to the **Overview** page for your intended environment. Click on **Settings** and then in the section **Branch Push** configure the `Branch name`  and hit save.
 
-## Custom build settings
+## Configuring custom build settings
 
-You can override certain aspects of the CI/CD process in the `encore.app` file:
+If you want, you can override certain aspects of the CI/CD process in the `encore.app` file:
 
 * The Docker base image to use when deploying
 * Whether to build with Cgo enabled

docs/platform/integrations/api-reference.md

@@ -1,24 +1,24 @@
 ---
-seotitle: Encore Platform API Reference
-seodesc: Learn how to use the Encore Platform API.
-title: Platform API Reference
+seotitle: Encore Cloud API Reference
+seodesc: Learn how to use the Encore Cloud API.
+title: Encore Cloud API Reference
 lang: platform
 ---
 
-The Encore Platform provides an API for programmatic access to control certain parts of the platform.
+Encore Cloud provides an API for programmatic access to control certain parts of the platform.
 
 We're working on expanding the set of features available over the API.
 Please reach out to us [on Discord](https://encore.dev/discord) if you have use cases where additional API functionality would be useful.
 
-The Base URL for the Encore Platform API is `https://api.encore.cloud`.
+The Base URL for the Encore Cloud API is `https://api.encore.cloud`.
 
 ## Authentication
 
 All API calls require valid authentication, which is provided by sending an access token in the `Authorization` header,
 in the format `Authorization: Bearer ${ACCESS_TOKEN}`.
 
 You can retrieve an API access token from the OAuth Token endpoint, using an OAuth Client.
-An API access token expires after one hour. For continuous access, shortly before an API access token expires, request a new API access token from the Encore Platform's OAuth token endpoint.
+An API access token expires after one hour. For continuous access, shortly before an API access token expires, request a new API access token from Encore Cloud's OAuth token endpoint.
 
 OAuth client libraries in popular programming languages can handle the API access token generation and renewal.
 
@@ -59,7 +59,7 @@ type Token = {
 
 ## Rollouts
 
-The Encore Platform's deployment system consists of several phases:
+Encore Cloud's deployment system consists of several phases:
 
 * A build phase
 * An infrastructure provisioning phase

docs/platform/integrations/auth-keys.md

@@ -53,4 +53,4 @@ $ encore auth login --auth-key=ena_nEQIkfeM43t7oxpleMsIULbhbtLAbYnnLf1D
 
 ## Revoking a key
 
-You can revoke a key simply by pressing the **Delete** button next to it. This will prevent any machines currently using it to authenticate to the Encore platform (regardless of the key type).
+You can revoke a key simply by pressing the **Delete** button next to it. This will prevent any machines currently using it to authenticate to Encore Cloud (regardless of the key type).

docs/platform/integrations/oauth-clients.md

@@ -1,25 +1,25 @@
 ---
-seotitle: Encore Platform OAuth Clients
-seodesc: Learn how to use OAuth Clients for access to the Encore Platform API
+seotitle: Encore Cloud OAuth Clients
+seodesc: Learn how to use OAuth Clients for access to the Encore Cloud API
 title: OAuth Clients
 lang: platform
 ---
 
-OAuth clients provide a framework for delegated and scoped access to the Encore Platform API. An OAuth client creates short-lived access tokens on demand, and supports the principle of least privilege by allowing fine-grained control on the access granted to the client using scopes.
+OAuth clients provide a framework for delegated and scoped access to the Encore Cloud API. An OAuth client creates short-lived access tokens on demand, and supports the principle of least privilege by allowing fine-grained control on the access granted to the client using scopes.
 
 ## How it works
-You create an OAuth client that defines the scopes to allow when your client application uses the Encore Platform API.
+You create an OAuth client that defines the scopes to allow when your client application uses the Encore Cloud API.
 
 Scopes are currently grouped into "roles", which include a set of permissions.
 For example, the `deployer` role grants access to the triggering deployments.
 
-An OAuth client consists of a client ID and a client secret. When you create an OAuth client, the Encore Platform creates these for you. Within your client application, use the client ID and client secret to request an API access token from the Encore Platform's OAuth token endpoint. You use the access token to make calls to the Encore Platform API. The access token grants permission only for the scopes that were defined when you created the OAuth client.
+An OAuth client consists of a client ID and a client secret. When you create an OAuth client, Encore Cloud creates these for you. Within your client application, use the client ID and client secret to request an API access token from the Encore Cloud's OAuth token endpoint. You use the access token to make calls to the Encore Cloud API. The access token grants permission only for the scopes that were defined when you created the OAuth client.
 
-An API access token expires after one hour. For continuous access, shortly before an API access token expires, request a new API access token from the Encore Platform's OAuth token endpoint.
+An API access token expires after one hour. For continuous access, shortly before an API access token expires, request a new API access token from Encore Cloud's OAuth token endpoint.
 
 OAuth client libraries in popular programming languages can handle the API access token generation and renewal.
 
-The Encore Platform's OAuth implementation is based on the [OAuth 2.0 protocol](https://www.rfc-editor.org/rfc/rfc6749).
+Encore Cloud's OAuth implementation is based on the [OAuth 2.0 protocol](https://www.rfc-editor.org/rfc/rfc6749).
 
 ## Prerequisites
 You need to be an Owner of the Encore application in order to create or revoke OAuth clients.
@@ -44,7 +44,7 @@ Roles define which operations are permitted in API access tokens that are create
 Currently there is a single supported role: **Deployer**. The deployer role
 allows for programatically triggering deployments.
 
-When new Encore Platform functionality is provided, we will add it to existing roles where applicable.
+When new Encore Cloud functionality is provided, we will add it to existing roles where applicable.
 That means a role is not restricted to only access of APIs that existed at the time the client was initially authorized — a role will contain additional access where it makes sense for new or updated functionality.
 
 ### Revoking an OAuth client
@@ -58,14 +58,14 @@ When you revoke an OAuth client, any active API access tokens that were created
 
 ### Encore Cloud OAuth token endpoint
 Encore Cloud's OAuth token endpoint is https://api.encore.cloud/api/oauth/token.
-See the [Platform API Reference](/docs/platform/integrations/api-reference) documentation for more information.
+See the [Encore Cloud API Reference](/docs/platform/integrations/api-reference) documentation for more information.
 
 Make requests to the OAuth token endpoint when you need an API access token. The OAuth token endpoint accepts requests that conform to the OAuth 2.0 client credentials grant request format, and returns responses that conform to the OAuth 2.0 client credentials grant response format.
 
 ## OAuth client libraries
 Popular programming languages provide OAuth client libraries to simplify your use of OAuth clients.
 
-For example, the following Go code shows how to create an OAuth client object that uses your client ID and client secret to generate an API access token for calls to the Encore Platform API.
+For example, the following Go code shows how to create an OAuth client object that uses your client ID and client secret to generate an API access token for calls to the Encore Cloud API.
 Similar libraries exist for other popular programming languages.
 
 ```go
@@ -96,7 +96,7 @@ func main() {
 The example requires that you define environment variables `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET`, with their values set to the client ID and client secret that are created when you set up an OAuth client.
 
 ### Verifying you can generate API access tokens
-After you set up an OAuth client, an easy way to confirm that you can generate API access tokens is to make a curl request to the Encore Platform OAuth token endpoint.
+After you set up an OAuth client, an easy way to confirm that you can generate API access tokens is to make a curl request to the Encore Cloud OAuth token endpoint.
 
 
 ```bash

docs/platform/integrations/webhooks.md

@@ -1,6 +1,6 @@
 ---
-seotitle: Subscribe to Encore webhooks and events
-seodesc: The Encore platform lets you define webhooks to react to events in your application, enabling you to build powerful integrations.
+seotitle: Subscribe to Encore Cloud webhooks and events
+seodesc: Encore Cloud lets you define webhooks to react to events in your application, enabling you to build powerful integrations.
 title: Webhooks & Events
 subtitle: Set up webhooks to react to Encore events
 infobox: {

docs/platform/introduction.md

@@ -1,7 +1,7 @@
 ---
-seotitle: Introduction to Encore Cloud Platform
+seotitle: Introduction to Encore Cloud
 seodesc: Learn how Encore works and how it helps backend developers build cloud-based backend applications without manually dealing with infrastructure.
-title: Encore Cloud Platform
+title: Encore Cloud
 subtitle: End-to-end development platform for building robust distributed systems
 lang: platform
 ---