docs(BRA-282): clarify that branches are created as clones of the base project (#49594)

## What kind of change does this PR introduce?

Docs update.


## What is the new behavior?

The branching docs now state consistently that every branch, preview or
persistent, is created as a clone of the base project, starting with
that project's schema, Edge Functions, and configuration. Data and
storage objects are not cloned by default.

## Additional context

This documents new branch-creation behavior. Two automated reviewers
flagged the clone wording and argued for a migration-replay description;
that reflects the previous implementation, so their findings don't apply
here and the clone framing stands.

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Jeremias Menichelli <jmenichelli@gmail.com>

apps/docs/content/guides/deployment/branching.mdx

@@ -15,7 +15,8 @@ Supabase branches create separate environments that spin off from your main proj
 - **Preview Branches**: Preview branches are ephemeral and best suited for focused testing. They are automatically deleted when a PR is merged or closed.
 - **Persistent Branches**: Persistent branches are long-lived and recommended for environments like staging, QA, or development. They aren't automatically paused or deleted due to inactivity or when a PR is merged or closed.
 - **Managing Branches**: You can create, review, and merge branches either automatically via our [GitHub integration](/docs/guides/deployment/branching/github-integration) or directly [through the dashboard](/docs/guides/deployment/branching/dashboard) (currently in beta). All branches show up in the branches page in the dashboard, regardless of how they were created.
-- **Data-less**: New branches do not start with any data from your main project. This is meant to better protect your sensitive production data. To start your branches with data, you can use a [seed file](/docs/guides/deployment/branching/github-integration#seeding) if using the GitHub integration.
+- **Cloned from your main project**: Each new branch is created as a clone of your main project. It starts with that project's Edge Functions deployed and the configuration set.
+- **Data-less by default**: By default, new branches do not start with any data or storage objects from your main project. This is meant to better protect your sensitive production data. To start your branches with data, you can use a [seed file](/docs/guides/deployment/branching/github-integration#seeding) if using the GitHub integration, or the [Include data](/docs/guides/deployment/branching/dashboard#include-production-data) option if you create the branch from the dashboard.
 
 ## Deploying to production
 

apps/docs/content/guides/deployment/branching/dashboard.mdx

@@ -41,6 +41,24 @@ Once you've enabled the feature, you can create a new branch:
 1. Click the arrows next to the branch name in the top menu bar. (The top menu bar has the format `YOUR_ORGANIZATION / YOUR_PROJECT / CURRENT_BRANCH_NAME`.)
 2. Click `Create branch`.
 
+The new branch is a clone of your base project. It starts with the project's schema, Edge Functions, and the configuration set.
+
+### Include production data
+
+By default, a branch starts without any of your production data or storage objects. If your project has the Point-in-Time Recovery add-on, you can turn on **Include data** when you create the branch to copy your production data into it.
+
+<Admonition type="caution">
+
+A branch created with **Include data** holds a copy of your production data, treat it with the same care as production.
+
+</Admonition>
+
+<Admonition type="note">
+
+A branch uses a larger disk and matches the compute size of your project, which increases its cost.
+
+</Admonition>
+
 ## Making changes to a branch
 
 Use the branch selector in the top bar to change to your branch. Any changes you make (including SQL run in the SQL editor, table editor changes, and configuration changes) are now made against the currently selected branch.

apps/docs/content/guides/deployment/branching/github-integration.mdx

@@ -83,19 +83,25 @@ Enable the **Automatic branching** option in your GitHub Integration configurati
 
 When a new branch is created in GitHub, a corresponding branch is created in Supabase. (You can enable the **Supabase changes only** option to only create Supabase branches when Supabase files change.)
 
+Every Supabase branch, preview or persistent, is created as a clone of your base project. The new branch starts with the Edge Functions and configuration of that project. Its database schema is not cloned. Instead, it is built from the migrations you commit to your repository.
+
 ### Configuration
 
 You can test configuration changes on your Preview Branch by configuring the `config.toml` file in your Supabase directory. See the [Configuration docs](/docs/guides/deployment/branching/configuration) for more information.
 
+Your branch starts with the configuration of your base project. The settings in your `config.toml` file are applied on top of that clone.
+
 A comment is added to your PR with the deployment status of your preview branch.
 
 ### Migrations
 
-The migrations in the `migrations` subdirectory of your Supabase directory are automatically run.
+The migrations in the `migrations` subdirectory of your Supabase directory are automatically run when the branch is created. Each later commit runs only the migrations that haven't been applied yet.
+
+If you want to rerun existing migrations, reset the branch from the Supabase dashboard to start from scratch. Note that existing data on your branch will also be dropped by a reset.
 
 ### Seeding
 
-No production data is copied to your Preview branch. This is meant to protect your sensitive production data.
+Cloning your base project copies its Edge Functions and configuration, but not its data or storage objects. This is meant to protect your sensitive production data. Your branch starts with the tables your migrations create, and the only rows in them are the ones your seed files add.
 
 You can seed your Preview Branch with sample data using the `seed.sql` file in your Supabase directory. See the [Seeding docs](/docs/guides/local-development/seeding-your-database) for more information.
 

apps/docs/content/guides/deployment/branching/troubleshooting.mdx

@@ -27,7 +27,9 @@ You might want to roll back changes you've made in an earlier migration change.
 
 To fix this, push the latest changes, then delete the preview branch in Supabase and reopen it.
 
-The new preview branch is reseeded from the `./supabase/seed.sql` file by default. Any additional data changes made on the old preview branch are lost. This is equivalent to running `supabase db reset` locally. All migrations are rerun in sequential order.
+The new preview branch is a fresh clone of your base project and is reseeded from the `./supabase/seed.sql` file by default. Any additional data changes made on the old preview branch are lost.
+
+To rerun migrations that your base project has already applied, reset the branch from the Supabase dashboard instead. A reset reruns all migrations in sequential order and drops existing data on the branch.
 
 ### Deployment failures
 

apps/docs/content/guides/deployment/branching/working-with-branches.mdx

@@ -181,7 +181,7 @@ After completing the steps above, you should receive a Slack message whenever an
 
 Migrations are run in sequential order. Each migration builds upon the previous one.
 
-The preview branch has a record of which migrations have been applied, and only applies new migrations for each commit. This can create an issue when rolling back migrations.
+The preview branch inherits the migration history of your base project, so it only applies migrations that haven't been run yet. This can create an issue when rolling back migrations.
 
 ### Using ORM or custom seed scripts
 
@@ -237,7 +237,9 @@ You might want to roll back changes you've made in an earlier migration change.
 
 To fix this, push the latest changes, then delete the preview branch in Supabase and reopen it.
 
-The new preview branch is reseeded from the `./supabase/seed.sql` file by default. Any additional data changes made on the old preview branch are lost. This is equivalent to running `supabase db reset` locally. All migrations are rerun in sequential order.
+The new preview branch is a fresh clone of your base project and is reseeded from the `./supabase/seed.sql` file by default. Any additional data changes made on the old preview branch are lost.
+
+To rerun migrations that your base project has already applied, reset the branch from the Supabase dashboard instead. A reset reruns all migrations in sequential order and drops existing data on the branch.
 
 ### Seeding behavior