fix(shell-docs): correct premium walkthrough on opt-in migrations Job

The Helm chart's `migrations.enabled` value defaults to `false`, but
the install walkthrough and overview prose both implied the
pre-install migrations Job always runs. Realign the docs with what the
chart actually does:

- intelligence-platform: rewrite the "Install" prose to describe the
  Job as conditional on `migrations.enabled: true`.
- self-hosting: add a new step in the install walkthrough between
  "Create secrets" and "Install the chart" that explains how to opt
  into migrations and when to leave them disabled. Update the
  "Verify the install" prose so it only claims a Completed Job if
  the reader opted in, and adjust the `--timeout` rationale to match.

Author: samjulien

showcase/shell-docs/src/content/docs/premium/intelligence-platform.mdx

@@ -56,7 +56,7 @@ Every meaningful configuration value that is sensitive — database URL, Redis U
 
 ### Install
 
-A `helm install` creates one namespace (by default `copilot-intelligence`), the Deployments above, their Services and ServiceAccounts, PodDisruptionBudgets, HorizontalPodAutoscalers, an Ingress resource, and any `ExternalSecret` resources you enabled. A pre-install `Job` runs schema migrations against your Postgres database; the chart blocks the rollout until migrations complete.
+A `helm install` creates one namespace (by default `copilot-intelligence`), the Deployments above, their Services and ServiceAccounts, PodDisruptionBudgets, HorizontalPodAutoscalers, an Ingress resource, and any `ExternalSecret` resources you enabled. If you set `migrations.enabled: true`, a pre-install `Job` runs schema migrations against your Postgres database; the chart blocks the rollout until migrations complete. The Job is opt-in (`migrations.enabled` defaults to `false`) — leave it disabled if you manage migrations out-of-band.
 
 ### Runtime lifecycle
 

showcase/shell-docs/src/content/docs/premium/self-hosting.mdx

@@ -191,6 +191,19 @@ Before starting, make sure the following are in place. The [How the Intelligence
     The exact Secret names referenced in your values file must match whatever you create.
   </Step>
 
+  <Step>
+    ### (Optional) Enable schema migrations
+
+    The chart can run database schema migrations as a pre-install `Job`. This is **disabled by default** (`migrations.enabled: false`). If you want the chart to apply migrations for you on install, set the following in `my-values.yaml`:
+
+    ```yaml title="my-values.yaml"
+    migrations:
+      enabled: true
+    ```
+
+    With this enabled, `helm install` blocks the rollout until the migrations Job reports `Completed`. Leave it disabled if you manage schema migrations out-of-band (for example, via your existing CI/CD or DBA pipeline).
+  </Step>
+
   <Step>
     ### Install the chart
 
@@ -203,7 +216,7 @@ Before starting, make sure the following are in place. The [How the Intelligence
       --timeout 10m
     ```
 
-    `--wait` blocks until the `Deployments` report healthy replicas; `--timeout 10m` allows enough time for image pulls and the initial database migration job.
+    `--wait` blocks until the `Deployments` report healthy replicas; `--timeout 10m` allows enough time for image pulls and (if you enabled it in the previous step) the initial database migration job.
   </Step>
 
   <Step>
@@ -216,7 +229,7 @@ Before starting, make sure the following are in place. The [How the Intelligence
     kubectl get ingress -n copilot-intelligence
     ```
 
-    You should see `app-api`, `app-frontend`, and — if enabled — `realtime-gateway` pods running. The migrations `Job` will appear as `Completed`.
+    You should see `app-api`, `app-frontend`, and — if enabled — `realtime-gateway` pods running. If you opted into migrations (`migrations.enabled: true`, see the values step above), the migrations `Job` will also appear as `Completed`; if you left migrations disabled, no Job is created.
 
     Confirm the API health check reports `ok`: