modscape 1.2.0 → 1.3.0

package/src/import-dbt.js

@@ -0,0 +1,181 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+
+const getFolderKey = (node) => {
+  if (node.resource_type === 'seed') return 'seeds';
+  return node.fqn?.[1] || 'default';
+};
+
+export async function importDbt(projectDir, options) {
+  const resolvedDir = path.resolve(projectDir || '.');
+  const manifestPath = path.join(resolvedDir, 'target', 'manifest.json');
+  const splitBy = options.splitBy || null;
+
+  // dbt_project.ymlからプロジェクト名を取得
+  const dbtProjectPath = path.join(resolvedDir, 'dbt_project.yml');
+  let projectName = path.basename(resolvedDir);
+
+  if (fs.existsSync(dbtProjectPath)) {
+    const dbtProject = yaml.load(fs.readFileSync(dbtProjectPath, 'utf8'));
+    projectName = dbtProject.name || projectName;
+  }
+
+  const outputDir = options.output || `modscape-${projectName}`;
+
+  try {
+    if (!fs.existsSync(manifestPath)) {
+      console.error(`  ❌ manifest.json not found at: ${manifestPath}`);
+      console.error(`  💡 Run 'dbt parse' in your dbt project first.`);
+      return;
+    }
+
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    console.log(`  🔍 Parsing dbt manifest: ${manifestPath}`);
+
+    const tables = [];
+    const domainsMap = new Map();
+    const tableSplitKeyMap = new Map();
+
+    const allNodes = { ...manifest.nodes, ...manifest.sources };
+
+    for (const [uniqueId, node] of Object.entries(allNodes)) {
+      if (!['model', 'seed', 'snapshot', 'source'].includes(node.resource_type)) continue;
+
+      const tableId = node.unique_id;
+
+      const columns = [];
+      if (node.columns) {
+        for (const [colKey, col] of Object.entries(node.columns)) {
+          columns.push({
+            id: col.name,
+            logical: {
+              name: col.name,
+              type: col.data_type || 'unknown',
+              description: col.description || ''
+            }
+          });
+        }
+      }
+
+      const tableEntry = {
+        id: tableId,
+        name: node.name,
+        logical_name: node.name,
+        physical_name: node.alias || node.name,
+        appearance: { type: 'table' },
+        conceptual: { description: node.description || '' },
+        columns,
+        lineage: { upstream: [] }
+      };
+
+      tables.push(tableEntry);
+
+      // split keyを決定
+      let splitKey = getFolderKey(node);
+      if (splitBy === 'schema') {
+        splitKey = node.schema || node.config?.schema || 'default';
+      } else if (splitBy === 'tag') {
+        const tags = node.tags || node.config?.tags || [];
+        splitKey = Array.isArray(tags) ? (tags[0] || 'untagged') : (tags || 'untagged');
+      }
+      tableSplitKeyMap.set(tableId, splitKey);
+
+      // domainsMapはfqn[1]ベースで常に構築
+      const domainName = getFolderKey(node);
+      if (domainName && domainName !== 'default') {
+        if (!domainsMap.has(domainName)) {
+          domainsMap.set(domainName, { id: domainName, name: domainName, tables: [] });
+        }
+        domainsMap.get(domainName).tables.push(tableId);
+      }
+    }
+
+    // lineage
+    for (const [uniqueId, node] of Object.entries(allNodes)) {
+      if (!['model', 'seed', 'snapshot', 'source'].includes(node.resource_type)) continue;
+      const tableEntry = tables.find(t => t.id === node.unique_id);
+      if (tableEntry && node.depends_on?.nodes) {
+        for (const upstreamId of node.depends_on.nodes) {
+          if (allNodes[upstreamId]) {
+            tableEntry.lineage.upstream.push(upstreamId);
+          }
+        }
+      }
+    }
+
+    // 出力先フォルダを作成
+    fs.mkdirSync(outputDir, { recursive: true });
+
+    if (splitBy) {
+      const splitMap = new Map();
+
+      for (const table of tables) {
+        const key = tableSplitKeyMap.get(table.id) || 'default';
+        if (!splitMap.has(key)) splitMap.set(key, []);
+        splitMap.get(key).push(table);
+      }
+
+      // 自己完結率を計算
+      const selfContainedRate = new Map();
+      for (const [key, splitTables] of splitMap.entries()) {
+        const tableIds = new Set(splitTables.map(t => t.id));
+        let internal = 0;
+        let external = 0;
+        for (const table of splitTables) {
+          for (const upstreamId of table.lineage?.upstream || []) {
+            if (tableIds.has(upstreamId)) internal++;
+            else external++;
+          }
+        }
+        const total = internal + external;
+        const rate = total > 0 ? Math.round(internal / total * 100) : 100;
+        selfContainedRate.set(key, { internal, external, rate });
+      }
+
+      let fileCount = 0;
+      for (const [key, splitTables] of splitMap.entries()) {
+        const splitOutputPath = path.join(outputDir, `${key}.yaml`);
+        const { rate, external } = selfContainedRate.get(key);
+
+        const splitDomains = Array.from(domainsMap.values())
+          .filter(d => d.tables.some(tid => splitTables.some(t => t.id === tid)))
+          .map(d => ({
+            ...d,
+            tables: d.tables.filter(tid => splitTables.some(t => t.id === tid))
+          }));
+
+        const outputModel = {
+          tables: splitTables,
+          relationships: [],
+          domains: splitDomains
+        };
+
+        fs.writeFileSync(splitOutputPath, yaml.dump(outputModel), 'utf8');
+
+        const icon = rate >= 80 ? '✅' : '⚠️ ';
+        const warning = rate < 80 ? ` (${external} cross-file lineage edges missing)` : '';
+        console.log(`  ${icon} ${splitOutputPath} (${splitTables.length} tables, ${rate}% self-contained${warning})`);
+        fileCount++;
+      }
+
+      console.log(`\n  📦 Split into ${fileCount} files → ${outputDir}/`);
+      console.log(`  🚀 Run 'modscape dev ${outputDir}' to visualize.`);
+
+    } else {
+      const outputPath = path.join(outputDir, 'dbt-model.yaml');
+      const outputModel = {
+        tables,
+        relationships: [],
+        domains: Array.from(domainsMap.values())
+      };
+
+      fs.writeFileSync(outputPath, yaml.dump(outputModel), 'utf8');
+      console.log(`  ✅ Successfully imported ${tables.length} tables → ${outputPath}`);
+      console.log(`  🚀 Run 'modscape dev ${outputDir}' to visualize.`);
+    }
+
+  } catch (error) {
+    console.error(`  ❌ Failed to import dbt metadata: ${error.message}`);
+  }
+}

package/src/index.js

@@ -8,8 +8,11 @@ import { build } from './build.js';
 import { initProject } from './init.js';
 import { exportModel } from './export.js';
 import { createModel } from './create.js';
+import { importDbt } from './import-dbt.js';
+import { syncDbt } from './sync-dbt.js';
 import { createRequire } from 'module';
-
+  import { mergeModels } from './merge.js';
+  
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
 
@@ -67,4 +70,38 @@ program
     exportModel(paths, options);
   });
 
+const dbtCommand = program
+  .command('dbt')
+  .description('dbt integration commands');
+
+dbtCommand
+  .command('import')
+  .description('Import dbt project into Modscape YAML models')
+  .argument('[project-dir]', 'path to dbt project directory (default: current directory)')
+  .option('-o, --output <dir>', 'output directory (default: modscape-<project-name>)')
+  .option('--split-by <key>', 'split output by "schema", "tag", or "folder"')
+  .action((projectDir, options) => {
+    importDbt(projectDir, options);
+  });
+
+// dbtCommandに追加
+dbtCommand
+  .command('sync')
+  .description('Sync dbt project changes into existing Modscape YAML models')
+  .argument('[project-dir]', 'path to dbt project directory (default: current directory)')
+  .option('-o, --output <dir>', 'output directory (default: modscape-<project-name>)')
+  .action((projectDir, options) => {
+    syncDbt(projectDir, options);
+  });
+
+
+program
+  .command('merge')
+  .description('Merge multiple YAML models into one')
+  .argument('<paths...>', 'YAML files or directories to merge')
+  .option('-o, --output <path>', 'output file path', 'merged.yaml')
+  .action((paths, options) => {
+    mergeModels(paths, options);
+  });
+
 program.parse();

package/src/init.js

@@ -64,25 +64,35 @@ export async function initProject(options = {}) {
 
     console.log('\n  Scaffolding modeling rules and commands...');
 
-    // 1. Create .modscape/rules.md
+    // 1. Create .modscape/rules.md and .modscape/codegen-rules.md
     const rulesTemplatePath = path.join(__dirname, 'templates/rules.md');
     const rulesTemplate = fs.readFileSync(rulesTemplatePath, 'utf8');
     await safeWriteFile('.modscape/rules.md', rulesTemplate);
 
+    const codegenRulesTemplatePath = path.join(__dirname, 'templates/codegen-rules.md');
+    const codegenRulesTemplate = fs.readFileSync(codegenRulesTemplatePath, 'utf8');
+    await safeWriteFile('.modscape/codegen-rules.md', codegenRulesTemplate);
+
     // 2. Create agent-specific files
     if (agents.includes('gemini')) {
-      const skillTemplate = fs.readFileSync(path.join(__dirname, 'templates/gemini/SKILL.md'), 'utf8');
-      await safeWriteFile('.gemini/skills/modscape/SKILL.md', skillTemplate);
+      const modelingTemplate = fs.readFileSync(path.join(__dirname, 'templates/gemini/modscape-modeling/SKILL.md'), 'utf8');
+      await safeWriteFile('.gemini/skills/modscape-modeling/SKILL.md', modelingTemplate);
+      const codegenTemplate = fs.readFileSync(path.join(__dirname, 'templates/gemini/modscape-codegen/SKILL.md'), 'utf8');
+      await safeWriteFile('.gemini/skills/modscape-codegen/SKILL.md', codegenTemplate);
     }
 
     if (agents.includes('codex')) {
-      const skillTemplate = fs.readFileSync(path.join(__dirname, 'templates/codex/SKILL.md'), 'utf8');
-      await safeWriteFile('.codex/skills/modscape-modeling/SKILL.md', skillTemplate);
+      const modelingTemplate = fs.readFileSync(path.join(__dirname, 'templates/codex/modscape-modeling/SKILL.md'), 'utf8');
+      await safeWriteFile('.codex/skills/modscape-modeling/SKILL.md', modelingTemplate);
+      const codegenTemplate = fs.readFileSync(path.join(__dirname, 'templates/codex/modscape-codegen/SKILL.md'), 'utf8');
+      await safeWriteFile('.codex/skills/modscape-codegen/SKILL.md', codegenTemplate);
     }
 
     if (agents.includes('claude')) {
-      const commandTemplate = fs.readFileSync(path.join(__dirname, 'templates/claude/command.md'), 'utf8');
-      await safeWriteFile('.claude/commands/modscape/modeling.md', commandTemplate);
+      const modelingTemplate = fs.readFileSync(path.join(__dirname, 'templates/claude/modeling.md'), 'utf8');
+      await safeWriteFile('.claude/commands/modscape/modeling.md', modelingTemplate);
+      const codegenTemplate = fs.readFileSync(path.join(__dirname, 'templates/claude/codegen.md'), 'utf8');
+      await safeWriteFile('.claude/commands/modscape/codegen.md', codegenTemplate);
     }
 
     console.log('\n  ✅ Initialization complete! Customize ".modscape/rules.md" to match your project standards.\n');

package/src/merge.js

@@ -0,0 +1,74 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+
+const collectYamlFiles = (inputPath) => {
+  const stat = fs.statSync(inputPath);
+  if (stat.isDirectory()) {
+    return fs.readdirSync(inputPath)
+      .filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))
+      .map(f => path.join(inputPath, f));
+  }
+  return [inputPath];
+};
+
+export function mergeModels(inputs, options) {
+  const outputPath = options.output || 'merged.yaml';
+
+  const mergedTables = [];
+  const mergedRelationships = [];
+  const mergedDomains = [];
+  const seenTableIds = new Set();
+  const seenDomainIds = new Set();
+
+  // 入力パスを全部ファイルに展開
+  const allFiles = [];
+  for (const input of inputs) {
+    allFiles.push(...collectYamlFiles(input));
+  }
+
+  if (allFiles.length === 0) {
+    console.error(`  ❌ No YAML files found`);
+    return;
+  }
+
+  for (const filePath of allFiles) {
+    try {
+      const data = yaml.load(fs.readFileSync(filePath, 'utf8'));
+      if (!data) continue;
+
+      // tables: 重複IDは除外
+      for (const table of data.tables || []) {
+        if (!seenTableIds.has(table.id)) {
+          mergedTables.push(table);
+          seenTableIds.add(table.id);
+        }
+      }
+
+      // relationships: そのまま全部追加
+      mergedRelationships.push(...(data.relationships || []));
+
+      // domains: 重複IDは除外
+      for (const domain of data.domains || []) {
+        if (!seenDomainIds.has(domain.id)) {
+          mergedDomains.push(domain);
+          seenDomainIds.add(domain.id);
+        }
+      }
+
+      console.log(`  📄 ${filePath} (${(data.tables || []).length} tables)`);
+    } catch (e) {
+      console.error(`  ❌ Failed to read ${filePath}: ${e.message}`);
+    }
+  }
+
+  const outputModel = {
+    tables: mergedTables,
+    relationships: mergedRelationships,
+    domains: mergedDomains
+  };
+
+  fs.writeFileSync(outputPath, yaml.dump(outputModel), 'utf8');
+  console.log(`\n  ✅ Merged ${allFiles.length} files → ${outputPath} (${mergedTables.length} tables)`);
+  console.log(`  🚀 Run 'modscape dev ${outputPath}' to visualize.`);
+}

package/src/sync-dbt.js

@@ -0,0 +1,146 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+
+const getFolderKey = (node) => {
+  if (node.resource_type === 'seed') return 'seeds';
+  return node.fqn?.[1] || 'default';
+};
+
+export async function syncDbt(projectDir, options) {
+  const resolvedDir = path.resolve(projectDir || '.');
+  const manifestPath = path.join(resolvedDir, 'target', 'manifest.json');
+
+  const dbtProjectPath = path.join(resolvedDir, 'dbt_project.yml');
+  let projectName = path.basename(resolvedDir);
+
+  if (fs.existsSync(dbtProjectPath)) {
+    const dbtProject = yaml.load(fs.readFileSync(dbtProjectPath, 'utf8'));
+    projectName = dbtProject.name || projectName;
+  }
+
+  const outputDir = options.output || `modscape-${projectName}`;
+
+  try {
+    if (!fs.existsSync(manifestPath)) {
+      console.error(`  ❌ manifest.json not found at: ${manifestPath}`);
+      console.error(`  💡 Run 'dbt parse' in your dbt project first.`);
+      return;
+    }
+
+    if (!fs.existsSync(outputDir)) {
+      console.error(`  ❌ Output directory not found: ${outputDir}`);
+      console.error(`  💡 Run 'modscape dbt import' first.`);
+      return;
+    }
+
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    console.log(`  🔍 Parsing dbt manifest: ${manifestPath}`);
+
+    const latestTablesMap = new Map();
+    const allNodes = { ...manifest.nodes, ...manifest.sources };
+
+    for (const [uniqueId, node] of Object.entries(allNodes)) {
+      if (!['model', 'seed', 'snapshot', 'source'].includes(node.resource_type)) continue;
+
+      const tableId = node.unique_id;
+
+      const columns = [];
+      if (node.columns) {
+        for (const [colKey, col] of Object.entries(node.columns)) {
+          columns.push({
+            id: col.name,
+            logical: {
+              name: col.name,
+              type: col.data_type || 'unknown',
+              description: col.description || ''
+            }
+          });
+        }
+      }
+
+      const lineageUpstream = [];
+      if (node.depends_on?.nodes) {
+        for (const upstreamId of node.depends_on.nodes) {
+          if (allNodes[upstreamId]) {
+            lineageUpstream.push(upstreamId);
+          }
+        }
+      }
+
+      latestTablesMap.set(tableId, {
+        id: tableId,
+        name: node.name,
+        logical_name: node.name,
+        physical_name: node.alias || node.name,
+        appearance: { type: 'table' },
+        conceptual: { description: node.description || '' },
+        columns,
+        lineage: { upstream: lineageUpstream }
+      });
+    }
+
+    const yamlFiles = fs.readdirSync(outputDir)
+      .filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));
+
+    if (yamlFiles.length === 0) {
+      console.error(`  ❌ No YAML files found in: ${outputDir}`);
+      return;
+    }
+
+    let addedCount = 0;
+    let updatedCount = 0;
+    const processedTableIds = new Set();
+
+    for (const yamlFile of yamlFiles) {
+      const yamlPath = path.join(outputDir, yamlFile);
+      const existing = yaml.load(fs.readFileSync(yamlPath, 'utf8'));
+
+      if (!existing || !Array.isArray(existing.tables)) continue;
+
+      const newTables = existing.tables.map(table => {
+        const latest = latestTablesMap.get(table.id);
+        if (!latest) return table;
+
+        processedTableIds.add(table.id);
+        updatedCount++;
+
+        return {
+          ...table,
+          name: latest.name,
+          logical_name: latest.logical_name,
+          physical_name: latest.physical_name,
+          conceptual: latest.conceptual,
+          columns: latest.columns,
+          lineage: latest.lineage
+        };
+      });
+
+      const updated = { ...existing, tables: newTables };
+      fs.writeFileSync(yamlPath, yaml.dump(updated), 'utf8');
+      console.log(`  📄 Updated: ${yamlPath}`);
+    }
+
+    const newTables = [];
+    for (const [tableId, latest] of latestTablesMap.entries()) {
+      if (!processedTableIds.has(tableId)) {
+        newTables.push(latest);
+        addedCount++;
+      }
+    }
+
+    if (newTables.length > 0) {
+      const firstYamlPath = path.join(outputDir, yamlFiles[0]);
+      const firstYaml = yaml.load(fs.readFileSync(firstYamlPath, 'utf8'));
+      firstYaml.tables = [...firstYaml.tables, ...newTables];
+      fs.writeFileSync(firstYamlPath, yaml.dump(firstYaml), 'utf8');
+      console.log(`  ➕ Added ${addedCount} new tables → ${yamlFiles[0]}`);
+    }
+
+    console.log(`  ✅ Sync complete: ${updatedCount} updated, ${addedCount} added`);
+    console.log(`  🚀 Run 'modscape dev ${outputDir}' to visualize.`);
+
+  } catch (error) {
+    console.error(`  ❌ Failed to sync dbt metadata: ${error.message}`);
+  }
+}

package/src/templates/claude/codegen.md

@@ -0,0 +1,15 @@
+Generate implementation code from a Modscape YAML model.
+
+## Instructions
+1. FIRST, read `.modscape/codegen-rules.md` to understand how to interpret the YAML.
+2. SECOND, read the target YAML file specified by the user (default: `model.yaml`).
+3. Ask the user which tool to target if not specified (dbt / SQLMesh / Spark SQL / plain SQL).
+4. Generate models in dependency order (upstream first) based on `lineage.upstream`.
+5. Add `-- TODO:` comments wherever the YAML does not provide enough information to generate definitive code.
+
+## Usage
+```
+/modscape:codegen
+/modscape:codegen path/to/model.yaml
+/modscape:codegen path/to/model.yaml --target dbt
+```

package/src/templates/claude/{command.md → modeling.md}

@@ -1,5 +1,3 @@
-# /modscape:modeling
-
 Start an interactive data modeling session.
 
 ## Instructions

package/src/templates/codegen-rules.md

@@ -0,0 +1,138 @@
+# Modscape Code Generation Rules
+
+This file defines how to interpret a Modscape `model.yaml` when generating implementation code (dbt, SQLMesh, Spark, etc.).
+
+Read this file alongside `.modscape/rules.md` (which defines the YAML schema) before generating any code.
+
+---
+
+## 1. Dependency Order (DAG)
+
+Use `lineage.upstream` to determine build order. Always generate upstream models before downstream ones.
+
+```yaml
+lineage:
+  upstream: [stg_orders, stg_order_items]  # these must be generated first
+```
+
+In dbt this becomes `{{ ref('stg_orders') }}`. In SQLMesh, `MODEL (... grain [...])` with `@this_model` references. Apply the equivalent pattern for your target tool.
+
+---
+
+## 2. Materialization Strategy
+
+Map `implementation.materialization` directly to your target tool's config block. If `implementation` is absent, fall back to `appearance.type` as a hint:
+
+| `appearance.type` | Default materialization |
+|-------------------|------------------------|
+| `fact`            | `incremental`          |
+| `dimension`       | `table`                |
+| `mart`            | `table`                |
+| `hub` / `link` / `satellite` | `table`   |
+| `table` / `staging` | `view`               |
+
+```yaml
+# Explicit — always prefer this over the default
+implementation:
+  materialization: incremental
+  incremental_strategy: merge
+  unique_key: order_id
+  partition_by: { field: order_date, granularity: day }
+  cluster_by: [customer_id]
+```
+
+---
+
+## 3. JOIN Conditions
+
+Derive JOIN keys from two sources:
+
+1. **`relationships`** — explicit FK links between tables
+2. **`columns[].logical.isForeignKey: true`** — columns that carry FK values
+
+Use matching column names across tables to infer the ON clause. When a column is `isForeignKey: true` and shares a name with another table's `isPrimaryKey: true` column, that is the join key.
+
+---
+
+## 4. SCD Type 2
+
+When `appearance.scd: type2`, the dimension requires historical tracking:
+
+- In **dbt**: generate a snapshot (`dbt snapshot`) driven by the `updated_at` column, then build the dimension model on top of the snapshot.
+- In other tools: apply the equivalent row-versioning pattern.
+- Always expose `valid_from`, `valid_to`, and `is_current` columns (defined in the YAML).
+- When joining to a SCD type2 dimension from a fact table, filter `WHERE is_current = true` unless the query is point-in-time.
+
+---
+
+## 5. Mart Aggregations
+
+When `implementation.grain` and `implementation.measures` are defined, use them directly:
+
+```yaml
+implementation:
+  grain: [month_key, region_id]       # → GROUP BY
+  measures:
+    - column: total_revenue
+      agg: sum
+      source_column: fct_sales.amount  # → SUM(s.amount) AS total_revenue
+    - column: order_count
+      agg: count_distinct
+      source_column: fct_orders.order_id
+```
+
+When `grain`/`measures` are **not** defined, infer from column metadata:
+- `isPrimaryKey: true` non-measure columns → likely GROUP BY candidates
+- `additivity: fully` → safe to use `SUM` or `COUNT`
+- `additivity: semi` → use `AVG`, `MIN`, `MAX` or similar non-summable aggregation
+- Column name patterns (`_count`, `_revenue`, `_total`, `_avg`) provide additional hints
+
+---
+
+## 6. Column Mapping
+
+| YAML field | Code generation use |
+|-----------|-------------------|
+| `logical.name` | Column alias / documentation |
+| `physical.name` | Actual column name in SQL (use this if present, otherwise use `id`) |
+| `isPrimaryKey: true` | Declare as primary key constraint or unique test |
+| `isForeignKey: true` | JOIN key candidate |
+| `isPartitionKey: true` | Confirm as partition column |
+| `isMetadata: true` | Audit/system column — include last, or exclude from business logic |
+| `additivity` | Aggregation function choice (see section 5) |
+| `physical.type` | Override the logical type for DDL generation |
+| `physical.constraints` | Add NOT NULL / UNIQUE constraints where supported |
+
+---
+
+## 7. TODO Comments for Inferred Logic
+
+When you must make an assumption that cannot be derived from the YAML, leave a `TODO` comment so the user can review it. Keep generated code runnable; do not leave placeholders that cause syntax errors.
+
+Common TODO patterns:
+
+```sql
+-- TODO: verify surrogate key generation method (currently using row_number — consider hash if order is non-deterministic)
+-- TODO: confirm incremental watermark column (currently using 'updated_at' — adjust if your source uses a different audit column)
+-- TODO: verify date range for date dimension (currently 2020-01-01 to 2030-12-31)
+-- TODO: grain/measures not defined in YAML — aggregations inferred from column names; verify before production use
+-- TODO: source schema assumed to be 'raw' — update {{ source(...) }} references to match your project
+```
+
+---
+
+## 8. Physical Table Names
+
+When `physical_name` is set on a table, use it as the actual table name in DDL or config blocks. The `id` field is the logical reference name used in `ref()` calls and `lineage.upstream`.
+
+---
+
+## 9. What Modscape Does Not Define (Always TODO)
+
+The following are intentionally out of scope for the YAML. Always emit a TODO when you encounter them:
+
+- Surrogate key generation strategy (hash vs. sequence vs. row_number)
+- Incremental filter / watermark logic
+- Source system schema names
+- Date dimension generation range and method
+- Database-specific SQL dialect quirks

package/src/templates/codex/modscape-codegen/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: modscape-codegen
+description: Generate implementation code (dbt, SQLMesh, Spark SQL, etc.) from a Modscape YAML model.
+---
+
+# Code Generation from Modscape YAML
+
+You are a data pipeline engineer. Your task is to generate implementation code from a Modscape `model.yaml`.
+
+BEFORE generating any code, you MUST read `.modscape/codegen-rules.md` to understand how to interpret the YAML.
+
+## Steps
+1. READ `.modscape/codegen-rules.md`.
+2. READ the target YAML file specified by the user (default: `model.yaml`).
+3. ASK which tool to target if not specified (dbt / SQLMesh / Spark SQL / plain SQL).
+4. GENERATE models in dependency order (upstream first) based on `lineage.upstream`.
+5. ADD `-- TODO:` comments wherever the YAML does not provide enough information to generate definitive code.
+
+## COMMAND: /modscape:codegen
+Usage: `/modscape:codegen [path/to/model.yaml] [--target dbt|sqlmesh|spark|sql]`