docs: document native Lightdash YAML Git projects

[Spissable]

Related: https://linear.app/lightdash/issue/PROD-8670
Implementation: lightdash/lightdash#28831 (final PR in the merged native YAML stack)

Description

 Lightdash YAML project
- deploy local files through the CLI
+ also connect through GitHub, refresh models, and open write-back pull requests

Extend the existing Lightdash YAML page with repository layout, GitHub setup, upgrading an existing CLI connection, refresh, custom-field write-back, AI/Issues fixes, and supported limits. Update the connection, CLI, preview, agent, and MCP pages to use the same behavior and link to the canonical guidance. Keep dbt-specific workflows identified as dbt.

Release timing: keep this PR in draft until the native Git project functionality is released. No release version is assumed in the public copy.

Validation

• node scripts/docs/validate.ts: 0 errors.
• mintlify broken-links: no broken links; MDX parses.
• node scripts/docs/render-ia-map.ts --check: all 40 nodes annotated, no orphans.
• Extracted the documented configuration/model YAML, validated against the native model schema, and compiled successfully with the shared native compiler in strict mode. No warehouse queries or persisted test data.
• git diff --check: passed.
• Compared documented behavior with the merged Lightdash implementation. No browser preview or new screenshots.

Risk assessment

• This is a high-risk change

Documentation only. Existing pages and URLs are retained; renamed section anchors keep aliases. The draft must be merged after product availability so users can follow the GitHub instructions.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
lightdash	🟢 Ready	View Preview	Sep 9, 2026, 1:24 PM

[github-actions]

Documentation validation

✅ All blocking checks passed.

Component system

0 finding(s) across the corpus.

Findings on lines this pull request touched are annotated inline in Files changed.

Download the structured JSON artifact.