[databricks-dabs] Dashboard resource section omits sync.exclude, producing a duplicate dashboard on every deploy

[rob7thousand]

Problem or opportunity

The databricks-dabs skill documents the dashboards resource but omits the sync.exclude guidance that the Databricks reference docs prescribe for it. Following the skill as written leaves a duplicate dashboard in the workspace on every bundle deploy.

A .lvdash.json file in a workspace folder is a dashboard object, so a deploy creates two:

	Workspace path	Named after	Intended?
Resource copy	${workspace.resource_path}/<display-name>.lvdash.json	display_name	yes
Synced copy	${workspace.file_path}/src/dashboards/<file-name>.lvdash.json	source file name	no

Because the two are named differently - one from display_name, one from the file name - they are easy to misread as unrelated dashboards rather than a duplicate.

Three things make this hard to self-diagnose from the skills alone:

1. The skill never mentions sync. Grepping ^\s*sync: across all skill markdown returns zero hits, in databricks-dabs and databricks-aibi-dashboards alike.
2. The one official note is scoped to Git folders (see Additional context), so an agent that finds it can reasonably conclude it does not apply - and still ship duplicates.
3. The canonical example, databricks/bundle-examples/knowledge_base/dashboard_nyc_taxi, also omits it, which reinforces the wrong conclusion when cross-checking.

Proposed change

Document the duplicate-dashboard behavior and its remedy in the "Dashboard Resources" section, stated unconditionally rather than as a Git-folder-only concern:

sync:
  exclude:
    - src/*.lvdash.json

Ideally the section would also note:

• Relocating the source file within the bundle is not an alternative. The entire bundle root is synced, so any .lvdash.json in the bundle reaches ${workspace.file_path}. The resource copy is written outside the sync tree by design.
• The surface to verify on. databricks lakeview list gives a false negative here; workspace list / workspace get-status on the synced path show the duplicate within seconds.

Two smaller corrections in the same section, unrelated to the above:

1. It states dataset_catalog / dataset_schema support was "added in Databricks CLI 0.281.0 (January 2026)". The reference docs say 0.283.0 for both fields.
2. No round-trip guidance: UI edits do not flow back to the local file, and a deploy whose local JSON differs from the remote errors out rather than overwriting - it needs --force. The recovery path is databricks bundle generate dashboard --resource <name> (optionally --watch). Agents hit that deploy error without knowing why.

Affected skill or area

• databricks-dabs - references/bundle-structure.md, "Dashboard Resources" (~L67-80). Primary.
• databricks-aibi-dashboards - secondary; also never mentions sync, and is the skill most likely loaded when authoring a dashboard for a bundle.

Additional context

Reproduction

CLI v1.12.1. <files> = ${workspace.file_path}.

T0  exclusion present
    $ databricks workspace list <files>/src/dashboards
    Error: Path (...) doesn't exist.

    $ databricks bundle deploy          # with the exclusion commented out

T1  +7 seconds
    $ databricks workspace list <files>/src/dashboards
    ID           Type       Path
    <object-id>  DASHBOARD  <files>/src/dashboards/<name>.lvdash.json

    $ databricks workspace get-status <files>/src/dashboards/<name>.lvdash.json
    { "object_type": "DASHBOARD", "object_id": <object-id>, "resource_id": "<object-id>" }

T2  exclusion restored, redeploy
    $ databricks workspace list <files>/src/dashboards
    Error: Path (...) doesn't exist.
    # resource dashboard unaffected: ACTIVE, all widgets and datasets intact

Reproducible in both directions, on demand, within seconds. Excluding the file is safe: file_path is documented as the local path and the content is pushed via the Lakeview API, so the resource does not need the file present in the workspace tree.

Why lakeview list misleads

Immediately after the deploy above, the duplicate exists as a DASHBOARD object in the workspace tree, but lakeview list returned only the resource dashboard. In a separate run the file-backed dashboard did eventually surface there with its own 01f... id and a path pointing at the synced file, but well after the deploy. So the natural check - deploy, then lakeview list - can report success while the duplicate exists.

Scope: which resources are affected

We probed which extensions the workspace promotes to first-class objects by importing an identical dummy payload under different names and reading back object_type:

Extension	object_type
.lvdash.json	DASHBOARD
.geniespace.json	import rejected: Requested node type [UNKNOWN] is not supported
.alert.json	FILE
.dbquery.json	FILE
.json / .sql / .py	FILE

dashboard appears to be the only currently-affected resource. Notably alert also takes a file_path, but its synced file stays inert, so alerts are unaffected. Promotion is extension-based rather than content-based: a file named *.lvdash.json becomes a DASHBOARD even when its contents are {"a":1}.

.geniespace.json may be worth a look by someone with more context. The workspace clearly recognizes the extension - it attempted to resolve a node type and rejected it as unsupported, rather than treating it as a plain file - so genie_space (which takes file_path + serialized_space, structurally identical to dashboard) may have the same exposure in workspaces where that object type is enabled. We could not trigger it here.

On the docs' scoping

The bundle resources reference carries the note, but conditions it on Git folders:

When using Declarative Automation Bundles with dashboard Git support, prevent duplicate dashboards from being generated by adding the sync mapping...

We are not using dashboard Git support. databricks repos list returns 0 Git folders in this workspace, and the duplicate appears at the ordinary bundle deployment path, not under /Repos. It reproduces on a plain databricks bundle deploy. If that scoping is unintentional, the underlying docs may warrant the same broadening as the skill.