fix(skills,docs): reorder flow — register MCP before generate-mdl

The previous ordering had generate-mdl (Phase 2) before MCP
registration (Phase 3). This meant agents had no MCP tools available
and fell back to calling ibis-server API directly, bypassing
connection info and hitting confusing errors.

New order across all docs and skills:
1. Start Docker container
2. Configure connection (Web UI) + Register MCP + New session
3. Generate MDL (via MCP tools)
4. Verify and query

Affected files:
- wren-quickstart skill (1.2 → 1.3)
- docs/quickstart.md Option B
- docs/getting_started_with_claude_code.md manual setup

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: goldmedal

docs/getting_started_with_claude_code.md

@@ -156,23 +156,43 @@ docker logs wren-mcp
 
 > **Database on localhost?** If your database runs on your host machine, replace `localhost` / `127.0.0.1` with `host.docker.internal` in your connection settings — the container cannot reach the host's `localhost` directly.
 
-### Phase 3 — Generate the MDL
+### Phase 3 — Configure connection and register MCP server
 
-In Claude Code, run:
+Configure connection info in the Web UI at `http://localhost:9001` — select the data source type and enter credentials. Use `/wren-connection-info` in Claude Code for field reference per data source.
+
+> **Connection info can only be configured through the Web UI.** Do not attempt to set it programmatically.
+
+Then register the MCP server with Claude Code:
+
+```bash
+claude mcp add --transport http wren http://localhost:9000/mcp
+```
+
+Verify it was added:
+
+```bash
+claude mcp list
+```
+
+**Start a new Claude Code session** — MCP servers are only loaded at session start.
+
+### Phase 4 — Generate the MDL
+
+In the new session, run:
 
 ```
 /generate-mdl
 ```
 
 The skill will:
 
-1. Run `health_check()` to verify the connection is configured
+1. Run `health_check()` to verify the connection is working
 2. Ask for your data source type (PostgreSQL, BigQuery, Snowflake, etc.) and optional schema filter
-3. Call `list_remote_tables()` and `list_remote_constraints()` via the MCP server to introspect your database schema
+3. Call `list_remote_tables()` and `list_remote_constraints()` via MCP tools to introspect your database schema
 4. Build the MDL JSON (models, columns, relationships)
 5. Validate the manifest with `deploy_manifest()` + `dry_run()`
 
-> **Connection info** must be configured in the Web UI (`http://localhost:9001`) before running `/generate-mdl`. Use `/wren-connection-info` in Claude Code for field reference per data source.
+> **Prerequisite:** The MCP server must be registered and a new session started (Phase 3). The `/generate-mdl` skill uses MCP tools — do not call ibis-server API directly.
 
 Then save the MDL as a versioned YAML project:
 
@@ -182,22 +202,6 @@ Then save the MDL as a versioned YAML project:
 
 This writes human-readable YAML files to your workspace and compiles `target/mdl.json`.
 
-### Phase 4 — Register the MCP server
-
-Add Wren to Claude Code's MCP configuration:
-
-```bash
-claude mcp add --transport http wren http://localhost:9000/mcp
-```
-
-Verify it was added:
-
-```bash
-claude mcp list
-```
-
-**Start a new Claude Code session** — MCP servers are only loaded at session start.
-
 ---
 
 ## Verify and start querying

docs/quickstart.md

@@ -141,9 +141,9 @@ docker ps --filter name=wren-mcp
 curl http://localhost:8000/health
 ```
 
-#### Phase 2 — Configure the connection and generate the MDL
+#### Phase 2 — Configure connection and register MCP server
 
-Before generating the MDL, configure the DuckDB connection via the Web UI at `http://localhost:9001`:
+Configure the DuckDB connection via the Web UI at `http://localhost:9001`:
 
 1. Open `http://localhost:9001` in your browser
 2. Select data source type: **DUCKDB**
@@ -161,33 +161,37 @@ The JSON looks like:
 
 > **Common mistake:** Do not point `url` to the `.duckdb` file directly (e.g. `/data/jaffle_shop.duckdb`). The ibis-server expects a **directory** — it scans for all `.duckdb` files in that directory and attaches them automatically. Pointing to the binary file causes a UTF-8 decode error.
 
-After saving the connection, run the skills in sequence in Claude Code:
+Then register the MCP server with Claude Code:
 
-```text
-/generate-mdl
+```bash
+claude mcp add --transport http wren http://localhost:9000/mcp
 ```
 
-Then save the MDL as a versioned YAML project:
+Verify it was added:
 
-```text
-/wren-project
+```bash
+claude mcp list
 ```
 
-This writes human-readable YAML files to `~/wren-workspace/` and compiles `target/mdl.json`.
+**Start a new Claude Code session** — MCP servers are only loaded at session start.
 
-#### Phase 3 — Register the MCP server
+#### Phase 3 — Generate the MDL
 
-```bash
-claude mcp add --transport http wren http://localhost:9000/mcp
+In the new session, run the skills in sequence:
+
+```text
+/generate-mdl
 ```
 
-Verify it was added:
+The skill uses MCP tools (`health_check()`, `list_remote_tables()`, etc.) to introspect the database — these tools are only available after the MCP server is registered and a new session is started.
 
-```bash
-claude mcp list
+Then save the MDL as a versioned YAML project:
+
+```text
+/wren-project
 ```
 
-**Start a new Claude Code session** — MCP servers are only loaded at session start.
+This writes human-readable YAML files to `~/wren-workspace/` and compiles `target/mdl.json`.
 
 </details>
 

skills/index.json

@@ -82,7 +82,7 @@
     },
     {
       "name": "wren-quickstart",
-      "version": "1.2",
+      "version": "1.3",
       "description": "End-to-end quickstart for Wren Engine — from zero to querying.",
       "tags": [
         "wren",

skills/versions.json

@@ -4,6 +4,6 @@
   "wren-project": "1.5",
   "wren-sql": "1.0",
   "wren-mcp-setup": "1.3",
-  "wren-quickstart": "1.2",
+  "wren-quickstart": "1.3",
   "wren-usage": "1.1"
 }

skills/wren-quickstart/SKILL.md

@@ -5,18 +5,18 @@ compatibility: Requires Docker Desktop (or Docker Engine). No local database dri
 license: Apache-2.0
 metadata:
   author: wren-engine
-  version: "1.2"
+  version: "1.3"
 ---
 
 # Wren Quickstart
 
 ## Version check
 
 Silently fetch `https://raw.githubusercontent.com/Canner/wren-engine/main/skills/versions.json`.
-Compare the `wren-quickstart` key with this skill's version (`1.2`).
+Compare the `wren-quickstart` key with this skill's version (`1.3`).
 If the remote version is newer, notify the user before proceeding:
 
-> A newer version of the **wren-quickstart** skill is available (remote: X.Y, installed: 1.2).
+> A newer version of the **wren-quickstart** skill is available (remote: X.Y, installed: 1.3).
 > Update with:
 > ```bash
 > curl -fsSL https://raw.githubusercontent.com/Canner/wren-engine/main/skills/install.sh | bash -s -- --force wren-quickstart
@@ -74,86 +74,85 @@ Recommended workspace layout after the quickstart completes:
 
 ---
 
-## Phase 2 — Generate MDL and save project
+## Phase 2 — Start Docker container and register MCP server
 
-### 2a — Generate MDL
-
-Invoke the **generate-mdl** skill to introspect the user's database and build the MDL manifest:
+Invoke the **wren-mcp-setup** skill to start the Docker container and register the MCP server with the AI client:
 
 ```
-@generate-mdl
+@wren-mcp-setup
 ```
 
-The generate-mdl skill will:
-1. Ask for data source type and connection credentials
-2. Call ibis-server to fetch table schema and foreign key constraints
-3. Build the MDL JSON (models, columns, relationships)
-4. Validate the manifest with a dry-plan
+Pass `<WORKSPACE_PATH>` as the workspace mount path when the skill asks.
 
-> **Important:** At this stage ibis-server may not be running yet. If the user has not started a container, proceed to Phase 3 first (start the container), then come back to generate the MDL using the running ibis-server on port 8000.
->
-> Alternatively, if the user already has a running ibis-server, run Phase 2 before Phase 3.
+The wren-mcp-setup skill will:
+1. Start the container with `-v <WORKSPACE_PATH>:/workspace`
+2. Set `MDL_PATH=/workspace/target/mdl.json`
+3. Register the MCP server with the AI client (`claude mcp add`)
+4. Verify the container is running
 
-### 2b — Save as YAML project
+### 2b — Configure connection info via Web UI
 
-After the MDL is generated, invoke the **wren-project** skill to save it as a versioned YAML project inside the workspace:
+Once the container is running, open the MCP server Web UI to configure connection info:
 
-```
-@wren-project
+```text
+http://localhost:9001
 ```
 
-Direct the skill to write the project files into `<WORKSPACE_PATH>`:
+Enter the data source credentials (host, port, database, user, password, etc.) in the UI form and save. The MCP server stores and applies the connection info without exposing credentials to this conversation.
 
-- `<WORKSPACE_PATH>/wren_project.yml`
-- `<WORKSPACE_PATH>/models/*.yml`
-- `<WORKSPACE_PATH>/relationships.yml`
-- `<WORKSPACE_PATH>/views.yml`
+> **Tip:** If your database is running locally, use `host.docker.internal` instead of `localhost` as the host address.
 
-Then build the compiled target:
+### 2c — Start a new session
 
-- `<WORKSPACE_PATH>/target/mdl.json`
+The user must **start a new Claude Code session** for the Wren MCP tools to be loaded. Instruct the user to do this now and come back to continue with Phase 3.
 
-The Docker container will auto-load this file at startup.
+> **Important:** Do not proceed to Phase 3 until the new session is started. The `generate-mdl` skill requires MCP tools (`health_check()`, `list_remote_tables()`, etc.) which are only available after the MCP server is registered and a new session is started.
 
 ---
 
-## Phase 3 — Start and register the MCP server
+## Phase 3 — Generate MDL and save project
 
-Invoke the **wren-mcp-setup** skill to start the Docker container and register the MCP server with the AI client:
+> **Prerequisite:** The MCP server must be registered and a new session started (Phase 2c). The `generate-mdl` skill uses MCP tools — do not call ibis-server API directly.
+
+### 3a — Generate MDL
+
+Invoke the **generate-mdl** skill to introspect the user's database and build the MDL manifest:
 
 ```
-@wren-mcp-setup
+@generate-mdl
 ```
 
-Pass `<WORKSPACE_PATH>` as the workspace mount path when the skill asks.
+The generate-mdl skill will:
+1. Run `health_check()` to verify the connection is working
+2. Ask for data source type and optional schema filter
+3. Call `list_remote_tables()` and `list_remote_constraints()` via MCP to fetch schema
+4. Build the MDL JSON (models, columns, relationships)
+5. Validate the manifest with `deploy_manifest()` + `dry_run()`
 
-The wren-mcp-setup skill will:
-1. Start the container with `-v <WORKSPACE_PATH>:/workspace`
-2. Set `MDL_PATH=/workspace/target/mdl.json`
-3. Register the MCP server with the AI client (`claude mcp add`)
-4. Verify the container is running
+### 3b — Save as YAML project
 
-> If `<WORKSPACE_PATH>/target/mdl.json` already exists before the container starts, it is loaded automatically at boot. No separate `deploy` call is needed.
+After the MDL is generated, invoke the **wren-project** skill to save it as a versioned YAML project inside the workspace:
 
-### 3b — Configure connection info via Web UI
+```
+@wren-project
+```
 
-Once the container is running, open the MCP server Web UI to configure connection info:
+Direct the skill to write the project files into `<WORKSPACE_PATH>`:
 
-```text
-http://localhost:9001
-```
+- `<WORKSPACE_PATH>/wren_project.yml`
+- `<WORKSPACE_PATH>/models/*.yml`
+- `<WORKSPACE_PATH>/relationships.yml`
+- `<WORKSPACE_PATH>/views.yml`
 
-Enter the data source credentials (host, port, database, user, password, etc.) in the UI form and save. The MCP server stores and applies the connection info without exposing credentials to this conversation.
+Then build the compiled target:
 
-> **Tip:** If your database is running locally, use `host.docker.internal` instead of `localhost` as the host address.
+- `<WORKSPACE_PATH>/target/mdl.json`
 
 ---
 
-## Phase 4 — Verify and confirm
-
-Once the MCP server is registered, the user must **start a new session** for the Wren MCP tools to be loaded. Instruct the user to do this now.
+## Phase 4 — Verify and start querying
 
-In the new session, ask the AI agent to run a health check:
+Run a health check to confirm everything is working:
 
 ```
 Use health_check() to verify Wren Engine is reachable.
@@ -164,7 +163,7 @@ Expected response: `SELECT 1` returns successfully.
 If the health check passes:
 
 - Tell the user setup is complete.
-- In this session, they can start querying immediately:
+- They can start querying immediately:
 
 ```
 Query: How many orders are in the orders table?
@@ -178,24 +177,22 @@ If the health check fails, follow the troubleshooting steps in the **wren-mcp-se
 
 | Phase | Skill | Purpose |
 |-------|-------|---------|
-| 2a | `@generate-mdl` | Introspect database and build MDL JSON |
-| 2b | `@wren-project` | Save MDL as YAML project + compile to `target/` |
-| 3 | `@wren-mcp-setup` | Start Docker container and register MCP server |
+| 2 | `@wren-mcp-setup` | Start Docker container and register MCP server |
+| 3a | `@generate-mdl` | Introspect database and build MDL JSON |
+| 3b | `@wren-project` | Save MDL as YAML project + compile to `target/` |
 
 ---
 
 ## Troubleshooting
 
-**Container not finding MDL at startup:**
-- Confirm `<WORKSPACE_PATH>/target/mdl.json` exists before starting the container.
-- Check container logs: `docker logs wren-mcp`
-
-**generate-mdl fails because ibis-server is not yet running:**
-- Start the container first (Phase 3), then return to Phase 2.
-- ibis-server is available at `http://localhost:8000` once the container is up.
-
-**MCP tools not available after registration:**
+**MCP tools not available:**
 - The MCP server is only loaded at session start. Start a new Claude Code session after registering.
+- Do not attempt to call ibis-server API directly — always use MCP tools.
+
+**generate-mdl fails:**
+- Ensure the container is running: `docker ps --filter name=wren-mcp`
+- Ensure connection info is configured in the Web UI (`http://localhost:9001`)
+- Ensure a new session was started after `claude mcp add`
 
 **Database connection refused inside Docker:**
 - Change `localhost` / `127.0.0.1` to `host.docker.internal` in connection credentials.