Updated docs to add section on fail-over to production and staging ennvironment / resolve refs in dowstream projects

website/docs/docs/collaborate/govern/project-dependencies.md

@@ -21,6 +21,7 @@ This year, dbt Labs is introducing an expanded notion of `dependencies` across m
 - Use a supported version of dbt (v1.6, v1.7, or go versionless with "[Versionless](/docs/dbt-versions/upgrade-dbt-version-in-cloud#versionless)") for both the upstream ("producer") project and the downstream ("consumer") project.
 - Define models in an upstream ("producer") project that are configured with [`access: public`](/reference/resource-configs/access). You need at least one successful job run after defining their `access`.
 - Define a deployment environment in the upstream ("producer") project [that is set to be your Production environment](/docs/deploy/deploy-environments#set-as-production-environment), and ensure it has at least one successful job run in that environment.
+- If the upstream project has a Staging environment, run a job in that Staging environment to ensure the downstream cross-project ref resolves.
 - Each project `name` must be unique in your dbt Cloud account. For example, if you have a dbt project (codebase) for the `jaffle_marketing` team, you should not create separate projects for `Jaffle Marketing - Dev` and `Jaffle Marketing - Prod`. That isolation should instead be handled at the environment level.
   - We are adding support for environment-level permissions and data warehouse connections; please contact your dbt Labs account team for beta access.
 - The `dbt_project.yml` file is case-sensitive, which means the project name must exactly match the name in your `dependencies.yml`.  For example, if your project name is `jaffle_marketing`, you should use `jaffle_marketing` (not `JAFFLE_MARKETING`) in all related files.
@@ -110,7 +111,10 @@ Read [Why use a staging environment](/docs/deploy/deploy-environments#why-use-a-
 
 #### Staging with downstream dependencies
 
-dbt Cloud begins using the Staging environment to resolve cross-project references from downstream projects as soon as it exists in a project without "fail-over" to Production. To avoid causing downtime for downstream developers, you should define and trigger a job before marking the environment as Staging:
+dbt Cloud begins using the Staging environment to resolve cross-project references from downstream projects as soon as it exists in a project without "fail-over" to Production. This means that dbt Cloud will consistently use metadata from the Staging environment to resolve references in downstream projects, even if there haven't been any successful runs in the configured Staging environment. 
+
+To avoid causing downtime for downstream developers, you should define and trigger a job before marking the environment as Staging:
+
 1. Create a new environment, but do NOT mark it as **Staging**.
 2. Define a job in that environment.
 3. Trigger the job to run, and ensure it completes successfully.

website/docs/guides/mesh-qs.md

@@ -300,6 +300,8 @@ To run your first deployment dbt Cloud job, you will need to create a new dbt Cl
 
 5. After the run is complete, click **Explore** from the upper menu bar. You should now see your lineage, tests, and documentation coming through successfully.
 
+For details on how dbt Cloud uses metadata from the Staging environment to resolve references in downstream projects, check out the section on [Staging with downstream dependencies](/docs/collaborate/govern/project-dependencies#staging-with-downstream-dependencies).
+
 ## Reference a public model in your downstream project
 
 In this section, you will set up the downstream project, "Jaffle | Finance", and [cross-project reference](/docs/collaborate/govern/project-dependencies) the `fct_orders` model from the foundational project. Navigate to the **Develop** page to set up our project: