lightdash · sdolidze · Sep 9, 2026 · Sep 9, 2026
diff --git a/agents/ai-writeback.mdx b/agents/ai-writeback.mdx
@@ -30,14 +30,14 @@ For other kinds of changes, the agent will pick a different tool:
 
 ## Prerequisites
 
-- Use a supported repository connection: **GitHub**, **GitLab.com**, or **Bitbucket Cloud** for dbt; **GitHub** for native Lightdash YAML. Azure DevOps, dbt Cloud, and CLI-only connections are not supported for AI writeback.
+- Use a supported repository connection: **GitHub**, **GitLab.com**, or **Bitbucket Cloud** for dbt; **GitHub** or **Bitbucket Cloud** for native Lightdash YAML. Azure DevOps, dbt Cloud, and CLI-only connections are not supported for AI writeback.
 - Configure repository access so the agent can open requests:
   - **GitHub** — install the Lightdash GitHub App on the repository.
   - **GitLab** — connect the Lightdash GitLab App for your organization. Writeback works against GitLab.com; self-hosted GitLab domains aren't reachable from the writeback sandbox yet.
   - **Bitbucket Cloud** — configure the [project API token and writeback permissions](/get-started/quickstart/connect-project#bitbucket-cloud-api-token).
 - You need at least [project Developer](/workspace-admin/roles) permissions on the project.
 
-For native projects, follow [Connect through GitHub](/semantic-layer/yaml#connect-through-github) and select **Native Lightdash YAML** as the semantic layer format.
+For native projects, follow [Connect through GitHub or Bitbucket Cloud](/semantic-layer/yaml#connect-through-github) and select **Native Lightdash YAML** as the semantic layer format.
 
 ## How it works
 
@@ -63,9 +63,9 @@ If you're driving writeback from an external client via MCP rather than the in-p
 
 ### Bitbucket Cloud behavior
 
-Bitbucket AI writeback edits the connected dbt repository. Follow-up requests can add commits to the same open pull request. If that request has been merged or declined, a follow-up starts a fresh pull request.
+Bitbucket AI writeback edits dbt or native Lightdash YAML files in the connected repository. Follow-up requests can add commits to the same open pull request. If that request has been merged or declined, a follow-up starts a fresh pull request.
 
-Review and merge Bitbucket pull requests in Bitbucket, then sync the project in Lightdash. The integration does not provide automatic preview projects, Bitbucket Pipelines status, or merging from the chat card. Repository browsing and file mentions have separate provider requirements, described below. Standalone Lightdash YAML projects, Bitbucket Server/Data Center, and general-purpose coding-agent access are outside this Bitbucket integration.
+Review and merge Bitbucket pull requests in Bitbucket, then sync the project in Lightdash. The integration does not provide automatic preview projects, Bitbucket Pipelines status, or merging from the chat card. Repository browsing and file mentions have separate provider requirements, described below. Bitbucket Server/Data Center and general-purpose coding-agent access are outside this Bitbucket integration.
 
 ## Using it in chat
 

diff --git a/get-started/quickstart/connect-project.mdx b/get-started/quickstart/connect-project.mdx
@@ -1485,7 +1485,7 @@ If your dbt project is in a sub-folder in your repo (e.g. `lightdash/lightdash-a
 
 ### Bitbucket
 
-Connect a dbt repository on Bitbucket using the project's **API Token** field. Choose **Bitbucket** in your project's connection settings.
+Connect a dbt or native Lightdash YAML repository on Bitbucket Cloud using the project's **API Token** field. Choose **Bitbucket** in your project's connection settings.
 
 #### Bitbucket Cloud API token
 
@@ -1509,18 +1509,19 @@ The token's owner must have access to the repository and permission to push bran
 
 #### Connection fields
 
+- **Semantic layer format:** choose **dbt** or **Native Lightdash YAML**. For native setup and repository layout, see [Connect through GitHub or Bitbucket Cloud](/semantic-layer/yaml#connect-through-github).
 - **Username:** your Bitbucket username, with the exact capitalization shown in your Bitbucket personal settings. Use the username, not your email address.
 - **API Token:** the token created above.
 - **Repository:** the workspace and repository slug, such as `my-workspace/analytics`. Do not enter the full URL.
 - **Branch:** the branch Lightdash syncs from, such as `main`. Writeback opens a separate change branch and targets this configured branch.
-- **Project directory path:** `/` if `dbt_project.yml` is at the repository root, or a subfolder such as `/dbt` if it lives at `dbt/dbt_project.yml`.
-- **Host domain:** leave blank for Bitbucket Cloud, or use `bitbucket.org`.
+- **Project directory path:** the directory containing `dbt_project.yml` for dbt, or `lightdash.config.yml` and your model directory for native YAML. Use `/` for the repository root.
+- **Host domain:** for dbt, leave blank for Bitbucket Cloud or use `bitbucket.org`. Native YAML uses `bitbucket.org` automatically and hides this field.
 
 <Frame>
   <img src="/images/get-started/quickstart/connect-project/bitbucket-connection.png" alt="Bitbucket connection fields showing the username, required API token permissions, and repository slug" />
 </Frame>
 
-Save the connection and complete the [dbt project settings](/integrations/dbt/projects#dbt-project-settings). For the available writeback actions, see [dbt write-back](/integrations/dbt/write-back) and [AI writeback](/agents/ai-writeback).
+Save the connection. For dbt, complete the [dbt project settings](/integrations/dbt/projects#dbt-project-settings). For the available writeback actions, see [dbt write-back](/integrations/dbt/write-back) and [AI writeback](/agents/ai-writeback).
 
 #### Updating credentials
 

diff --git a/integrations/dbt/write-back.mdx b/integrations/dbt/write-back.mdx
@@ -14,7 +14,7 @@ For a project using standalone YAML, see [Lightdash YAML write-back](/semantic-l
 
 Connect your project using the [Bitbucket token setup instructions](/get-started/quickstart/connect-project#bitbucket-cloud-api-token). All three workflows below use that stored project token and the configured repository, branch, and dbt directory.
 
-Bitbucket support covers dbt projects on `bitbucket.org`. Standalone Lightdash YAML projects and Bitbucket Server/Data Center are not supported by this Bitbucket writeback integration. Review and merge the pull request in Bitbucket, then sync the project in Lightdash. Writeback does not run your dbt models, display Bitbucket Pipelines status, or create an automatic preview project.
+Bitbucket support covers dbt projects on `bitbucket.org`. These UI workflows do not support standalone Lightdash YAML on Bitbucket or Bitbucket Server/Data Center. For native YAML on Bitbucket Cloud, use [AI writeback](/agents/ai-writeback#bitbucket-cloud-behavior). Review and merge the pull request in Bitbucket, then sync the project in Lightdash. Writeback does not run your dbt models, display Bitbucket Pipelines status, or create an automatic preview project.
 
 ## Write back Metrics from Custom Metrics
 

diff --git a/self-host/enterprise-features/ai-writeback.mdx b/self-host/enterprise-features/ai-writeback.mdx
@@ -7,18 +7,16 @@ description: "Enable AI writeback on a self-hosted Lightdash instance"
   <Badge icon="building-plus" color="blue" size="sm" shape="pill">Enterprise</Badge> AI writeback needs a valid `LIGHTDASH_LICENSE_KEY` set on your instance ([enterprise features](/self-host/enterprise-features) covers applying the key) before any of the configuration below takes effect.
 </Info>
 
-AI writeback lets an AI agent edit the dbt repository that backs a project and open a pull request (GitHub) or merge request (GitLab) with the change. The edits run inside an isolated [sandbox](/self-host/customize-deployment/sandboxes) where a Claude-driven agent applies the diff, runs `lightdash compile` to validate, and pushes a new branch. To enable the feature on a self-hosted Lightdash instance you need a configured sandbox provider, an Anthropic API key, and the matching Lightdash git app connected to the repositories you want writeback against.
+AI writeback lets an AI agent edit the semantic layer repository that backs a project and open a pull request with the change. The edits run inside an isolated [sandbox](/self-host/customize-deployment/sandboxes). Validation depends on the project format; see [how AI writeback works](/agents/ai-writeback#how-it-works). To enable the feature on a self-hosted Lightdash instance you need a configured sandbox provider, an Anthropic API key, and repository access.
 
 For an overview of what the feature does and how to use it in chat, see [AI writeback](/agents/ai-writeback).
 
 ## Prerequisites
 
 - **Enterprise license** — `LIGHTDASH_LICENSE_KEY` must be set on your instance.
-- **A configured sandbox provider** — see [sandboxes](/self-host/customize-deployment/sandboxes). The writeback agent edits files and runs `lightdash compile` there.
+- **A configured sandbox provider** — see [sandboxes](/self-host/customize-deployment/sandboxes). The writeback agent edits files there.
 - **An Anthropic API key** — sign up at [console.anthropic.com](https://console.anthropic.com/) and create an API key. Claude is the model that drives the writeback agent.
-- **A supported git host** — each project that should support writeback must be connected to a **GitHub** or **GitLab** repository (Bitbucket, Azure DevOps, dbt Cloud, and local dbt projects are not supported), with the matching Lightdash app installed:
-  - **GitHub** — install the Lightdash GitHub App on the repository.
-  - **GitLab** — connect the Lightdash GitLab App for your organization. Writeback works against GitLab.com; self-hosted GitLab domains aren't reachable from the writeback sandbox yet.
+- **Repository access** — configure a supported provider and semantic layer format using the [AI writeback prerequisites](/agents/ai-writeback#prerequisites).
 
 ## Configuration
 
@@ -29,7 +27,7 @@ Add the following environment variables to your Lightdash deployment:
 | `E2B_AI_WRITEBACK_TEMPLATE_NAME` | `lightdash/lightdash-ai-writeback` | Lightdash's public E2B template for writeback — pulls our prebuilt sandbox image so you don't have to build one yourself. The `lightdash/` prefix points at our public team template; without it E2B looks in your own team and won't find the image. |
 | `ANTHROPIC_API_KEY` | `<your-anthropic-api-key>` | Your [Anthropic](https://console.anthropic.com/) API key. Claude is the model that drives the writeback agent. |
 
-Restart the backend. Users with AI Analyst access on a project connected to a supported git host will see the agent offer to open a pull request when they ask for a change that belongs in the dbt repo.
+Restart the backend. Users with AI Analyst access on a project connected to a supported git host will see the agent offer to open a pull request when they ask for a change that belongs in the semantic layer repo.
 
 ### Optional configuration
 
@@ -39,6 +37,8 @@ Restart the backend. Users with AI Analyst access on a project connected to a su
 
 ## Supported dbt versions
 
+This section applies to dbt projects. Native Lightdash YAML uses [native validation](/semantic-layer/yaml#ai-writeback-and-issues) and needs no dbt installation.
+
 The writeback sandbox runs `lightdash compile` using the dbt version configured on the project, so validation behaves the same way it would locally. The sandbox ships with dbt **1.8, 1.9, 1.10, 1.11, and 1.12** preinstalled:
 
 - Projects pinned to one of those versions compile against that exact version.
@@ -58,15 +58,16 @@ Both providers expose usage dashboards. We recommend setting spend limits on bot
 
 ## Permissions
 
-AI writeback is gated by the user's project role. Anyone asking the agent to open a pull request needs at least [project Developer](/workspace-admin/roles) permissions on the project the agent is connected to. The git commits themselves are made by the installed Lightdash app, not by the end user:
+AI writeback is gated by the user's project role. Anyone asking the agent to open a pull request needs at least [project Developer](/workspace-admin/roles) permissions on the project the agent is connected to. Git authentication depends on the provider:
 
 - **GitHub** commits are signed by the Lightdash GitHub App.
 - **GitLab** commits are pushed over OAuth and are unsigned.
+- **Bitbucket Cloud** uses the [project API token owner's identity](/get-started/quickstart/connect-project#bitbucket-cloud-api-token).
 
 ## Troubleshooting
 
 **The agent never offers to open a pull request.**
-Check that `LIGHTDASH_LICENSE_KEY` is set and the project's dbt connection is GitHub or GitLab with the matching Lightdash app installed.
+Check that `LIGHTDASH_LICENSE_KEY` is set and the project meets the [repository and permission prerequisites](/agents/ai-writeback#prerequisites).
 
 **Writebacks fail immediately with a sandbox creation error.**
 Check your [sandbox provider's](/self-host/customize-deployment/sandboxes) credentials, and verify `E2B_AI_WRITEBACK_TEMPLATE_NAME` is set to `lightdash/lightdash-ai-writeback` (the `lightdash/` prefix is required to pull our public template — a bare name resolves to your own team). If you've overridden `E2B_AI_WRITEBACK_TEMPLATE_TAG`, double-check the tag exists.