docs(intro): rewrite overview — ground every claim in concrete examples

[PaulChen79]

Summary

Two independent reviews (Senior DE + teammate) converged on the same critique of the overview: too much telling, not enough showing. Specifically:

• Lots of high-level claims that the reader cannot verify ("agent-native", "primitives", "governed surface", "first-class SDKs")
• The Correctness section reads like AI slop
• "How you use it" and "When to use Wren AI" are vague / redundant
• The "Where this is going" three-bullet roadmap teases without delivering

The fix is not to strip framing — overview pages need a 30-second pitch. The fix is to anchor every claim in a snippet a reader can verify: an MDL YAML file, a CLI shell session, a dry-plan expansion.

What changed

Section	Before	After
Lede	jargon-heavy tagline	one-sentence what-it-is, one-sentence why-it-exists
Why Wren AI exists	good prose, kept	tightened; merged "Why open source matters" closing line about flat files
What Wren AI provides	abstract claim + 5-layer table + second image	real MDL YAML for `customers` + `wren --sql` shell output + 5-step explanation of what happens behind the scenes
Correctness is a system	6-bullet abstract list + image	one paragraph + concrete `wren dry-plan` example showing planned SQL
How you use it	scaffold/enrich prose	3 numbered shell commands
Where this is going	3 abstract bullets	one sentence + link to GitHub Discussions
When to use Wren AI	6 bullet use-cases	deleted (vague + redundant)
Why open source matters	standalone section	merged into Why exists
Images	3 images	1 image (`missing-context-layer.png`, the one the reviewer flagged as setting context); dropped `with_without_wren` and the correctness image

Net length is roughly the same (~140 → ~130 lines), but signal density is up significantly — every claim now has a snippet next to it.

Test plan

• Visually QA on the docs site once sync lands (companion PR on Canner/docs.getwren.ai will run on master deploy)
• Spot-check that linked routes still exist after the IA refresh (concepts/correctness, reference/mdl, etc. — all present per previous refine work)

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Rewrote and restructured the introduction to position Wren AI as the open context layer and clarify its value.
  • Added "What Wren AI provides" with authoring, CLI query examples, components (MDL, CLI tools, semantic engine, Skills, SDKs) and example-driven guidance.
  • Updated roadmap, condensed "Start here" steps, refreshed learning links, and noted GenBI app sunset with legacy docs location.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

This PR rewrites docs/core/introduction.mdx: it repositions Wren AI as an “open context layer,” replaces prior narratives, and adds sections for What Wren AI provides, open-core components, correctness via wren dry-plan, usage/onboarding, roadmap, and GenBI sunset notes.

Changes

Introduction content rewrite

Layer / File(s)	Summary
Opening positioning and value proposition docs/core/introduction.mdx	Top-of-page intro is rewritten to replace the prior long-form explanation with a shorter "open context layer" framing and clarifies the missing-meaning problem an agent cannot infer from schema alone.
Main content sections and feature overview docs/core/introduction.mdx	Document body is substantially restructured: prior multi-section narrative is removed and replaced with new sections including "What Wren AI provides" (MDL overview, wren --sql example, and behind-the-scenes resolution steps), "What ships in the open core" (MDL, wren CLI features like dry-plan/dry-run/memory/profile, Rust semantic engine/DataFusion, Skills, SDKs), updated Roadmap, condensed Start here, GenBI sunset/legacy note, and shortened Learn more links.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Canner/WrenAI#2314: Overlaps edits to docs/core/introduction.mdx and the introduction's opening positioning.
• Canner/WrenAI#2285: Related docs refactor in the same narrative area and may overlap with the introduction restructuring.
• Canner/WrenAI#2234: Documentation reframing that aligns on "open context layer" positioning across docs.

Suggested labels

core

Suggested reviewers

• goldmedal
• douenergy

Poem

🐰 A fresh intro hops into view,
"Open context layer" — crisp and true,
MDL and dry-plan lead the way,
CLI and Skills in bright array,
A rabbit cheers this clearer day.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly summarizes the main change: a documentation rewrite of the overview that grounds claims in concrete examples, which aligns with the PR's core objective of replacing abstract language with verifiable code snippets and real examples.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/refine-overview

---

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.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/core/introduction.mdx (1)

3-3: ⚡ Quick win

Remove the legacy tagline to keep the opening crisp.

Line 3 is a long, jargon-heavy sentence that dilutes the stronger concise framing introduced at Line 7. Dropping it will make the lede align with the rewrite goal and reduce repetition.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/core/introduction.mdx` at line 3, Remove the legacy tagline sentence
"Turn any AI Agents into world-class data analysts through the open context
layer that gives AI agents grounded, governed memory, context, and SQL across
20+ data sources, that helps you build GenBI, dashboards, and agentic
analytics." from docs/core/introduction.mdx so the opening is shorter and aligns
with the new concise lede; simply delete that full line/paragraph (it is the
long jargon-heavy sentence at the top) and ensure surrounding
whitespace/formatting remains correct.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/core/introduction.mdx`:
- Line 3: Remove the legacy tagline sentence "Turn any AI Agents into
world-class data analysts through the open context layer that gives AI agents
grounded, governed memory, context, and SQL across 20+ data sources, that helps
you build GenBI, dashboards, and agentic analytics." from
docs/core/introduction.mdx so the opening is shorter and aligns with the new
concise lede; simply delete that full line/paragraph (it is the long
jargon-heavy sentence at the top) and ensure surrounding whitespace/formatting
remains correct.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 1201ff6f-0376-4708-bfb3-f99f8d072a1f

📥 Commits

Reviewing files that changed from the base of the PR and between 8518639 and c59b870.

📒 Files selected for processing (1)

• docs/core/introduction.mdx