docs(wren): clarify catalog/schema as Wren Engine namespace, not DB settings

cli-skills/wren-generate-mdl/SKILL.md

@@ -154,6 +154,16 @@ project/
 └── instructions.md
 ```
 
+> **IMPORTANT: `catalog` and `schema` in `wren_project.yml`**
+>
+> These are Wren Engine's internal namespace — they are NOT the database's
+> native catalog or schema. Always keep the defaults:
+> - `catalog: wren`
+> - `schema: public`
+>
+> The actual database catalog/schema is specified per-model in `table_reference`.
+> Do NOT copy database catalog/schema values into `wren_project.yml`.
+
 ### Step 2 — Write model files
 
 For each table, create a YAML file under `models/`. Use snake_case
@@ -163,9 +173,9 @@ naming (the build step converts to camelCase automatically).
 # models/orders/metadata.yml
 name: orders
 table_reference:
-  catalog: ""
-  schema: public
-  table: orders
+  catalog: ""           # database catalog (empty string if not applicable)
+  schema: public        # database schema (this IS the DB schema)
+  table: orders         # database table name
 primary_key: order_id
 columns:
   - name: order_id

wren/docs/wren_project.md

@@ -98,10 +98,25 @@ data_source: postgres
 | `schema_version` | Directory layout version. `2` = folder-per-entity (current). Owned by the CLI — do not bump manually. |
 | `name` | Project name |
 | `version` | User's own project version (free-form, no effect on parsing) |
-| `catalog` | MDL catalog |
-| `schema` | MDL schema |
+| `catalog` | **Wren Engine namespace** — NOT your database catalog. Identifies this MDL project within the engine. Default: `wren`. |
+| `schema` | **Wren Engine namespace** — NOT your database schema. Default: `public`. |
 | `data_source` | Data source type (e.g. `postgres`, `bigquery`, `snowflake`) |
 
+> **`catalog` / `schema` are NOT database settings.**
+>
+> These two fields define the Wren Engine's internal namespace for addressing models in SQL. They exist to support future multi-project querying. For single-project use, keep the defaults (`catalog: wren`, `schema: public`).
+>
+> Your database's actual catalog and schema are specified per-model in the `table_reference` section of each model's `metadata.yml`.
+
+#### Two levels of catalog/schema
+
+The same field names appear in two places with completely different meanings:
+
+| Location | Refers to | Example | When to change |
+|----------|-----------|---------|----------------|
+| `wren_project.yml` → `catalog`, `schema` | Wren Engine namespace | `wren`, `public` | Only for multi-project setups |
+| `models/*/metadata.yml` → `table_reference.catalog`, `table_reference.schema` | Database location | `""`, `main` | Must match your actual database |
+
 ### Model (`models/<name>/metadata.yml`)
 
 A model must define its source in exactly one of two ways:

wren/src/wren/context_cli.py

@@ -52,9 +52,14 @@ def init(
         "schema_version: 2\n"
         "name: my_project\n"
         'version: "1.0"\n'
+        "\n"
+        "# Wren Engine namespace (NOT your database's catalog/schema).\n"
+        "# These identify this MDL project within the engine.\n"
+        "# Your database's actual catalog/schema goes in each model's table_reference.\n"
         "catalog: wren\n"
         "schema: public\n"
-        "data_source: postgres\n"
+        "\n"
+        "data_source: postgres  # change to your datasource type\n"
     )
     project_file.write_text(project_yml)
 
@@ -64,10 +69,11 @@ def init(
     (example_model_dir / "metadata.yml").write_text(
         "# Example model — replace with your actual table\n"
         "name: example\n"
+        "# table_reference points to the ACTUAL database table location\n"
         "table_reference:\n"
-        '  catalog: ""\n'
-        "  schema: public\n"
-        "  table: example\n"
+        '  catalog: ""        # your database catalog (empty if N/A)\n'
+        "  schema: public      # your database schema\n"
+        "  table: example      # your database table name\n"
         "columns:\n"
         "  - name: id\n"
         "    type: INTEGER\n"