diff --git a/references/integrations/dbt-projects.mdx b/references/integrations/dbt-projects.mdx
index cbedc673..5f10f985 100644
--- a/references/integrations/dbt-projects.mdx
+++ b/references/integrations/dbt-projects.mdx
@@ -121,6 +121,22 @@ For ready-to-use workflow templates, see the [`lightdash/cli-actions`](https://g
   </Accordion>
 </AccordionGroup>
 
+### `lightdash deploy` vs `lightdash refresh`
+
+The two CLI commands above (`lightdash deploy` and `lightdash refresh`) are often confused. Here's the quick difference:
+
+| | `lightdash deploy` | `lightdash refresh` |
+| --- | --- | --- |
+| **What it does** | Pushes your local dbt project to a Lightdash project. Runs `dbt compile` (or `dbt list`) locally to produce a fresh `manifest.json`, then sends the compiled models/explores to the Lightdash server. | Tells the Lightdash server to re-pull from the connected git remote and recompile, server-side. No local dbt run, no local files involved — it's the API-driven equivalent of clicking **Refresh dbt** in the UI. |
+| **Where compilation happens** | Locally (laptop or CI runner) | Lightdash servers |
+| **Requires a remote git connection?** | No | Yes |
+| **Flags** | Many (`--project`, `--select`, `--full-refresh`, `--create`, `--use-batched-deploy`, etc.) | Essentially none (just `--verbose`) |
+| **Use when** | You've changed dbt models or Lightdash YAML metadata locally and want those changes to land in a Lightdash project. | Lightdash already points at a git repo and you just want it to pull the latest. |
+
+**Rule of thumb:**
+- Local dbt code you want to push → `deploy`
+- Lightdash already points at a git repo and you just want it to pull the latest → `refresh`
+
 ### Decision matrix
 
 |                                       | #1 `lightdash deploy` — local CLI | #2 `lightdash deploy` — CI | #3 "Refresh dbt" — UI button | #4 `lightdash refresh` — CI | #5 `POST /refresh` API — CI |