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

[goldmedal]

Summary

• context_cli.py: Add inline comments to the wren context init template so catalog/schema are clearly marked as Wren Engine namespace fields — not the database catalog/schema. Also annotate the example model table_reference to make clear that IS the actual database location.
• wren_project.md: Expand the catalog/schema field descriptions with an explicit callout and add a two-level distinction table showing where each level of catalog/schema lives and what it refers to.
• wren-generate-mdl/SKILL.md: Add an IMPORTANT warning block in Phase 4 Step 1 (after wren context init) explicitly telling agents to keep the defaults and not copy database catalog/schema into wren_project.yml. Annotate the model table_reference YAML example with inline comments.

Motivation

AI agents (and users) consistently copy their database's native catalog/schema into wren_project.yml, which causes schema resolution failures. The field names are identical at two levels of the project but have completely different semantics — this patch makes the distinction impossible to miss.

Test plan

• wren context init output includes the namespace comments in wren_project.yml
• Example models/example/metadata.yml has annotated table_reference
• wren_project.md field table clearly distinguishes Wren namespace from DB location
• SKILL.md IMPORTANT block appears between wren context init scaffold and Step 2

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Updated project configuration documentation with clarification distinguishing Wren Engine internal namespace settings from database catalog/schema configuration.
  • Added inline comments to metadata file examples.

• Chores

  • Enhanced project initialization templates with clarifying comments for catalog/schema and datasource fields.

• Tests

  • Extended initialization test with content assertions for generated project files.

[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: defaults

Review profile: CHILL

Plan: Pro

Run ID: d40d0765-c0e6-4354-a1a9-9aa542a4201a

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)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@cli-skills/wren-generate-mdl/SKILL.md`:
- Around line 157-165: Revise the guidance about `catalog` and `schema` in
`wren_project.yml` to soften the absolute tone: change the “Always keep the
defaults” wording to something like “Keep the defaults (`catalog: wren`,
`schema: public`) unless you are intentionally configuring a multi-project
namespace,” and add a brief pointer referencing per-model `table_reference` for
actual DB catalog/schema so the existing multi-project exception is clear;
update the sentence that currently reads “Do NOT copy database catalog/schema
values into `wren_project.yml`” to match the softened guidance.

In `@wren/src/wren/context_cli.py`:
- Around line 55-63: Update the unit tests in
wren/tests/unit/test_context_cli.py to assert the scaffolded file contents (not
just existence): open the generated wren_project.yml and assert it contains the
exact lines "catalog: wren", "schema: public" and "data_source: postgres" (from
the scaffold in context_cli.py), and open models/example/metadata.yml and assert
it contains the expected model metadata strings created by the scaffold (e.g.,
table_reference or any known keys your scaffold writes). Locate and modify the
existing test function(s) that currently only check file presence (look for
names like test_context_scaffold or test_write_project_scaffold) to add these
content assertions and fail if the strings are missing.

🪄 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: defaults

Review profile: CHILL

Plan: Pro

Run ID: a6411503-57c0-4411-973e-c769583a779b

📥 Commits

Reviewing files that changed from the base of the PR and between 6a8ea38 and aa16039.

📒 Files selected for processing (3)

• cli-skills/wren-generate-mdl/SKILL.md
• wren/docs/wren_project.md
• wren/src/wren/context_cli.py