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

[devin-ai-integration]

Summary

Agent feedback: following config-as-code/project-config-file.mdx literally led an agent to poll ravion pipeline run get in a loop, because the docs never mentioned pipeline run wait --watch. This rewrites the run-review guidance so waiting is the documented default, and adds the agent rule that would have changed that behavior:

After applying config, use ravion pipeline run wait <id> --watch instead of repeatedly polling pipeline run get.

Changed pages:

• config-as-code/project-config-file.mdx — review step now leads with wait --watch --timeout 30m, then get-plan/get-apply; separate manual-approval flow (--until PENDING_APPROVAL → get-plan → approve → wait); new agent rule plus a "don't poll in a loop" entry.
• modules/stack.mdx, modules/build.mdx, migrate/import-into-*.mdx — same wait-first ordering where they previously showed get polling.
• modules/deploy.mdx — documents the new ravion deploy wait <deployment-id> --watch, which did not exist before (the deploy namespace had no wait equivalent, so agents fell back to deploy get polling).

cli/reference/* and cli/overview.mdx are regenerated from the CLI source by make docs in packages/cli (companion PR in flightcontrol): new ravion deploy wait page section, examples/long help for pipeline run wait/get/get-plan/get-apply, and the flightcontrolhq → ravionhq install URLs that had drifted from the generator. og:image frontmatter was re-synced with pnpm sync:og-images.

Link to Devin session: https://app.devin.ai/sessions/daa0ed23475843dca66cf50223f6387f
Requested by: @flybayer

Greptile Summary

The PR replaces polling guidance with wait --watch, documents the new deployment wait command, and updates generated CLI installation links. The primary config-review example waits for completion before a manually gated run can be inspected and approved, and the new installation organization conflicts with other canonical installation pages.

• Adds wait-first pipeline and deployment monitoring examples.
• Separates a manual-approval pipeline workflow in the project-config guide.
• Expands generated CLI command descriptions and examples.
• Changes the overview’s GitHub release and Homebrew tap organizations.

Confidence Score: 4/5

The documentation should not merge until the default manual-approval workflow is reordered so users can inspect and approve the plan before waiting for completion.

The documented config apply defaults to a manually gated run, but the primary review sequence waits for terminal completion first and therefore stalls at PENDING_APPROVAL until timeout; the installation organization is also inconsistent across linked pages.

Files Needing Attention: config-as-code/project-config-file.mdx, modules/stack.mdx, cli/overview.mdx

Important Files Changed

Filename	Overview
config-as-code/project-config-file.mdx	Adds wait-first and manual-approval guidance, but the general example blocks at the default manual approval gate before plan inspection.
cli/reference/pipeline.mdx	Clarifies snapshot versus wait behavior and adds examples for completion and approval-gate waiting.
cli/reference/deploy.mdx	Documents the new deploy wait command, its flags, examples, and terminal failure behavior.
cli/overview.mdx	Changes installation commands to ravionhq, creating a non-blocking inconsistency with the linked installation and getting-started pages.
modules/deploy.mdx	Replaces deploy polling guidance with the new streaming wait command.
modules/stack.mdx	Adds terminal waiting before Terraform inspection, which also needs approval-aware qualification for manually gated runs.

Prompt To Fix All With AI

### Issue 1
config-as-code/project-config-file.mdx:124
**Terminal wait blocks approval flow**

When a config apply starts a Terraform run without `--autoapprove`, this command waits for terminal completion while the run is paused at `PENDING_APPROVAL`, causing the documented `get-plan` and approval workflow to stall until the 30-minute timeout.

### Issue 2
cli/overview.mdx:18-24
**Installation organizations are inconsistent**

These commands use `ravionhq`, while the linked Installation page and getting-started guide still use `flightcontrolhq` for the same release repository and Homebrew tap, leaving readers with conflicting canonical installation commands.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "docs: lead with wait --watch workflows f..." | Re-trigger Greptile}

Greptile also left 2 inline comments on this PR.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Ravion	🟢 Ready	View Preview	Aug 10, 2026, 7:34 PM

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[greptile-apps]

Installation organizations are inconsistent

These commands use ravionhq, while the linked Installation page and getting-started guide still use flightcontrolhq for the same release repository and Homebrew tap, leaving readers with conflicting canonical installation commands.

Prompt To Fix With AI

This is a comment left during a code review.
Path: cli/overview.mdx
Line: 18-24

Comment:
**Installation organizations are inconsistent**

These commands use `ravionhq`, while the linked Installation page and getting-started guide still use `flightcontrolhq` for the same release repository and Homebrew tap, leaving readers with conflicting canonical installation commands.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[flybayer]

the cli reference files are generated from main repo and need updated there

[devin-ai-integration]

Right — dropped cli/reference/* and cli/overview.mdx from this PR. The help/example changes they came from live in ravionhq/flightcontrol#6894, and cli-release.yml regenerates them into this repo on the next CLI release. This PR is now hand-written pages only.