docs(core): restructure OSS docs around context-layer narrative#2285
Merged
Conversation
github-actions
Bot
added
the
documentation
Contributor
|
Note Reviews pausedIt 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 Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
<review_stack_artifact_start> 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
PaulChen79
force-pushed
the
refactor/document
branch
from
1d18b07 to
490151d
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 15
🧹 Nitpick comments (7)
docs/core/guides/connect/mysql.md (2)
40-40: ⚡ Quick winClarify "default" vs. "required" for the port field.
Line 40 states "Default
3306" in the description, but the "Required" column marks the field as "yes". If the port is truly required in the YAML, consider rephrasing to "Port number (default:3306)" to indicate users must specify it even though3306is the standard.🤖 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/guides/connect/mysql.md` at line 40, Update the documentation row for the `port` field in the MySQL connection table to clarify default vs required: change the description text from "Default `3306`" to a phrase like "Port number (default: `3306`)" so readers understand they must specify the port in the YAML even though 3306 is the usual default; ensure this edit targets the `port` table entry in the connect/mysql.md table and do not change the "Required" column unless the implementation actually makes the port optional.
44-44: ⚡ Quick winImprove clarity of SSL field description.
The description "
truefor SSL, omit for plaintext" could be clearer. Consider: "trueto enable SSL/TLS encryption; omit or setfalsefor plaintext connections."🤖 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/guides/connect/mysql.md` at line 44, Update the `ssl` field description in the MySQL connection docs to a clearer phrase: replace "`true` for SSL, omit for plaintext`" with "`true` to enable SSL/TLS encryption; omit or set `false` for plaintext connections`" so readers understand how to enable or disable encrypted connections for the `ssl` option.docs/core/guides/connect/sqlserver.md (1)
27-27: ⚡ Quick winClarify driver field default behavior.
Line 27 shows
driver: "ODBC Driver 18 for SQL Server"in the example YAML, and line 39 states it "defaults to 18". If the driver truly defaults, consider either:
- Omitting it from the example YAML (to show minimal required config), or
- Adding a comment in the YAML like
# optional, defaults to "ODBC Driver 18 for SQL Server"This would help users understand they don't need to specify it unless using a different driver version.
Also applies to: 39-39
🤖 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/guides/connect/sqlserver.md` at line 27, The example YAML currently sets the driver field to "ODBC Driver 18 for SQL Server" which may imply it's required; update the snippet to clarify default behavior by either removing the driver line from the example YAML to show the minimal required config, or keep the driver line but add an inline comment like `# optional, defaults to "ODBC Driver 18 for SQL Server"` so readers understand the `driver` field is optional unless they need a different version.docs/core/guides/connect/oracle.md (2)
20-20: ⚡ Quick winInconsistent inline comment style.
Line 20 uses an inline comment
# 1521to show the default port, while other files in this cohort use the Description column for defaults. For consistency, consider moving "Default1521" to the table's Description column (like line 29 inmysql.md).🤖 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/guides/connect/oracle.md` at line 20, The inline comment showing the default port next to the "port: ${ORACLE_PORT} # 1521" entry is inconsistent with the project's style; remove the trailing inline comment and instead add "Default `1521`" into the table's Description cell for the "port" / "ORACLE_PORT" row (follow the pattern used in the mysql.md Description column example) so the default is documented in the Description column rather than as an inline comment.
31-32: 💤 Low valueAdd descriptions for user and password fields.
Lines 31-32 have empty descriptions. While self-explanatory, brief descriptions like "Oracle username" and "Oracle password" would maintain consistency with other connector guides.
🤖 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/guides/connect/oracle.md` around lines 31 - 32, Update the empty table descriptions for the `user` and `password` fields by replacing the blank cells with brief descriptions (e.g., "Oracle username" for `user` and "Oracle password" for `password`) so the connector guide matches other connector docs; edit the table rows containing `user` and `password` to include these short descriptions.docs/core/guides/connect/clickhouse.md (1)
28-28: ⚡ Quick winConsider clarifying port default behavior.
Line 28 states "Default
9000for native,8443for HTTPS", but the Required column marks port as "yes". This creates ambiguity:
- If
secure: true, should users specify8443?- If
secure: false, should users specify9000?Consider rephrasing to: "Port number (
9000for native protocol,8443for HTTPS; must match your ClickHouse server configuration)".🤖 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/guides/connect/clickhouse.md` at line 28, Update the table entry for the "port" field to remove ambiguity: change the Required column to reflect that a port must be provided or clarify that it defaults based on protocol, and rephrase the Description from "`Default 9000 for native, 8443 for HTTPS`" to something like "Port number (9000 for native protocol, 8443 for HTTPS; must match your ClickHouse server configuration and the `secure` setting)". Ensure the new text references the `port` field and the `secure` flag so readers know the value must correspond to their ClickHouse server and protocol.docs/core/guides/connect/trino.md (1)
33-33: ⚡ Quick winClarify password requirement phrasing.
Line 33 states password is required "depending on auth", which is accurate but could be clearer. Consider: "Required if cluster uses password authentication; otherwise can be omitted."
🤖 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/guides/connect/trino.md` at line 33, Update the table row describing `password` in the Trino connection guide so the requirement is explicit: replace "depending on auth" with "Required if cluster uses password authentication; otherwise can be omitted" (locate the table cell containing `password` in the Trino connection options and update its description accordingly).
🤖 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 `@docs/core/concepts/memory_system.md`:
- Line 3: The phrase "natural-language to SQL pairs" in the sentence starting
"Wren AI's memory layer is the second of five layers of context — the place
where successful natural-language to SQL pairs, prior interactions, and user
feedback accumulate..." should be hyphenated as "natural-language-to-SQL pairs"
to improve clarity; update that exact phrase in the
docs/core/concepts/memory_system.md content so the sentence reads with the
hyphenated compound.
In `@docs/core/concepts/skills.md`:
- Line 5: Update the install command string "npx skills add Canner/WrenAI" so it
includes the missing --skill '*' flag to match the bundle-first onboarding flow;
find the sentence containing "npx skills add Canner/WrenAI" and change it to use
the full command including the --skill '*' option so the docs reflect the
correct installation path and ensure complete skill setup.
In `@docs/core/get_started/installation.md`:
- Around line 45-51: The two fenced code blocks containing the questions "How
many customers placed more than one order this month?" and "What are the top 5
products by total revenue?" are missing language identifiers and trigger
markdownlint MD040; update each fence to include a language (e.g., change ``` to
```text) so both blocks read ```text ... ``` to satisfy the linter while leaving
the content unchanged.
In `@docs/core/get_started/quickstart.md`:
- Around line 70-82: Quick summary: the memory guide omits that the "main" extra
already bundles "interactive", which can mislead users. Update the memory.md
text around the pip example that currently shows wren-engine[memory,interactive]
to instead clarify that wren-engine[memory,main] (which includes both
interactive and ui) is the recommended quickstart, and keep the
wren-engine[memory,interactive] example only as the minimal alternative;
explicitly state that "main" includes "interactive" (per pyproject extras) so
readers know they don't need to add both.
In `@docs/core/guides/connect/athena.md`:
- Around line 50-52: Add the missing IAM permissions to the Athena/Glue
permissions list by including athena:GetTableMetadata to enable Athena table
metadata retrieval and, if your workloads use partitioned tables, add
glue:GetPartitions to support partition operations; update the permission list
entries near the existing `athena:StartQueryExecution`,
`athena:GetQueryExecution`, `athena:GetQueryResults`, `glue:GetDatabase`,
`glue:GetTable`, `glue:GetTables`, and S3 permissions so the policy explicitly
contains `athena:GetTableMetadata` and optionally `glue:GetPartitions`.
In `@docs/core/guides/connect/duckdb.md`:
- Line 26: The docs incorrectly show the hidden "format" profile field as a
user-configurable required field; update the DuckDB guide to either remove the
`format: duckdb` line from the YAML example and the profile fields list or add a
short note that the `format` field is auto-injected and defaults to "duckdb" (do
not instruct users to set it). Reference the hidden field in field_registry.py
and the DuckDB connector when making the change so the doc matches the
implementation.
In `@docs/core/guides/connect/overview.md`:
- Line 7: The overview sentence claiming a profile is “a single YAML file”
conflicts with the Profiles guide which describes a profiles.yml file vs a
profiles directory; pick one canonical storage model (single YAML vs directory
of profiles), decide the exact filename/structure, then update the overview.md
sentence ("Wren AI talks to your database through a profile — a single YAML
file...") and all other docs (Profiles guide and any examples) to use that
canonical wording and path consistently; ensure CLI/SDK examples, sample config
snippets, and references use the same filename/format and the term "profile"
consistently across docs.
- Around line 21-34: The supported-source table in
docs/core/guides/connect/overview.md is inconsistent with the profile reference
that lists "spark"; either add a Spark row to that table (e.g., add a line with
Data source "Spark", appropriate Connector extra value `spark` and a link to a
new or existing Spark doc page) or remove "spark" from the profile reference
(docs/core/reference/profile_yaml.md) so both places match; update whichever
file you change so the supported sources are consistent and include the same
connector identifier "spark".
In `@docs/core/guides/use-with-agents/claude-code.md`:
- Around line 42-44: The fenced code block containing the line "How many
customers placed more than one order this month?" is missing a language hint;
update the opening fence from ``` to ```text so the block becomes a ```text
fenced code block (this satisfies markdownlint MD040) and leave the block
content unchanged.
- Around line 19-20: Replace the unsafe "curl | bash" pattern for the remote
installer URL
(https://raw.githubusercontent.com/Canner/WrenAI/main/skills/install.sh) with a
safe three-step flow: download the script to a local file (e.g.,
install-wren-skills.sh), inspect it (e.g., open with less or your pager/editor)
to verify contents, then execute it explicitly with bash; update the docs in
docs/core/guides/use-with-agents/claude-code.md to show these three steps and
reference the remote filename install.sh/install-wren-skills.sh so users can
audit before running.
In `@docs/core/introduction.mdx`:
- Line 84: Replace the incorrect product name "WrenAI GenBI" with the correct
spaced form "Wren AI GenBI" throughout the document; search for the literal
string "WrenAI GenBI" in introduction.mdx (and any occurrences of "Wren AI
GenBI") and update them so the product name is consistently "Wren AI GenBI" in
all places (e.g., the occurrences currently mismatched on lines that reference
the product).
In `@docs/core/reference/mdl_schema.md`:
- Around line 87-93: The snippet defines a relationship using a top-level "type"
field (e.g., the "orders_to_customers" item) which conflicts with the rest of
the docs that use a "relationships: [...]" array with "join_type"; update the
example to match the canonical YAML shape used in the modeling guide by
replacing the top-level "type" pattern with the "relationships" array and
"join_type" keys (or, if both formats are intentionally supported, add an
explicit versioned note calling out both shapes and when to use each), ensuring
the example uses "orders_to_customers", the models list, and the equivalent join
expression under "join_type" to match the guide.
- Around line 37-40: The docs use conflicting fields for table_reference
(table_reference.database vs table_reference.catalog); pick the canonical shape
used by the project (e.g., if `catalog` is canonical) and update all occurrences
in this document so examples, descriptions, and the schema snippet consistently
use `table_reference.catalog` (or alternatively add a short section explaining
both variants and when to use `database` vs `catalog`), and ensure the same
change is applied to the other duplicated example referenced by the review (the
second table_reference example).
In `@docs/core/reference/profile_yaml.md`:
- Around line 93-94: The example in profile_yaml.md shows the Snowflake profile
field "account" as a full hostname; update the example to use the account
locator format (consistent with docs/core/guides/connect/snowflake.md) so the
"account" value is the locator only (e.g., "my-account" or the correct account
locator string) rather than "my-account.snowflakecomputing.com" to unify formats
across docs.
- Around line 73-77: The BigQuery credential field is inconsistent: this doc
uses credentials_path while the BigQuery connector guide documents credentials
(base64 JSON); pick one canonical field and update both docs to match. Replace
the credentials_path example in this profile YAML with the chosen canonical
field (either credentials containing base64 JSON or credentials_path pointing to
a file) and adjust the example value to the correct format, and then update the
BigQuery connector guide to use the same field name and format so both
references (credentials_path vs credentials) are identical across docs.
---
Nitpick comments:
In `@docs/core/guides/connect/clickhouse.md`:
- Line 28: Update the table entry for the "port" field to remove ambiguity:
change the Required column to reflect that a port must be provided or clarify
that it defaults based on protocol, and rephrase the Description from "`Default
9000 for native, 8443 for HTTPS`" to something like "Port number (9000 for
native protocol, 8443 for HTTPS; must match your ClickHouse server configuration
and the `secure` setting)". Ensure the new text references the `port` field and
the `secure` flag so readers know the value must correspond to their ClickHouse
server and protocol.
In `@docs/core/guides/connect/mysql.md`:
- Line 40: Update the documentation row for the `port` field in the MySQL
connection table to clarify default vs required: change the description text
from "Default `3306`" to a phrase like "Port number (default: `3306`)" so
readers understand they must specify the port in the YAML even though 3306 is
the usual default; ensure this edit targets the `port` table entry in the
connect/mysql.md table and do not change the "Required" column unless the
implementation actually makes the port optional.
- Line 44: Update the `ssl` field description in the MySQL connection docs to a
clearer phrase: replace "`true` for SSL, omit for plaintext`" with "`true` to
enable SSL/TLS encryption; omit or set `false` for plaintext connections`" so
readers understand how to enable or disable encrypted connections for the `ssl`
option.
In `@docs/core/guides/connect/oracle.md`:
- Line 20: The inline comment showing the default port next to the "port:
${ORACLE_PORT} # 1521" entry is inconsistent with the project's style; remove
the trailing inline comment and instead add "Default `1521`" into the table's
Description cell for the "port" / "ORACLE_PORT" row (follow the pattern used in
the mysql.md Description column example) so the default is documented in the
Description column rather than as an inline comment.
- Around line 31-32: Update the empty table descriptions for the `user` and
`password` fields by replacing the blank cells with brief descriptions (e.g.,
"Oracle username" for `user` and "Oracle password" for `password`) so the
connector guide matches other connector docs; edit the table rows containing
`user` and `password` to include these short descriptions.
In `@docs/core/guides/connect/sqlserver.md`:
- Line 27: The example YAML currently sets the driver field to "ODBC Driver 18
for SQL Server" which may imply it's required; update the snippet to clarify
default behavior by either removing the driver line from the example YAML to
show the minimal required config, or keep the driver line but add an inline
comment like `# optional, defaults to "ODBC Driver 18 for SQL Server"` so
readers understand the `driver` field is optional unless they need a different
version.
In `@docs/core/guides/connect/trino.md`:
- Line 33: Update the table row describing `password` in the Trino connection
guide so the requirement is explicit: replace "depending on auth" with "Required
if cluster uses password authentication; otherwise can be omitted" (locate the
table cell containing `password` in the Trino connection options and update its
description accordingly).
🪄 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: 353dee69-4056-44a1-8f26-484cc011712b
📒 Files selected for processing (36)
docs/core/concepts/architecture.mddocs/core/concepts/benefits_llm.mddocs/core/concepts/memory_system.mddocs/core/concepts/skills.mddocs/core/concepts/what_is_context.mddocs/core/concepts/what_is_mdl.mddocs/core/get_started/connect.mddocs/core/get_started/installation.mddocs/core/get_started/quickstart.mddocs/core/guides/connect/athena.mddocs/core/guides/connect/bigquery.mddocs/core/guides/connect/clickhouse.mddocs/core/guides/connect/databricks.mddocs/core/guides/connect/duckdb.mddocs/core/guides/connect/mysql.mddocs/core/guides/connect/oracle.mddocs/core/guides/connect/overview.mddocs/core/guides/connect/postgresql.mddocs/core/guides/connect/redshift.mddocs/core/guides/connect/snowflake.mddocs/core/guides/connect/sqlserver.mddocs/core/guides/connect/trino.mddocs/core/guides/memory.mddocs/core/guides/modeling/model.mddocs/core/guides/modeling/overview.mddocs/core/guides/modeling/wren_project.mddocs/core/guides/profiles.mddocs/core/guides/use-with-agents/claude-code.mddocs/core/introduction.mdxdocs/core/reference/cli.mddocs/core/reference/mdl_schema.mddocs/core/reference/profile_yaml.mddocs/core/reference/skills.mddocs/core/sdk/langchain.mddocs/core/sdk/overview.mddocs/core/sdk/pydantic.md
💤 Files with no reviewable changes (2)
- docs/core/get_started/connect.md
- docs/core/concepts/benefits_llm.md
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (1)
docs/core/introduction.mdx (1)
83-84:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix product name spacing inconsistency.
Line 84 uses "WrenAI GenBI" (no space), but Line 143 uses "Wren AI GenBI" (with space). Consistent spacing should be maintained throughout.
✏️ Proposed fix
-Wren AI powers many agent-facing workflows. The flagship reference application is **WrenAI GenBI**, a chat-first BI app, but Wren AI is also used to wire governed warehouse access into chat bots, AI coding agent workflows, internal copilots, customer-facing analytics agents, and downstream BI surfaces that can talk to a SQL endpoint. +Wren AI powers many agent-facing workflows. The flagship reference application is **Wren AI GenBI**, a chat-first BI app, but Wren AI is also used to wire governed warehouse access into chat bots, AI coding agent workflows, internal copilots, customer-facing analytics agents, and downstream BI surfaces that can talk to a SQL endpoint.🤖 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` around lines 83 - 84, The product name spacing is inconsistent: replace the incorrect "WrenAI GenBI" occurrence with the standardized "Wren AI GenBI" so all mentions match; search for the string "WrenAI GenBI" in docs/core/introduction.mdx and update it to "Wren AI GenBI" to match other occurrences such as "Wren AI GenBI" used elsewhere in the file.
🧹 Nitpick comments (1)
docs/core/introduction.mdx (1)
11-11: 💤 Low valueConsider varying sentence structure for improved flow.
Three successive sentences begin with "It", which can feel repetitive. While the parallel structure may be intentional for emphasis, varying the opening could improve readability.
♻️ Alternative phrasing
-Your AI agent does not know what your data means. It reads schemas. It catches column names. It even reads your semantic-layer YAML. But it misses the things that actually decide whether an answer is right — that `status = 4` means refunded, that `loyalty_v3` is the table your team actually uses, that "monthly active users" excludes service accounts, that "Project Lighthouse" was renamed to `campaign_id = 4172` six months ago in a doc nobody linked to the warehouse. +Your AI agent does not know what your data means. It reads schemas, catches column names, and even parses your semantic-layer YAML. But it misses the things that actually decide whether an answer is right — that `status = 4` means refunded, that `loyalty_v3` is the table your team actually uses, that "monthly active users" excludes service accounts, that "Project Lighthouse" was renamed to `campaign_id = 4172` six months ago in a doc nobody linked to the warehouse.🤖 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 11, The three consecutive sentences in the paragraph all start with "It", creating repetitive rhythm; edit the sentence openings to vary structure while preserving meaning — e.g., start one sentence with "Your AI agent reads schemas and catches column names," another with "However, it can miss domain-specific rules such as `status = 4` meaning refunded," and a third with "For example, your team may use `loyalty_v3`, treat 'monthly active users' as excluding service accounts, or have renamed 'Project Lighthouse' to `campaign_id = 4172`." Use the unique tokens `status = 4`, `loyalty_v3`, "monthly active users", "Project Lighthouse", and `campaign_id = 4172` to ensure examples remain intact.
🤖 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 `@docs/core/guides/connect/bigquery.md`:
- Line 54: Update the error guidance text that currently reads "404 Not found:
Dataset — `dataset` is wrong" to consistently use the documented profile key
`dataset_id` so it reads something like "404 Not found: Dataset — `dataset_id`
is wrong or the SA doesn't have access to that dataset"; change the mention of
`dataset` to `dataset_id` wherever that specific error example "404 Not found:
Dataset" appears to avoid config-key confusion.
- Around line 9-11: Replace the direct pip install instruction (the line
containing pip install "wren-engine[bigquery,main]") with the new
skill-bundle-first onboarding flow: instruct users to run npx skills add
<bigquery-skill-bundle> (or the documented bundle name) followed by the
wren-onboarding command to complete setup; update any surrounding text to remove
manual install steps and instead reference the npx skills add and
wren-onboarding commands as the canonical OSS onboarding path.
- Around line 33-40: Update the Linux example so the base64 output is
single-line before pasting into BIGQUERY_CREDENTIALS in the .env: change the
Linux command to one that disables line wrapping (e.g., use base64 -w0 or pipe
through tr -d '\n') and mention that macOS already emits a single line; update
the docs/core/guides/connect/bigquery.md Linux block and the surrounding text so
readers know to produce a single-line base64 string safe for .env parsers and to
paste it into BIGQUERY_CREDENTIALS.
---
Duplicate comments:
In `@docs/core/introduction.mdx`:
- Around line 83-84: The product name spacing is inconsistent: replace the
incorrect "WrenAI GenBI" occurrence with the standardized "Wren AI GenBI" so all
mentions match; search for the string "WrenAI GenBI" in
docs/core/introduction.mdx and update it to "Wren AI GenBI" to match other
occurrences such as "Wren AI GenBI" used elsewhere in the file.
---
Nitpick comments:
In `@docs/core/introduction.mdx`:
- Line 11: The three consecutive sentences in the paragraph all start with "It",
creating repetitive rhythm; edit the sentence openings to vary structure while
preserving meaning — e.g., start one sentence with "Your AI agent reads schemas
and catches column names," another with "However, it can miss domain-specific
rules such as `status = 4` meaning refunded," and a third with "For example,
your team may use `loyalty_v3`, treat 'monthly active users' as excluding
service accounts, or have renamed 'Project Lighthouse' to `campaign_id = 4172`."
Use the unique tokens `status = 4`, `loyalty_v3`, "monthly active users",
"Project Lighthouse", and `campaign_id = 4172` to ensure examples remain intact.
🪄 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: 99d04b52-ae9c-4b08-92b7-a8c25ca8056e
📒 Files selected for processing (10)
docs/core/concepts/memory_system.mddocs/core/concepts/skills.mddocs/core/get_started/installation.mddocs/core/guides/connect/bigquery.mddocs/core/guides/connect/overview.mddocs/core/guides/connect/spark.mddocs/core/guides/use-with-agents/claude-code.mddocs/core/introduction.mdxdocs/core/reference/mdl_schema.mddocs/core/reference/profile_yaml.md
✅ Files skipped from review due to trivial changes (5)
- docs/core/guides/connect/spark.md
- docs/core/concepts/skills.md
- docs/core/reference/profile_yaml.md
- docs/core/reference/mdl_schema.md
- docs/core/guides/connect/overview.md
🚧 Files skipped from review as they are similar to previous changes (3)
- docs/core/concepts/memory_system.md
- docs/core/guides/use-with-agents/claude-code.md
- docs/core/get_started/installation.md
PaulChen79
force-pushed
the
refactor/document
branch
2 times, most recently
from
f08c679 to
2cb982d
Compare
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (2)
docs/core/guides/connect/mysql.md (1)
5-5: ⚡ Quick winAdd preposition for grammatical correctness.
The title "Connect MySQL" is missing the preposition "to". It should read "Connect to MySQL" for proper English grammar and consistency with standard technical documentation style.
✏️ Proposed fix
-# Connect MySQL +# Connect to MySQL🤖 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/guides/connect/mysql.md` at line 5, Update the document title string "Connect MySQL" to include the missing preposition so it reads "Connect to MySQL"; locate the heading text (currently "Connect MySQL") in the docs/core/guides/connect/mysql.md content and replace it with "Connect to MySQL" to correct grammar and match documentation style.docs/core/introduction.mdx (1)
11-11: 💤 Low valueConsider reducing content duplication across documentation files.
The opening paragraph at line 11 ("Your AI agent does not know what your data means...") is duplicated verbatim in
docs/core/concepts/what_is_context.mdat line 3. While the repetition serves both documents well, duplicated content can create maintenance overhead if the messaging needs to evolve.Consider either:
- Keeping the duplication but documenting it as intentional shared messaging
- Slightly varying the framing in each context to reduce exact duplication
- Cross-referencing rather than duplicating (though this may hurt readability)
🤖 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 11, The opening paragraph text "Your AI agent does not know what your data means. It reads schemas. It catches column names..." is duplicated verbatim in another doc; decide whether to (A) mark the duplication as intentional shared messaging, (B) alter the framing in one of the occurrences to avoid exact duplication, or (C) replace one occurrence with a cross-reference to the other; then update the two documents to implement the chosen approach (edit the duplicated sentence, add a short note stating it's shared messaging, or insert a cross-reference link), and run a quick search for the exact paragraph to ensure no other identical copies remain.
🤖 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 `@docs/core/guides/connect/mysql.md`:
- Around line 37-44: The docs table is inconsistent for the `port` field: either
mark `port` as optional and keep "Default `3306`" in the description, or keep
`port` as required and remove the default text; update the row for `port` in the
table (the line containing `| `port` | yes | Default `3306` |`) to reflect the
correct behavior (e.g., change `yes` to `no` if it truly defaults to 3306, or
remove "Default `3306`" if the caller must supply it) and ensure the
accompanying description clearly states the default behavior when optional.
In `@docs/core/introduction.mdx`:
- Line 13: The documentation references four missing image assets in
docs/core/introduction.mdx; add the PNG files with the exact filenames used in
the markdown (/img/oss/vision/vision-paper-02-agent-lacks-business-meaning.png,
/img/oss/vision/vision-paper-03-five-layers-of-context.png,
/img/oss/vision/vision-paper-04-correctness-system.png,
/img/oss/vision/vision-paper-05-scaffold-fast-enrich-deep.png) into the
repository under the img/oss/vision directory so the markdown image links in
introduction.mdx resolve and render correctly.
- Line 25: Update the two broken documentation links referenced as
'/oss/overview/introduction' (in the GenBI sunset notice) and
'/oss/genbi/upgrade-to-commercial' (in the upgrade information) so they point to
valid pages or create the missing pages; locate the occurrences of these exact
link strings in the introduction content and either replace them with the
correct existing paths or add the new docs at those routes, then verify
navigation works for both the GenBI sunset notice and the upgrade-to-commercial
link.
---
Nitpick comments:
In `@docs/core/guides/connect/mysql.md`:
- Line 5: Update the document title string "Connect MySQL" to include the
missing preposition so it reads "Connect to MySQL"; locate the heading text
(currently "Connect MySQL") in the docs/core/guides/connect/mysql.md content and
replace it with "Connect to MySQL" to correct grammar and match documentation
style.
In `@docs/core/introduction.mdx`:
- Line 11: The opening paragraph text "Your AI agent does not know what your
data means. It reads schemas. It catches column names..." is duplicated verbatim
in another doc; decide whether to (A) mark the duplication as intentional shared
messaging, (B) alter the framing in one of the occurrences to avoid exact
duplication, or (C) replace one occurrence with a cross-reference to the other;
then update the two documents to implement the chosen approach (edit the
duplicated sentence, add a short note stating it's shared messaging, or insert a
cross-reference link), and run a quick search for the exact paragraph to ensure
no other identical copies remain.
🪄 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: d7420892-cc87-45c7-89ee-9362dc4efe43
📒 Files selected for processing (38)
docs/core/.sync.ymldocs/core/concepts/architecture.mddocs/core/concepts/benefits_llm.mddocs/core/concepts/memory_system.mddocs/core/concepts/skills.mddocs/core/concepts/what_is_context.mddocs/core/concepts/what_is_mdl.mddocs/core/get_started/connect.mddocs/core/get_started/installation.mddocs/core/get_started/quickstart.mddocs/core/guides/connect/athena.mddocs/core/guides/connect/bigquery.mddocs/core/guides/connect/clickhouse.mddocs/core/guides/connect/databricks.mddocs/core/guides/connect/duckdb.mddocs/core/guides/connect/mysql.mddocs/core/guides/connect/oracle.mddocs/core/guides/connect/overview.mddocs/core/guides/connect/postgresql.mddocs/core/guides/connect/redshift.mddocs/core/guides/connect/snowflake.mddocs/core/guides/connect/spark.mddocs/core/guides/connect/sqlserver.mddocs/core/guides/connect/trino.mddocs/core/guides/memory.mddocs/core/guides/modeling/model.mddocs/core/guides/modeling/overview.mddocs/core/guides/modeling/wren_project.mddocs/core/guides/profiles.mddocs/core/guides/use-with-agents/claude-code.mddocs/core/introduction.mdxdocs/core/reference/cli.mddocs/core/reference/mdl_schema.mddocs/core/reference/profile_yaml.mddocs/core/reference/skills.mddocs/core/sdk/langchain.mddocs/core/sdk/overview.mddocs/core/sdk/pydantic.md
💤 Files with no reviewable changes (2)
- docs/core/concepts/benefits_llm.md
- docs/core/get_started/connect.md
✅ Files skipped from review due to trivial changes (30)
- docs/core/guides/connect/clickhouse.md
- docs/core/guides/connect/trino.md
- docs/core/guides/connect/snowflake.md
- docs/core/guides/connect/redshift.md
- docs/core/guides/modeling/overview.md
- docs/core/guides/connect/databricks.md
- docs/core/guides/modeling/model.md
- docs/core/concepts/memory_system.md
- docs/core/guides/connect/athena.md
- docs/core/guides/profiles.md
- docs/core/reference/cli.md
- docs/core/guides/connect/postgresql.md
- docs/core/guides/connect/sqlserver.md
- docs/core/guides/connect/oracle.md
- docs/core/.sync.yml
- docs/core/concepts/skills.md
- docs/core/reference/profile_yaml.md
- docs/core/guides/memory.md
- docs/core/reference/mdl_schema.md
- docs/core/guides/connect/bigquery.md
- docs/core/guides/modeling/wren_project.md
- docs/core/get_started/quickstart.md
- docs/core/guides/use-with-agents/claude-code.md
- docs/core/concepts/what_is_mdl.md
- docs/core/get_started/installation.md
- docs/core/sdk/overview.md
- docs/core/sdk/pydantic.md
- docs/core/guides/connect/overview.md
- docs/core/guides/connect/spark.md
- docs/core/reference/skills.md
🚧 Files skipped from review as they are similar to previous changes (3)
- docs/core/sdk/langchain.md
- docs/core/concepts/architecture.md
- docs/core/guides/connect/duckdb.md
Major content + IA refactor for the Wren AI Core docs. Aligns the doc set with our positioning as an open context layer for AI agents (per the team vision review) and trims competitor names per review feedback. Structure - Move connect.md from get_started/ to guides/connect/ and split into one page per data source (DuckDB, Postgres, MySQL, BigQuery, Snowflake, ClickHouse, Trino, SQL Server, Databricks, Redshift, Oracle, Athena) + overview page. - Add Concepts pages: skills, memory_system. Merge benefits_llm into what_is_context with the five-layers-of-context framing from the vision paper. Rewrite architecture around the "correctness as a system" six pillars. - Add Reference pages: mdl_schema, profile_yaml. - Add guides/use-with-agents/claude-code.md. Content - Rebrand: drop "Wren AI Core" / "Wren Engine 1.x" references — product name is just "Wren AI" everywhere. - Remove third-party brand names per team review (dbt / Cube / Lightdash / AtScale / Hex / Mode / Metabase / Superset / Notion). Keep neutral framings where the comparison was making a point. - Remove MCP references from active OSS docs (MCP is no longer the story we lead with; the SDK / skills layer is). - Update Installation flow to be agent-driven by design: skill bundle first (`npx skills add Canner/WrenAI --skill '*'`), then ask the agent to run wren-onboarding. Drop the manual install path. - Update Quickstart with an inline "Terms used" mini-glossary so the jaffle_shop / MDL / Skills jargon isn't dropped on a new reader. - Memory page: clarify the `memory` extra is now opt-in (not bundled in `main`). - Pass through grammar / flow polish: passive→active voice, weak verbs, parallel structure on H3 lists, acronym expansion on first occurrence, dead-link / outdated-path cleanup.
- Group A copy fixes: install command flag, brand consistency, hyphenation, code block lang tags - MDL table_reference: rename database → catalog, mark catalog/schema optional - Relationships: wrap in relationships: key, rename type → join_type, uppercase enums - BigQuery profile: credentials (base64) instead of credentials_path, dataset_id, drop nonexistent location - Snowflake account: clarify locator format, not full hostname - Profile storage: single ~/.wren/profiles.yml, not per-profile directory - Add Spark connector page; surface in overview supported list Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
PaulChen79
force-pushed
the
refactor/document
branch
from
2cb982d to
ca70dd7
Compare
goldmedal
reviewed
May 15, 2026
Collaborator
Review notesRead through carefully and verified claims against the codebase ( High — incorrect connector / profile fields
DuckDB, ClickHouse, and Spark look correct. Suggested fix: regenerate the "Profile fields" block on each High — incorrect CLI flags
Medium — skills install identifier mismatchDocs use Low
CIDocs-only — none of the engine-side gates run. Just the docs-site sync workflow. With |
The reference page duplicated guides/modeling/wren_project.md and had gone stale (missing schema_version, ref_sql, dialect, column flags, field mapping). Consolidating onto the project guide as the single source of truth for MDL schema details. Repoint the inbound link from get_started/quickstart.md to the guide. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…tifier Address goldmedal review on #2285: * Replace 14 per-connector pages and overview with a single docs/core/guides/connect.md that points users to `wren docs connection-info <ds>` for field details. The CLI command is always in sync with the engine's Pydantic schema, removing the drift risk that flagged most of the review. * reference/cli.md: `wren docs connection-info <ds>` is positional, not --datasource. * guides/use-with-agents/claude-code.md: drop the `wren memory store --pinned` tip — the flag does not exist on the CLI. * skills/install.sh + skills/README.md: flip the repo identifier from Canner/wren-engine to Canner/WrenAI to match the docs and the post-merge repo layout. * Repoint all inbound /oss/guides/connect/overview links to /oss/guides/connect. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Collaborator
Round 2 reviewSolid response. Key fixes verified:
One miss
Since per-DB pages are gone, Two ways to close this:
I'd lean toward delete — half a reference page contradicting the CLI is worse than no reference page. Nothing else blocking from my side. |
goldmedal round-2 review: with per-connector pages now deferring to `wren docs connection-info <ds>`, profile_yaml.md was the only doc still hand-rolling YAML examples — and it kept several inaccurate fields (Postgres `url`/`sslmode`, MySQL `ssl`, Snowflake `role`). Half a reference contradicting the CLI is worse than no reference. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Collaborator
Round 3 — LGTM
PR scope is now +454 / −813 across 26 files — net reduction, mostly narrative work and structure. No remaining blockers from my side. |
goldmedal
approved these changes
May 15, 2026
This was referenced May 20, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Major content + IA refactor for the Wren AI Core docs. Aligns the doc set with our positioning as an open context layer for AI agents (per the team vision review) and trims competitor / brand mentions per review feedback.
Structure changes
Content changes
Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit