docs: lead with wait --watch instead of polling get

config-as-code/project-config-file.mdx

@@ -117,10 +117,25 @@ Store the config file in your repository and manage it with the CLI.
   <Step title="Review and approve the stack run">
     Applying a config change starts a [stack change pipeline run](/modules/stack#stacks-change-through-pipelines) when the affected module has a Terraform stack. The stack run creates a Terraform plan and waits for manual approval before applying, unless you pass `--autoapprove` to an apply command that supports it.
 
-    After the stack run starts, inspect the run and its Terraform results with these commands:
+    The apply prints a `PIPELINE_RUN_ID` for every stack run it starts, plus the wait command for those runs. Follow a run with `wait --watch` instead of polling `pipeline run get`.
+
+    The runs are listed in dependency order, so you can work through them one at a time: a run only starts once the runs it depends on succeed.
+
+    Without `--autoapprove`, each run stops at its approval gate, so wait for that gate, review the plan, approve, then wait for the apply:
 
     ```bash
-    ravion pipeline run get <pipeline-run-id>
+    ravion pipeline run wait <pipeline-run-id> --until PENDING_APPROVAL --watch
+
+    ravion pipeline run get-plan <pipeline-run-id>
+    ravion pipeline run approve <pipeline-run-id>
+    ravion pipeline run wait <pipeline-run-id> --watch
+    ```
+
+    With `--autoapprove`, wait for the run to finish, then inspect the Terraform results:
+
+    ```bash
+    ravion pipeline run wait <pipeline-run-id> --watch --timeout 30m
+
     ravion pipeline run get-plan <pipeline-run-id>
     ravion pipeline run get-apply <pipeline-run-id>
     ravion logs pipeline-step <step-execution-id>
@@ -171,6 +186,18 @@ ravion project config apply <project-id> --file ravion.yaml --dry-run
 ravion project config apply <project-id> --file ravion.yaml
 ```
 
+6. After applying config, use `ravion pipeline run wait <id> --watch` instead of repeatedly polling `pipeline run get`. The apply output lists a `PIPELINE_RUN_ID` for every stack run it starts, followed by the exact wait command to run. Work through the commands in the printed order, which is dependency order:
+
+```bash
+# Runs stop for approval unless the apply passed --autoapprove
+ravion pipeline run wait <pipeline-run-id> --until PENDING_APPROVAL --watch
+
+# Autoapproved runs go straight through
+ravion pipeline run wait <pipeline-run-id> --watch --timeout 30m
+```
+
+7. Follow application deployments the same way, with `ravion deploy wait <deployment-id> --watch` instead of polling `deploy get`.
+
 ### Helpful hints
 
 - Pull the latest live config anytime with `ravion project config pull <project-id> --file ravion.yaml`.
@@ -191,6 +218,7 @@ ravion project config apply <project-id> --file ravion.yaml
 - Copy module inputs from unrelated files or examples.
 - Invent fields that are not present in the CLI schema output.
 - Apply changes without a successful dry run first.
+- Poll `ravion pipeline run get` or `ravion deploy get` in a loop. Use the matching `wait --watch` command instead.
 
 ## Schema reference
 

migrate/import-into-standard-module.mdx

@@ -108,8 +108,8 @@ The example below imports an existing AWS RDS PostgreSQL instance into an `rvn-r
     # Find the run attached to the stack
     ravion pipeline run list --attached-entity-id <stack-id> --json
 
-    # Poll until the status is PENDING_APPROVAL
-    ravion pipeline run get <run-id> --json
+    # Stream the run until it reaches the approval gate
+    ravion pipeline run wait <run-id> --until PENDING_APPROVAL --watch
 
     ravion pipeline run get-plan <run-id>
     ```

migrate/import-into-terraform-stack.mdx

@@ -114,8 +114,8 @@ The example imports an existing AWS S3 bucket. The same flow works for any resou
     When the run reaches the approval gate, check the plan:
 
     ```bash
-    # Poll until the status is PENDING_APPROVAL
-    ravion pipeline run get <run-id> --json
+    # Stream the run until it reaches the approval gate
+    ravion pipeline run wait <run-id> --until PENDING_APPROVAL --watch
 
     ravion pipeline run get-plan <run-id>
     ```

modules/build.mdx

@@ -100,7 +100,8 @@ Both `tag` and `digest` are optional, accept template tokens, and resolve agains
 A build is a pipeline step execution — there's no separate build entity or command. Find it in the pipeline run:
 
 ```bash
-ravion pipeline run get <pipeline-run-id>
+# Stream the run until it finishes, then read the step logs
+ravion pipeline run wait <pipeline-run-id> --watch --timeout 30m
 ravion logs pipeline-step <step-execution-id>
 ```
 

modules/deploy.mdx

@@ -73,7 +73,15 @@ Ravion surfaces every low-level event during a rollout — far more than a CI lo
 - **Resource-level status**: each ECS task's status ladder (provisioning → pending → running) and target-group health.
 - **AWS infrastructure events**: task state changes, service actions, and deployment state changes ingested from EventBridge.
 
-All of this streams live to the dashboard and is available via the API and `ravion deploy get`.
+All of this streams live to the dashboard and is available via the API.
+
+From the CLI, follow a deploy to completion instead of polling `ravion deploy get`:
+
+```bash
+ravion deploy wait <deployment-id> --watch --timeout 30m
+```
+
+`--watch` prints each status change as it happens, and the command exits non-zero if the deploy fails or is cancelled. Use `--until <status>` to return early on a specific status, such as `IN_PROGRESS`.
 
 ## Rollback, redeploy, cancel
 

modules/stack.mdx

@@ -142,7 +142,8 @@ ravion stack trigger-pipeline <stack-id> --pipeline-type change \
 ravion stack trigger-pipeline <stack-id> --pipeline-type change --autoapprove \
   --description "Apply infrastructure changes automatically"
 
-# Inspect Terraform runs and resources
+# Follow a run to completion, then inspect Terraform runs and resources
+ravion pipeline run wait <pipeline-run-id> --watch --timeout 30m
 ravion terraform execution-summary list --stack-id <stack-id>
 ravion pipeline run get-plan <pipeline-run-id>
 ravion pipeline run get-apply <pipeline-run-id>