coalesce-transform-mcp 0.1.0

package/dist/resources/context/pipeline-workflows.md

@@ -0,0 +1,355 @@
+# Pipeline Building Workflows
+
+## Quick Reference
+
+| User says | Node type | Action |
+|-----------|-----------|--------|
+| "stage my X data" | `Stage` | `create-workspace-node-from-predecessor` with source node |
+| "create a dimension for X" | `Dimension` | `create-workspace-node-from-predecessor` with staging node |
+| "build a fact table from X and Y" | `Fact` | `create-workspace-node-from-predecessor` with both, then `convert-join-to-aggregation` |
+| "create a view for X" | `View` | `create-workspace-node-from-predecessor` with upstream node |
+| "join X and Y" | `View` | `create-workspace-node-from-predecessor` with both, then apply join condition |
+| "build an incremental pipeline" | `Incremental Load` | See "Incremental Pipeline Setup" below |
+| "create an empty node" | Any | `create-workspace-node-from-scratch` with `name` and `metadata.columns` |
+
+Use this table as a heuristic for likely node families, but still call `plan-pipeline` before creating anything so the exact `nodeType` is confirmed from the repo/workspace context. Use the full workflow whenever the request is ambiguous or involves multiple layers.
+
+## Choosing the Right Node Type
+
+**Step 1: Check available types**
+
+```javascript
+list-workspace-node-types({ workspaceID })
+```
+
+Prefer types already in use. If `base-nodes:::Stage` etc. are observed, use those over built-in types. If a recommended type is not observed, tell the user it may need installation via Build Settings > Packages.
+
+**Step 2: Read source columns**
+
+```javascript
+get-workspace-node({ workspaceID, nodeID: "source-id" })
+```
+
+Look for timestamp columns (UPDATED_AT, CREATED_AT) for incremental loading, business keys (CUSTOMER_ID) for merge keys, and SCD columns (EFFECTIVE_FROM, IS_CURRENT) for dimension tracking.
+
+**Step 3: Select by pipeline layer**
+
+| Layer | Default | Use Instead When |
+|-------|---------|-----------------|
+| Staging | `Stage` | Source has timestamps AND is large -> `Incremental Load` (requires package) |
+| Intermediate | `View` | Expensive computation -> `Stage` or `Work` |
+| Dimension (gold) | `Dimension` | Has SCD columns -> configure SCD Type 2 |
+| Fact (gold) | `Fact` | Large append-heavy data -> incremental config |
+| Metrics | `View` | Complex/frequently queried -> `Fact` |
+
+IMPORTANT: `View` types can ONLY materialize as views. For aggregations queried repeatedly, use `Dimension` or `Fact`. See `coalesce://context/data-engineering-principles` for platform-specific materialization guidance.
+
+Node type format: `"Stage"` (simple) or `"IncrementalLoading:::230"` (PackageName:::NodeTypeID). Prefer the package-prefixed format when known.
+
+## Pipeline Building Sequence
+
+### Step 1: Discover the Workspace
+
+```javascript
+list-projects({ includeWorkspaces: true })
+```
+
+### Step 2: Find Source Nodes
+
+```javascript
+list-workspace-nodes({ workspaceID, detail: true })
+```
+
+Note node IDs, names, and `locationName` (needed for `{{ ref() }}` syntax).
+
+### Step 3: Plan to discover the correct node type
+
+**Always call `plan-pipeline` before creating nodes.** The planner scans the repo for all committed node type definitions, scores them against your use case, and returns the best match. Do not guess node types — use what the planner recommends.
+
+```javascript
+plan-pipeline({
+  workspaceID,
+  goal: "stage customer data",
+  sourceNodeIDs: ["source-id-1"],
+  repoPath: "/path/to/repo"  // or rely on COALESCE_REPO_PATH
+})
+```
+
+The response includes:
+
+- `nodeTypeSelection.consideredNodeTypes` — ranked candidates with scores and reasons
+- `supportedNodeTypes` — types that support automatic creation
+- `nodes[].nodeType` — the recommended type for each planned node
+
+**If the user provides SQL:** Pass it directly to the planner.
+
+```javascript
+plan-pipeline({ workspaceID, sql: "<USER-PROVIDED SQL HERE>" })
+```
+
+Never author SQL yourself to pass to these tools.
+
+### Step 4: Review and Execute
+
+- Plan returns `status: "ready"` -> use the recommended node type to create, or call `create-pipeline-from-plan`
+- Plan returns `status: "needs_clarification"` -> address `openQuestions`, then re-plan
+
+### Step 5: Create Nodes with the planned node type
+
+Use `create-workspace-node-from-predecessor` with the node type from the plan. **Always pass `repoPath`** so config completion runs automatically:
+
+```javascript
+create-workspace-node-from-predecessor({
+  workspaceID,
+  nodeType: "base-nodes:::Stage",  // from plan-pipeline result
+  predecessorNodeIDs: ["source-id-1"],
+  changes: { name: "STG_CUSTOMER" },
+  repoPath: "/path/to/repo"  // enables automatic config completion
+})
+```
+
+**Always use `create-workspace-node-from-predecessor` or `create-workspace-node-from-scratch`** — they handle validation, config completion, and column-level attributes automatically.
+
+For joins and aggregations:
+
+```javascript
+convert-join-to-aggregation({
+  workspaceID, nodeID: "join-node-id",
+  groupByColumns: [...], aggregates: [...],
+  maintainJoins: true,
+  repoPath: "/path/to/repo"
+})
+```
+
+### Step 6: Verify Config Completion
+
+Config is applied automatically when `repoPath` is provided. Check the `configCompletion` field in the response:
+
+- `configCompletion.configReview.status` — `complete`, `needs_attention`, or `incomplete`
+- `configCompletion.configReview.summary` — human-readable status summary
+- `configCompletion.configReview.missingRequired` — required fields/columnSelectors still unset
+- `configCompletion.configReview.warnings` — issues needing manual review (e.g., missing business keys on dimension nodes)
+- `configCompletion.configReview.suggestions` — optional improvements (e.g., change tracking, materialization)
+- `configCompletion.appliedConfig` — node-level config values that were set
+- `configCompletion.columnAttributeChanges.applied` — column-level attributes (isBusinessKey, etc.)
+- `configCompletion.reasoning` — why each decision was made
+
+**Action required when `configReview.status` is not `complete`:**
+
+- `incomplete` — required fields are missing. Set them via `update-workspace-node` or `replace-workspace-node-columns`.
+- `needs_attention` — warnings need manual review (e.g., set `isBusinessKey` on the correct columns).
+
+If `configCompletionSkipped` appears instead, call `complete-node-configuration` with `repoPath` to retry.
+
+### Step 7: Follow-Up Edits
+
+Use `update-workspace-node` for post-creation changes.
+
+## Multi-Node Pipelines
+
+Create nodes bottom-up — upstream before downstream. Each step uses node IDs from the previous step.
+
+**Example: join two sources then aggregate**
+
+```javascript
+// 0. Plan to discover correct node types for each layer
+plan-pipeline({
+  workspaceID,
+  goal: "stage customer and orders, then build CLV fact",
+  sourceNodeIDs: ["source-customer-id", "source-orders-id"],
+  repoPath: "/path/to/repo"
+})
+// -> nodeTypeSelection shows e.g. "base-nodes:::Stage" for staging,
+//    "base-nodes:::Fact" for the fact layer
+
+// 1. Stage each source using the planned node type (independent — parallelize)
+create-workspace-node-from-predecessor({
+  workspaceID, nodeType: "base-nodes:::Stage",  // from plan
+  predecessorNodeIDs: ["source-customer-id"],
+  changes: { name: "STG_CUSTOMER" },
+  repoPath: "/path/to/repo"  // auto-completes config
+})
+// -> "stg-cust-id" + configCompletion shows applied config
+
+create-workspace-node-from-predecessor({
+  workspaceID, nodeType: "base-nodes:::Stage",  // from plan
+  predecessorNodeIDs: ["source-orders-id"],
+  changes: { name: "STG_ORDERS" },
+  repoPath: "/path/to/repo"
+})
+// -> "stg-orders-id" + configCompletion shows applied config
+
+// 2. Create join/fact node with planned fact type
+create-workspace-node-from-predecessor({
+  workspaceID, nodeType: "base-nodes:::Fact",  // from plan
+  predecessorNodeIDs: ["stg-cust-id", "stg-orders-id"],
+  changes: { name: "FACT_CLV" },
+  repoPath: "/path/to/repo"
+})
+// -> "fact-clv-id", joinSuggestions with common columns, configCompletion
+
+// 3. Aggregate with automatic JOIN ON generation
+convert-join-to-aggregation({
+  workspaceID, nodeID: "fact-clv-id",
+  groupByColumns: ['"STG_CUSTOMER"."CUSTOMER_ID"'],
+  aggregates: [
+    { name: "TOTAL_ORDERS", function: "COUNT", expression: 'DISTINCT "STG_ORDERS"."ORDER_ID"' },
+    { name: "LIFETIME_VALUE", function: "SUM", expression: '"STG_ORDERS"."ORDER_TOTAL"' }
+  ],
+  maintainJoins: true,
+  repoPath: "/path/to/repo"
+})
+```
+
+**Verification after each step:** Check `validation.allPredecessorsRepresented`, `validation.autoPopulatedColumns`, `warning`, and `joinSuggestions` before proceeding.
+
+**If a node is created with 0 columns:** The predecessor may have no columns, the IDs were wrong, or the node type doesn't auto-inherit. Try a projection-capable type (Stage, View, Work) or add columns with `replace-workspace-node-columns`.
+
+### UNION / Multi-Source Nodes
+
+```javascript
+create-workspace-node-from-predecessor({
+  workspaceID, nodeType: "Stage",
+  predecessorNodeIDs: ["stg-orders-us-id", "stg-orders-eu-id"],
+  changes: { name: "STG_ORDERS_ALL" }
+})
+
+update-workspace-node({
+  workspaceID, nodeID: "new-node-id",
+  changes: { config: { insertStrategy: "UNION ALL" } }
+})
+```
+
+Values: `"UNION"` (dedup), `"UNION ALL"` (keep all), `"INSERT"` (sequential, default).
+
+## Incremental Pipeline Setup
+
+**With the Incremental-Nodes package** (check `list-workspace-node-types` for `IncrementalLoading:::230`):
+
+```javascript
+// 1. Create the node
+create-workspace-node-from-predecessor({
+  workspaceID, nodeType: "IncrementalLoading:::230",
+  predecessorNodeIDs: ["source-orders-id"],
+  changes: { name: "INC_ORDERS" }
+})
+
+// 2. Configure incremental settings
+update-workspace-node({
+  workspaceID, nodeID: "inc-orders-id",
+  changes: {
+    config: {
+      filterBasedOnPersistentTable: true,
+      persistentTableLocationName: "STAGING",
+      persistentTableName: "INC_ORDERS",
+      incrementalLoadColumn: "UPDATED_AT"
+    }
+  }
+})
+```
+
+How it works: reads MAX of the high-water mark column from the target, filters source to rows above that value, INSERTs new rows. Any MERGE/upsert/SCD logic happens downstream in Dimension or Fact nodes.
+
+**Without the package** — use a regular Stage with a MAX subquery in joinCondition:
+
+```javascript
+update-workspace-node({
+  workspaceID, nodeID: "new-node-id",
+  changes: {
+    config: { truncateBefore: false },
+    metadata: {
+      sourceMapping: [{
+        name: "STG_ORDERS_INCREMENTAL",
+        dependencies: [{ locationName: "RAW", nodeName: "ORDERS" }],
+        join: {
+          joinCondition: 'FROM {{ ref(\'RAW\', \'ORDERS\') }} "ORDERS"\nWHERE "ORDERS"."UPDATED_AT" > (\n  SELECT COALESCE(MAX("UPDATED_AT"), \'1900-01-01\')\n  FROM {{ ref_no_link(\'STAGING\', \'STG_ORDERS_INCREMENTAL\') }}\n)'
+        },
+        customSQL: { customSQL: "" }, aliases: {}, noLinkRefs: []
+      }]
+    }
+  }
+})
+```
+
+Use `{{ ref_no_link() }}` for the self-reference to avoid circular DAG dependencies.
+
+## Data Engineering Best Practices
+
+### Naming Conventions
+
+Follow layer-appropriate naming to keep pipelines readable:
+
+| Layer | Convention | Examples |
+|-------|-----------|----------|
+| Staging | `STG_<SOURCE>` | `STG_CUSTOMERS`, `STG_ORDERS` |
+| Intermediate | `INT_<PURPOSE>` or `WRK_<PURPOSE>` | `INT_ORDER_ENRICHMENT`, `WRK_CUSTOMER_DEDUP` |
+| Dimension | `DIM_<ENTITY>` | `DIM_CUSTOMER`, `DIM_PRODUCT` |
+| Fact | `FACT_<PROCESS>` or `FCT_<PROCESS>` | `FACT_SALES`, `FCT_CLV` |
+| View | `V_<PURPOSE>` | `V_ACTIVE_CUSTOMERS` |
+| Hub | `HUB_<KEY>` | `HUB_CUSTOMER` |
+| Satellite | `SAT_<HUB>_<CONTEXT>` | `SAT_CUSTOMER_DETAILS` |
+| Link | `LNK_<RELATIONSHIP>` | `LNK_CUSTOMER_ORDER` |
+
+For Snowflake, UPPERCASE node names are conventional (`STG_LOCATION`) since unquoted identifiers are uppercase. For Databricks/BigQuery, lowercase is typical. **Always respect the user's chosen casing** — if they provide or create a node with a specific case, preserve it exactly.
+
+### Join Verification Checklist
+
+After creating a multi-predecessor node, ALWAYS:
+
+1. **Review `joinSuggestions`** — the response shows common columns between predecessors. Confirm these are the correct business keys for the join.
+2. **Choose the right join type:**
+   - `INNER JOIN` — only matching rows (use when every record must exist in both tables)
+   - `LEFT JOIN` — keep all rows from the primary table (use when the left table is the "driver" and right table may have missing matches)
+   - `FULL OUTER JOIN` — keep all rows from both tables (rare, use for reconciliation)
+3. **Verify join cardinality:** Joining a 1M-row table to a 10M-row table on a non-unique key causes fan-out (row multiplication). Ensure at least one side of the join is unique on the join key.
+4. **Set the join condition** — call `convert-join-to-aggregation` (for aggregation), `apply-join-condition` (for row-level joins), or `update-workspace-node` (for full manual control)
+5. **Verify columns** — call `get-workspace-node` to confirm the final column list and transforms are correct
+
+### Fact Table Grain
+
+When building fact tables, define the **grain** (the set of columns that uniquely identifies each row):
+
+- Grain columns become your `groupByColumns` in `convert-join-to-aggregation`
+- Mark grain columns as `isBusinessKey: true`
+- All other columns should be aggregates (COUNT, SUM, AVG, etc.)
+- If unsure about the grain, ask the user: "What uniquely identifies each row in this fact table?"
+
+Example: A sales fact table might have grain = `[CUSTOMER_ID, ORDER_DATE, PRODUCT_ID]` with measures `QUANTITY`, `REVENUE`, `DISCOUNT_AMOUNT`.
+
+### Post-Creation Verification
+
+After creating each node, verify before moving to the next:
+
+1. **Check `nextSteps`** in the creation response — follow all required steps
+2. **Check `validation.allPredecessorsRepresented`** — if false, predecessors are missing from column sources
+3. **Check `configCompletion`** — verify applied config and column attributes make sense
+4. **For multi-predecessor nodes:** Confirm the join condition was set (call `get-workspace-node` to verify `metadata.sourceMapping[].join.joinCondition` is not empty)
+5. **For aggregation nodes:** Verify GROUP BY is valid (`validation.valid: true` from `convert-join-to-aggregation`)
+
+### Materialization Strategy
+
+Choose materialization based on the node's role and query patterns:
+
+- **Staging/Bronze:** Always `table` (preserve raw data; Snowflake: use transient tables)
+- **Intermediate:** `view` for lightweight transforms; `table` for expensive computations
+- **Dimensions:** `table` (small, queried repeatedly, need persistence)
+- **Facts:** `table` with incremental loading for large volumes
+- **Metrics/aggregations queried frequently:** `table` via Dimension or Fact (NEVER `view` for repeated aggregation queries)
+
+IMPORTANT: `View` node types can ONLY materialize as views. If you need a table, use `Dimension`, `Fact`, `Stage`, or `Work`.
+
+## After Building the Pipeline
+
+1. **Deploy**: `start-run` with `runType: "deploy"`
+2. **Run**: `start-run` with `runType: "refresh"`
+3. **Monitor**: `run-status` or `run-and-wait`
+4. **Troubleshoot**: `get-run-results` for errors, `retry-run` to re-run
+
+Scheduling is configured via Jobs in the Coalesce UI. Trigger existing jobs with `start-run` and `jobID`. See `coalesce://context/run-operations` for full guidance.
+
+## Related Resources
+
+- `coalesce://context/node-creation-decision-tree` — routing: which tool to use
+- `coalesce://context/node-operations` — editing nodes after creation
+- `coalesce://context/data-engineering-principles` — architecture and materialization
+- `coalesce://context/aggregation-patterns` — GROUP BY, datatype inference

package/dist/resources/context/run-operations.md

@@ -0,0 +1,55 @@
+# Run Operations
+
+This guidance matches the Coalesce run source model and the actual run workflows registered in this MCP.
+
+## Current Tool Surface
+
+Use these run tools and workflows:
+
+- `list-runs`
+- `get-run`
+- `get-run-results`
+- `get-run-details`
+- `start-run`
+- `run-status`
+- `run-and-wait`
+- `retry-run`
+- `retry-and-wait`
+- `cancel-run`
+
+## Identifier And Status Model
+
+- Coalesce scheduler start and rerun flows return a numeric `runCounter`.
+- `run-status` polls by `runCounter`.
+- The same numeric identifier is used as `runID` for `get-run`, `get-run-results`, and `get-run-details`.
+- Non-terminal statuses are `waitingToRun` and `running`.
+- Terminal statuses are `completed`, `failed`, and `canceled`.
+
+## Source-Derived Lifecycle
+
+- Coalesce app helpers call `/scheduler/startRun` or `/scheduler/rerun`, then poll `/scheduler/runStatus` until the run reaches a terminal status.
+- The source only treats terminal completion as the point where success or failure can actually be asserted.
+- The MCP `run-and-wait` and `retry-and-wait` workflows follow that same model and then fetch `/api/v1/runs/{runCounter}/results`.
+
+## Routing Rules
+
+- Use `run-and-wait` when the user wants the final run outcome in one call.
+- Use `retry-and-wait` when the prior run has already failed and should be retried immediately.
+- Use `start-run` or `retry-run` when you want explicit control over the polling sequence.
+- Use `run-status` for live scheduler state by `runCounter`.
+- Use `get-run-details` when you want run metadata and results together.
+- Use `get-run` or `get-run-results` when you only need one side of that data.
+- Use `cancel-run` only with `runID`, `environmentID`, and org context.
+
+## Practical Checks
+
+- Do not treat "request accepted" as the same thing as "run completed".
+- Inspect terminal status and result payloads before reporting success.
+- If the user only knows a job name, resolve its numeric ID first.
+- `run-and-wait` and `retry-and-wait` can still return `resultsError`, `incomplete`, or `timedOut`; inspect those fields before calling the workflow successful.
+
+## Avoid
+
+- Do not use browser URL UUID fragments as run IDs.
+- Do not poll `run-status` with a job ID or environment ID.
+- Do not retry runs that are still `waitingToRun` or `running`.

package/dist/resources/context/sql-bigquery.md

@@ -0,0 +1,41 @@
+# SQL Rules: BigQuery
+
+This guidance is based on the AI runtime platform rules for BigQuery and the related Coalesce SQL rendering behavior.
+
+## Default SQL Style
+
+- Prefer lowercase identifiers.
+- Use backticks to quote identifiers when needed.
+- For raw physical references, prefer fully qualified `project.dataset.table` paths and quote the entire path with one pair of backticks when quoting is necessary.
+- Avoid `SELECT *`; prefer explicit column lists.
+
+## Coalesce `ref()` Syntax
+
+- In Coalesce node SQL, node-to-node dependencies should stay in logical ref form:
+
+```jinja
+FROM {{ ref('sample', 'nation') }} nation
+LEFT JOIN {{ ref('storage_location', 'stg_foo') }} stg_foo
+  ON nation.id = stg_foo.nation_id
+```
+
+- The SQL processing layer treats `ref()` arguments as exact `locationName` and `nodeName` values.
+- Keep `ref()` arguments aligned with the saved Coalesce names, even when the rest of the SQL follows BigQuery lowercase conventions.
+- For more on logical locations, use `coalesce://context/storage-mappings`.
+
+## Physical Object Names
+
+- When Coalesce renders physical database and schema locations for BigQuery, generated physical references may appear in backtick form such as `` `project`.`dataset`. ``
+- Preserve that generated style when editing SQL that already includes physical references from Coalesce metadata or templates.
+
+## Common Source-Backed Functions
+
+- String: `split`, `substr`, `upper`, `lower`, `regexp_extract`, `replace`
+- Date: `date_trunc`, `timestamp_trunc`, `date_add`, `date_sub`, `timestamp_add`, `timestamp_diff`
+- Aggregate: `sum`, `count`, `avg`, `min`, `max`, `any_value`, `string_agg`, `array_agg`
+
+## Avoid
+
+- Do not replace Coalesce `ref()` references with raw project.dataset.table paths unless the user explicitly wants physical SQL.
+- Do not switch BigQuery identifier quoting to Snowflake-style double quotes.
+- Do not introduce wildcard projections when explicit columns are practical.

package/dist/resources/context/sql-databricks.md

@@ -0,0 +1,40 @@
+# SQL Rules: Databricks
+
+This guidance is based on the AI runtime platform rules for Databricks and the related Coalesce SQL rendering behavior.
+
+## Default SQL Style
+
+- Table references should use backticks rather than double quotes.
+- Use lowercase identifiers for SQL you introduce.
+- Use clear naming prefixes such as `stg_`, `dim_`, and `fct_` when naming new objects.
+
+## Coalesce `ref()` Syntax
+
+- Coalesce node-to-node SQL should use logical refs:
+
+```jinja
+FROM {{ ref('sample', 'nation') }} `nation`
+JOIN {{ ref('storage_location', 'stg_foo') }} `stg_foo`
+```
+
+- The SQL processing layer treats `ref()` arguments as exact `locationName` and `nodeName` values.
+- Keep `ref()` arguments aligned with the saved Coalesce names, even when the rest of the SQL follows Databricks lowercase conventions.
+- For more on logical locations, use `coalesce://context/storage-mappings`.
+
+## Physical Object Names
+
+- When Coalesce renders physical database and schema locations for Databricks, object names appear in backtick form such as `` `catalog`.`schema`. `` or `` `db`.`schema`. ``
+- Preserve that generated style when editing SQL that already includes physical references from Coalesce metadata or templates.
+
+## Common Source-Backed Functions
+
+- String: `split`, `regexp_extract`, `initcap`, `translate`, `reverse`
+- Date: `date_trunc`, `add_months`, `months_between`, `next_day`, `current_date`
+- Array: `explode`, `array_contains`, `size`, `slice`, `posexplode`
+- Aggregate: `collect_list`, `collect_set`, `count_distinct`, `percentile_approx`, `any_value`
+
+## Avoid
+
+- Do not rewrite `ref()` arguments into physical warehouse paths.
+- Do not use Snowflake double quotes for Databricks identifiers.
+- Do not mix uppercase Snowflake-style aliasing with Databricks lowercase conventions unless the saved names require it.

package/dist/resources/context/sql-platform-selection.md

@@ -0,0 +1,70 @@
+# SQL Platform Selection
+
+Read this resource before writing or editing SQL in a Coalesce node.
+
+## Goal
+
+Determine the platform first, then read exactly one dialect resource:
+
+- `coalesce://context/sql-snowflake`
+- `coalesce://context/sql-databricks`
+- `coalesce://context/sql-bigquery`
+
+Follow exactly one dialect's rules per edit. Mixing dialect conventions in one node creates compilation errors.
+
+## Best Signal Order
+
+### 1. Check Project Metadata First
+
+Use `get-project` or `list-projects` and inspect the returned project metadata for the warehouse or platform type.
+
+This is the best first signal because it reflects the project configuration directly.
+
+### 2. Check Existing Node SQL
+
+If you are editing an existing node, read the current node and inspect:
+
+- identifier casing
+- quoting style
+- function names
+- date/time function patterns
+- join and alias style
+
+Prefer preserving the existing node and workspace conventions rather than normalizing everything.
+
+### 3. Check Neighboring Nodes
+
+If one node is ambiguous, inspect nearby workspace nodes in the same layer or dependency chain.
+
+Workspace-local conventions are a better guide than generic SQL style advice.
+
+### 4. Ask the User If Still Unclear
+
+If project metadata and existing SQL still do not settle the dialect, ask the user.
+
+When the dialect choice materially affects correctness (e.g., function names, quoting, type syntax), ask the user rather than guessing.
+
+## Coalesce-Specific Rule
+
+Inside Coalesce node SQL, prefer `{{ ref(...) }}` for node and storage references. For full reference syntax details, see `coalesce://context/storage-mappings`.
+
+Preserve `{{ ref(...) }}` syntax for node references. Only replace with raw warehouse-qualified table names if the user explicitly wants warehouse-native SQL outside normal Coalesce patterns.
+
+## Editing Principles
+
+This is the canonical source for "preserve workspace conventions" when editing SQL.
+
+When modifying existing SQL:
+
+- preserve the current dialect
+- preserve the current quoting and casing style unless it is clearly broken
+- avoid broad formatting rewrites that do not change behavior
+- preserve existing workspace style over personal preferences
+
+When generating entirely new SQL and no local convention exists:
+
+- use the selected platform resource as the default style guide
+
+## Special Note
+
+Run-tool authentication in this MCP server is Snowflake Key Pair-based, but that does not mean every project uses Snowflake SQL semantics. Determine the SQL platform from project metadata and node SQL, not from run-tool auth requirements.

package/dist/resources/context/sql-snowflake.md

@@ -0,0 +1,43 @@
+# SQL Rules: Snowflake
+
+This guidance is based on the AI runtime platform rules for Snowflake and the related Coalesce SQL rendering behavior.
+
+## Default SQL Style
+
+- Default to uppercase unquoted identifiers for column names, aliases, and SQL identifiers (Snowflake convention).
+- Node names become Snowflake table/view names. Default to UPPERCASE (`STG_LOCATION`, `FACT_ORDERS`), but **respect the user's chosen casing** — if they name a node in lowercase, preserve it.
+- Use double quotes only when you must preserve exact case or quote a reserved word.
+- Column names and aliases should normally be uppercase and unquoted.
+- Table aliases should normally be uppercase and unquoted.
+- Avoid backticks, single-quoted identifiers, or mixed quoting styles.
+
+## Coalesce `ref()` Syntax
+
+- Coalesce node-to-node SQL should use logical refs:
+
+```jinja
+FROM {{ ref("SAMPLE", "NATION") }} N
+LEFT JOIN {{ ref("STORAGE_LOCATION", "STG_FOO") }} F
+  ON N.ID = F.NATION_ID
+```
+
+- The SQL processing layer treats `ref()` arguments as exact `locationName` and `nodeName` values.
+- Keep `ref()` arguments aligned with the saved Coalesce names, even when the rest of the SQL follows Snowflake casing preferences.
+- For more on logical locations, use `coalesce://context/storage-mappings`.
+
+## Physical Object Names
+
+- When Coalesce renders physical database and schema locations, Snowflake object names may appear in double-quoted form such as `"DB"."SCHEMA".`
+- Preserve that generated style when editing SQL that already includes physical object references from Coalesce metadata or templates.
+
+## Common Source-Backed Functions
+
+- String: `SPLIT`, `SUBSTR`, `UPPER`, `LOWER`, `REGEXP_SUBSTR`
+- Date: `DATEADD`, `DATEDIFF`, `TO_DATE`, `DATE_TRUNC`
+- Aggregate: `SUM`, `COUNT`, `AVG`, `MIN`, `MAX`, `MEDIAN`
+
+## Avoid
+
+- Do not rewrite `ref()` arguments into raw warehouse object paths.
+- Do not switch Snowflake identifier quoting to backticks.
+- Do not introduce mixed-case quoted identifiers unless preserving exact case is required.

package/dist/resources/context/storage-mappings.md

@@ -0,0 +1,49 @@
+# Storage Locations and References
+
+This guidance is based on the AI runtime storage-context section and the related Coalesce ref-handling code.
+
+## What Storage Locations Mean
+
+- Storage locations are short logical names that map to `DATABASE.SCHEMA` pairs where tables live.
+- Users may have many storage locations configured in a workspace.
+- Any node can be manually configured to live somewhere other than the obvious default, so always pay attention to the existing node storage locations when writing joins or downstream refs.
+
+## Default Placement Matters
+
+- New nodes normally default to the storage location specified by their node type.
+- That default matters when you create multiple nodes at once or in parallel because downstream refs may need to target the new node's default location, not the source node's location.
+
+## Source Example
+
+- You create a chain `A -> B -> C`
+- `A` already exists in `SOURCE_A`
+- `B` is created and defaults to `USER_WORKSPACE`
+- `C` is created at the same time and also defaults to `USER_WORKSPACE`
+
+That means:
+
+- `B` should reference `A` with `{{ ref('SOURCE_A', 'ORDERS') }}`
+- `C` should reference `B` with `{{ ref('USER_WORKSPACE', 'NODE_B') }}`
+
+## `ref()` Contract
+
+- Coalesce node SQL uses logical refs in this shape:
+
+```jinja
+FROM {{ ref('LOCATION_NAME', 'NODE_NAME') }}
+```
+
+- The SQL processing layer extracts refs into exact `locationName` and `nodeName` pairs.
+- Keep `ref()` arguments aligned with the saved Coalesce names.
+
+## Practical Rules
+
+- Treat `locationName` as logical Coalesce state and `database` or `schema` as the resolved physical target behind it.
+- When chaining node creation, confirm where the upstream node was actually placed before referencing it.
+- If storage mappings are missing, fix that first instead of guessing raw warehouse paths.
+
+## Avoid
+
+- Do not guess logical location names from database or schema values.
+- Do not assume new nodes land in the same location as their predecessors.
+- Do not normalize `ref()` arguments to warehouse casing rules.