WIP Full audit and reorg to DRY, sustainable architecture by gwenwindflower · Pull Request #1057 · lightdash/mintlify-docs

gwenwindflower · 2026-07-29T00:40:38Z

Details, plan, and purpose are in ia-audit/ — summary artifact shared internally.

github-actions · 2026-07-29T00:40:59Z

🤖 Documentation Bot

Status

⚠️ 4 broken links need manual attention

🔗 Broken Links (Manual Fix Required)

Click to view details

   📄 ia-audit/_audit/report.mdx
   📄 ia-audit/ia-rules.mdx
   📄 ia-audit/reorg-plan.mdx
   📄 ia-audit/tree-map.mdx

mintlify · 2026-07-29T00:42:28Z

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

Project	Status	Preview	Updated (UTC)
lightdash	🟢 Ready	View Preview	Jul 29, 2026, 12:42 AM

Add simplified guidance with IA rules and audit exceptions system accessible specifically to mintlify agents

Delete the audit script, the logic has been expanded and ported out to a TypeScript-based tool in the Cloudy repo for use as a tool by docs management workflow agents

github-actions · 2026-07-31T06:26:39Z

🤖 Documentation Bot

Status

⚠️ 3 broken links need manual attention

🔗 Broken Links (Manual Fix Required)

Click to view details

   📄 ia-audit/_audit/report.mdx
   📄 ia-audit/reorg-plan.mdx
   📄 ia-audit/tree-map.mdx

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BCpRRE2XhnfPLRH1ZHmQiS

* move 176 pages into product-area directories per ia-audit/move-map.csv * declare doc-type frontmatter and sidebar pills on all typed pages * rebuild docs.json nav as root+card area groups in two tabs; 253 redirects * rewrite internal links and image paths to final URLs, relocate image dirs * fold merged pages wholesale into targets; add seven area landing pages Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BCpRRE2XhnfPLRH1ZHmQiS

* rewrite agents landing with one decision guide and comparison table (D11) * canonicalize dbt field-tagging in data-access; set-up-agents links (D6) * title MCP pages by call direction: external-in vs agents-out (D33) * trim ai_hint, verified-answers, evals restatements to links (D27) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BCpRRE2XhnfPLRH1ZHmQiS

* per-surface embed tutorials link setup and schema instead of restating (D30) * make react-sdk canonical for CORS; fix broken jwt-structure anchors * rewrite integrations/slack as one install-use-reference page (D15) * replace integrations landing card grid with orientation prose * snowflake-cortex links lightdash-mcp; fix docs-MCP endpoint command Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BCpRRE2XhnfPLRH1ZHmQiS

… dedup * rewrite timezones as setup tutorial + daily-use page from draft (D21) * extract shared impersonation mechanics to a snippet (D9) * scope sso landing, setup, and verified-domains to distinct jobs (D26) * drop deprecated okta-groups section; link scim provisioning (D32) * rewrite workspace-admin landing as governance orientation (D20) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BCpRRE2XhnfPLRH1ZHmQiS

* extract granularity-placeholder and delivery-destinations snippets (D4, D8) * correct alerts page to current Power Automate teams flow * sql-template recipes link their superseding native functions (D29) * spaces defers to canonical space-roles table (D25) * formatting walkthrough links format tables in field references (D1) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BCpRRE2XhnfPLRH1ZHmQiS

* extract shared strict-compilation flags to a snippet (D3) * split virtual-views and vs-code sections out of content-as-code (D14) * canonicalize ci secrets in set-up-ci-cd; compile and reference link (D24) * validate defers to validating-your-content for when validation runs (D23) * authenticate owns the token-login workaround; install links (D12) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BCpRRE2XhnfPLRH1ZHmQiS

* rewrite quickstart landing as the three-step golden path * frame both track landings as persona journeys linking forward (D36) * extract shared tables-intro to a snippet for both onboarding pages (D7) * rebuild help/support around the support-routing decision (D19) * introduction: plain-language framing and hosted MCP endpoint note (D34) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BCpRRE2XhnfPLRH1ZHmQiS

…ndex * extract per-feature env tables to snippets shared with the catalog (D5) * share the nats worker config block across both worker pages (D10) * unify versioning, upgrade mechanics, migration job, and rollback (D16) * make the production checklist a true index; facts live on their pages (D31) * apply scheduler 500m and NATS_ENABLED query-offload semantics; unpin browserless versions in prose Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BCpRRE2XhnfPLRH1ZHmQiS

* extract format, compact, and separator tables to a shared snippet (D1) * canonicalize the parameters schema; tables and config-yml link (D2) * caching owns the pre-aggregates comparison; the landing links (D22) * document group-level ai_hint in writing-descriptions (D27) * condense the dbt packages section to a current-state reference (D35) * rewrite the area landing as a short orientation Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BCpRRE2XhnfPLRH1ZHmQiS

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BCpRRE2XhnfPLRH1ZHmQiS

gwenwindflower · 2026-07-31T07:21:46Z

Needs engineering sign-off

Plausibility picks applied in this branch (fix in place if wrong):

Scheduler CPU: 500m (was stated as 1 in recommended-resources) — self-host/customize-deployment/scheduler, recommended-resources.
NATS_ENABLED = query-execution offload — env-var catalog row rewritten to match self-host/nats-workers.
Warehouse NATS worker CPU: 250m (checklist said 500m; worker config examples say 250m) — reconciled to 250m.
dbt Fusion: docs still underclaim ("not yet officially verified; dbt Core supported") pending confirmation.

Unresolved contradictions left as-is (need a ruling):

LIGHTDASH_CUSTOM_METRICS_CONFIG_PATH has two conflicting definitions — catalog says YAML config for catalog custom metrics; Prometheus page says JSON config for custom event counters. Same var, different format+purpose. Name collision or drift?
AI_AGENTS_ENABLED vs AI_COPILOT_ENABLED — enterprise-on-prem lists the former; the env-var catalog only documents the latter. Which is current?

Timezone items withheld from the shipped pages until confirmed shipped (from the draft's GLITCH markers):

wall_clock_timezone: per-column source-zone override — live pages say per-column override is not supported; draft said otherwise.
Connection Preview three-value output (raw / interpreted / project-rendered) — kept the simpler description.
${ldQueryTimezone} custom-SQL template variable — omitted.
Whether the profile Default timezone is admin-gated — kept ungated phrasing.

Also worth a glance: org-settings credentials nav label reconstructed as Organization settings → Credentials (source text was truncated mid-word).

…ctices' Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BCpRRE2XhnfPLRH1ZHmQiS

gwenwindflower added 2 commits July 28, 2026 19:37

chore(markdown): add basic markdownlint rules

a996032

docs: WIP audit and reorg plan

31c7998

github-actions Bot assigned gwenwindflower Jul 29, 2026

mintlify Bot deployed to staging July 29, 2026 00:42 View deployment

gwenwindflower added 5 commits July 31, 2026 01:20

chore(mintlify): add mintignore file

eb1a723

chore(agents): add .mcp.json with linear config

02dc59a

feat(mintlify): encode guidance system to .mintlify dir

3516c71

Add simplified guidance with IA rules and audit exceptions system accessible specifically to mintlify agents

chore(audit): move audit script out to cloudy tool

3e00d74

Delete the audit script, the logic has been expanded and ported out to a TypeScript-based tool in the Cloudy repo for use as a tool by docs management workflow agents

chore(audit): update reorg plan with setup and reconciliation

dbb4f88

mintlify Bot deployed to staging July 31, 2026 06:27 View deployment

gwenwindflower and others added 12 commits July 31, 2026 01:49

fix(scripts): skip mintignored files in link checker

656b059

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BCpRRE2XhnfPLRH1ZHmQiS

docs(readme): describe the product-area structure and snippet pattern

2548da9

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BCpRRE2XhnfPLRH1ZHmQiS

fix(docs): repoint cross-area anchor links to canonical headings

35d3e42

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BCpRRE2XhnfPLRH1ZHmQiS

style(semantic-layer): name sections for their content, not 'best pra…

4249d67

…ctices' Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BCpRRE2XhnfPLRH1ZHmQiS

mintlify Bot deployed to staging July 31, 2026 07:23 View deployment

mintlify Bot deployed to staging July 31, 2026 07:24 View deployment

chore(agents): update cloudy docs manager workflow

32a874e

chore(git): cleanup and add claude worktrees to gitignore

30e5f5c

mintlify Bot deployed to staging July 31, 2026 08:48 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

WIP Full audit and reorg to DRY, sustainable architecture - #1057

WIP Full audit and reorg to DRY, sustainable architecture#1057
gwenwindflower wants to merge 22 commits into
mainfrom
refactor/full-audit-reorg

gwenwindflower commented Jul 29, 2026

Uh oh!

github-actions Bot commented Jul 29, 2026 •

edited

Loading

Uh oh!

mintlify Bot commented Jul 29, 2026

Uh oh!

github-actions Bot commented Jul 31, 2026 •

edited

Loading

Uh oh!

gwenwindflower commented Jul 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

gwenwindflower commented Jul 29, 2026

Uh oh!

github-actions Bot commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Documentation Bot

Status

🔗 Broken Links (Manual Fix Required)

Uh oh!

mintlify Bot commented Jul 29, 2026

Uh oh!

github-actions Bot commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Documentation Bot

Status

🔗 Broken Links (Manual Fix Required)

Uh oh!

gwenwindflower commented Jul 31, 2026

Needs engineering sign-off

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

github-actions Bot commented Jul 29, 2026 •

edited

Loading

github-actions Bot commented Jul 31, 2026 •

edited

Loading