docs(wren): cube skills and user-facing docs for phase G

[goldmedal]

Phase G: cube skills + docs updates

Wires cube knowledge into the wren-usage skill and user-facing docs. Final phase of the cube rollout (impl-cube-skills.md).

Skill

• skills/wren-usage/SKILL.md — new ## Cube Query Workflow + ## Aggregation decision tree sections, extra command-decision-tree line; version 2.2 → 2.3
• skills/wren-usage/references/wren-sql.md — new "Cube query SQL generation" section (generated SQL pattern, key points, how to diagnose cube SQL errors with --sql-only)
• skills/wren-usage/references/memory.md — new "Cube schema items" subsection in Schema context
• skills/wren-generate-mdl/SKILL.md — context init directory tree now lists cubes/; a one-line "When to define cubes" hint links to the Cube guide

Docs

• README.md — "Why WrenAI?" gains a pre-aggregation cubes callout
• core/wren/README.md — Quick start gains step 4a (cubes)
• docs/core/reference/cli.md — new ## wren cube section with flag table, supported granularities, and operators
• docs/core/get_started/quickstart.md — new optional step 8 demoing cube query
• docs/core/guides/modeling/overview.md — Cube added as a core modeling object between View and Memory; rule-of-thumb list updated
• docs/core/guides/modeling/cube.md — new guide parallel to model.md / view.md / relation.md (YAML structure, fields, time granularity, derived measures, filter operators, CLI, WASM, validation)

Verify-only

• core/wren-core-wasm/AGENT_GUIDE.md — PR feat(wren-core-wasm): cubeQuery + listCubes browser API #2278's Cube Query API section is already present (grep confirms "Cube Query API", listCubes(), cubeQuery({...}), loadMDL() precondition, CDN URL @0.3.0).

Not in this PR (file as follow-ups)

• core/wren-mdl/mdl.schema.json still uses old metrics naming from pre-PR chore(wren-ui): enhance model substitution error message #1574. Renaming the public JSON schema is a breaking change and needs its own PR with alias decision + version bump.

Verification

• skills/wren-usage/SKILL.md frontmatter shows version: "2.3" ✓
• wren cube --help, wren cube list --help, wren cube query --help — every flag documented in cli.md and cube.md matches the actual CLI surface ✓
• Internal markdown links across all touched docs resolve (Python link-check script) ✓ (one pre-existing ./examples placeholder in root README is unrelated)
• All 10 files Phase G specifies, plus the new cube.md, committed

Trail: PR #1574 (cube types) → PR #2264 (validate_cubes) → PR #2265 (cube_query_to_sql) → PR #2276 (cleanup) → PR #2277 (PyO3 + CLI) → PR #2278 (WASM + AGENT_GUIDE) → this PR (skills + docs).

After this merges, feat/wasm-cube is ready to merge into main and release-please will publish wren, wren-core-py, and @wrenai/wren-core-wasm new versions with full cube support.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added Cube support for pre-aggregated queries and new CLI commands to list, describe and query cubes with time aggregation and filtering.

• Documentation

  • Added a comprehensive Cube guide, CLI reference, quickstart step, and updated usage guides showing cube workflows and SQL generation behavior.

• Chores

  • Bumped skill version for the usage guide to reflect Cube-related updates.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: b2fa2366-e19d-492e-8dd6-1c6bad8960c3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• ✅ Review completed - (🔄 Check again to review again)

Walkthrough

This PR adds comprehensive documentation for WrenAI's pre-aggregation Cube feature across guides, CLI references, and skill workflows. A new cube modeling guide defines the feature; user documentation shows how to discover and query cubes; skill updates teach the agent cube query workflows; and project scaffolding includes cubes in generated structure.

Changes

Cube Feature Documentation & Skills

Layer / File(s)	Summary
Core Cube Concept Documentation README.md, docs/core/guides/modeling/overview.md, docs/core/guides/modeling/cube.md	Introduces Cube as a pre-aggregated semantic modeling primitive built on Models or Views. A comprehensive cube guide covers YAML/JSON structure, field semantics (measures, dimensions, time_dimensions, hierarchies), query-time granularities, derived-measure expansion rules, supported filter operators, and validation behavior during context build and analysis.
User-Facing Cube Query Documentation core/wren/README.md, docs/core/get_started/quickstart.md, docs/core/reference/cli.md	Documents the cube query user experience: core/wren README adds aggregation query examples; quickstart adds Step 8 for cube discovery and querying; CLI reference comprehensively covers wren cube list, wren cube describe <name>, and wren cube query with input modes (CLI flags and JSON), output formats, time granularities, and filter operators.
Cube Query Skill Workflow & Intelligence skills/wren-usage/SKILL.md, skills/wren-usage/references/memory.md, skills/wren-usage/references/wren-sql.md, skills/index.json, skills/versions.json	Bumps wren-usage skill to v2.3 with new cube query logic: decision tree routes aggregation-across-dimensions questions to cube queries; adds cube workflow section covering discovery, measure/dimension/filter mapping, CLI execution, JSON input, and SQL inspection via --sql-only; documents cube schema items in memory index; explains cube SQL generation (DATE_TRUNC time bucketing, base object resolution, derived-measure inlining, half-open date ranges); provides cube-specific error recovery.
Cube Project Scaffolding skills/wren-generate-mdl/SKILL.md	Updates generated project structure to include cubes/ directory and adds guidance on when to define cubes for aggregation-focused modeling questions.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• Canner/WrenAI#1666: Modifies the same "Why WrenAI?" section of README.md; overlaps in top-level documentation messaging.

Suggested reviewers

• imAsterSun
• chilijung

Poem

🐰 Cubes stack high, dimensions align,
Pre-aggregated metrics shine!
Measures flow like morning dew,
No more GROUP BY for you—
Wren's new way makes queries clean,
The smartest semantic schema you've seen! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
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.
Title check	✅ Passed	The PR title clearly summarizes the main change: adding cube-related documentation to skills and user-facing guides as part of the phase G rollout.

_{✏️ 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/cube-skills-docs

---

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]

Actionable comments posted: 1

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

Inline comments:
In `@core/wren/README.md`:
- Around line 119-120: The README link uses the wrong anchor "#cube-commands";
update the anchor in core/wren/README.md to match the actual target anchor in
docs/core/reference/cli.md by replacing "#cube-commands" with
"#wren-cube--pre-aggregation-queries" (or, if the docs anchor has been renamed,
adjust to the current anchor name), ensuring the link to the CLI reference
correctly navigates to the "wren cube / pre-aggregation queries" section.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 88745feb-09f8-48e2-b671-99ea60271358

📥 Commits

Reviewing files that changed from the base of the PR and between 8f7ecf4 and 8c205c5.

📒 Files selected for processing (12)

• README.md
• core/wren/README.md
• docs/core/get_started/quickstart.md
• docs/core/guides/modeling/cube.md
• docs/core/guides/modeling/overview.md
• docs/core/reference/cli.md
• skills/index.json
• skills/versions.json
• skills/wren-generate-mdl/SKILL.md
• skills/wren-usage/SKILL.md
• skills/wren-usage/references/memory.md
• skills/wren-usage/references/wren-sql.md