From ad0e1562fcbdded651cd23c7e7aa7c66fd453f28 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Thu, 11 Jun 2026 19:15:31 +0000
Subject: [PATCH] docs: document multi-app porter.yaml and --wait support for
 addons

---
 .../configuration-as-code/addons-porter-yaml.mdx   | 14 ++++++++++++--
 standard/cli/command-reference/porter-apply.mdx    |  4 ++--
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/applications/configuration-as-code/addons-porter-yaml.mdx b/applications/configuration-as-code/addons-porter-yaml.mdx
index ef60f42..90d80fc 100644
--- a/applications/configuration-as-code/addons-porter-yaml.mdx
+++ b/applications/configuration-as-code/addons-porter-yaml.mdx
@@ -9,12 +9,22 @@ You can deploy multiple Porter apps alongside multiple Porter addons in a single
 
 ### Usage
 
-To enable this feature, set the `PORTER_ADDON_YAML` environment variable while running the apply command.
+Run `porter apply` against a `porter.yaml` that uses the top-level `apps:` and `addons:` arrays. The CLI automatically detects the multi-app format and applies each addon and app in sequence.
 
 ```bash
-PORTER_ADDON_YAML=true porter apply -f porter.yaml
+porter apply -f porter.yaml
 ```
 
+### Waiting for addons to become available
+
+Pass the `--wait` (`-w`) flag to block until each datastore addon reaches the `AVAILABLE` state before any apps are deployed. This is useful when your apps reference an addon's connection environment group (for example `db` or `cache` in the example below) — without `--wait`, an app can start rolling out before the datastore (and its generated env group) is ready, causing the app to crash on startup.
+
+```bash
+porter apply -f porter.yaml --wait
+```
+
+`--wait` polls each addon for up to 10 minutes. After all addons are available, Porter applies the apps and, as before, waits for each app's rollout to complete.
+
 ## Example Configuration
 
 ```yaml
diff --git a/standard/cli/command-reference/porter-apply.mdx b/standard/cli/command-reference/porter-apply.mdx
index 05db14b..a12937f 100644
--- a/standard/cli/command-reference/porter-apply.mdx
+++ b/standard/cli/command-reference/porter-apply.mdx
@@ -36,7 +36,7 @@ porter apply -f porter.yaml [flags]
 | `--file` | `-f` | Path to the `porter.yaml` configuration file (optional if app already exists) |
 | `--app` | | Override the app name specified in `porter.yaml` |
 | `--target` | `-x` | Specify a deployment target (name or ID) |
-| `--wait` | `-w` | Wait for the deployment to complete before exiting |
+| `--wait` | `-w` | Wait for the deployment to complete before exiting. For multi-app `porter.yaml` files that include datastore addons, also waits up to 10 minutes for each addon to reach the `AVAILABLE` state before apps are deployed |
 | `--preview` | `-p` | Deploy to a preview environment based on current git branch |
 
 <Warning>
@@ -161,7 +161,7 @@ When you run `porter apply`, the following steps occur:
     Porter deploys or updates all services defined in the configuration
   </Step>
   <Step title="Wait for Rollout (if --wait)">
-    If `--wait` is specified, Porter waits for all services to become healthy
+    If `--wait` is specified, Porter waits for all services to become healthy. When the `porter.yaml` defines datastore addons, Porter also waits for each addon to reach the `AVAILABLE` state before deploying the apps that depend on it.
   </Step>
 </Steps>