From 0c0172ff5b94e648441eaedb1ec1c586b0b0dff6 Mon Sep 17 00:00:00 2001 From: Jax Liu Date: Sun, 5 Apr 2026 22:30:16 +0800 Subject: [PATCH 1/2] docs(quickstart): fix prerequisites and add venv setup step - Bump Python requirement from 3.9+ to 3.11+ (matches pyproject.toml) - Add Node.js/npm to prerequisites (required for npx) - Add Step 0 for creating a shared Python virtual environment - Remove per-project venv from Step 1 (now handled by Step 0) - Remove incorrect note about restarting Claude Code session after skill install Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/quickstart.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index 0b4f6ee9f..17be9c22f 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -11,11 +11,25 @@ Use natural-language questions against the **jaffle\_shop** dataset using **Wren ## Prerequisites - **Claude Code** — installed and authenticated ([install guide](https://docs.anthropic.com/en/docs/claude-code/overview)) -- **Python 3.9+** +- **Python 3.11+** +- **Node.js / npm** — required for `npx` skill installer - **Git** --- +## Step 0 — Create a Python virtual environment + +Create and activate a virtual environment before installing any packages. This keeps dbt and wren-engine dependencies isolated from your system Python: + +```bash +python3 -m venv ~/.venvs/wren +source ~/.venvs/wren/bin/activate +``` + +> **Tip:** Activate this environment (`source ~/.venvs/wren/bin/activate`) in every new terminal session before running `dbt` or `wren` commands. + +--- + ## Step 1 — Seed the jaffle_shop dataset Clone the dbt jaffle\_shop project and build the DuckDB database: @@ -23,8 +37,6 @@ Clone the dbt jaffle\_shop project and build the DuckDB database: ```bash git clone https://github.com/dbt-labs/jaffle_shop_duckdb.git cd jaffle_shop_duckdb -python3 -m venv .venv -source .venv/bin/activate pip install dbt-core dbt-duckdb dbt build ``` @@ -82,7 +94,6 @@ This installs two skills: | **wren-usage** | Day-to-day workflow — gather context, recall past queries, write SQL, store results | | **wren-generate-mdl** | One-time setup — explore database schema and generate the MDL project | -> **Important:** Start a **new Claude Code session** after installing skills so they are loaded. --- From 66f5ba14f0a1bb1e3ce8a8369ae693acfe985222 Mon Sep 17 00:00:00 2001 From: Jax Liu Date: Sun, 5 Apr 2026 22:34:26 +0800 Subject: [PATCH 2/2] docs(quickstart): fix CLI flags, profile example, and simplify Step 5 - Fix memory fetch/recall flag from --question to --query - Add format: duckdb to from-file profile example (required for attach) - Mark Node.js/npm as conditional prerequisite (npx only) - Simplify Step 5: remove redundant manual wren_project.yml edit - Clean up extra blank line Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/quickstart.md | 23 ++++++----------------- 1 file changed, 6 insertions(+), 17 deletions(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index 17be9c22f..635ee2ff9 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -12,7 +12,7 @@ Use natural-language questions against the **jaffle\_shop** dataset using **Wren - **Claude Code** — installed and authenticated ([install guide](https://docs.anthropic.com/en/docs/claude-code/overview)) - **Python 3.11+** -- **Node.js / npm** — required for `npx` skill installer +- **Node.js / npm** — required if using `npx` to install skills (see Step 3) - **Git** --- @@ -94,7 +94,6 @@ This installs two skills: | **wren-usage** | Day-to-day workflow — gather context, recall past queries, write SQL, store results | | **wren-generate-mdl** | One-time setup — explore database schema and generate the MDL project | - --- ## Step 4 — Set up a profile @@ -128,6 +127,7 @@ Create a YAML file `jaffle-profile.yml`: ```yaml datasource: duckdb url: /Users/you/jaffle_shop_duckdb +format: duckdb ``` Then import it: @@ -172,20 +172,9 @@ This creates: └── instructions.md # business rules for the AI ``` -Edit `wren_project.yml` to set the data source: - -```yaml -schema_version: 2 -name: jaffle_shop -version: "1.0" -# catalog and schema are Wren Engine's internal namespace for this MDL project. -# They are NOT your database's native catalog/schema. Keep the defaults. -catalog: wren -schema: public -data_source: duckdb -``` +The generated `wren_project.yml` contains default values for `catalog` and `schema`: -> **Note:** `catalog` and `schema` here define the **Wren Engine namespace** — how the engine addresses this MDL project internally. They have nothing to do with your database's catalog or schema. The actual database location of each table is specified per-model in the `table_reference` section. Keep the defaults (`wren` / `public`) unless you plan to query across multiple MDL projects. +> **Note:** `catalog` and `schema` in `wren_project.yml` define the **Wren Engine namespace** — they have nothing to do with your database's catalog or schema. Keep the defaults (`wren` / `public`). The actual database location of each table is specified per-model in the `table_reference` section. --- @@ -315,8 +304,8 @@ wren memory index | Show project context | `wren context show` | | Show instructions | `wren context instructions` | | Build manifest | `wren context build` | -| Fetch context for a question | `wren memory fetch --question "..."` | -| Recall similar queries | `wren memory recall --question "..."` | +| Fetch context for a question | `wren memory fetch --query "..."` | +| Recall similar queries | `wren memory recall --query "..."` | | Store a NL-SQL pair | `wren memory store --nl "..." --sql "..."` | | Check memory status | `wren memory status` | | Re-index memory | `wren memory index` |