docs: update readme

[royendo]

Remove the fluff, ToC, etc.

Separate the feature sets of RD and RC and link to our different examples/demos where applicable.
Checklist:

• Covered by tests
• Ran it and it works as intended
• Reviewed the diff before requesting a review
• Checked for unhandled edge cases
• Linked the issues it closes
• Checked if the docs need to be updated. If so, create a separate Linear DOCS issue
• Intend to cherry-pick into the release branch
• I'm proud of this work!

[ericpgreen2]

Review: README rewrite

Nice work stripping out the fluff and separating Developer vs. Cloud — the direction is right. I benchmarked this against the READMEs of Metabase, Grafana, DuckDB, Cube, Superset, Evidence, and Lightdash to see where we can tighten it further. Three themes stood out:

---

1. Fix the rendering bugs before anything else

• Duplicate nav bars (lines 9–17). There are two nav rows — the old markdown-style links (Docs/Install/Quickstart/Guides/Reference) carried over alongside the new HTML links (Docs/Quickstart/Examples/Capabilities/Contributing/Data Talks). The first <p> tag is never closed, which makes this invalid HTML. Remove the old markdown nav entirely and keep one clean HTML nav bar.
• Screenshot won't render on GitHub. The relative path /docs/static/img/... doesn't resolve on GitHub. Use the absolute URL: https://docs.rilldata.com/img/explore/dashboard101/multi-measure-select.png
• "Explore Dashboards" says "locally" in the Cloud section (line 74). Copy-paste artifact from the Developer table.
• Connector example mislabeled. connectors/s3.yaml but driver: gcs — confusing for newcomers.

---

2. Rethink the information architecture

The best OSS READMEs follow a clear funnel: show → explain → try → learn → join. Our current flow is close but has some ordering issues and a section that's too heavy.

Proposed structure (~120 lines total):

Section	Lines	Notes
Header (logo + tagline + badges + one nav bar)	~12	Fix broken HTML
Elevator pitch (1-liner + 4 bullet value props)	~8	Already strong, keep
Screenshot	~5	Fix to absolute URL
Why Rill? (new)	~12	Problem framing + differentiation
Get Started + live demo CTAs	~10	Demo links early, not buried at line 88
Features: Rill Developer	~10	Bullets, not tables
Features: Rill Cloud	~12	Bullets, not tables
Example (trimmed)	~22	2 files, not 4
Production Examples	~10	3 rows, cut Playlists
Community	~6	Move here from line 32
Contributing + License	~4	Minimal

Key changes from what's there now:

a) Add a "Why Rill?" section. Cube and Superset both frame the problem before listing features. Without it, the README reads as a feature catalog. Propose 4 bullets:

• Full-stack analytics — OLAP + modeling + metrics + visualization in one deployment
• Code + AI — Engineers get code-first; business users get AI-first; both are first-class
• Fast at every layer — Sub-second queries on large datasets, hours from raw data to production
• Low barrier to entry — Two commands to start, free tier, managed cloud, or self-hosted

b) Replace feature tables with linked bold-bullets. The two capability tables (27 rows total) are exhausting to scan and cause horizontal scroll on mobile. Metabase, Grafana, and Cube all use linked bullets — they scan faster, render better on mobile, and feel less like docs. Keep 7 bullets for Developer, 8 for Cloud. Cut features that are table stakes rather than differentiating (Public URLs, Themes) to docs only. Keep differentiating features like Incremental Models and Model Tests — they reinforce the full-stack story and signal to data engineers that Rill handles the pipeline side too, not just visualization.

c) Move Community to the bottom. It's currently between the intro and Quickstart, which is prime real estate. Every benchmark README puts community near the footer. Move the demo CTAs into Get Started instead — every top README (Grafana's play.grafana.org, Metabase's cloud trial) surfaces a live demo within the first scroll.

d) Trim the YAML example from 4 files to 2. Keep the model + metrics view (they show the core pattern). Cut the connector (mislabeled and shows an opaque templated env var) and the dashboard file (near-empty, just type: explore, dimensions: "*"). Remove boilerplate comments. DuckDB's 2-line SQL example works precisely because it's minimal.

e) Cut the Playlists section. No context about what the videos contain. YouTube links belong in docs, not competing for space in a tight README.

---

3. Design polish

• ~120 lines total. Brevity signals confidence. Grafana is 72 lines with 65k stars. The README is the lobby, not the building.
• HTML only for the header block + screenshot (they need centering/sizing). Everything else in pure markdown. The current mix of <p>, <div>, markdown links inside HTML tags causes rendering inconsistencies.
• 2 badges (Release + License) is the right call — the old 6-badge row was noise.
• Twitter badge should link to the official Rill account, not a personal handle.
• Subtle Cloud positioning — demo links after Quickstart and a Cloud features section, but no hard sell. Let the product speak.

[ericpgreen2]

1. Broken admonition syntax (lines 45, 113)

Both [!TIP] callouts are on a single line, so they render as literal text instead of callout boxes. GitHub requires the directive on its own line:

> [!TIP]
> **Try it live:** ...

2. Consolidate examples into one list

Examples and demos appear in three places: the tip after Quickstart, the tip after the YAML example, and the Production Examples table. Consider consolidating into one section — the Production Examples table already does this well, so the inline tips could just reference it (or be removed).

3. Redundancy between intro bullets and "Why Rill?"

The four intro bullets (Sub-second queries, Metrics layer, AI-ready, Git-native) and the four "Why Rill?" bullets (Full-stack, Code + AI, Fast, Low barrier) overlap — both mention speed, AI, and code-first. Consider cutting one section or giving them clearer roles (e.g., intro = what it is, Why Rill = how it's different).

4. "Sub-second queries" links to Connectors page

This bullet links to docs.rilldata.com/build/connectors/, which is about data source connectors rather than OLAP performance. A page about the OLAP engine or architecture would be a better fit.

5. "Rill Developer (local, open-source)" label

Both Rill Developer and Rill Cloud are open-source (they're in this repo). Labeling only Developer as "open-source" implies Cloud isn't. Consider dropping the label or applying it to both.

6. Top nav bar and license duplication

Minor: The nav links (Docs · Quickstart · Examples · Capabilities · Data Talks) are dense and lack context — not sure they earn the prime real estate. The Docs link is useful; the in-page anchors less so since the README is short enough to scroll. Separately, the license badge at the top and the License section at the bottom are redundant — one or the other would suffice.

---

Developed in collaboration with Claude Code

[royendo]

added some changes for the new Agent first wording

Thoughts; prob a good time to puish this out

[ericpgreen2]

Re-review: README rewrite

The structure is in good shape — the author addressed nearly everything from the prior two rounds. The "agent-first" framing is distinctive and the Developer/Cloud split works. At 119 lines, it's tight. A few substantive issues remain before this is ready to merge.

1. "Embedded OLAP" is too narrow

The phrase "embedded OLAP engines" appears twice (elevator pitch, line 20; "Real-time performance" bullet, line 34) but Rill also supports BYODB — ClickHouse Cloud, Druid, Pinot, MotherDuck — none of which are "embedded."

2. Semantic layer is not "materialized"

defined in YAML, materialized in your OLAP engine

Metrics views aren't materialized — they're query templates that generate SQL at runtime against the OLAP engine. Models can be materialized, but the semantic layer itself is not.

3. "Explore with agents" wording

Conversational BI and MCP server let business users and AI agents query your semantic layer in natural language

Two issues: the grammar reads awkwardly, and AI agents don't query in "natural language" — they use structured APIs and MCP tool calls. Humans use natural language; agents use the MCP interface.

4. "No extra config" claim is misleading (line 101)

Dashboards, conversational BI, alerts, and APIs are live — no extra config.

The example only showed a model and a metrics view. No dashboard YAML, no alert YAML, no API YAML was defined. Claiming these are all "live — no extra config" after showing two files that don't define any of them overpromises.

5. Capability bullets are too terse for newcomers

Some bullets under Rill Developer and Rill Cloud read like internal notes rather than explanations for someone unfamiliar with Rill. A few examples: "Managed ClickHouse or DuckDB, or bring your own" (managed by whom?), "Partitioned, incremental data loading" (what problem does this solve?), "rill deploy or Git CI/CD" (a newcomer doesn't know what this does).

6. Duplicate "Examples" presence

"Examples" appears in the top nav bar (linking to the GitHub repo) and again as the "Production Examples" section with a table and demo links. This creates a déjà vu moment — pick one location.

7. Add a screenshot

Still the biggest gap for a visual analytics tool. Every benchmark README (Metabase, Grafana, Superset) shows the product. The old one had a broken relative path — fix it rather than removing it.

8. Minor: drop the ! in the elevator pitch

"ClickHouse, DuckDB and more!" — the exclamation mark reads breathlessly.

---

Developed in collaboration with Claude Code

[ericpgreen2]

Re-review: README rewrite (round 3)

All eight items from the previous review have been addressed — nice work. The "embedded OLAP" language is fixed, the semantic layer description is accurate, the capability bullets are more descriptive, and the screenshot is back with a working URL. The YAML example now honestly includes a dashboard step. Overall this is very close.

1. The rill init interactive flow doesn't exist

The "Scaffold a project with agent context" section shows an interactive prompt-based flow (? Project name, ? OLAP engine, ? Agent instructions) that the CLI doesn't support. rill init uses a --template flag, and the claude template is a separate step that adds files to an existing project — it can't be combined with project creation. The output also claims .mcp.json is created, but the claude template doesn't produce that file. Either show commands that work today or remove the section until the CLI supports it.

2. "Sub-second queries on billions of rows via ClickHouse, DuckDB"

DuckDB doesn't operate at billions-of-rows scale. This overpromises for one of the two named engines. The claim should be scoped to ClickHouse or stated more carefully.

3. Deploy bullet frames rill deploy as a feature

Push to Rill Cloud with rill deploy or automate via Git-triggered CI/CD

A CLI command isn't really a feature worth highlighting. The actual differentiator is git-backed, versioned, reviewable deployments — that's what this bullet should convey.

4. "Production Examples" → "Examples"

The "Production" qualifier is unnecessary. Just "Examples."

---

Developed in collaboration with Claude Code