@revos/cli 0.2.1 → 0.2.2

package/dist/templates/skills/create-cubes/references/jira-entities.md

@@ -0,0 +1,201 @@
+# Jira Entities Reference
+
+## Table naming
+
+Airbyte syncs Jira tables with a configurable prefix (default: `jira_`).
+Inspect the BigQuery dataset to find the actual prefix:
+
+```sql
+SELECT table_name FROM `<dataset>.INFORMATION_SCHEMA.TABLES`
+WHERE table_name LIKE '%issues%' OR table_name LIKE '%projects%'
+ORDER BY table_name LIMIT 20;
+```
+
+Throughout this document `<prefix>` is a placeholder for that prefix.
+
+---
+
+## Primary entities
+
+| Cube name                    | BigQuery table               | PK          | Notes                                            |
+| ---------------------------- | ---------------------------- | ----------- | ------------------------------------------------ |
+| `<prefix>issues`             | `<prefix>issues`             | `id`        | `key` is display name; metadata in `fields` JSON |
+| `<prefix>projects`           | `<prefix>projects`           | `id`        | `name`                                           |
+| `<prefix>issue_types`        | `<prefix>issue_types`        | `id`        | `name`                                           |
+| `<prefix>issue_priorities`   | `<prefix>issue_priorities`   | `id`        | `name`                                           |
+| `<prefix>users`              | `<prefix>users`              | `accountId` | `displayName`; aliased 4× (see below)            |
+| `<prefix>sprints`            | `<prefix>sprints`            | `id`        | `name`; FK `boardId`                             |
+| `<prefix>boards`             | `<prefix>boards`             | `id`        | `name`; FK `projectId`                           |
+| `<prefix>issue_comments`     | `<prefix>issue_comments`     | —           | FK `issueId`; `author` is JSON object            |
+| `<prefix>issue_worklogs`     | `<prefix>issue_worklogs`     | —           | FK `issueId`; `author` is JSON object            |
+| `<prefix>project_components` | `<prefix>project_components` | —           | FK `projectId` as INT64                          |
+| `<prefix>project_versions`   | `<prefix>project_versions`   | —           | FK `projectId` as INT64                          |
+
+---
+
+## Users table aliasing
+
+The single `<prefix>users` table must be exposed as **separate cubes** for each
+role because Cube.js does not support joining the same table twice with
+different conditions. Each alias has its own cube name and `sql_table` pointing
+to the same physical table.
+
+| Cube name                      | Role           | Join condition on `<prefix>issues`                 |
+| ------------------------------ | -------------- | -------------------------------------------------- |
+| `<prefix>users_assignee`       | Assignee       | `JSON_VALUE(fields, '$.assignee.accountId')`       |
+| `<prefix>users_reporter`       | Reporter       | `JSON_VALUE(fields, '$.reporter.accountId')`       |
+| `<prefix>users_creator`        | Creator        | `JSON_VALUE(fields, '$.creator.accountId')`        |
+| `<prefix>users_comment_author` | Comment author | `JSON_VALUE(issue_comments.author, '$.accountId')` |
+| `<prefix>users_worklog_author` | Worklog author | `JSON_VALUE(issue_worklogs.author, '$.accountId')` |
+| `<prefix>users`                | Direct queries | (no joins defined)                                 |
+
+Template for each alias:
+
+```yaml
+name: <prefix>users_assignee
+sql_table: "`<dataset>.<prefix>users`"
+joins:
+  <prefix>issues:
+    relationship: one_to_many
+    sql: >
+      ${CUBE}.accountId =
+      JSON_VALUE(${<prefix>issues.fields}, '$.assignee.accountId')
+```
+
+Corresponding join on `<prefix>issues`:
+
+```yaml
+joins:
+  <prefix>users_assignee:
+    relationship: many_to_one
+    sql: >
+      JSON_VALUE(${CUBE}.fields, '$.assignee.accountId') =
+      ${<prefix>users_assignee.accountId}
+```
+
+---
+
+## Issues: fields JSON column
+
+Issue metadata lives in a single `fields` JSON column. Extract with `JSON_VALUE`:
+
+| Field               | JSON path                                 |
+| ------------------- | ----------------------------------------- |
+| Issue type ID       | `$.issuetype.id`                          |
+| Priority ID         | `$.priority.id`                           |
+| Assignee account ID | `$.assignee.accountId`                    |
+| Reporter account ID | `$.reporter.accountId`                    |
+| Creator account ID  | `$.creator.accountId`                     |
+| Status              | `$.status.name`                           |
+| Summary             | `$.summary`                               |
+| Story points        | `$.story_points` or `$.customfield_10016` |
+
+Example dimension:
+
+```yaml
+dimensions:
+  status:
+    sql: "JSON_VALUE(${CUBE}.fields, '$.status.name')"
+    type: string
+  issue_type_name:
+    sql: "JSON_VALUE(${CUBE}.fields, '$.issuetype.name')"
+    type: string
+```
+
+---
+
+## Bridge / junction cubes (public: false)
+
+### sprint_issues
+
+Sprints and issues are many-to-many. The `sprint_issues` table has columns
+`issueId` (STRING) and `sprintId` (INT64). Composite PK required.
+
+```yaml
+name: <prefix>sprint_issues
+sql_table: "`<dataset>.<prefix>sprint_issues`"
+public: false
+dimensions:
+  id:
+    sql: "${CUBE}.issueId || '_' || CAST(${CUBE}.sprintId AS STRING)"
+    type: string
+    primary_key: true
+joins:
+  <prefix>issues:
+    relationship: many_to_one
+    sql: "${CUBE}.issueId = ${<prefix>issues.id}"
+  <prefix>sprints:
+    relationship: many_to_one
+    sql: "${CUBE}.sprintId = ${<prefix>sprints.id}"
+```
+
+Issues and sprints join through this bridge:
+
+```yaml
+# On <prefix>issues:
+joins:
+  <prefix>sprint_issues:
+    relationship: one_to_many
+    sql: "${CUBE}.id = ${<prefix>sprint_issues.issueId}"
+
+# On <prefix>sprints:
+joins:
+  <prefix>sprint_issues:
+    relationship: one_to_many
+    sql: "${CUBE}.id = ${<prefix>sprint_issues.sprintId}"
+```
+
+### board_issues
+
+Board issues (`board_issues` table) link boards to issues. Composite PK uses `id` + `boardId`.
+
+```yaml
+name: <prefix>board_issues
+sql_table: "`<dataset>.<prefix>board_issues`"
+public: false
+dimensions:
+  composite_id:
+    sql: "${CUBE}.id || '_' || CAST(${CUBE}.boardId AS STRING)"
+    type: string
+    primary_key: true
+joins:
+  <prefix>issues:
+    relationship: many_to_one
+    sql: "${CUBE}.id = ${<prefix>issues.id}"
+  <prefix>boards:
+    relationship: many_to_one
+    sql: "${CUBE}.boardId = ${<prefix>boards.id}"
+```
+
+---
+
+## Type casting pitfalls
+
+### project_components / project_versions → projects
+
+`project_components.projectId` and `project_versions.projectId` are INT64 but
+`projects.id` is STRING. Always cast:
+
+```yaml
+# On <prefix>project_components:
+joins:
+  <prefix>projects:
+    relationship: many_to_one
+    sql: "CAST(${CUBE}.projectId AS STRING) = ${<prefix>projects.id}"
+
+# On <prefix>projects:
+joins:
+  <prefix>project_components:
+    relationship: one_to_many
+    sql: "SAFE_CAST(${CUBE}.id AS INT64) = ${<prefix>project_components.projectId}"
+```
+
+---
+
+## Common pitfalls
+
+1. **`fields` JSON column** — most issue attributes live here, not as top-level columns. Always check `INFORMATION_SCHEMA` before assuming a column exists at the top level.
+2. **User aliases must be separate cubes** — do not try to join `users` twice from `issues`; Cube.js requires distinct cube names per join target.
+3. **`sprintId` is INT64** — cast to STRING in the composite PK to avoid type errors.
+4. **`issue_comments.author` is a JSON object** — extract `accountId` with `JSON_VALUE`, not a direct column reference.
+5. **`boards.projectId` vs `projects.id`** — both are strings here; no cast needed. But `project_components.projectId` is INT64 — always cast.

package/dist/templates/skills/create-cubes/references/netsuite-entities.md

@@ -0,0 +1,121 @@
+# NetSuite Entities Reference
+
+## Table naming
+
+Airbyte syncs NetSuite tables with a configurable prefix (default: `netsuite_`).
+Inspect the BigQuery dataset to confirm:
+
+```sql
+SELECT table_name FROM `<dataset>.INFORMATION_SCHEMA.TABLES`
+WHERE table_name LIKE '%customer%' OR table_name LIKE '%salesorder%'
+ORDER BY table_name LIMIT 20;
+```
+
+Throughout this document `<prefix>` is a placeholder for that prefix.
+
+---
+
+## Primary entities
+
+| Cube name             | BigQuery table        | PK   | Notes                          |
+| --------------------- | --------------------- | ---- | ------------------------------ |
+| `<prefix>customer`    | `<prefix>customer`    | `id` | FK `subsidiary` is JSON object |
+| `<prefix>contact`     | `<prefix>contact`     | `id` | FK `company` is JSON object    |
+| `<prefix>opportunity` | `<prefix>opportunity` | `id` | FK `entity` is JSON object     |
+| `<prefix>salesorder`  | `<prefix>salesorder`  | `id` | FK `entity` is JSON object     |
+| `<prefix>employee`    | `<prefix>employee`    | `id` | —                              |
+
+---
+
+## FK extraction pattern
+
+NetSuite stores foreign keys as **JSON objects** with an `id` field rather than
+as flat FK columns. Use `JSON_VALUE` to extract the ID and expose it as a
+computed dimension.
+
+### contact → customer
+
+`contact.company` is a JSON object: `{"id": "123", "refName": "Acme Corp"}`.
+
+```yaml
+name: <prefix>contact
+sql_table: "`<dataset>.<prefix>contact`"
+dimensions:
+  id:
+    sql: "id"
+    type: string
+    primary_key: true
+  customer_id:
+    sql: "JSON_VALUE(${CUBE}.company, '$.id')"
+    type: string
+joins:
+  <prefix>customer:
+    relationship: many_to_one
+    sql: "${CUBE.customer_id} = ${<prefix>customer.id}"
+```
+
+### customer → subsidiary
+
+`customer.subsidiary` is a JSON object: `{"id": "1", "refName": "Main Subsidiary"}`.
+
+```yaml
+name: <prefix>customer
+sql_table: "`<dataset>.<prefix>customer`"
+dimensions:
+  subsidiary_id:
+    sql: "JSON_VALUE(${CUBE}.subsidiary, '$.id')"
+    type: string
+joins:
+  <prefix>contact:
+    relationship: one_to_many
+    sql: "${CUBE}.id = ${<prefix>contact.customer_id}"
+  <prefix>salesorder:
+    relationship: one_to_many
+    sql: "${CUBE}.id = ${<prefix>salesorder.customer_id}"
+  <prefix>opportunity:
+    relationship: one_to_many
+    sql: "${CUBE}.id = ${<prefix>opportunity.customer_id}"
+```
+
+### opportunity / salesorder → customer
+
+Both `opportunity` and `salesorder` use `entity` (not `company`) as the FK column:
+
+```yaml
+name: <prefix>opportunity
+sql_table: "`<dataset>.<prefix>opportunity`"
+dimensions:
+  id:
+    sql: "id"
+    type: string
+    primary_key: true
+  customer_id:
+    sql: "JSON_VALUE(${CUBE}.entity, '$.id')"
+    type: string
+joins:
+  <prefix>customer:
+    relationship: many_to_one
+    sql: "${CUBE.customer_id} = ${<prefix>customer.id}"
+```
+
+Same pattern for `<prefix>salesorder`.
+
+---
+
+## Relationship graph
+
+```
+customer ──< contact
+customer ──< opportunity
+customer ──< salesorder
+```
+
+---
+
+## Common pitfalls
+
+1. **FK columns are JSON objects** — `contact.company`, `opportunity.entity`, `salesorder.entity`, `customer.subsidiary` are all JSON objects. Never join directly; always extract with `JSON_VALUE(..., '$.id')` and expose as a computed dimension.
+2. **`entity` vs `company`** — contacts use `company`, but opportunities and sales orders use `entity` as the customer FK column.
+3. **PK column name is `id` (lowercase)** — not `internalId` or similar. Verify in INFORMATION_SCHEMA.
+4. **Subsidiary** — `customer.subsidiary` holds the subsidiary FK. If the schema has multiple subsidiaries, you may need a `subsidiary` cube joined via `subsidiary_id`.
+5. **No `_airbyte_extracted_at` guarantee** — some NetSuite streams use `lastModifiedDate` instead. Check actual column names before writing `refresh_key`.

package/dist/templates/skills/create-cubes/references/stripe-entities.md

@@ -0,0 +1,114 @@
+# Stripe Entities Reference
+
+## Table naming
+
+Airbyte syncs Stripe tables with a configurable prefix (default: `stripe_`).
+Inspect the BigQuery dataset to confirm:
+
+```sql
+SELECT table_name FROM `<dataset>.INFORMATION_SCHEMA.TABLES`
+WHERE table_name LIKE '%customers%' OR table_name LIKE '%invoices%'
+ORDER BY table_name LIMIT 20;
+```
+
+Throughout this document `<prefix>` is a placeholder for that prefix.
+
+---
+
+## Primary entities
+
+| Cube name               | BigQuery table          | PK   | Notes                            |
+| ----------------------- | ----------------------- | ---- | -------------------------------- |
+| `<prefix>customers`     | `<prefix>customers`     | `id` | `name` is display name           |
+| `<prefix>subscriptions` | `<prefix>subscriptions` | `id` | FK `customer` (→ customers.id)   |
+| `<prefix>invoices`      | `<prefix>invoices`      | `id` | FK `customer`, FK `subscription` |
+
+---
+
+## Relationship graph
+
+```
+customers ──< subscriptions ──< invoices
+    └────────────────────────< invoices
+```
+
+- customer → subscriptions: `one_to_many` via `subscriptions.customer = customers.id`
+- customer → invoices: `one_to_many` via `invoices.customer = customers.id`
+- subscription → invoices: `one_to_many` via `invoices.subscription = subscriptions.id`
+- subscription → latest_invoice: `many_to_one` via `subscriptions.latest_invoice = latest_invoice.id`
+
+---
+
+## Standard cube definitions
+
+### customers
+
+```yaml
+name: <prefix>customers
+sql_table: "`<dataset>.<prefix>customers`"
+joins:
+  <prefix>subscriptions:
+    relationship: one_to_many
+    sql: "${CUBE}.id = ${<prefix>subscriptions.customer}"
+  <prefix>invoices:
+    relationship: one_to_many
+    sql: "${CUBE}.id = ${<prefix>invoices.customer}"
+```
+
+### subscriptions
+
+```yaml
+name: <prefix>subscriptions
+sql_table: "`<dataset>.<prefix>subscriptions`"
+joins:
+  <prefix>customers:
+    relationship: many_to_one
+    sql: "${CUBE}.customer = ${<prefix>customers.id}"
+  <prefix>invoices:
+    relationship: one_to_many
+    sql: "${CUBE}.id = ${<prefix>invoices.subscription}"
+  <prefix>latest_invoice:
+    relationship: many_to_one
+    sql: "${CUBE}.latest_invoice = ${<prefix>latest_invoice.id}"
+```
+
+### invoices
+
+```yaml
+name: <prefix>invoices
+sql_table: "`<dataset>.<prefix>invoices`"
+joins:
+  <prefix>customers:
+    relationship: many_to_one
+    sql: "${CUBE}.customer = ${<prefix>customers.id}"
+  <prefix>subscriptions:
+    relationship: many_to_one
+    sql: "${CUBE}.subscription = ${<prefix>subscriptions.id}"
+```
+
+---
+
+## Special cube: latest_invoice
+
+`latest_invoice` is an alias for the `invoices` table (public: false) used
+exclusively for the `subscriptions.latest_invoice` FK join. Needed because
+Cube.js does not support two joins to the same table under the same cube name.
+
+```yaml
+name: <prefix>latest_invoice
+sql_table: "`<dataset>.<prefix>invoices`"
+public: false
+joins:
+  <prefix>subscriptions:
+    relationship: one_to_many
+    sql: "${CUBE}.id = ${<prefix>subscriptions.latest_invoice}"
+```
+
+---
+
+## Common pitfalls
+
+1. **`latest_invoice` must be a separate cube** — subscriptions needs both `invoices` (for all invoices) and `latest_invoice` (for the most recent one). Same physical table, different cube names.
+2. **FK column names without suffix** — `subscriptions.customer` is the raw Stripe customer ID (not `customer_id`). Same for `invoices.subscription` and `invoices.customer`. Check actual column names in INFORMATION_SCHEMA.
+3. **Stripe IDs are strings** — all IDs start with a prefix (`cus_`, `sub_`, `in_`, etc.). No casting needed.
+4. **Timestamps** — Stripe tables from Airbyte use `_airbyte_extracted_at` as the sync timestamp. Use it for `refresh_key`.

package/dist/templates/skills/create-dbt-transformations/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-dbt-transformations
-description: Create new dbt transformations (bronze/silver/gold models) in the RevOS dbt project. Use when asked to create a dbt model, build a transformation, add a new layer model, declare a raw source, or register a new Airbyte-ingested table. Covers dbt project conventions, sources, materialization, schema.yml, and validation commands.
+description: Create new dbt transformations (silver/gold models) in the RevOS dbt project. Use when asked to create a dbt model, build a transformation, add a new layer model, declare a raw source, or register a new raw table. Bronze is source-declarations only — no SQL files. Covers dbt project conventions, sources, materialization, schema.yml, and validation commands.
 ---
 
 # Create dbt Transformations
@@ -22,32 +22,35 @@ Warn the user: "The `explore-lakehouse` skill is not installed — using `bq sho
 ## Layer Conventions
 
 - **gold** — business-ready models exposed for reporting or downstream consumption.
-- **silver** — cleaned, deduplicated, type-conformed intermediates.
-- **bronze** — thin views over raw source data. References sources via `{{ source() }}`.
+- **silver** — cleaned, deduplicated, type-conformed intermediates. Lowest SQL layer; reads raw data via `{{ source('bronze', '<table>') }}`.
+- **bronze** — **not a SQL layer**. Holds only `dbt/models/bronze/schema.yml`, which declares raw tables as dbt sources. No `.sql` files belong under `dbt/models/bronze/`.
 
 When layer is not obvious from context, ask (see Checkpoint 1).
 
 ## Sources (bronze layer)
 
-Raw tables ingested by Airbyte are not dbt models. Declare them as dbt sources so bronze models can reference them with `{{ source() }}`.
+Raw tables loaded into the warehouse by your ingestion pipeline are not dbt models. Declare them as dbt sources so silver models can reference them with `{{ source() }}`.
 
 Sources are declared in `dbt/models/bronze/schema.yml` under a `sources:` block using `schema` (the BigQuery dataset):
 
 ```yaml
 sources:
-  - name: raw
+  - name: bronze
     schema: "{{ env_var('REVOS_BQ_DATASET') }}"
     tables:
       - name: hubspot_contacts
 ```
 
-Reference in bronze SQL:
+Reference in silver SQL:
 
 ```sql
-SELECT * FROM {{ source('raw', 'hubspot_contacts') }}
+-- dbt/models/silver/silver_hubspot_contacts.sql
+SELECT * FROM {{ source('bronze', 'hubspot_contacts') }}
 ```
 
-See [schema-conventions.md](references/schema-conventions.md) for the full declaration pattern alongside `models:`.
+`{{ source('bronze', 'hubspot_contacts') }}` resolves to `${REVOS_BQ_DATASET}.hubspot_contacts` — the same dataset where raw tables live — so silver has direct access without a bronze SQL view in between.
+
+See [schema-conventions.md](references/schema-conventions.md) for the full declaration pattern.
 
 ## Materialization
 
@@ -63,10 +66,12 @@ Materialized table lives at: `$REVOS_BQ_DATASET.<model_name>`
 
 **When to use `{{ ref() }}` vs. `{{ source() }}`:**
 
-| Context                             | Use                              |
-| ----------------------------------- | -------------------------------- |
-| dbt SQL → other dbt model           | `{{ ref('<model>') }}`           |
-| dbt SQL → raw source table (bronze) | `{{ source('raw', '<table>') }}` |
+| Context                                            | Use                                 |
+| -------------------------------------------------- | ----------------------------------- |
+| dbt SQL → other dbt model                          | `{{ ref('<model>') }}`              |
+| dbt SQL → raw table (silver reading from `bronze`) | `{{ source('bronze', '<table>') }}` |
+
+Silver is the lowest SQL layer — `{{ source('bronze', ...) }}` is used in silver only. Gold reads from silver via `{{ ref() }}`. There are no SQL files in `dbt/models/bronze/`.
 
 Always declare raw tables as sources before referencing them. Do not use bare fully qualified names — that bypasses dbt's dependency graph and source freshness tracking.
 
@@ -89,12 +94,12 @@ dbt build --select path:models/<layer>  # entire layer
 
 For each transformation (one at a time — do not batch):
 
-1. Determine the target layer (Checkpoint 1 if unclear).
+1. Determine the target layer — **silver** or **gold** only (Checkpoint 1 if unclear). Refuse bronze SQL models (see Checkpoint 4).
 2. Determine the model name.
 3. Check if that model already exists (Checkpoint 2 if yes).
 4. Gather source data and transformation logic. For bridge models, apply the bridge template ([sql-templates.md](references/sql-templates.md)).
-5. For bronze models: check if required sources are declared in `dbt/models/bronze/schema.yml`; add them if missing.
-6. Generate `dbt/models/<layer>/<model_name>.sql`.
+5. If the model reads raw data, ensure each raw table is declared under the `bronze` source in `dbt/models/bronze/schema.yml`; add it if missing.
+6. Generate `dbt/models/<silver|gold>/<model_name>.sql`. **Never** generate `.sql` files under `dbt/models/bronze/`.
 7. Detect the primary key (Checkpoint 3 if ambiguous).
 8. Add model entry to `dbt/models/<layer>/schema.yml` with PK and FK tests. See [schema-conventions.md](references/schema-conventions.md).
 9. Run `dbt run --select <model_name>` and report result.
@@ -115,8 +120,9 @@ Ask if the layer is not obvious:
 Which layer should this transformation live in?
 
 - gold: business-ready, exposed for reporting or downstream consumption
-- silver: cleaned/intermediate, shared across downstream uses
-- bronze: close-to-source view over raw data, references sources
+- silver: cleaned/intermediate, reads raw via `{{ source('bronze', ...) }}`
+
+(bronze is not a SQL layer — it only holds `schema.yml` source declarations.)
 ```
 
 Layer is obvious when the user explicitly names it.
@@ -148,6 +154,21 @@ I could not unambiguously detect the primary key. Candidates:
 Which column(s) should be the primary key?
 ```
 
+### Checkpoint 4: Bronze SQL Model Refused
+
+If the user explicitly asks to create a bronze SQL model:
+
+```text
+Bronze is not a SQL layer in this project — it only holds source
+declarations in `dbt/models/bronze/schema.yml`. Silver reads raw data
+directly via `{{ source('bronze', '<raw_table>') }}`.
+
+Would you like to create this as a silver model instead?
+```
+
+Do not generate any file under `dbt/models/bronze/` other than
+`schema.yml`.
+
 ---
 
 ## Primary Key Detection
@@ -169,9 +190,9 @@ A column is a FK candidate if it matches `<entity>_id` where `<entity>` ≠ mode
 
 ## Timestamp Column Propagation (Gold Models)
 
-Every gold model **must** propagate at least one timestamp column so downstream Cube overlays can use SQL-based `refresh_key` (see `create-semantic-model` skill). Priority:
+Every gold model **must** propagate at least one timestamp column so downstream cubes can use SQL-based `refresh_key` (see `create-cubes` skill). Priority:
 
-1. `_airbyte_extracted_at` — present on all Airbyte sources; always propagate if available in upstream.
+1. An ingestion-time column on the raw table (e.g. Airbyte writes `_airbyte_extracted_at`) — propagate when present.
 2. `updated_at` / `modified_at` — CDC-friendly streams.
 3. `created_at` — insert-only fact tables.
 
@@ -181,8 +202,8 @@ If the upstream source has none of these, document it in a SQL comment: `-- no t
 
 See [sql-templates.md](references/sql-templates.md) for:
 
-- Bronze model template using `{{ source() }}`
-- Standard silver/gold model template
+- Standard silver model template (reads raw via `{{ source('bronze', ...) }}`)
+- Standard gold model template (reads silver via `{{ ref() }}`)
 - Bridge model (JSON array) template with concrete example
 - Bridge model naming convention and SQL content rules
 
@@ -201,7 +222,7 @@ See [edge-cases.md](references/edge-cases.md) for: missing SQL details, missing
 ```text
 Created dbt transformation: <model_name>
 
-Layer:           <bronze | silver | gold>
+Layer:           <silver | gold>
 File:            dbt/models/<layer>/<model_name>.sql
 Materialization: <inherited: table | overridden: <type>>
 Primary key:     <pk_column>  (or composite: <col_1>, <col_2>)

package/dist/templates/skills/create-dbt-transformations/references/edge-cases.md

@@ -26,9 +26,27 @@ The transformation you described references `<missing_model>`, which does not
 exist in dbt/models/. Should I create that model first?
 ```
 
-## Source is a raw Airbyte table not yet declared as a dbt source
+## Source is a raw table not yet declared as a dbt source
 
-Declare it as a source in `dbt/models/bronze/schema.yml` first (see [schema-conventions.md](schema-conventions.md)), then reference it with `{{ source('raw', '<table>') }}` in the bronze model SQL. Do not use fully qualified BigQuery names directly — that bypasses dbt's dependency graph and source freshness tracking.
+Declare it under `sources: - name: bronze` in `dbt/models/bronze/schema.yml`
+first (see [schema-conventions.md](schema-conventions.md)), then reference it
+with `{{ source('bronze', '<table>') }}` in the silver model SQL. Do not use
+fully qualified BigQuery names directly — that bypasses dbt's dependency
+graph and source freshness tracking.
+
+## User asks to create a bronze SQL model
+
+Refuse and redirect:
+
+```text
+Bronze is not a SQL layer in this project — `dbt/models/bronze/` only
+contains `schema.yml` declaring raw tables as sources. Silver reads raw
+data directly via `{{ source('bronze', '<raw_table>') }}`.
+
+Should I create this as a silver model instead?
+```
+
+Do not generate any file under `dbt/models/bronze/` other than `schema.yml`.
 
 ## run fails
 

package/dist/templates/skills/create-dbt-transformations/references/schema-conventions.md

@@ -10,9 +10,14 @@
 
 ---
 
-Each layer has one shared `schema.yml` at `dbt/models/<layer>/schema.yml`. Append new models; do not create per-model files.
+Each SQL layer (silver, gold) has one shared `schema.yml` at
+`dbt/models/<layer>/schema.yml`. Append new models; do not create per-model
+files.
 
-If the file does not exist, create it with:
+The bronze directory is **not** a SQL layer — its `schema.yml` contains only
+source declarations, no `models:` block.
+
+If a layer's `schema.yml` does not exist, create it with:
 
 ```yaml
 version: 2
@@ -22,7 +27,9 @@ models:
 
 ## Declaring Sources (bronze layer)
 
-Raw tables must be declared as dbt sources before they can be referenced with `{{ source() }}`. Sources live in `dbt/models/bronze/schema.yml` under a `sources:` block alongside the `models:` block.
+`dbt/models/bronze/schema.yml` is the only file in `dbt/models/bronze/`. It
+declares raw tables as dbt sources so that silver models can reference them
+with `{{ source('bronze', '<table>') }}`.
 
 `schema` maps to the BigQuery dataset (`REVOS_BQ_DATASET`):
 
@@ -30,23 +37,30 @@ Raw tables must be declared as dbt sources before they can be referenced with `{
 version: 2
 
 sources:
-  - name: raw
+  - name: bronze
     schema: "{{ env_var('REVOS_BQ_DATASET') }}"
     tables:
       - name: hubspot_contacts
       - name: hubspot_deals
       - name: stripe_charges
+```
+
+The corresponding silver model entry lives in `dbt/models/silver/schema.yml`:
+
+```yaml
+version: 2
 
 models:
-  - name: bronze_hubspot_contacts
+  - name: silver_hubspot_contacts
     ...
 ```
 
 Rules:
 
-- Use `raw` as the source name for all Airbyte-ingested tables.
-- Each raw table referenced in bronze SQL needs a corresponding entry under `tables:`.
+- Use `bronze` as the source name for all raw tables.
+- Each raw table referenced in silver SQL needs a corresponding entry under `tables:`.
 - If the source block already exists, append to the `tables:` list only.
+- Do **not** add a `models:` block to `dbt/models/bronze/schema.yml` — bronze contains source declarations only.
 
 ## Standard Model Entry