docs: improve quickstart DuckDB setup to reduce user pitfalls

[goldmedal]

Summary

• Promote /wren-quickstart skill as the default path — manual setup is now collapsed in a <details> block for advanced users
• Add explicit DuckDB connectionInfo format with JSON example and "common mistake" callout (url must be a directory, not the .duckdb file)
• Add two new troubleshooting entries: UTF-8 decode error and catalog name mismatch

Context

A user followed the quickstart with an AI agent and hit several DuckDB-specific pitfalls (see session summary analysis). The agent bypassed skills and tried to configure connectionInfo manually, leading to:

1. 'utf-8' codec can't decode byte — pointed url to the binary .duckdb file instead of its parent directory
2. Catalog "xxx" does not exist — catalog name mismatch between MDL and DuckDB filename
3. Missing CONNECTION_FILE_ROOT env var

These changes make the happy path (skill-driven) the obvious default and provide enough detail in the manual path to avoid the most common mistakes.

Test plan

• Verify markdown renders correctly on GitHub (especially <details> block and anchor links)
• Walk through Option B manually to confirm connection info instructions are accurate

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Enhanced quickstart guide with a new manual setup option provided alongside the automated workflow.
  • Added detailed configuration guidance for setting up DuckDB connections via the Web UI interface.
  • Included common mistakes and expanded error troubleshooting sections for an improved setup experience.
  • Reorganized and clarified setup steps with explicit phase breakdowns for better navigation and clarity.

[coderabbitai]

📝 Walkthrough

Walkthrough

The quickstart documentation has been expanded to include a detailed manual setup workflow alongside the existing automated path. The changes introduce phased instructions, inline configuration guidance, warnings about common mistakes, and enhanced troubleshooting information to support users setting up DuckDB connections manually.

Changes

Cohort / File(s)	Summary
Documentation Expansion docs/quickstart.md	Extended Step 4 with a new Manual setup option featuring three phases (start container, configure connection/generate MDL, register MCP server). Added inline warnings about DuckDB path configuration, common mistakes, and enhanced troubleshooting for UART/UTF-8, catalog mismatch, and MCP availability errors.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• docs(skills): add file-based connector docs, venv setup, and fix path/typo issues #1438: Both PRs modify docs/quickstart.md to update DuckDB input guidance from file paths to folder paths with connection configuration details.
• docs: add Wren Engine documentation #1437: Both PRs expand docs/quickstart.md with phased manual setup instructions, connection configuration guidance, and troubleshooting additions.

Suggested labels

documentation

Suggested reviewers

• douenergy

Poem

🐰 A quickstart guide now shines so bright,
With phases, warnings, and steps set right,
Manual paths and automated flows,
Configuration guidance that clearly shows,
Documentation magic—hop, hop, hooray! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: improving the DuckDB setup documentation to reduce user pitfalls. It directly aligns with the PR's primary objective of addressing documented user issues and reorganizing the quickstart guide.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Tip

You can disable poems in the walkthrough.

Disable the reviews.poem setting to disable the poems in the walkthrough.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/quickstart.md (1)

119-133: ⚠️ Potential issue | 🟠 Major

Manual setup still misses CONNECTION_FILE_ROOT, so the documented failure mode can persist.

Given the PR context, Option B should include CONNECTION_FILE_ROOT in docker run, and troubleshooting should mention it explicitly; otherwise users can still hit the same setup failure even with correct url/format.

Suggested doc patch

 docker run -d \
   --name wren-mcp \
   -p 8000:8000 \
   -p 9000:9000 \
   -p 9001:9001 \
   -e ENABLE_MCP_SERVER=true \
   -e MCP_TRANSPORT=streamable-http \
   -e MCP_HOST=0.0.0.0 \
   -e MCP_PORT=9000 \
   -e WREN_URL=localhost:8000 \
   -e MDL_PATH=/workspace/target/mdl.json \
+  -e CONNECTION_FILE_ROOT=/data \
   -v ~/wren-workspace:/workspace \
   -v "$JAFFLE_SHOP_DIR":/data \
   ghcr.io/canner/wren-engine-ibis:latest

 **`/generate-mdl` fails immediately:**
 The container must be running first. Run `docker ps --filter name=wren-mcp` to confirm, then retry.
+
+**Connection configuration fails due to missing root path env:**
+Ensure `CONNECTION_FILE_ROOT` is set when starting the container (for this guide: `/data`).

Also applies to: 245-267

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/quickstart.md` around lines 119 - 133, The docker run snippets are
missing the required environment variable CONNECTION_FILE_ROOT; update both
docker run blocks (the one with WREN_URL/MDL_PATH and the other similar block)
to include -e CONNECTION_FILE_ROOT=<path inside container where connection files
live> (choose a path that matches your mounted volume), and add a
troubleshooting note that a missing or incorrect CONNECTION_FILE_ROOT will cause
the described setup failure even if url/format are correct so users should
verify this env var points at the mounted connection files directory.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@docs/quickstart.md`:
- Around line 119-133: The docker run snippets are missing the required
environment variable CONNECTION_FILE_ROOT; update both docker run blocks (the
one with WREN_URL/MDL_PATH and the other similar block) to include -e
CONNECTION_FILE_ROOT=<path inside container where connection files live> (choose
a path that matches your mounted volume), and add a troubleshooting note that a
missing or incorrect CONNECTION_FILE_ROOT will cause the described setup failure
even if url/format are correct so users should verify this env var points at the
mounted connection files directory.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4798c6bd-57aa-49da-a019-54a79548b279

📥 Commits

Reviewing files that changed from the base of the PR and between 545e9a5 and b220b7c.

📒 Files selected for processing (1)

• docs/quickstart.md