modscape 2.0.3 → 2.0.4

package/README.ja.md

@@ -62,6 +62,8 @@ npm install -g modscape
     ```
     `.modscape/rules.md`（YAMLスキーマのルール）と `.modscape/codegen-rules.md`（実装コード生成のルール）、および各エージェント用のコマンドファイルが生成されます。
 
+    > **ルールの更新**: Modscape をアップグレードした後は、`modscape init` を再実行することで `.modscape/rules.md` と `.modscape/codegen-rules.md` を最新版に上書きできます。
+
 2.  **起動**: ビジュアライザーを起動します。
     ```bash
     modscape dev model.yaml
@@ -73,10 +75,12 @@ npm install -g modscape
 4.  **実装コードの生成** — `/modscape:codegen` でYAMLをdbt / SQLMesh / Spark SQLに変換します。
     > *".modscape/codegen-rules.md に従って、model.yaml からdbtモデルを生成して。"*
 
-    エージェントは `lineage.upstream` を元に依存関係の順でモデルを生成し、YAMLで定義しきれない箇所には `-- TODO:` コメントを残します。
+    エージェントは `lineage` セクションを元に依存関係の順でモデルを生成し、YAMLで定義しきれない箇所には `-- TODO:` コメントを残します。
 
 ### B: 手動モデリング
-1.  **YAML作成**: `model.yaml` ファイルを作成します。
+アーキテクチャを直接コントロールしたい場合に最適です。
+
+1.  **YAML作成**: `model.yaml` ファイルを作成します（[YAMLリファレンス](#モデルの定義-yaml) を参照）。
 2.  **起動**: ビジュアライザーを起動します。
     ```bash
     modscape dev model.yaml

package/README.md

@@ -63,6 +63,8 @@ Leverage AI coding assistants (**Gemini CLI, Claude Code, or Codex**) to build y
     ```
     This creates `.modscape/rules.md` (YAML schema rules) and `.modscape/codegen-rules.md` (code generation rules), plus agent-specific command files.
 
+    > **Updating rules**: After upgrading Modscape, re-run `modscape init` to overwrite `.modscape/rules.md` and `.modscape/codegen-rules.md` with the latest bundled version.
+
 2.  **Start Dev**: Launch the visualizer.
     ```bash
     modscape dev model.yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modscape",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Modscape: A YAML-driven data modeling visualizer CLI",
   "repository": {
     "type": "git",

package/src/templates/rules.md

@@ -16,7 +16,7 @@ COORDINATES    ONLY in `layout`. NEVER inside tables or domains.
 LINEAGE        Use top-level `lineage` section (not relationships, not table.lineage.upstream).
 parentId       Declare a table's domain membership inside layout, not inside domains.
 IDs            Every object (table, domain, annotation) needs a unique `id`.
-sampleData     First row = column IDs. At least 3 realistic data rows.
+sampleData     At least 3 realistic data rows. No header row.
 Grid           All x/y values must be multiples of 40.
 ```
 
@@ -45,13 +45,12 @@ layout:        # (object) ALL coordinates — REQUIRED if any objects exist
 
 | Field | Required | Description |
 |-------|----------|-------------|
-| `id` | **REQUIRED** | Unique identifier used as a key in `layout`, `domains.tables`, `lineage.upstream`, etc. Use snake_case. |
+| `id` | **REQUIRED** | Unique identifier used as a key in `layout`, `domains.tables`, `lineage`, etc. Use snake_case. |
 | `name` | **REQUIRED** | Conceptual (business) name shown large on the canvas. |
 | `logical_name` | optional | Formal business name shown medium. Omit if same as `name`. |
 | `physical_name` | optional | Actual database table name shown small. |
 | `appearance` | optional | Visual type, icon, color. |
 | `conceptual` | optional | AI-friendly business context metadata. |
-| `lineage` | optional | Upstream table IDs. Only for `mart` / aggregated tables. |
 | `columns` | optional | Column definitions. |
 | `sampleData` | optional | 2D array of sample rows. Strongly recommended. |
 
@@ -72,7 +71,7 @@ appearance:
 |------|-------------|
 | `fact` | Events, transactions, measurements. Has measures (numbers) and FK columns. |
 | `dimension` | Entities, master data, reference lists. Descriptive attributes. |
-| `mart` | Aggregated or consumer-facing output. **Always add `lineage.upstream`.** |
+| `mart` | Aggregated or consumer-facing output. **Always add a top-level `lineage` entry.** |
 | `hub` | Data Vault: stores a single unique business key. |
 | `link` | Data Vault: joins two or more hubs (transaction or relationship). |
 | `satellite` | Data Vault: descriptive attributes of a hub, tracked over time. |
@@ -96,7 +95,7 @@ Each column has an `id` plus optional `logical` and `physical` blocks.
 
 ```yaml
 columns:
-  - id: order_id           # REQUIRED. Unique within the table. Used in sampleData header.
+  - id: order_id           # REQUIRED. Unique within the table.
     logical:
       name: "Order ID"     # Display name
       type: Int            # Int | String | Decimal | Date | Timestamp | Boolean | ...
@@ -138,7 +137,7 @@ relationships:
 | `many-to-one` | Fact → Dimension *(inverse notation of above)* |
 | `many-to-many` | Via a bridge / link table |
 
-**MUST NOT** use `relationships` to express data lineage (use `lineage.upstream` instead).
+**MUST NOT** use `relationships` to express data lineage (use the top-level `lineage` section instead).
 
 ---
 
@@ -497,7 +496,7 @@ The command reads `target/manifest.json` and produces YAML with:
 | `physical_name` | `node.alias` | Falls back to `node.name` |
 | `conceptual.description` | `node.description` | From dbt docs |
 | `columns[].logical.name/type/description` | `node.columns` | From dbt schema.yml |
-| `lineage.upstream` | `node.depends_on.nodes` | Auto-populated |
+| `lineage` (top-level) | `node.depends_on.nodes` | Auto-populated as `{from, to}` entries |
 | `appearance.type` | — | **Always `table`. Must be reclassified.** |
 | `sampleData` | — | **Not generated. Must be added.** |
 | `layout` | — | **Not generated. Must be added.** |
@@ -517,7 +516,7 @@ After running `modscape dbt import`, the generated YAML needs enrichment. AI age
 
 3. **Add `sampleData`** — The import does not generate sample data. Add at least 3 realistic rows per table.
 
-4. **Do NOT re-generate `lineage.upstream`** — It is already correctly populated from `depends_on.nodes`.
+4. **Do NOT re-generate `lineage` entries** — Top-level `lineage` is already correctly populated from `depends_on.nodes`.
 
 ### 11-4. `dbt sync` — Incremental updates
 
@@ -527,7 +526,7 @@ Use `modscape dbt sync` when the dbt project has changed (new models, updated co
 - `name`, `logical_name`, `physical_name`
 - `conceptual.description`
 - `columns` (all)
-- `lineage.upstream`
+- `lineage` (top-level)
 
 **What `sync` preserves (safe to edit manually):**
 - `appearance` (type, icon, color, scd)
@@ -549,14 +548,15 @@ id: "model.my_project.fct_orders"
 id: "source.my_project.raw.orders"
 id: "seed.my_project.product_categories"
 
-# lineage.upstream also uses unique_id format
+# top-level lineage also uses unique_id format
 lineage:
-  upstream:
-    - "model.my_project.stg_orders"
-    - "source.my_project.raw.customers"
+  - from: "model.my_project.stg_orders"
+    to: "model.my_project.fct_orders"
+  - from: "source.my_project.raw.customers"
+    to: "model.my_project.fct_orders"
 ```
 
-**MUST NOT** shorten these IDs. They are the join keys between `tables`, `domains.tables`, `lineage.upstream`, and `layout`.
+**MUST NOT** shorten these IDs. They are the join keys between `tables`, `domains.tables`, `lineage`, and `layout`.
 
 ---
 
@@ -611,6 +611,17 @@ Use the built-in mutation commands to **add, update, or remove individual entiti
 
 ### 13-2. Recommended AI Agent Flow
 
+When inspecting a model's current state, **prefer using the list/get commands** over reading the YAML file directly.
+They return validated, structured JSON output that is easier to process.
+
+```bash
+# Inspect current state before making changes
+modscape table list model.yaml --json
+modscape domain list model.yaml --json
+modscape relationship list model.yaml --json
+modscape lineage list model.yaml --json
+```
+
 Before `add` or `update`, check existence with `get` or `list`:
 
 ```bash

package/visualizer/package.json

@@ -1,7 +1,7 @@
 {
   "name": "visualizer",
   "private": true,
-  "version": "2.0.3",
+  "version": "2.0.4",
   "type": "module",
   "scripts": {
     "dev": "vite",