diff --git a/docs.json b/docs.json
index b9e38b50..b1855d7b 100644
--- a/docs.json
+++ b/docs.json
@@ -26,6 +26,7 @@
"get-started/setup-lightdash/get-project-lightdash-ready",
"get-started/setup-lightdash/connect-project",
"get-started/setup-lightdash/ssh-tunnel",
+ "get-started/setup-lightdash/migrating-from-other-bi-tools",
"get-started/setup-lightdash/invite-new-users"
]
}
diff --git a/get-started/setup-lightdash/migrating-from-other-bi-tools.mdx b/get-started/setup-lightdash/migrating-from-other-bi-tools.mdx
new file mode 100644
index 00000000..9a077b60
--- /dev/null
+++ b/get-started/setup-lightdash/migrating-from-other-bi-tools.mdx
@@ -0,0 +1,229 @@
+---
+title: "Migrating from another BI tool"
+description: "A step-by-step process for moving reports, dashboards, and modeling logic from an existing BI tool (Looker, Tableau, Power BI, Metabase, Mode, and others) into Lightdash."
+sidebarTitle: Migrate from another BI tool
+icon: right-left
+---
+
+Use this guide when you're replacing an existing BI tool with Lightdash. It works for any source tool — Looker, Tableau, Power BI, Metabase, Mode, Sigma, or an in-house solution — because the process is the same: extract what you have, translate the modeling into Lightdash YAML or dbt, and rebuild the dashboards on top of your new semantic layer.
+
+The steps below are designed to be followed in order. You'll do most of the modeling work with an AI coding agent (Claude Code, Cursor, or Codex) using Lightdash skills, and finish by rebuilding the dashboards visually in Lightdash.
+
+
+ Before you start, make sure you have:
+ - A Lightdash project connected to your warehouse. See [Setting up a new project](/get-started/setup-lightdash/intro).
+ - Admin (or export-equivalent) access to the BI tool you're migrating from.
+ - A dbt project (or an empty repo where one will live) connected to the same warehouse.
+
+
+## 1. Install the Lightdash CLI and skills
+
+The AI-assisted path is by far the fastest way to migrate. Install the CLI and skills first so your coding agent knows how to write Lightdash YAML, metrics, and dashboards correctly.
+
+
+
+ Follow the [CLI installation guide](/guides/cli/how-to-install-the-lightdash-cli) and [authenticate](/guides/cli/cli-authentication) against your Lightdash project.
+
+
+
+ Run this from your dbt or YAML project root:
+
+ ```bash
+ lightdash install-skills
+ ```
+
+ This installs skills into `.claude/skills/` (also read by GitHub Copilot). For Cursor or Codex, pass `--agent cursor` or `--agent codex`. To share across projects, add `--global`. See [Agent skills](/guides/developer/agent-skills) for all options.
+
+
+
+ In Claude Code, prefix migration prompts with `/developing-in-lightdash` so the agent uses the Lightdash context. Cursor and Codex pick the skills up automatically.
+
+
+
+## 2. Set up your migration workspace
+
+Before touching your source BI tool, get a clean workspace ready to receive the migrated content.
+
+
+
+ Work on a branch (for example `migration/from-looker`) so you can iterate without affecting production models.
+
+
+
+ Use a [preview project](/guides/developer/preview-projects) or a separate development project so the migrated content is isolated until you're ready to promote it. This gives you a safe place to validate metrics against the source tool.
+
+
+
+ In the repo, add a folder like `migration/source/` to hold everything you export from the source tool (LookML, `.twb` files, `.pbix` unpacks, question JSON, screenshots). Your agent will read from this folder.
+
+
+
+## 3. Extract your source information
+
+Pull every piece of information out of the source BI tool that Lightdash will need to rebuild the reports. What you extract depends on the tool, but the goal is the same: capture the modeling logic, the queries, and the visual layout.
+
+Choose the option that matches your source tool. If more than one applies, do them all — the more source material your agent has, the better the translation.
+
+### Modeling logic as code
+
+If the source tool stores modeling logic in files, export those files first. This is the highest-signal input for the migration.
+
+- **Looker** — clone the LookML project (`.lkml`, `.view.lkml`, `.model.lkml`, `.dashboard.lookml`).
+- **dbt-based tools** (Metabase Metrics Layer, Mode with dbt) — you already have the source; note which models are actually used by the reports.
+- **Sigma / Hex / Omni** — export workbook or dataset definitions as JSON or YAML where the tool supports it.
+
+Copy the files into `migration/source/` in your repo.
+
+### Workbooks and reports as files
+
+If the source tool stores reports as binary or archive files, unpack them so the agent can read the SQL and field definitions.
+
+- **Tableau** — save workbooks as `.twbx` (packaged) then unzip to expose the underlying `.twb` XML. The XML contains data source definitions, calculated fields, filters, and worksheet layouts.
+- **Power BI** — export `.pbix` files and unpack them (for example with a `.pbix` viewer or `pbi-tools`) to extract the data model, DAX measures, and report layout as JSON/XML.
+- **Mode / Metabase / Redash** — export questions or reports as SQL. Group them by dashboard so you know which queries feed which report.
+
+Put the extracted files under `migration/source//`.
+
+### API extraction
+
+For SaaS BI tools without a file export, pull the definitions through the API. This is usually the best route when there are hundreds of reports and manual export isn't practical.
+
+- **Looker** — [Looker API](https://cloud.google.com/looker/docs/reference/looker-api/latest) endpoints for `looks`, `dashboards`, and `queries`.
+- **Tableau** — [Metadata API](https://help.tableau.com/current/api/metadata_api/en-us/index.html) for workbooks, data sources, calculated fields, and lineage.
+- **Power BI** — [REST API](https://learn.microsoft.com/en-us/rest/api/power-bi/) for datasets, reports, and DAX definitions.
+- **Metabase** — `/api/card` and `/api/dashboard` for questions and dashboards.
+- **Mode** — `/api/{workspace}/reports` for reports and their queries.
+
+Write a small script to dump the responses to JSON in `migration/source/api/`. Include the raw SQL, field definitions, filters, and any joins.
+
+### Direct SQL
+
+For everything else — bespoke reports, undocumented queries, ad-hoc dashboards — capture the executed SQL. Query your warehouse's query history (Snowflake `QUERY_HISTORY`, BigQuery `INFORMATION_SCHEMA.JOBS`, Redshift `STL_QUERY`) filtered to the BI tool's service user to see what actually runs in production. Save the top queries by frequency into `migration/source/sql/`.
+
+## 4. Take screenshots of the source dashboards
+
+Screenshots are the reference for rebuilding the visual layer. Your coding agent can't see the source tool, so it needs the images to match layout, chart types, and filter positions.
+
+
+
+ Take a full-page screenshot of every dashboard you're migrating. Include the filters, tab structure, and any drilldowns.
+
+
+
+ For complex visualizations (custom colors, conditional formatting, mixed chart types), take a zoomed-in screenshot too. Also grab the underlying query where the source tool exposes it.
+
+
+
+ Save them under `migration/source/screenshots/`, named by dashboard. Reference them in your prompts so the agent uses them when rebuilding layouts.
+
+
+
+## 5. Translate the modeling into Lightdash
+
+With everything extracted, use your coding agent to translate the source modeling into Lightdash's semantic layer. Do this in passes — models first, then metrics, then joins — rather than all at once.
+
+
+
+ Point the agent at both the source files and your warehouse schema. For example:
+
+ ```
+ /developing-in-lightdash
+
+ Read the LookML files under migration/source/looker/ and profile the
+ corresponding tables in our warehouse. For each Looker view that
+ underlies a dashboard in migration/source/screenshots/, propose a
+ Lightdash model with matching dimensions and metrics. Do not create
+ files yet — list the models and metrics you plan to create.
+ ```
+
+ Review the plan before letting it write files.
+
+
+
+ Ask the agent to write the Lightdash YAML (or dbt `meta` tags) for one source at a time. See [Lightdash YAML](/guides/lightdash-yaml) for the format. After each file, run:
+
+ ```bash
+ lightdash lint
+ ```
+
+ Fix errors before moving on.
+
+
+
+ Map source metric types to Lightdash [metric types](/references/metrics). Common mappings:
+
+ | Source | Lightdash |
+ | ------------------------------ | ------------------------------------------------------------ |
+ | Looker `measure: sum` | `type: sum` metric |
+ | Looker `measure: count_distinct` | `type: count_distinct` metric |
+ | Tableau calculated field (agg) | Lightdash metric with `sql` |
+ | Power BI DAX `SUMX` / `CALCULATE` | Lightdash metric, or a dbt column plus a `sum` metric |
+ | Metabase custom expression | Lightdash metric with `sql`, or a [table calculation](/guides/table-calculations) if it's row-level |
+
+ Ask the agent to add descriptions and categories so the migrated fields land in the [metrics catalog](/guides/metrics-catalog) cleanly.
+
+
+
+ Translate source joins to Lightdash [joins](/references/joins). Specify the relationship (`one-to-many`, `many-to-one`, `one-to-one`) — this is what unlocks correct fan-out handling.
+
+
+
+ ```bash
+ lightdash deploy
+ ```
+
+ Then run [`lightdash validate`](/guides/cli/how-to-use-lightdash-validate) to catch broken references.
+
+
+
+## 6. Rebuild the dashboards
+
+With the semantic layer in place, rebuild the dashboards on top of it.
+
+
+
+ Open each source dashboard screenshot side by side with Lightdash. For each chart, build the equivalent in Lightdash using the migrated metrics and dimensions. See [Configuring your charts](/guides/configure-charts) and the [chart types reference](/references/chart-types/overview).
+
+ If you'd rather do this conversationally, ask your agent to build the dashboards for you — it can generate [dashboards as code](/guides/developer/dashboards-as-code) from the screenshots and the migrated models.
+
+
+
+ Recreate the source dashboard's filter set with [dashboard filters](/guides/filters) and multi-tab layouts. Match the visual grouping from the screenshots.
+
+
+
+ For every migrated dashboard, run the same query in the source tool and in Lightdash and compare the results. Any mismatch usually points to:
+
+ - A missing or mismapped join
+ - A different aggregation type
+ - A silent filter in the source tool (default date range, hidden user filter)
+ - A timezone difference — see [Working with timezones](/guides/developer/timezones)
+
+ Do this before you cut anyone over.
+
+
+
+## 7. Layer in best practices and the customer's own conventions
+
+Once the content works, take a pass to align it with Lightdash conventions and any modeling standards the team already follows.
+
+- **Follow Lightdash's modeling guidance.** Read [dbt model best practices for Lightdash](/guides/developer/dbt-model-best-practices) and apply it: name fields consistently, keep grain explicit, use pre-aggregates where warranted.
+- **Apply the customer's own style guide.** If the team has a metric naming convention, category structure, or documentation standard, feed that into the agent as extra context so the migrated fields match. Skills read anything in the project — a `MODELING_GUIDE.md` at the repo root is often enough.
+- **Write good descriptions.** See [Writing descriptions](/references/writing-descriptions). Migrations are the best time to fix the descriptions that never got written in the source tool.
+- **Verify canonical content.** Mark the migrated dashboards and charts as [verified content](/guides/verified-content) so users know which reports are the source of truth going forward.
+- **Set up promotion.** Once validated in preview, use [content promotion](/guides/how-to-promote-content) to move dashboards to production.
+- **Plan the cutover.** Announce a date, keep the source tool read-only for a defined grace period, and use [scheduled deliveries](/guides/how-to-create-scheduled-deliveries) to replace any recurring exports from the old tool.
+
+## Common pitfalls
+
+- **Migrating everything.** Most BI tools carry hundreds of stale reports. Use warehouse query history to see what's actually used, and migrate that subset first.
+- **Trying to match the old tool 1:1.** Lightdash's metric definitions are reusable across charts. Consolidate duplicates instead of copying every one-off calculated field.
+- **Skipping joins.** LookML `explores` and Tableau data sources bake in joins that aren't obvious from the SQL. Read the model definitions, not just the queries.
+- **Forgetting user attributes and access.** Row-level filters and user attributes from the source tool need to be re-modeled with Lightdash [user attributes](/references/workspace/user-attributes).
+
+## Next steps
+
+- [Install Lightdash skills](/get-started/develop-in-lightdash/install-skills)
+- [Lightdash YAML](/guides/lightdash-yaml)
+- [dbt model best practices for Lightdash](/guides/developer/dbt-model-best-practices)
+- [Dashboards as code](/guides/developer/dashboards-as-code)