From 9d2df3ac85c7163dcfcf1e8cc2d566f95b9db119 Mon Sep 17 00:00:00 2001
From: Marcus Kohlberg <78424526+marcuskohlberg@users.noreply.github.com>
Date: Fri, 20 Dec 2024 15:33:46 +0100
Subject: [PATCH] update docs (#1664)

---
 README.md                                     |   2 +-
 docs/go/develop/metadata.md                   |   2 +-
 docs/go/primitives/cron-jobs.md               |   2 +-
 docs/go/quick-start.mdx                       |   2 +-
 docs/menu.cue                                 |  10 +-
 docs/platform/deploy/deploying.md             |  54 +++++-----
 docs/platform/deploy/environments.md          | 100 ++++++++----------
 .../{infrastructure => deploy}/own-cloud.md   |   0
 docs/platform/deploy/preview-environments.md  |  35 +++---
 docs/platform/deploy/security.md              |  24 +++--
 .../import-kubernetes-cluster.md              |   4 +-
 docs/platform/infrastructure/infra.md         |  32 +++---
 docs/platform/infrastructure/kubernetes.md    |  11 +-
 docs/platform/introduction.md                 |  86 ++++++++-------
 docs/platform/management/billing.md           |   2 +-
 docs/platform/migration/migrate-to-encore.md  |   2 +-
 docs/platform/migration/try-encore.md         |   6 +-
 docs/ts/develop/metadata.md                   |   2 +-
 docs/ts/primitives/cron-jobs.md               |   2 +-
 docs/ts/quick-start.mdx                       |   2 +-
 20 files changed, 200 insertions(+), 180 deletions(-)
 rename docs/platform/{infrastructure => deploy}/own-cloud.md (100%)

diff --git a/README.md b/README.md
index 73aa38b131..ae67eb5aba 100644
--- a/README.md
+++ b/README.md
@@ -185,7 +185,7 @@ Encore comes with several built-in tools to help with testing:
 
 Encore Cloud is Encore's managed service offering for teams wanting to focus their engineering effort on their product development, avoiding investing time in platformization and DevOps.
 
-Encore Cloud provides **automatic infrastructure provisioning in your cloud on AWS & GCP**. So instead of writing Terraform, YAML, or clicking in cloud consoles, you [connect your cloud account](https://encore.dev/docs/platform/infrastructure/own-cloud) and simply deploy your application. Since using Encore's open source backend frameworks means your application code is cloud agnostic and not tied to any specific infrastructure services, Encore Cloud enables you to change your infrastructure depending on your evolving needs, without needing to make code changes or manually update infrastructure config files.
+Encore Cloud provides **automatic infrastructure provisioning in your cloud on AWS & GCP**. So instead of writing Terraform, YAML, or clicking in cloud consoles, you [connect your cloud account](https://encore.dev/docs/platform/deploy/own-cloud) and simply deploy your application. Since using Encore's open source backend frameworks means your application code is cloud agnostic and not tied to any specific infrastructure services, Encore Cloud enables you to change your infrastructure depending on your evolving needs, without needing to make code changes or manually update infrastructure config files.
 
 When you deploy, Encore Cloud automatically provisions [infrastructure](https://encore.dev/docs/platform/infrastructure/infra) using battle-tested cloud services on AWS and GCP, such as:
 - **Compute:** GCP Cloud Run, AWS Fargate, Kubernetes (GKE and EKS)
diff --git a/docs/go/develop/metadata.md b/docs/go/develop/metadata.md
index 7df919cc09..7dc1dae42a 100644
--- a/docs/go/develop/metadata.md
+++ b/docs/go/develop/metadata.md
@@ -51,7 +51,7 @@ however by calling `encore.CurrentRequest().PathParams()` you can get access to
 
 ### Using Cloud Specific Services
 
-All the [clouds](/docs/platform/infrastructure/own-cloud) contain a large number of services, not all of which Encore natively supports.
+All the [clouds](/docs/platform/deploy/own-cloud) contain a large number of services, not all of which Encore natively supports.
 By using information about the [environment](/docs/platform/deploy/environments), you can define the implementation of these and
 use different services for each environment's provider. For instance if you are pushing audit logs into a data warehouse, when running on GCP you could use BigQuery, but when running on AWS you could use Redshift, when running locally you could
 simply write them to a file.
diff --git a/docs/go/primitives/cron-jobs.md b/docs/go/primitives/cron-jobs.md
index 4c4112efa6..02a64f12f1 100644
--- a/docs/go/primitives/cron-jobs.md
+++ b/docs/go/primitives/cron-jobs.md
@@ -67,7 +67,7 @@ Cron Job executions across all your environments via the `Cron Jobs` menu item:
 ## Keep in mind when using Cron Jobs
 
 - Cron Jobs do not execute during local development or in [Preview Environments](/docs/platform/deploy/preview-environments). However, you can manually invoke the API to test its behavior.
-- In Encore Cloud, Cron Job executions are limited to **once every hour**, with the exact minute randomized within that hour for users on the Free Tier. To enable more frequent executions or to specify the exact minute within the hour, consider [deploying to your own cloud](/docs/platform/infrastructure/own-cloud) or upgrading to the [Pro plan](/pricing).
+- In Encore Cloud, Cron Job executions are limited to **once every hour**, with the exact minute randomized within that hour for users on the Free Tier. To enable more frequent executions or to specify the exact minute within the hour, consider [deploying to your own cloud](/docs/platform/deploy/own-cloud) or upgrading to the [Pro plan](/pricing).
 - Both public and private APIs are supported for Cron Jobs.
 - Ensure that the API endpoints used in Cron Jobs are idempotent, as they may be called multiple times under certain network conditions.
 - The API endpoints used in Cron Jobs must not take any request parameters. That is, their signatures must be `func(context.Context) error` or `func(context.Context) (*T, error)`.
diff --git a/docs/go/quick-start.mdx b/docs/go/quick-start.mdx
index 8a8dabf46b..a2acec8223 100644
--- a/docs/go/quick-start.mdx
+++ b/docs/go/quick-start.mdx
@@ -203,7 +203,7 @@ It will look something like: `https://app.encore.cloud/$APP_ID/deploys/...`
 
 🥐 Open the URL to access the Encore Cloud dashboard and check the progress of your deployment.
 
-You can now use the Cloud Dashboard to view production [traces](/docs/go/observability/tracing), [connect your cloud account](/docs/platform/infrastructure/own-cloud), [integrate with GitHub](/docs/platform/integrations/github), and much more.
+You can now use the Cloud Dashboard to view production [traces](/docs/go/observability/tracing), [connect your cloud account](/docs/platform/deploy/own-cloud), [integrate with GitHub](/docs/platform/integrations/github), and much more.
 
 <video autoPlay playsInline loop controls muted className="w-full h-full">
   <source src="/assets/docs/webdashvideo.mp4" className="w-full h-full" type="video/mp4"/>
diff --git a/docs/menu.cue b/docs/menu.cue
index a2715a5a25..45bad9a6d3 100644
--- a/docs/menu.cue
+++ b/docs/menu.cue
@@ -996,6 +996,11 @@
 				text: "Deploying & CI/CD"
 				path: "/platform/deploy/deploying"
 				file: "platform/deploy/deploying"
+			}, {
+				kind: "basic"
+				text: "Connect your cloud account"
+				path: "/platform/deploy/own-cloud"
+				file: "platform/deploy/own-cloud"
 			}, {
 				kind: "basic"
 				text: "Environments"
@@ -1017,11 +1022,6 @@
 			kind: "section"
 			text: "Infrastructure"
 			items: [{
-				kind: "basic"
-				text: "Connect your cloud account"
-				path: "/platform/infrastructure/own-cloud"
-				file: "platform/infrastructure/own-cloud"
-			}, {
 				kind: "basic"
 				text: "Infrastructure overview"
 				path: "/platform/infrastructure/infra"
diff --git a/docs/platform/deploy/deploying.md b/docs/platform/deploy/deploying.md
index 46752e37b8..e569353842 100644
--- a/docs/platform/deploy/deploying.md
+++ b/docs/platform/deploy/deploying.md
@@ -6,51 +6,55 @@ subtitle: Encore Cloud automates the deployment and infrastructure provisioning
 lang: platform
 ---
 
-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.
+Encore Cloud simplifies deploying your application, making it as simple as pushing to a git repository, removing the need for manual steps.
 
 ## Deploying your application
 
 ### Step 1: Pre-requisites
 
-Before deploying, ensure that you have created an **Encore application** and an **Encore Cloud account**.
+Before deploying, ensure that you have an **Encore Cloud account** and have created an **Encore application**.
 
-If you haven't created one yet, you can do so by running the following command:
+You can create both an account and an application by running the following command:
 
 ```shell
 $ encore app create
 ```
 
-You will be asked to create a free Encore Cloud account first and can then create a new Encore application.
+You will be asked to create a free Encore Cloud account first, and you will then proceed to 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.
+When creating an Encore application, 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:
+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.
+#### **Connecting your GitHub account**
 
-For more information and details on how to configure different repository structures, [see the full docs on integrating with GitHub](/docs/platform/integrations/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 the relevant repositorie(s).
 
-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.
+[See the full docs](/docs/platform/integrations/github) on integrating with GitHub to learn how to configure different repository structures.
+
+Once connected to GitHub, pushing code will trigger deployments automatically. Encore Cloud Pro users get [Preview Environments](/docs/platform/deploy/preview-environments) for each pull request.
 
 ### Step 3: Connect your AWS / GCP account (Optional)
 
-If you want to deploy to your own cloud on AWS or GCP, you first need to connect your cloud account to Encore Cloud.
+Deploy to your own cloud on AWS or GCP by connection your cloud account to Encore Cloud.
+
+If you're just trying out Encore Cloud, skip this step to deploy to a free development environment using Encore Cloud's hosting, subject to [fair use limits](/docs/platform/management/usage).
 
-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).
+#### **Connecting your cloud account**
 
-**Connect your cloud account:** Open your app in the **[Encore Cloud dashboard](https://app.encore.cloud/) > (Select your app) > App Settings > Integrations > Connect Cloud**.
+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).
+Learn more in the [connecting your cloud docs](/docs/platform/deploy/own-cloud).
 
-### Step 4: Deploying Your Application
+### Step 4: Push to deploy
 
-To deploy your application, simply push your code to the connected Git repository.
+Deploy your application by pushing your code to the connected Git repository.
 
-- **If you are using Encore Cloud's managed git**: Run the following command to deploy your application:
+- **Using Encore Cloud's managed git**:
 
 ```shell
 $ git add -A .
@@ -58,7 +62,7 @@ $ git commit -m 'Commit message'
 $ git push encore
 ```
 
-- **If you are using GitHub:** Just a standard `git push` to your repository will work:
+- **If you have connected your GitHub account:**
 
 ```shell
 $ git add -A .
@@ -66,27 +70,23 @@ $ git commit -m 'Commit message'
 $ git push origin
 ```
 
-In both scenarios, this will trigger Encore Cloud's deployment process, consisting of the following phases:
+This will trigger Encore Cloud's deployment process, consisting of the following phases:
 * A build & test phase
 * An infrastructure provisioning phase
 * A deployment phase
 
-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*.)
-
 Once you've pushed your code, you can monitor the progress in the **[Encore Cloud dashboard](https://app.encore.cloud/) > (Select your app) > Deployments**.
 
-### 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).
-
 ## Configuring deploy trigger
 
 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.
 
+### Integrating using Encore Cloud's API
+
+You can trigger deployments using Encore Cloud's API, learn more in the [API reference](/docs/platform/integrations/api-reference).
+
 ## Configuring custom build settings
 
 If you want, you can override certain aspects of the CI/CD process in the `encore.app` file:
diff --git a/docs/platform/deploy/environments.md b/docs/platform/deploy/environments.md
index cb72e0414a..4d43ba33a6 100644
--- a/docs/platform/deploy/environments.md
+++ b/docs/platform/deploy/environments.md
@@ -1,32 +1,16 @@
 ---
 seotitle: Environments – Creating local, preview, and prod environments
 seodesc: Learn how to create all the environments you need for your backend application, local, preview, testing and production. Here's how you keep them in sync!
-title: Environments
-subtitle: The environments you want, with none of the work
+title: Creating & configuring environments
+subtitle: Get the environments you need, without the work
 lang: platform
 ---
 
-Encore makes it simple to create the environments you need to build your application with confidence: local, preview, testing, and production.
-Each environment is an isolated fully working instance of your backend, automatically provisioned by Encore.
-
-Environments always stay in sync, as they are created based on the needs of your application, using the [Encore Application Model](/docs/ts/concepts/application-model). Environments are provisioned using contextually appropriate [infrastructure](/docs/platform/infrastructure/infra) depending on the type of environment.
-
-## Creating environments
-
-To create an environment for your app, open your app in the [Encore Cloud dashboard](https://app.ewcloudev) and go to the **Environments** page,
-then click on `Create env` in the top right.
-
-There you can pick a name, and decide if you want a **production**
-or **development environment** (see [Environment Types](#environment-types) below).
-
-You can also choose how you would like to **trigger deploys** for the environment (either by pushing
-to a Git branch or manually), and if you want to **manually approve infrastructure changes**.
-
-Finally, select which **cloud provider** you want to deploy to (see the [Cloud Providers](/docs/platform/infrastructure/own-cloud) documentation to learn more) and decide which type of **process allocation** you want: should all services be deployed to one process or separately?
-
-Click `Create` and you're done!
-
-![Creating an environment](/assets/docs/createenv.png "Creating an environment")
+Encore automatically sets up and manages different environments for your application (local, preview, testing, and production). Each environment is:
+- Fully isolated
+- Automatically provisioned
+- Always in sync with your codebase
+- Configured with appropriate infrastructure for its purpose
 
 ## Environment Types
 
@@ -37,53 +21,57 @@ Encore has four types of environments:
 - `local`
 
 Some environment types differ in how infrastructure is provisioned:
-- `preview` environments are provisioned in Encore Cloud and are optimized to be cost-efficient and fast to provision.
-- `local` is provisioned by Encore's CLI using local versions of infrastructure.
-
-Aside from determining infrastructure, environment type is also used for [Secrets management](/docs/ts/primitives/secrets).
-
-### Local environment
+- `local` is provisioned by Encore's Open Source CLI using local versions of infrastructure.
+- `preview` environments are provisioned in Encore Cloud hosting and are optimized to be cost-efficient and fast to provision.
+- `production` and `development` environments are provisioned by Encore Cloud, either in your [cloud account](/docs/platform/deploy/own-cloud) or using Encore Cloud's free development hosting. Both environment types offer the same infrastructure options when deployed using your own cloud account.
+  
+Environment type is also used for [Secrets management](/docs/ts/primitives/secrets), allowing you to configure different secrets for different environment types. Therefore, you can easily configure different secrets for your `production` and `development` environments.
 
-When you've installed the [Encore CLI](/docs/ts/install), you start your local environment by simply running `encore run`.
-This builds and tests your application, and provisions all the necessary infrastructure to run your application locally (see the [infra docs](/docs/platform/infrastructure/infra#local-development) to learn exactly how local infrastructure is provisioned).
-
-By default, the local environment runs on `http://localhost:4000`.
+## Creating environments
 
-### Preview environments
+1. Open your app in the [Encore Cloud dashboard](https://app.encore.cloud)
+2. Go to **Environments** > **Create env**
+3. Configure your environment:
+   - Name your environment
+   - Choose type: **Production** or **Development** (see [Environment Types](#environment-types) below)
+   - Set deploy trigger: Git branch or manual
+   - Configure infrastructure approval: automatic or manual
+   - Select cloud provider
+   - Choose process allocation: single or separate processes
 
-When you [connect your application to GitHub](/docs/platform/integrations/github), Encore will automatically provision ephemeral Preview Environments for each Pull Request. See the [Preview Environments documentation](/docs/platform/deploy/preview-environments) to learn more.
+![Creating an environment](/assets/docs/createenv.png "Creating an environment")
 
-#### Frontend Collaboration
+### Configuring deploy trigger
 
-Preview Environments make it really easy to collaborate and test changes with your frontend.
-Just update your frontend API client to point to the `pr:#` environment.
-This is a one-line change since your API client always specifies the environment name, e.g. `https://<env>-<my-app>.encr.app/`.
+When using GitHub, you can configure Encore Cloud to automatically trigger deploys when you push to a specific branch name.
 
-If your pull request makes changes to the API, you can [generate a new API client](/docs/ts/cli/client-generation)
-for the new backend API using `encore gen client --env=pr:72 --lang=typescript my-app`
+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.
 
-### Cloud environments
+### Configuring infrastructure approval
 
-Encore makes it simple to create multiple cloud environments in different cloud providers by [connecting your cloud account(s)](/docs/platform/infrastructure/own-cloud). Cloud environments can be created as `Development`, or `Production`, depending on your use case (see the [infra docs](/docs/platform/infrastructure/infra#production-infrastructure) to learn exactly what infrastructure is provisioned in each cloud).
+For environments you may want to enforce infrastructure approval before deploying. You can configure this in the **Settings** > **Infrastructure Approval** section for your environment.
 
-#### Process Allocation
+When infrastructure approval is enabled, an application **Admin** will need to manually approve the infrastructure changes before the deployment can proceed.
 
-Just because you want to deploy each service separately in some environments, doesn't mean you want to do it in all environments.
+### Configuring process allocation
 
-Handily, Encore lets you decide how you want to deploy your services for cloud environments. You don't need to change a single line of code.
+Encore Cloud offers flexible process allocation options:
+- **Single process**: All services run in one process (simpler, lower cost)
+- **Separate processes**: Each service runs independently (better isolation, independent scaling)
 
-When you create an environment, you decide which process allocation you want for that environment.
+Choose your preferred deployment model when creating each environment. You can use different models for production and development environments without changing any code.
 
 <img src="/assets/docs/microservices-process-allocation.png" title="Microservices - Process Allocation" />
 
-<Callout type="info">
-
-Deploying services as separate processes is not yet supported when using AWS Fargate. For multi-process deployments, select AWS EKS or GCP CloudRun / GKE.
-
-</Callout>
-
-## Primary environment
+## Setting a Primary environment
 
-Encore application's have a **primary environment** that is used as the default environment for functionality like viewing API documentation or app insights in the [Encore Cloud dashboard](https://app.encore.cloud), and as the default for CLI functionality like API client generation. It should generally reflect what you consider to be the main 'production' environment.
+Every Encore app has a configurable Primary environment that serves as the default for:
+- App insights in the Encore Cloud dashboard
+- API documentation
+- CLI functionality (like API client generation)
 
-To configure which environment should be used as the primary environment, open your app in the [Encore Cloud dashboard](https://app.encore.cloud), go to **Settings** > **General** > **Primary Environment**, then select the environment you want from the dropdown and click **Update**.
+**Configuring your Primary environment:**
+1. Open your app in the [Encore Cloud dashboard](https://app.encore.cloud)
+2. Navigate to **Settings** > **General** > **Primary Environment**
+3. Select your desired environment from the dropdown
+4. Click **Update**
diff --git a/docs/platform/infrastructure/own-cloud.md b/docs/platform/deploy/own-cloud.md
similarity index 100%
rename from docs/platform/infrastructure/own-cloud.md
rename to docs/platform/deploy/own-cloud.md
diff --git a/docs/platform/deploy/preview-environments.md b/docs/platform/deploy/preview-environments.md
index f1b4e7b44f..c21f6ead97 100644
--- a/docs/platform/deploy/preview-environments.md
+++ b/docs/platform/deploy/preview-environments.md
@@ -6,35 +6,42 @@ subtitle: Accelerate development with isolated test environments for each Pull R
 lang: platform
 ---
 
-When you [connect your application to GitHub](/docs/platform/integrations/github), Encore will begin to automatically provision ephemeral Preview Environments for each Pull Request. Preview Environments are fully functional, isolated, environments where you can test your application as it would run in production.
+When using [Encore Cloud Pro](https://encore.cloud/pricing), you automatically get ephemeral Preview Environments for each Pull Request.
 
-Preview Environments are named after the pull request, for example PR #72 creates a Preview Environment named `pr:72` with the API base url `https://pr72-$APP_ID.encr.app`.
+Preview Environments are free, fully-managed development environments that run on Encore Cloud. They let you test changes without managing infrastructure or incurring cost.
 
-You can also view the environment in the Encore Cloud dashboard, where the url will be `https://app.encore.cloud/$APP_ID/envs/pr:72`.
+See the [infra docs](/docs/platform/infrastructure/infra#preview-environments) if you're curious about exactly how Preview Environments are provisioned.
 
-## Preview Infrastructure
+## Using Preview Environments
 
-Preview Environments run in Encore's free development cloud, removing the need to manually manage and pay for your own sandbox environments. This gives you a cost-efficient way to validate your changes before they are merged and deployed to the [primary environment](/docs/platform/deploy/environments#primary-environment).
+To use Preview Environments, you first need to [connect your application to GitHub](/docs/platform/integrations/github).
 
-See the [infra docs](/docs/platform/infrastructure/infra#preview-environments) if you're curious about exactly how Preview Environments are provisioned.
+Preview Environments are named after the pull request, for example PR #72 creates a Preview Environment named `pr:72` with the API base url `https://pr72-$APP_ID.encr.app`.
+
+You can also view the environment in the Encore Cloud dashboard, where the url will be `https://app.encore.cloud/$APP_ID/envs/pr:72`.
 
 ![Preview environment linked in GitHub](/assets/docs/ghpreviewenv.png "Preview environment linked in GitHub")
 
-## Populate databases with data automatically
+## Populate databases with test data automatically
 
-Encore Cloud, and Encore managed environments on AWS and GCP, can be provisioned using [Neon](/docs/platform/infrastructure/neon) as the database provider.
+Preview Environments can automatically come with pre-populated test data thanks to Neon's database branching feature. Here's how it works:
 
-Neon is a serverless postgres provider that supports [database branches](https://neon.tech/docs/introduction/branching), which are similar to branches in git.
-Branches enable you to automatically seed your Preview Environments with test data by branching off a populated database, e.g. the database in a staging environment.
+1. Your main database (typically in staging) contains your test data
+2. When a Preview Environment is created, it gets a fresh database that's an exact copy of your main database
+3. This happens automatically - no manual data copying needed!
 
-To configure which branch to use for PR environments, head to the [Encore Cloud dashboard](https://app.encore.cloud) > (Select your app) > App Settings > Preview Environments
-and select the environment with the database you want to branch from. Hit save and you're all done.
+#### Setup instructions
+1. Go to [Encore Cloud dashboard](https://app.encore.cloud)
+2. Select your app > App Settings > Preview Environments
+3. Choose which environment's database to copy from (e.g., staging)
+4. Save your changes
 
-Keep in mind that you can only branch from environments that use Neon as the database provider; this is the default for Encore Cloud environments, but is a configurable option when creating AWS and GCP environments.
+**Note:** This feature requires using Neon as your database provider, which is:
+- Default for Encore Cloud environments
+- Optional for AWS and GCP environments
 
 <img src="/assets/docs/pr-neon.png" title="Use Neon for PR environments" className="mx-auto"/>
 
-
 ## Frontend Collaboration
 
 Preview Environments make it really easy to collaborate and test changes with your frontend. Just update your frontend API client to point to the `pr:#` environment.
diff --git a/docs/platform/deploy/security.md b/docs/platform/deploy/security.md
index af8c0ccd01..3541a863bf 100644
--- a/docs/platform/deploy/security.md
+++ b/docs/platform/deploy/security.md
@@ -2,18 +2,28 @@
 seotitle: Security – How Encore keeps your backend application secure
 seodesc: Encore applications come with built-in security best practises. See how Encore keeps your application secure by default.
 title: Application Security
-subtitle: Encore makes strong security the default path
+subtitle: Encore Cloud makes strong security the default path
 lang: platform
 ---
 
-The security practices implemented by Encore are informed by our team's decades-long experience working with banking, payments, and other sensitive systems, at companies like Google, Spotify, and Monzo.
+## Built on industry experience
 
-We have designed Encore to make building secure applications an effortless task, rather than an inconvenience, allowing you to focus on functionality instead of laborious security concerns.
+The security practices in Encore Cloud are built on our team's decades of experience designing and operating sensitive systems at companies like Google, Spotify, and Monzo.
 
-For example, Encore's [secrets management](/docs/ts/primitives/secrets) gives you a simple way of using secret keys, while at the same time providing state of the art security behind the scenes.
+## Security by Default
 
-Furthermore, thanks to the Backend Framework, Encore understands which services require access to specific resources. **Encore automatically manages IAM policies** based on the _principle of least privilege_ by default. This ensures each service only has the minimum necessary permissions.
+Encore Cloud is designed to make security effortless rather than burdensome:
 
-When your application is running, all communication to Encore uses mutual TLSv1.3 connections, and all database access is encrypted with certificate validation and strong security credentials.
+- **Zero-config security**: Focus on building features while Encore Cloud automatically implements security best practices
+- **Built-in secrets management**: Safely handle sensitive data using the built-in [secrets management system](/docs/ts/primitives/secrets)
+- **Automated IAM management**: Encore Cloud automatically manages IAM policies based on the principle of least privilege
 
-For cloud environments, Encore automatically provisions infrastructure using security best practices for each of the supported cloud providers (GCP, AWS). Learn more in the [infrastructure documentation](/docs/platform/infrastructure/infra).
+## Security features
+
+When Encore Cloud deploys your application and infrastructure, it takes care of implementing security best practices:
+
+- **Strong encryption**: All communication uses mutual TLSv1.3
+- **Secure databases**: Database access is encrypted with certificate validation and strong security credentials
+- **Cloud security**: Automatic provisioning with security best practices specific to each cloud provider
+  - Learn more about [Google Cloud Platform (GCP)](/docs/platform/infrastructure/gcp)
+  - Learn more about [Amazon Web Services (AWS)](/docs/platform/infrastructure/aws)
diff --git a/docs/platform/infrastructure/import-kubernetes-cluster.md b/docs/platform/infrastructure/import-kubernetes-cluster.md
index c5e431c1d6..93b01ccd5c 100644
--- a/docs/platform/infrastructure/import-kubernetes-cluster.md
+++ b/docs/platform/infrastructure/import-kubernetes-cluster.md
@@ -8,9 +8,9 @@ lang: platform
 
 When you deploy your application to your own cloud, Encore Cloud can provision infrastructure for it in many different ways – including setting up a Kubernetes cluster.
 
-However, if you already have a Kubernetes cluster, you may want to deploy your Encore application into this pre-existing cluster. This is often useful if you want to integrate your Encore application with other parts of your system that are not built using Encore.
+If you already have a Kubernetes cluster, Encore Cloud can deploy your Encore application into this pre-existing cluster. This is often useful if you want to integrate your Encore application with other parts of your system that are not built using Encore.
 
-To support this use case, Encore Cloud enables you to import existing Kubernetes clusters on Google Cloud Platform (AWS coming soon).
+Kubernetes imports are supported on GCP, AWS support is coming soon.
 
 ## Importing a cluster
 
diff --git a/docs/platform/infrastructure/infra.md b/docs/platform/infrastructure/infra.md
index 6d98394c08..9ec3fc37ec 100644
--- a/docs/platform/infrastructure/infra.md
+++ b/docs/platform/infrastructure/infra.md
@@ -6,7 +6,7 @@ subtitle: How Encore Cloud provisions infrastructure for your application
 lang: platform
 ---
 
-Encore Cloud automatically provisions all necessary infrastructure, in all environments and across all major cloud providers, without requiring application code changes. You simply [connect your cloud account](/docs/platform/infrastructure/own-cloud) and create an environment.
+Encore Cloud automatically provisions all necessary infrastructure, in all environments and across all major cloud providers, without requiring application code changes. You simply [connect your cloud account](/docs/platform/deploy/own-cloud) and create an environment.
 
 <img src="/assets/docs/encore_overview.png" title="Infrastructure Overview" className="noshadow"/>
 
@@ -24,7 +24,7 @@ Having an end-to-end integration between application code and infrastructure als
 
 By default, Encore Cloud provisions infrastructure using contextually appropriate objectives for each environment type. You retain control over the infrastructure in your cloud account, and can configure it directly both via the Encore Cloud dashboard and your cloud provider's console. Encore Cloud takes care of syncing your changes.
 
-|                        | Local              | Encore Cloud Hosting              | GCP / AWS                          |
+|                        | Local              | Encore Cloud Hosting       | GCP / AWS                          |
 | ---------------------- | ------------------ | -------------------------- | ---------------------------------- |
 | **Environment types:** | Development        | Preview, Development       | Development, Production            |
 | **Objectives:**        | Provisioning speed | Provisioning speed, Cost\* | Reliability, Security, Scalability |
@@ -35,11 +35,11 @@ By default, Encore Cloud provisions infrastructure using contextually appropriat
 
 Encore Cloud provisions infrastructure resources differently for each type of development environment.
 
-|                     | Local                             | Preview / Development (Encore Cloud Hosting)                   | GCP / AWS                                                      |
-| ------------------- | --------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------- |
+|                     | Local                             | Preview / Development (Encore Cloud Hosting)                 | GCP / AWS                                                      |
+| ------------------- | --------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------- |
 | **SQL Databases:**  | Docker                            | Encore Cloud Managed (Kubernetes), [Neon](/docs/deploy/neon) | [See production](/docs/deploy/infra#production-infrastructure) |
-| **Pub/Sub:**        | In-memory ([NSQ](https://nsq.io)) | GCP Pub/Sub                                            | [See production](/docs/deploy/infra#production-infrastructure) |
-| **Caches:**         | In-memory (Redis)                 | In-memory (Redis)                                      | [See production](/docs/deploy/infra#production-infrastructure) |
+| **Pub/Sub:**        | In-memory ([NSQ](https://nsq.io)) | GCP Pub/Sub                                                  | [See production](/docs/deploy/infra#production-infrastructure) |
+| **Caches:**         | In-memory (Redis)                 | In-memory (Redis)                                            | [See production](/docs/deploy/infra#production-infrastructure) |
 | **Cron Jobs:**      | Disabled                          | [Encore Cloud Managed](/docs/primitives/cron-jobs)           | [See production](/docs/deploy/infra#production-infrastructure) |
 | **Object Storage:** | Local Disk                        | Encore Cloud Managed                                         | [See production](/docs/deploy/infra#production-infrastructure) |
 
@@ -83,16 +83,16 @@ are provisioned with small-scale use in mind.
 
 Encore Cloud provisions production infrastructure resources using best-practice guidelines and services for each respective cloud provider.
 
-|                     | GCP                                                                         | AWS                                                                        |
-| ------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| **Networking:**     | [VPC](/docs/platform/infrastructure/gcp#networking-architecture)                                           | [VPC](/docs/platform/infrastructure/aws#networking-architecture)                                            |
-| **Compute:**        | [Cloud Run](/docs/platform/infrastructure/gcp#google-cloud-run), [GKE](/docs/platform/infrastructure/gcp#google-kubernetes-engine)  | [Fargate ECS](/docs/platform/infrastructure/aws#aws-fargate), [EKS](/docs/platform/infrastructure/aws#aws-eks)   |
-| **SQL Databases:**  | [GCP Cloud SQL](/docs/platform/infrastructure/gcp#databases), [Neon](/docs/platform/infrastructure/neon) | [Amazon RDS](/docs/platform/infrastructure/aws#databases), [Neon](/docs/platform/infrastructure/neon) |
-| **Pub/Sub:**        | [GCP Pub/Sub](/docs/platform/infrastructure/gcp#pubsub)                                                      | [Amazon SQS & Amazon SNS](/docs/platform/infrastructure/aws#pubsub)                            |
-| **Object Storage:** | [GCS/Cloud CDN](/docs/platform/infrastructure/gcp#object-storage)                                                      | [Amazon S3/CloudFront](/docs/platform/infrastructure/aws#object-storage)                                             |
-| **Caches:**         | [GCP Memorystore (Redis)](/docs/platform/infrastructure/gcp#caching)                                         | [Amazon ElastiCache (Redis)](/docs/platform/infrastructure/aws#caching)                                   |
-| **Cron Jobs:**      | Encore Cloud Managed                                                              | Encore Cloud Managed                                                             | Encore Cloud Managed |
-| **Secrets:**        | [Secret Manager](/docs/platform/infrastructure/gcp#secrets-management)                                               | [AWS Secrets Manager](/docs/platform/infrastructure/aws#se)                                         |
+|                     | GCP                                                                                                                                | AWS                                                                                                            |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| **Networking:**     | [VPC](/docs/platform/infrastructure/gcp#networking-architecture)                                                                   | [VPC](/docs/platform/infrastructure/aws#networking-architecture)                                               |
+| **Compute:**        | [Cloud Run](/docs/platform/infrastructure/gcp#google-cloud-run), [GKE](/docs/platform/infrastructure/gcp#google-kubernetes-engine) | [Fargate ECS](/docs/platform/infrastructure/aws#aws-fargate), [EKS](/docs/platform/infrastructure/aws#aws-eks) |
+| **SQL Databases:**  | [GCP Cloud SQL](/docs/platform/infrastructure/gcp#databases), [Neon](/docs/platform/infrastructure/neon)                           | [Amazon RDS](/docs/platform/infrastructure/aws#databases), [Neon](/docs/platform/infrastructure/neon)          |
+| **Pub/Sub:**        | [GCP Pub/Sub](/docs/platform/infrastructure/gcp#pubsub)                                                                            | [Amazon SQS & Amazon SNS](/docs/platform/infrastructure/aws#pubsub)                                            |
+| **Object Storage:** | [GCS/Cloud CDN](/docs/platform/infrastructure/gcp#object-storage)                                                                  | [Amazon S3/CloudFront](/docs/platform/infrastructure/aws#object-storage)                                       |
+| **Caches:**         | [GCP Memorystore (Redis)](/docs/platform/infrastructure/gcp#caching)                                                               | [Amazon ElastiCache (Redis)](/docs/platform/infrastructure/aws#caching)                                        |
+| **Cron Jobs:**      | Encore Cloud Managed                                                                                                               | Encore Cloud Managed                                                                                           | Encore Cloud Managed |
+| **Secrets:**        | [Secret Manager](/docs/platform/infrastructure/gcp#secrets-management)                                                             | [AWS Secrets Manager](/docs/platform/infrastructure/aws#se)                                                    |
 
 ### Configurability
 
diff --git a/docs/platform/infrastructure/kubernetes.md b/docs/platform/infrastructure/kubernetes.md
index cbee9b5860..db6c5f71d4 100644
--- a/docs/platform/infrastructure/kubernetes.md
+++ b/docs/platform/infrastructure/kubernetes.md
@@ -6,13 +6,18 @@ subtitle: Deploying your app to a new Kubernetes cluster
 lang: platform
 ---
 
-When you build your app using Encore's Backend Framework, you can deploy the same code to many different types of [cloud infrastructure](/docs/platform/infrastructure/infra). Encore Cloud will automatically handle provisioning different infrastructure for each environment — depending on your goals. Configuring what type of compute platform you want is done through the [Encore Cloud Dashboard](https://app.encore.cloud) rather than in the application code.
+# Deploying Encore Apps to Kubernetes
 
-If you already have a Kubernetes cluster, you may want to deploy your Encore application into this pre-existing cluster. [See the docs](/docs/platform/infrastructure/import-kubernetes-cluster) for how to do this.
+Encore Cloud gives you flexibility in where you run your applications. You have two options for Kubernetes deployments:
+
+1. **Deploy to a new cluster**: Encore Cloud can automatically provision and manage a new Kubernetes cluster in your cloud account on AWS or GCP.
+2. **Use an existing cluster**: Deploy to your pre-existing Kubernetes cluster ([see instructions here](/docs/platform/infrastructure/import-kubernetes-cluster))
+
+All infrastructure provisioning is automated, and configuration is managed through the [Encore Cloud Dashboard](https://app.encore.cloud), keeping your application code clean and infrastructure-agnostic.
 
 ## Deploying to a new Kubernetes cluster
 
-**1. Connect your cloud account:** Ensure your cloud account (such as Google Cloud Platform or AWS) is connected to Encore Cloud. ([See docs](/docs/platform/infrastructure/own-cloud))
+**1. Connect your cloud account:** Ensure your cloud account (Google Cloud Platform or AWS) is connected to Encore Cloud. ([See docs](/docs/platform/deploy/own-cloud))
 
 **2. Create environment:** Open your app in the [Encore Cloud dashboard](https://app.encore.cloud) and go to **Environments**, then click on **Create Environment**.
 
diff --git a/docs/platform/introduction.md b/docs/platform/introduction.md
index f7378ae2b9..77dbd54b6a 100644
--- a/docs/platform/introduction.md
+++ b/docs/platform/introduction.md
@@ -1,14 +1,17 @@
 ---
 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.
+seodesc: Learn how Encore Cloud works and how it helps backend developers build cloud-based backend applications without manually dealing with infrastructure.
 title: Encore Cloud
 subtitle: End-to-end development platform for building robust distributed systems
 lang: platform
 ---
 
-Cloud services enable us to build highly scalable applications, but offer a poor developer experience. They force developers to manage a lot of added complexity during development and commonly introduce repetitive work that steals time away from the real goal of building your product. Launching a new app, migrating to the cloud, or breaking apart a monolith into microservices, can therefore be a daunting task.
+While cloud services enable us to build powerful applications, they come with significant complexity.
 
-Encore is purpose-built to solve this problem, restoring creativity for developers and productivity for teams.
+Developers spend countless hours managing infrastructure, writing boilerplate code, and dealing with complex deployment processes instead of building features that matter to users.
+
+Launching a new app, migrating to the cloud, or breaking apart a monolith into microservices, can therefore be a daunting task.
+Encore Cloud is purpose-built to solve this problem, restoring creativity for developers and productivity for teams.
 
 ## Intro video
 
@@ -16,28 +19,27 @@ Encore is purpose-built to solve this problem, restoring creativity for develope
 
 ## A simplified cloud backend development workflow
 
-Encore provides a complete toolset for backend development, from local development and testing, to cloud infrastructure management and DevOps.
+Encore Cloud provides a complete toolset for backend development: from local development, testing, and observability, to cloud infrastructure and DevOps automation.
 
 <img className="noshadow mx-auto d:w-3/4" src="/assets/docs/arch_full.png" title="Encore Overview" />
 
-Much of Encore's functionality is enabled by the Open Source Backend Frameworks [Encore.ts](/docs/ts) and [Encore.go](/docs/go), which let you define resources like services, databases, cron jobs, and Pub/Sub, as type-safe objects in your application code.
+Much of Encore Cloud's functionality is enabled by Encore's open source backend frameworks, [Encore.ts](/docs/ts) and [Encore.go](/docs/go), which let you define resources like services, databases, cron jobs, and Pub/Sub, as type-safe objects in your application code.
 
-With the Backend Framework you only define **infrastructure semantics** — _the things that matter to your application's behavior_ — not configuration for _specific_ cloud services. Encore then automatically generates boilerplate and orchestrates the relevant infrastructure for each environment. This means your application code can be used to run locally, test in preview environments, and provision and deploy to cloud environments on AWS and GCP.
+With the backend frameworks you only define **infrastructure semantics** — _the things that matter to your application's behavior_ — not configuration for _specific_ cloud services. Encore Cloud then automatically generates boilerplate and orchestrates the relevant infrastructure for each environment. This means your application code can be used to run locally, test in preview environments, and provision and deploy to cloud environments on AWS and GCP.
 
-When your application is deployed to your cloud, there are **no runtime dependencies on Encore** and there is **no proprietary code running in your cloud**.
+When your application is deployed to your cloud, there are **no runtime dependencies on Encore Cloud** and there is **no proprietary code running in your cloud**.
 
 ## Local Development
 
 <img className="noshadow mx-auto d:w-3/4" src="/assets/docs/arch_local.png" title="Encore's Local Development Workflow" />
 
-When you run your app locally using the [Encore CLI](/docs/ts/install), Encore parses your code and automatically sets up the necessary local infrastructure on the fly. _No more messing around with Docker Compose!_
+The local development tooling is fully open source. When you run your app locally using the [Encore CLI](/docs/ts/install), it parses your code and automatically sets up the necessary local infrastructure on the fly. _No more messing around with Docker Compose!_
 
 Aside from managing infrastructure, Encore's local development workflow comes with a lot of tools to make building distributed systems easier:
 
 - **Local environment matches cloud:** Encore automatically handles the semantics of service communication and interfacing with different types of infrastructure services, so that the local environment is a 1:1 representation of your cloud environment.
 - **Cross-service type-safety:** When building microservices applications with Encore, you get type-safety and auto-complete in your IDE when making cross-service API calls.
 - **Type-aware infrastructure:** With Encore, infrastructure like Pub/Sub queues are type-aware objects in your program. This enables full end-to-end type-safety when building event-driven applications.
-- **Secrets management:** Built-in [secrets management](/docs/ts/primitives/secrets) for all environments.
 - **Tracing:** The [local development dashboard](/docs/ts/observability/dev-dash) provides local tracing to help understand application behavior and find bugs.
 - **Automatic API docs & clients:** Encore generates [API docs](/docs/ts/observability/service-catalog) and [API clients](/docs/ts/cli/client-generation) in Go, TypeScript, JavaScript, and OpenAPI specification.
 
@@ -45,62 +47,70 @@ Aside from managing infrastructure, Encore's local development workflow comes wi
 
 <img className="noshadow mx-auto d:w-3/4" src="/assets/docs/arch_testing.png" title="Encore's Testing Workflow" />
 
-Encore comes with several built-in tools to help with testing:
+Encore's open source framework comes with several built-in tools to help with testing:
 
 - **Built-in service/API mocking:** Encore provides built-in support for [mocking API calls](/docs/go/develop/testing/mocking), and interfaces for automatically generating mock objects for your services.
 - **Local test infra:** When running tests locally, Encore automatically provides dedicated [test infrastructure](/docs/go/develop/testing#test-only-infrastructure) to isolate individual tests.
 - **Local test tracing:** The [Local Development Dashboard](/docs/go/observability/dev-dash) provides distributed tracing for tests, providing great visibility into what's happening and making it easier to understand why a test failed.
+
+Encore Cloud adds to this tool-set with:
 - **Preview Environments:** Encore automatically provisions a [Preview Environment](/docs/platform/deploy/preview-environments) for each Pull Request, an effective tool when doing end-to-end testing.
 
-## DevOps
+## Infrastructure & DevOps automation
 
 <img className="noshadow mx-auto d:w-3/4" src="/assets/docs/arch_devops.png" title="Encore's DevOps Workflow" />
 
-Our goal is that when you use Encore, you can focus your engineering effort on your product and completely avoid investing time in building a developer platform. You also get built-in tools that automate >90% of the normal day-to-day DevOps work.
-
-To achieve this, the headline feature Encore provides is automatic infrastructure provisioning in your cloud. Instead of writing Terraform, YAML, or clicking in cloud consoles, you [connect your cloud account](/docs/platform/infrastructure/own-cloud) and hit deploy. At deployment Encore automatically provisions [infrastructure](/docs/platform/infrastructure/infra) using battle-tested cloud services on AWS or GCP. Such as Cloud Run, Fargate, Kubernetes, CloudSQL, RDS, Pub/Sub, Redis, Cron Jobs, and more.
+Encore Cloud removes the need to build your own developer platform, automating over 90% of typical DevOps tasks. Here's how:
 
-This is enabled by [Encore.ts](/docs/ts) and [Encore.go](/docs/go), which lets you declare infrastructure semantics in application code. This approach lets you modify and swap out your infrastructure over time, without needing to make code changes or manually update infrastructure config files.
+### Core Infrastructure Management
+- **Zero-config deployment:** Connect your cloud account and deploy - Encore Cloudhandles the rest
+- **Battle-tested cloud services:** Automatic provisioning on AWS/GCP (Cloud Run, Fargate, Kubernetes, CloudSQL, etc.)
+- **No IaC required:** Say goodbye to Terraform and YAML - your code is the single source of truth
 
-Here are some of the other benefits and DevOps tools provided by Encore:
+### Security & Governance
+- **Automated IAM:** Least-privilege security permissions generated from parsing your code
+- **Infrastructure tracking:** Complete visibility of all provisioned resources
+- **Change management:** Built-in approval workflow for infrastructure changes
+- **Configuration management:** Simple UI for config changes that automatically 2-way syncs to your cloud
 
-- **No IaC or YAML needed:** Encore removes the need for manual infrastructure configuration, the application code is the source of truth for both business logic and infrastructure semantics.
-- **Automatic least-privilege IAM:** Encore parses your application code and sets up least-privilege IAM to match the requirements of the application.
-- **Infra tracking & approvals workflow:** Encore keeps track of all the [infrastructure](/docs/platform/infrastructure/infra) it provisions and provides an approval workflow as part of the deployment process, so Admins can verify and approve all infra changes.
-- **Cloud config 2-way sync:** Encore provides [a simple UI to make configuration changes](/docs/platform/infrastructure/infra#configurability), and also supports syncing changes you make in your cloud console on AWS/GCP.
-- **Cost analytics:** A simple overview to monitor costs for all infrastructure provisioned by Encore in your cloud.
-- **Logging & Metrics:** Encore automatically provides [logging](/docs/ts/observability/logging), [metrics](/docs/platform/observability/metrics), and [integrates with 3rd party tools](/docs/platform/observability/metrics#integrations-with-third-party-observability-services) like Datadog and Grafana.
-- **Service Catalog:**  Encore automatically generates a service catalog with complete [API documentation](/docs/ts/observability/service-catalog).
-- **Architecture diagrams:** To help with onboarding and collaboration, Encore generates [architecture diagrams](/docs/ts/observability/encore-flow) for your application, including infrastructure dependencies.
+### Monitoring & Observability
+- **Cost monitoring:** Track infrastructure costs across your cloud resources (currently for GCP, AWS coming soon)
+- **Integrated observability:** Built-in logging, metrics, and tracing
+- **Third-party integration:** Works with Datadog, Grafana, and other tools
+- **Auto-generated documentation:**
+  - Service catalog with complete API docs
+  - Live architecture diagrams showing infrastructure dependencies
 
-## Why choose Encore?
+## Why choose Encore Cloud?
 
-We believe Encore's end-to-end workflow is an unfair advantage for teams that want to focus on their product, and avoid investing engineering time in building *yet another developer platform*.
+Encore Cloud's end-to-end workflow is an unfair advantage for teams that need to move quickly without sacrificing quality and scalability.
+By automating over 90% of the normal day-to-day DevOps work, you can focus on building your product instead of building your own developer platform.
 
-Encore is designed to provide engineering teams with all the tools they need to build production-ready cloud backends:
+The benefits of Encore Cloud are:
 
-- **Faster Development**: Encore streamlines the development process with its Backend Framework, clear abstractions, and built-in development tools, enabling you to build and deploy applications more quickly.
-- **Reduced Costs**: Encore's infrastructure management minimizes wasteful cloud expenses and reduces DevOps workload, allowing you to work more efficiently.
-- **Scalability & Performance**: Encore simplifies building microservices applications that can handle growing user bases and demands, without the normal boilerplate and complexity.
-- **Control & Standardization**: Encore enforces standardization and provisions infrastructure consistently according to best practices for each cloud provider.
-- **Quality through understandability:** Built-in tools like automated architecture diagrams, generated API docs, and distributed tracing make it simple for teams to get an overview of their system and understand its behavior.
-- **Security**: Encore ensures your application is secure by implementing cloud security best practices and _principle of least privilege_ security by default.
+- **Faster Development**: Encore Cloud enables 2-3x faster iterations thanks to the streamlined the development process with its clear abstractions and built-in development tools.
+- **Reduced Costs**: Encore Cloud's infrastructure management minimizes wasteful cloud expenses and reduces DevOps workload by 90%.
+- **Scalability & Performance**: Encore Cloud simplifies building microservices applications that can handle growing user bases and demands, without the normal boilerplate and complexity.
+- **Control & Standardization**: Encore Cloud enforces standardization and provisions infrastructure consistently according to best practices for each cloud provider.
+- **Quality through understandability:** Built-in tools like automated architecture diagrams, generated API docs, and distributed tracing make it simple for teams to get an overview of their system and ensure the correct behavior.
+- **Security**: Encore Cloud makes your application secure by automatically implementing security best practices for each cloud provider.
 
 ## Common use cases
 
-Encore is designed to give teams a productive and less complex experience when solving most backend use cases. Many teams use Encore to build things like:
+Encore Cloud is designed to give teams a productive and less complex experience when solving most common backend use cases.
+Many teams use Encore Cloud to build things like:
 
+-   Consumer apps
 -   High-performance B2B Platforms
--   Fintech & Consumer apps
+-   Fintech & Crypto applications
 -   Global E-commerce marketplaces
--   Microservices backends and event-driven systems for SaaS applications and mobile apps
+-   Microservices backends and event-driven systems for scalable SaaS applications
 -   And much more...
 
-Check out the [showcase](/showcase) section for some examples of real-world products being built with Encore.
+Check out the [showcase](https://encore.cloud/showcase) section for some examples of real-world products being built with Encore.
 
 ## Getting started
 
 1. [Follow the Quick Start Guide](/docs/ts/quick-start)
 2. [Join Discord](https://encore.dev/discord) to ask questions and meet other Encore developers
 3. Follow and star the project on [GitHub](https://github.com/encoredev/encore) to stay up to date
-4. Explore the Documentation to learn about Encore's features
diff --git a/docs/platform/management/billing.md b/docs/platform/management/billing.md
index 3b8002bba6..48e92ce6b4 100644
--- a/docs/platform/management/billing.md
+++ b/docs/platform/management/billing.md
@@ -32,7 +32,7 @@ You can activate your trial from the [pricing page](https://encore.dev/pricing).
 All plans come with free use of Encore Cloud, subject to [Fair Use limits](/docs/platform/management/usage).
 Encore Cloud is intended for development environments and limited scale professional use that does not require specific SLAs.
 
-For production use, you can [connect your own cloud account on AWS/GCP](/docs/platform/infrastructure/own-cloud) and use Encore to deploy there, including provisioning infrastructure and managing IAM. When you connect your own cloud account, you pay for usage directly to your cloud provider.
+For production use, you can [connect your own cloud account on AWS/GCP](/docs/platform/deploy/own-cloud) and use Encore to deploy there, including provisioning infrastructure and managing IAM. When you connect your own cloud account, you pay for usage directly to your cloud provider.
 
 If you prefer to manage deployment yourself, you can export your application as a standalone Docker image and deploy in any way you prefer. ([Learn more](/docs/ts/self-host/build))
 
diff --git a/docs/platform/migration/migrate-to-encore.md b/docs/platform/migration/migrate-to-encore.md
index 526ed6d93f..1968ac4072 100644
--- a/docs/platform/migration/migrate-to-encore.md
+++ b/docs/platform/migration/migrate-to-encore.md
@@ -53,7 +53,7 @@ When you create an Encore service and add a [database](/docs/ts/primitives/datab
 
 ### 3. Deploy to your cloud account
 
-Once you're ready to deploy, you can [connect your cloud account](/docs/platform/infrastructure/own-cloud) (GCP or AWS) and have Encore deploy and provision your new system directly in your existing account.
+Once you're ready to deploy, you can [connect your cloud account](/docs/platform/deploy/own-cloud) (GCP or AWS) and have Encore deploy and provision your new system directly in your existing account.
 
 See the [infrastructure documentation](/docs/platform/infrastructure/infra#production-infrastructure) for details on how Encore provisions cloud infrastructure for each cloud provider.
 
diff --git a/docs/platform/migration/try-encore.md b/docs/platform/migration/try-encore.md
index 70b36a2092..ea9d83a210 100644
--- a/docs/platform/migration/try-encore.md
+++ b/docs/platform/migration/try-encore.md
@@ -31,7 +31,7 @@ For example when:
 - **2. Create New Services:** Develop new services or systems using [Encore.ts](/docs/ts) or [Encore.go](/docs/go) to get off the ground quickly. This lets you try out all Encore features and enables you to design your new system with Encore’s [automatic architecture diagrams](/docs/ts/observability/encore-flow).
 - **3. Integrate via APIs:**  Where relevant, integrate your new system with your existing backend application using APIs. This can be made simpler by using Encore’s [generated API clients](/docs/ts/cli/client-generation).
 - **4. Validate & Iterate:** Deploy the new services to a [cloud environment](/docs/platform/infrastructure/infra), automatically provisioned by Encore, and validate their performance and interoperability. Use Encore’s [distributed tracing](/docs/ts/observability/tracing) to find bugs or performance issues.
-- **5. Connect cloud and Deploy:** When you are satisfied that your application is working as expected, [connect your cloud account](/docs/platform/infrastructure/own-cloud) (AWS or GCP) and create a production environment for your application. Encore automatically provisions the infrastructure needed using each cloud’s native services, or you can deploy your application into an [existing Kubernetes cluster](/docs/platform/infrastructure/import-kubernetes-cluster).
+- **5. Connect cloud and Deploy:** When you are satisfied that your application is working as expected, [connect your cloud account](/docs/platform/deploy/own-cloud) (AWS or GCP) and create a production environment for your application. Encore automatically provisions the infrastructure needed using each cloud’s native services, or you can deploy your application into an [existing Kubernetes cluster](/docs/platform/infrastructure/import-kubernetes-cluster).
 
 ## Refactor
 Refactoring can serve as a breath of fresh air for your existing code, revitalizing it by optimizing existing structures. In this approach, your goal is to improve on your existing backend application, often focusing on shedding unnecessary complexity and enabling new opportunities.
@@ -51,7 +51,7 @@ Your application is already built using a supported programming language like **
 - **2. Implement Backend Framework:** Start using [Encore.ts](/docs/ts) or [Encore.go](/docs/go) in your application by replacing existing infrastructure configuration and boilerplate. This enables you to use Encore's infrastructure automation and removes the hassle of manual infrastructure setup. **Tip:** [Existing databases can be integrated](/docs/go/primitives/connect-existing-db) so you don’t need to migrate existing data.
 - **3. Resolve compile-time errors:** Encore comes with a parser and compiler that ensures your application correctly implements the Backend Framework. This lets you discover problems at compile time and provides insightful error messages to help you quickly resolve any errors.
 - **4. Test & Iterate:** Test the refactored application to ensure stability and reliability using Encore’s automatically provisioned cloud [environments](/docs/platform/deploy/environments) and [distributed tracing](/docs/ts/observability/tracing) for fast debugging and iteration. If relevant, you can use a [generated client](/docs/ts/cli/client-generation) to integrate with your existing application frontend.
-- **5. Connect cloud and Deploy:** When you are satisfied that your application is working as expected, [connect your cloud account](/docs/platform/infrastructure/own-cloud) (AWS or GCP) and create a production environment for your application. Encore automatically provisions the infrastructure needed using each cloud’s native services, or you can deploy your application into an [existing Kubernetes cluster](/docs/platform/infrastructure/import-kubernetes-cluster).
+- **5. Connect cloud and Deploy:** When you are satisfied that your application is working as expected, [connect your cloud account](/docs/platform/deploy/own-cloud) (AWS or GCP) and create a production environment for your application. Encore automatically provisions the infrastructure needed using each cloud’s native services, or you can deploy your application into an [existing Kubernetes cluster](/docs/platform/infrastructure/import-kubernetes-cluster).
 
 ## Rebuild
 The Rebuild strategy is for those who want a fresh start by recreating an application from the ground up. It’s particularly relevant for companies looking to make a bigger change like changing programming language or migrating from legacy self-hosted infrastructure. A full rebuild, although potentially labor-intensive, opens up opportunities to harness the latest cloud services and developer tools like Encore.
@@ -70,7 +70,7 @@ The Rebuild strategy is for those who want a fresh start by recreating an applic
 - **1. Plan & Design:** Start by creating a design, considering the application's core requirements and architecture. Decide on the programming language, keeping in mind Encore's supported languages.
 - **2. Develop from Scratch:** Develop your new application using Encore [Encore.ts](/docs/ts) or [Encore.go](/docs/go) to get up and running quickly in a shared environment using Encore’s built-in development cloud.
 - **3. Test & Iterate:** Test your new application to ensure reliability using Encore’s [distributed tracing](/docs/ts/observability/tracing) for fast debugging and iteration. Use the [generated API clients](/docs/ts/cli/client-generation) to integrate with your application frontend.
-- **4. Connect cloud and Deploy:** When you are satisfied that your application is working as expected, [connect your cloud account](/docs/platform/infrastructure/own-cloud) (AWS or GCP) and create a production environment for your application. Encore automatically provisions the infrastructure needed using each cloud’s native services, or you can deploy your application into an [existing Kubernetes cluster](/docs/platform/infrastructure/import-kubernetes-cluster).
+- **4. Connect cloud and Deploy:** When you are satisfied that your application is working as expected, [connect your cloud account](/docs/platform/deploy/own-cloud) (AWS or GCP) and create a production environment for your application. Encore automatically provisions the infrastructure needed using each cloud’s native services, or you can deploy your application into an [existing Kubernetes cluster](/docs/platform/infrastructure/import-kubernetes-cluster).
 
 ## Get support adopting Encore
 Each approach has different benefits and is relevant in different scenarios. Which one is right for your team depends on your priorities and existing setup.
diff --git a/docs/ts/develop/metadata.md b/docs/ts/develop/metadata.md
index 87da95649a..0f0b73ee95 100644
--- a/docs/ts/develop/metadata.md
+++ b/docs/ts/develop/metadata.md
@@ -126,7 +126,7 @@ initialization, `currentRequest()` returns `undefined`.
 
 ### Using Cloud Specific Services
 
-All the [clouds](/docs/platform/infrastructure/own-cloud) contain a large number of services, not all of which Encore natively supports.
+All the [clouds](/docs/platform/deploy/own-cloud) contain a large number of services, not all of which Encore natively supports.
 
 By using information about the [environment](/docs/platform/deploy/environments), you can define the implementation of these and use different services for each environment's provider.
 
diff --git a/docs/ts/primitives/cron-jobs.md b/docs/ts/primitives/cron-jobs.md
index 7ff3cd719b..6574fadb54 100644
--- a/docs/ts/primitives/cron-jobs.md
+++ b/docs/ts/primitives/cron-jobs.md
@@ -65,7 +65,7 @@ Cron Job executions across all your environments via the `Cron Jobs` menu item:
 ## Keep in mind when using Cron Jobs
 
 - Cron Jobs do not execute during local development or in [Preview Environments](/docs/platform/deploy/preview-environments). However, you can manually invoke the API to test its behavior.
-- In Encore Cloud, Cron Job executions are limited to **once every hour**, with the exact minute randomized within that hour for users on the Free Tier. To enable more frequent executions or to specify the exact minute within the hour, consider [deploying to your own cloud](/docs/platform/infrastructure/own-cloud) or upgrading to the [Pro plan](/pricing).
+- In Encore Cloud, Cron Job executions are limited to **once every hour**, with the exact minute randomized within that hour for users on the Free Tier. To enable more frequent executions or to specify the exact minute within the hour, consider [deploying to your own cloud](/docs/platform/deploy/own-cloud) or upgrading to the [Pro plan](/pricing).
 - Both public and private APIs are supported for Cron Jobs.
 - Ensure that the API endpoints used in Cron Jobs are idempotent, as they may be called multiple times under certain network conditions.
 - API endpoints utilized in Cron Jobs must not accept any request parameters.
diff --git a/docs/ts/quick-start.mdx b/docs/ts/quick-start.mdx
index b3d52f518e..43ac20d5cc 100644
--- a/docs/ts/quick-start.mdx
+++ b/docs/ts/quick-start.mdx
@@ -195,7 +195,7 @@ It will look something like: `https://app.encore.cloud/$APP_ID/deploys/...`
 
 🥐 Open the URL to access the Cloud Dashboard and check the progress of your deployment.
 
-You can now use the Cloud Dashboard to view production [traces](/docs/ts/observability/tracing), [connect your cloud account](/docs/platform/infrastructure/own-cloud), [integrate with GitHub](/docs/platform/integrations/github), and much more.
+You can now use the Cloud Dashboard to view production [traces](/docs/ts/observability/tracing), [connect your cloud account](/docs/platform/deploy/own-cloud), [integrate with GitHub](/docs/platform/integrations/github), and much more.
 
 <video autoPlay playsInline loop controls muted className="w-full h-full">
   <source src="/assets/docs/webdashvideo.mp4" className="w-full h-full" type="video/mp4"/>