docs: add promotion flow for data apps

Author: mintlify[bot]

guides/data-apps.mdx

@@ -132,6 +132,30 @@ Personal apps stay tied to whoever created them until they're moved into a space
   ![Clean Shot 2026 04 29 At 18 39 56@2x](/images/CleanShot-2026-04-29-at-18.39.56@2x.png)
 </Frame>
 
+## Promoting an app
+
+If you're building in a [preview project](/guides/developer/preview-projects), you can promote a data app into the preview's upstream (production) project once it's ready. This mirrors how chart and dashboard [promotion](/guides/how-to-promote-content) works: you iterate safely in preview, then push a snapshot to production.
+
+To promote an app:
+
+1. Open the app's **⋯** menu - either on the app card in a list, or in the chat header inside the app - and select **Promote**.
+2. In the confirmation dialog, review whether the action will **create** a new production app or **update** the existing linked one, and which space it will land in.
+3. Click **Promote**. When it finishes, you're taken to the promoted app in the production project.
+
+The first promotion creates a new app in the upstream project and links the two together. Every later promotion of the same preview app appends a new version to that linked production app, so production keeps a clean history of what was promoted and when. The latest ready version in preview is what gets snapshotted - in-progress builds are skipped.
+
+The app lands in a space that matches the source app's space by path. If no space with that path exists in the upstream project, Lightdash creates one. Personal apps (apps not in a space) are promoted as personal apps owned by the promoter.
+
+To promote, you need:
+
+- **Manage** access on the source data app in the preview project.
+- **Create** permission for data apps in the upstream project.
+- The preview project must have an upstream project configured under **Settings → Data ops**.
+
+<Info>
+  Promotion copies the built app artifacts as-is, so the production app renders immediately without rebuilding. Iterating on the production copy is supported, but chart and dashboard references attached to earlier preview versions stay pinned to their preview uuids and won't resolve in production - re-attach them in production if you need to keep iterating there.
+</Info>
+
 ## Data context and the app model
 
 Data apps don't ship with their own copy of your data. They run inside a sandboxed iframe with no direct access to the Lightdash API, so every query the app wants to run is proxied through the Lightdash UI hosting the iframe.

guides/how-to-promote-content.mdx

@@ -66,3 +66,7 @@ If the dashboard or charts are in a space that doesn't exist in the upstream pro
 </Frame>
 
 Once the dashboard is promoted, you can click on the `success` banner to open a new tab into this dashboard in the `production project`.
+
+## Promote data apps
+
+You can also promote data apps from a preview project into their upstream project. See [Promoting an app](/guides/data-apps#promoting-an-app) in the data apps guide for details.