docs(destination-motherduck): Update destination documentation

[devin-ai-integration]

Triggering Context

Run triggered by: Automated Connector Docs Playbook run after the merged destination-motherduck bug fix.

Relevant context: Source commit cd2e3b3, merged through PR #81511.

Confidence impact: The small, merged bug fix provided a clear connector and concrete behavior to review, supporting a Triggering Context score of 5/5.

Documentation Confidence Assessment

Overall Confidence: 3/5

Dimension	Score	Rationale
Code Comprehension	2/5	This Python CDK destination has about 1,000 lines across custom buffering and SQL processor modules, although the documented behaviors were directly traceable.
API Documentation Quality	5/5	MotherDuck provides comprehensive official documentation for connections, token types, service accounts, resource ownership, status, and client-version lifecycle.
Change Scope & Risk	3/5	The 129-line diff moderately restructures setup guidance, corrects limitations, and reconciles changelog metadata.
Existing Doc Maturity	3/5	The existing 112-line document covered basic configuration and sync modes but had sparse setup guidance and a misleading namespace claim.
Connector Sensitivity	4/5	This is a certified connector with low current quality and support-level metrics (ql: 100, sl: 100).
Triggering Context	5/5	A small, merged bug-fix PR clearly identified the connector and the behavior requiring review.

What I Verified vs. What I Inferred

• Verified from code: The destination defaults to md:, passes the token through DuckDB configuration rather than the URL, writes all streams to one configured schema, ignores source namespace during writes, normalizes table and field names, skips records with normalized field collisions, and preserves other streams' buffers after a single-stream flush.
• Verified from API docs: MotherDuck requires a Read/Write token for writes, supports md:<database-name> connection strings, creates my_db as the default database for new accounts, supports expiring tokens and service accounts, and requires organization Admin access to configure service accounts.
• Inferred: The /local to LOCAL_ROOT host-path explanation relies on the connector's path normalization and Airbyte's existing DuckDB destination documentation rather than an end-to-end local-file test.

Areas of Concern

• Review the wording of the single-schema/source-namespace limitation; it reflects the current implementation but wasn't validated in an end-to-end sync.

---

What

• Correct the misleading namespace-to-schema claim and document the connector's single-schema behavior.
• Add setup guidance for Read/Write access tokens, MotherDuck database paths, schemas, local DuckDB files, and name normalization limitations.
• Reconcile changelog dates with GitHub merge timestamps and replace unmerged PR ✨ Destination DuckDB: upgrade to DuckDB v1.4.2 #70221 with the merged implementation PR chore(destination-duckdb, destination-motherduck): upgrade DuckDB client and bump base image to python-connector-base:4.0.0 (Python 3.10+) #71063.

How

• Corrections: Align namespace, token, and changelog claims with connector source, specification, GitHub merge metadata, and official MotherDuck documentation.
• Additions: Add prerequisites, step-by-step destination setup, service-account guidance, identifier normalization, and concrete limitations.
• Removals: Remove the unsupported filesystem-performance generalization and the incorrect claim that source namespaces map to MotherDuck schemas.
• Restructuring: Organize the page around prerequisites, setup, sync behavior, output schema, local files, and limitations.

Review Guide

1. Review MotherDuck prerequisites and token guidance in docs/integrations/destinations/motherduck.md.
2. Review the corrected schema, namespace, and normalized-name limitations.
3. Review changelog dates and replacement PR links against GitHub merge metadata.

Validation

• markdownlint-cli2 docs/integrations/destinations/motherduck.md: passed with 0 errors.
• vale --minAlertLevel=warning docs/integrations/destinations/motherduck.md: passed with 0 errors and two proper-noun heading warnings for MotherDuck and Destinations V2.
• pnpm build from docusaurus: passed. The build reported existing repository-wide broken-anchor warnings, none from the changed MotherDuck page.

User Impact

Users get accurate setup requirements and limitations, including the need for a Read/Write token and the fact that source namespaces don't map to separate MotherDuck schemas. Runtime connector behavior is unchanged.

Can this PR be safely reverted and rolled back?

• YES 💚
• NO ❌

---

Note: I am an AI assistant (Devin) and have proposed these documentation updates based on a review of the connector source code and third-party API documentation. Reviewers may merge, modify, or close this PR as they see fit.

Requested by GitHub CI Service User through the Connector Docs Playbook.

---

Devin session

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

💡 Show Tips and Tricks

PR Slash Commands

Airbyte Maintainers (that's you!) can execute the following slash commands on your PR:

• 🛠️ Quick Fixes
  • /format-fix - Fixes most formatting issues.
  • /bump-version - Bumps connector versions, scraping changelog description from the PR title.
    • Bump types: patch (default), minor, major, major_rc, rc, promote.
    • The rc type is a smart default: applies minor_rc if stable, or bumps the RC number if already RC.
    • The promote type strips the RC suffix to finalize a release.
    • Example: /bump-version type=rc or /bump-version type=minor
  • /bump-progressive-rollout-version - Alias for /bump-version type=rc. Bumps with an RC suffix and enables progressive rollout.
• ❇️ AI Testing and Review (internal link: AI-SDLC Docs):
  • /ai-prove-fix - Runs prerelease readiness checks, including testing against customer connections.
  • /ai-canary-prerelease - Rolls out prerelease to 5-10 connections for canary testing.
  • /ai-review - AI-powered PR review for connector safety and quality gates.
• 📝 AI Documentation:
  • /ai-docs-review - AI-powered documentation review for PRs with connector changes.
  • /ai-create-docs-pr - Creates a documentation PR for connector changes, stacked on the current PR.
• 🚀 Connector Releases:
  • /publish-connectors-prerelease - Publishes pre-release connector builds (tagged as {version}-preview.{git-sha}) for all modified connectors in the PR.
  • /enable-autopilot-rollouts - Enables autopilot progressive rollouts for the modified connector(s) in the PR, remediating "autopilot rollouts not enabled for {connector-name}" auto-merge blockers. Sets defaultRolloutMode: autopilot and enableProgressiveRollout: true, preserving any existing autopilotConfig.
    • Optional args: connector=<CONNECTOR_NAME> (defaults to the modified connectors in the PR), strategy=fast|slow|default (defaults to fast).
    • Example: /enable-autopilot-rollouts or /enable-autopilot-rollouts connector=source-faker strategy=slow
• ☕️ JVM connectors:
  • /update-connector-cdk-version connector=<CONNECTOR_NAME> - Updates the specified connector to the latest CDK version.
    Example: /update-connector-cdk-version connector=destination-bigquery
• 🐍 Python connectors:
  • /poe connector source-example lock - Run the Poe lock task on the source-example connector, committing the results back to the branch.
  • /poe source example lock - Alias for /poe connector source-example lock.
  • /poe source example use-cdk-branch my/branch - Pin the source-example CDK reference to the branch name specified.
  • /poe source example use-cdk-latest - Update the source-example CDK dependency to the latest available version.
• ⚙️ Admin commands:
  • /force-merge reason="<REASON>" - Force merges the PR using admin privileges, bypassing CI checks. Requires a reason.
    Example: /force-merge reason="CI is flaky, tests pass locally"

📚 Show Repo Guidance

Helpful Resources

• Breaking Changes Guide - Breaking changes, migration guides, and upgrade deadlines
• Developing Connectors Locally
• Managing Connector Secrets
• On-Demand Regression Tests
• #connector-ci-issues
• #connector-publish-updates
• #connector-build-statuses

📝 Edit this welcome message.

[github-actions]

Deploy preview for airbyte-docs ready!

Project:	airbyte-docs
Status:	✅  Deploy successful!
Preview URL:	https://airbyte-docs-kble2hivv-airbyte-growth.vercel.app
Latest Commit:	52bd3a2

Deployed with vercel-action