modscape 0.8.0 → 0.9.0

package/README.ja.md

@@ -6,25 +6,35 @@
 [![Publish to NPM](https://github.com/yujikawa/modscape/actions/workflows/publish.yml/badge.svg)](https://github.com/yujikawa/modscape/actions/workflows/publish.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 
-Modscapeは、YAMLベースのデータモデリング・ビジュアライザーです。データエンジニアやアーキテクトが、概念・論理・物理モデルのギャップを埋め、サンプルデータに基づいた「ストーリー」を共有しながら設計を進めることを支援します。
+**Modscape** は、モダンなデータ基盤（Modern Data Stack）に特化した、YAML駆動のデータモデリング・ビジュアライザーです。物理的なスキーマとビジネスロジックのギャップを埋め、データチームがデータを通じた「ストーリー」を設計、文書化、共有することを可能にします。
 
 [ライブデモ](https://yujikawa.github.io/modscape/)
 
+## なぜ Modscape なのか？
+
+現代のデータ分析基盤において、データモデリングは単に図を描くだけの作業ではありません。バージョン管理が可能で、AIと親和性が高く、エンジニアとステークホルダーの双方が理解できる **「信頼できる唯一の情報源（SSOT）」** を維持することが不可欠です。
+
+- **データエンジニア向け**: 物理テーブルと論理エンティティの明確なマッピングを維持。複雑な **Data Vault** や **スター・スキーマ** を視覚化。
+- **アナリティクスエンジニア向け**: dbt などのツールに適した、モジュール性の高いモデルを設計。SQLを書く前に、データの粒度（Grain）や主キー、リレーションを定義。
+- **データサイエンティスト向け**: **サンプルデータ「ストーリー」** によるデータ探索。クエリを叩くことなく、統合されたサンプルプレビューからテーブルの目的と内容を把握。
+
 ## 主な機能
 
-- **YAMLファースト**: 単一のシンプルなYAMLファイルでデータモデル全体を定義。
-- **統合サイドバー**: ナビゲーション、検索、YAML編集機能を備えた高機能サイドバー。
-- **インタラクティブ・モデリング**: 
-  - **ドラッグで接続**: カラムから別のテーブルへドラッグするだけでリレーションを作成。
-  - **プロパティ・エディタ**: テーブルやリレーションのメタデータをUIから直接編集。
-  - **インタラクティブ削除**: クリック一つでテーブルやリレーションを削除。
-- **サンプルデータ「ストーリー」**: エンティティにサンプルデータを紐付け、データの目的を具体的に解説。
-- **スマート・レイアウト**: 
-  - **自動位置保存**: ドラッグ＆ドロップで配置を調整。座標はYAMLに即座に反映。
-  - **適応型サイジング**: カラム数が多いテーブル（10行以上）は自動でリミットがかかり、スクロール表示に。
-- **マルチファイル・サポート**: ディレクトリ内の複数のモデルをシームレスに切り替え。
-- **ドキュメント・エクスポート**: Mermaid互換のMarkdownドキュメント（ER図、ドメインカタログを含む）を生成。
-- **AIエージェント対応**: Gemini, Claude, Codex向けのプロンプトを用意。AIとの共同モデリングを支援。
+- **YAML-as-Code**: データアーキテクチャ全体を人間が読みやすい単一のYAMLファイルで定義。Gitによる変更管理が可能。
+- **ローカルYAMLの即時可視化**: Modscapeのスキーマに従ったYAMLファイルを指定するだけで、即座にビジュアライズ。データベース接続やクラウド設定は一切不要で、すぐにモデリング結果を確認できます。
+- **データ分析特化のモデリング**: `fact`, `dimension`, `hub`, `link`, `satellite` などのエンティティタイプを標準サポート。
+- **サンプルデータ「ストーリー」**: エンティティに現実的なサンプルデータを紐付け、データの背後にある「物語」を解説。
+- **インタラクティブなビジュアルキャンバス**: 
+  - **ドラッグで接続**: カラム間のリレーションを直感的に作成。
+  - **自動レイアウト永続化**: キャンバス上の配置は、即座に元のYAMLファイルの座標情報として保存。
+  - **ドメイン・グルーピング**: テーブルをビジネスドメインごとに整理。
+- **分析メタデータ**: 
+  - **ファクト・ストラテジー**: `transaction`, `periodic`, `accumulating`, `factless` といったデータの「粒度」を定義。
+  - **SCD（徐変ディメンション）管理**: `SCD Type 2` などの履歴管理方式を可視化。
+  - **加算規則（Additivity）**: カラムが合計可能か（`fully`, `semi`, `non`）を明示し、BI開発をガイド。
+  - **メタデータ/監査追跡**: 監査用カラムを専用アイコンで識別。
+- **AIエージェント対応**: **Gemini, Claude, Codex** 用の雛形を内蔵。LLMを活用してモデリング作業を劇的に加速。
+- **ドキュメント・エクスポート**: 社内WikiやGitHub/GitLab Pagesで利用可能な、Mermaid図入りのMarkdownを生成。
 
 ## インストール
 
@@ -38,30 +48,35 @@ npm install -g modscape
 
 ## はじめに
 
-ワークフローに合わせて以下のいずれかの方法で開始してください。
-
 ### A: AI駆動のモデリング（推奨）
-Gemini CLI, Claude Code, Cursor/CodexなどのAIアシスタントを使用する場合に最適です。
+Gemini CLI, Claude Code, Codex などのAIアシスタントを活用してモデルを構築します。
 
-1.  **初期化**: モデリングルールとAIエージェント用手順書を生成します。
+1.  **初期化**: 使用するAIエージェントに合わせてモデリングルールと手順書を生成します。
     ```bash
-    modscape init
+    # Gemini CLI の場合
+    modscape init --gemini
+
+    # Claude Code の場合
+    modscape init --claude
+
+    # Codex の場合
+    modscape init --codex
     ```
-2.  **起動**: モデルファイルを指定してビジュアライザーを起動します。
+2.  **起動**: ビジュアライザーを起動します。
     ```bash
     modscape dev model.yaml
     ```
-3.  **AIに指示**: `.modscape/rules.md` のルールに従って `model.yaml` にテーブルやカラムを追加するようAIに伝えてください。
+3.  **AIに指示**: AIエージェントにこう伝えてください： *" .modscape/rules.md のルールに従って、model.yaml に新しい 'Marketing' ドメインと 'campaign_performance' ファクトテーブルを追加して。"*
 
 ### B: 手動モデリング
-YAMLを直接編集して詳細なコントロールを行いたい場合に最適です。
+詳細な設計コントロールを行いたい場合に最適です。
 
-1.  **YAML作成**: `model.yaml` ファイルを作成します（[モデルの定義](#モデルの定義-yaml)を参照）。
+1.  **YAML作成**: `model.yaml` ファイルを作成します（[YAMLリファレンス](#モデルの定義-yaml)を参照）。
 2.  **起動**: ビジュアライザーを起動します。
     ```bash
     modscape dev model.yaml
     ```
-3.  **サンプルを試す**: 付属のサンプルディレクトリを読み込むことも可能です：
+3.  **サンプルを試す**: 組み込みのパターンを確認できます：
     ```bash
     modscape dev samples/
     ```
@@ -70,139 +85,111 @@ YAMLを直接編集して詳細なコントロールを行いたい場合に最
 
 ## モデルの定義 (YAML)
 
-Modscapeは、包括的でありながら人間が読みやすいYAMLスキーマを採用しています。この単一のファイルが、概念・論理・物理データモデルの「信頼できる唯一の情報源（SSOT）」として機能します。
-
-### 完全なYAMLリファレンス
+Modscapeは、データ分析のコンテキストに最適化されたスキーマを採用しています。この単一のファイルが、論理および物理データアーキテクチャの「信頼できる唯一の情報源（SSOT）」として機能します。
 
 ```yaml
 # 1. Domains: 関連するテーブルをグループ化する視覚的なコンテナ
 domains:
-  - id: sales_domain
-    name: 売上と注文
-    description: 主要な商取引
+  - id: core_sales
+    name: 主要売上
+    description: "ドメインの任意の説明"
     color: "rgba(59, 130, 246, 0.05)" # コンテナの背景色
-    tables: [orders, order_items] # 所属するテーブルIDのリスト
+    tables: [orders, products] # 所属するテーブルIDのリスト
 
-# 2. Tables: エンティティの定義
+# 2. Tables: マルチレイヤーのメタデータを持つエンティティ定義
 tables:
   - id: orders
     name: ORDERS
     appearance:
       type: fact    # fact | dimension | hub | link | satellite
-      icon: 📦      # 絵文字や任意の文字
-      color: "#f87171" # このエンティティのカスタムテーマカラー
+      # --- 分析メタデータ ---
+      strategy: transaction # transaction | periodic | accumulating | factless
+      scd: null             # type0 | type1 | type2 | type3 | type6 (Dimension用)
+      icon: 📦      # カスタム絵文字や文字
+      color: "#f87171" # エンティティのテーマカラー
     
     conceptual:
-      description: "顧客の購入記録"
-      tags: ["WHAT", "WHEN"] # BEAM* メソドロジーのタグ
+      description: "販売取引記録"
+      tags: ["WHO", "WHEN", "HOW MUCH"] # 粒度の識別子（BEAM*等）
     
     physical:
-      name: T_ORDERS     # データベース上の実際のテーブル名
-      schema: RAW_SALES  # データベースのスキーマ名
+      name: STG_ORDERS     # 実際のDBテーブル名
+      schema: ANALYTICS_DB # DBスキーマ/名前空間
     
     columns:
       - id: order_id
         logical:
           name: ORDER_ID
-          type: Integer
-          description: "注文のユニークな識別子"
+          type: Int
+          description: "ユニークな識別子"
           isPrimaryKey: true
+          isForeignKey: false
+          isPartitionKey: false
+          # --- 分析メタデータ ---
+          isMetadata: false # 監査用カラム等に true を設定 (🕒 アイコン)
+          additivity: fully # fully | semi | non (Σ アイコン)
         physical:
           name: O_ID
           type: NUMBER(38,0)
           constraints: ["NOT NULL"]
       
       - id: customer_id
-        logical:
-          name: CUSTOMER_ID
-          type: Integer
-          isForeignKey: true # 外部キーであることを示す
+        logical: { name: CUSTOMER_ID, type: Int, isForeignKey: true }
 
-    # 3. Sample Data: ストーリーを伝えるための現実的なデータ
-    # (2次元配列を直接記述。論理カラムの定義順にマッピングされます)
+    # 3. Sample Data: データを通じたストーリーの提示
     sampleData:
       - [1001, 501]
       - [1002, 502]
 
-# 4. Relationships: テーブル間の接続
+# 4. Relationships: カラムレベルの接続
 relationships:
   - from: { table: orders, column: customer_id }
     to: { table: customers, column: id }
     type: many-to-one # one-to-one | one-to-many | many-to-many
 
 # 5. Layout: 座標情報 (自動管理)
-# 手動で記述する必要はありません。ドラッグするとModscapeが自動更新します。
 layout:
   orders: { x: 100, y: 100, width: 320, height: 400 }
 ```
 
-### スキーマの詳細解説
-
-| セクション | フィールド | 説明 |
-| :--- | :--- | :--- |
-| **`domains`** | `color` | ビジュアライザー上でグループを囲むコンテナの背景色を定義します。 |
-| **`appearance`**| `type` | 指定がない場合のヘッダーアイコンと色を決定します（標準: スター・スキーマまたはData Vault）。 |
-| **`conceptual`**| `tags` | ビジネスコンテキストタグ。モデリングの粒度（WHO, WHAT, WHERE）の識別に役立ちます。 |
-| **`physical`** | `name`/`schema` | 論理エンティティを実際のデータベースオブジェクトにマッピングします。 |
-| **`columns`** | `isPrimaryKey` | 🔑 アイコンを表示し、テーブルの粒度を明示します。 |
-| | `isForeignKey` | 🔩 アイコンを表示し、下流への接続を示します。 |
-| **`sampleData`**| - | 2次元配列。論理カラムの定義順に値がマッピングされます。 |
-| **`relationships`**| `type` | 接続線の矢印の形や視覚的なスタイルを制御します。 |
-
 ---
 
 ## 使い方
 
-### 開発モード (Interactive Editor)
-YAMLを編集し、エンティティを視覚的に配置するためのローカルセッションを開始します。
+### 開発モード (インタラクティブ)
+YAMLを編集し、エンティティを視覚的に配置します。
 
 ```bash
-# ディレクトリを指定して、中のすべてのモデルを管理
-modscape dev models/
-
-# または特定のファイルを指定
-modscape dev my-model.yaml
+modscape dev ./models
 ```
-- 自動的に `http://localhost:5173` が開きます。
-- **永続化**: エンティティの配置変更はYAMLファイルに即座に保存されます。
-- **セキュアルーティング**: モデルはスラッグ経由でアクセスされ、ローカルの絶対パスは隠蔽されます。
+- `http://localhost:5173` が開きます。
+- **永続化**: レイアウトやメタデータの変更は、直接ファイルに書き戻されます。
 
-### ビルドモード (Static Site Generation)
-ドキュメントを共有するための静的ウェブサイトを生成します（GitHub Pagesなどに最適）。
+### ビルドモード (静的サイト)
+チーム共有用のスタンドアロンなドキュメントサイトを生成します。
 
 ```bash
-modscape build models/ -o dist-site
+modscape build ./models -o docs-site
 ```
 
-### エクスポートモード (Static Documentation)
-Mermaid図を含むMarkdownドキュメントを一括生成します。
+### エクスポートモード (Markdown)
+Mermaid図を含むMarkdownドキュメントを生成します。
 
 ```bash
-# 標準出力に書き出し
-modscape export models/ecommerce.yaml
-
-# ファイルに保存
-modscape export models/ -o docs/
+modscape export ./models -o docs/ARCHITECTURE.md
 ```
 
 ## AIエージェントとの統合
 
-ModscapeはAIアシスタントとの連携を前提に設計されています。`modscape init` を実行すると以下のファイルが生成されます：
-
-- **`.modscape/rules.md`**: モデリング規約の「信頼できる唯一の情報源（SSOT）」。
-- **エージェント向け手順書**: Gemini, Claude, Cursor/Codex向けの事前定義プロンプト。
-
-AIに対して：*"Follow the rules in .modscape/rules.md to add a new billing domain to my model.yaml."* と指示してください。
+Modscapeは **AI-First** を掲げて設計されています。 `modscape init` を実行することで、 `.modscape/rules.md` を通じてAIエージェントと「契約」を結び、プロジェクト全体で一貫したモデリングパターン（命名規則、データ型など）を維持できます。
 
 ## クレジット
 
-Modscapeは以下の素晴らしいオープンソースプロジェクトによって支えられています：
-
-- **[React Flow](https://reactflow.dev/)**: インタラクティブなグラフエンジン。
-- **[Radix UI](https://www.radix-ui.com/)**: アクセシブルなUIプリミティブ。
-- **[Lucide](https://lucide.dev/)**: 美しく一貫性のあるアイコン。
-- **[shadcn/ui](https://ui.shadcn.com/)**: コンポーネントパターンとデザインインスピレーション。
-- **[Express](https://expressjs.com/)**: ローカル開発環境のサーバー。
+Modscapeは以下のプロジェクトによって支えられています：
+- **React Flow**: インタラクティブなグラフエンジン。
+- **Lucide**: 一貫性のあるアイコンセット。
+- **Express**: ローカル開発サーバー。
+- **Commander**: CLIフレームワーク。
 
 ## ライセンス
 MIT

package/README.md

@@ -6,25 +6,35 @@
 [![Publish to NPM](https://github.com/yujikawa/modscape/actions/workflows/publish.yml/badge.svg)](https://github.com/yujikawa/modscape/actions/workflows/publish.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 
-Modscape is a YAML-driven data modeling visualizer. It helps data engineers and architects bridge the gap between conceptual, logical, and physical data models while maintaining sample data "stories".
+**Modscape** is a YAML-driven data modeling visualizer specialized for **Modern Data Stack** architectures. It bridges the gap between raw physical schemas and high-level business logic, empowering data teams to design, document, and share their data stories.
 
 [Live Demo](https://yujikawa.github.io/modscape/)
 
-## Features
-
-- **YAML-First**: Define your entire data model in a single, simple YAML file.
-- **Unified Sidebar**: A feature-rich sidebar for navigation, search, and YAML editing.
-- **Interactive Modeling**: 
-  - **Drag-to-Connect**: Create relationships by dragging from a column handle to another table.
-  - **Property Editor**: Edit table and relationship metadata directly in the UI.
-  - **Interactive Deletion**: Remove tables or relationships with a single click.
-- **Sample Data "Stories"**: Attach sample data to entities to explain the data's purpose.
-- **Smart Layout**: 
-  - **Auto-Positioning**: Arrange entities via drag-and-drop; positions are saved directly back to your YAML.
-  - **Adaptive Sizing**: Tables with many columns are automatically capped at 10 rows with scrolling for better canvas visibility.
-- **Multi-file Support**: Manage multiple models in a single directory and switch between them seamlessly.
-- **Documentation Export**: Generate Mermaid-compatible Markdown documentation including ER diagrams and domain catalogs.
-- **AI-Agent Ready**: Scaffolding for Gemini, Claude, and Codex to help you model via AI.
+## Why Modscape?
+
+In modern data analysis platforms, data modeling is no longer just about drawing boxes. It's about maintaining a **Single Source of Truth (SSOT)** that is version-controllable, AI-friendly, and understandable by both engineers and stakeholders.
+
+- **For Data Engineers**: Maintain clear mappings between physical tables and logical entities. Visualize complex **Data Vault** or **Star Schema** structures.
+- **For Analytics Engineers**: Design modular dbt-ready models. Document table grains, primary keys, and relationships before writing a single line of SQL.
+- **For Data Scientists**: Discover data through **Sample Stories**. Understand the purpose and content of a table through integrated sample data previews without running a single query.
+
+## Key Features
+
+- **YAML-as-Code**: Define your entire data architecture in a single, human-readable YAML file. Track changes via Git.
+- **Instant Local Visualization**: Visualize your YAML models (following the Modscape schema) instantly on your machine. No database connections or cloud infrastructure required—just point to your file and start exploring.
+- **Specialized Modeling Types**: Native support for entity types like `fact`, `dimension`, `hub`, `link`, and `satellite`.
+- **Sample Data Stories**: Attach real-world data samples to your entities to explain the "Story" behind the data.
+- **Interactive Visual Canvas**: 
+  - **Drag-to-Connect**: Create relationships between columns intuitively.
+  - **Auto-Layout Persistence**: Arrange nodes on the canvas; coordinates are saved directly back to your YAML.
+  - **Domain Grouping**: Organize tables into visual business domains.
+- **Analytics Metadata**: 
+  - **Fact Strategies**: Define `transaction`, `periodic`, `accumulating`, or `factless` grains.
+  - **SCD Management**: Visualize `SCD Type 2` and other history-tracking dimensions.
+  - **Additivity Rules**: Mark columns as `fully`, `semi`, or `non-additive` to guide BI development.
+  - **Metadata/Audit Tracking**: Identify audit columns with specialized visual cues.
+- **AI-Agent Ready**: Built-in scaffolding for **Gemini, Claude, and Codex** to accelerate your modeling workflow using LLMs.
+- **Documentation Export**: Generate Mermaid-compatible Markdown for your internal wikis or GitHub/GitLab pages.
 
 ## Installation
 
@@ -38,32 +48,36 @@ npm install -g modscape
 
 ## Getting Started
 
-Choose the path that fits your workflow.
-
 ### Path A: AI-Driven Modeling (Recommended)
-Best if you use AI coding assistants (Gemini CLI, Claude Code, Cursor/Codex).
+Leverage AI coding assistants (**Gemini CLI, Claude Code, or Codex**) to build your models.
 
-1.  **Initialize**: Scaffold modeling rules and AI agent instructions.
+1.  **Initialize**: Scaffold modeling rules and instructions for your preferred agent.
     ```bash
-    modscape init
+    # For Gemini CLI
+    modscape init --gemini
+
+    # For Claude Code
+    modscape init --claude
+
+    # For Codex
+    modscape init --codex
     ```
-2.  **Start Dev**: Launch the visualizer on your model.
+2.  **Start Dev**: Launch the visualizer.
     ```bash
     modscape dev model.yaml
     ```
-3.  **Prompt Your AI**: Tell your agent to use the rules in `.modscape/rules.md` to add tables or columns to your `model.yaml`.
+3.  **Prompt Your AI**: Tell your agent: *"Use the rules in .modscape/rules.md to add a new 'Marketing' domain with a 'campaign_performance' fact table to my model.yaml."*
 
 ### Path B: Manual Modeling
-Best for direct YAML editing and architectural control.
+Best for direct architectural control.
 
-1.  **Create YAML**: Create a file named `model.yaml` (see [Defining Your Model](#defining-your-model-yaml)).
+1.  **Create YAML**: Create a file named `model.yaml` (see [YAML Reference](#defining-your-model-yaml)).
 2.  **Start Dev**: Launch the visualizer.
     ```bash
     modscape dev model.yaml
     ```
-3.  **Explore Samples**: Try it out with our built-in samples:
+3.  **Explore Samples**: Try the built-in patterns:
     ```bash
-    # Clone the repo or download the samples directory
     modscape dev samples/
     ```
 
@@ -71,139 +85,111 @@ Best for direct YAML editing and architectural control.
 
 ## Defining Your Model (YAML)
 
-Modscape uses a comprehensive yet human-readable YAML schema. This single file acts as the **Single Source of Truth** for your conceptual, logical, and physical data models.
-
-### Complete YAML Reference
+Modscape uses a schema designed for data analysis contexts. This single file acts as the **Single Source of Truth** for your logical and physical data architecture.
 
 ```yaml
-# 1. Domains: Visual containers to group related tables
+# 1. Domains: Visual containers for grouping business logic
 domains:
-  - id: sales_domain
-    name: Sales & Orders
-    description: Core commerce transactions
-    color: "rgba(59, 130, 246, 0.05)" # Container background
-    tables: [orders, order_items] # List of table IDs
+  - id: core_sales
+    name: Core Sales
+    description: "Optional description of the domain"
+    color: "rgba(59, 130, 246, 0.05)" # Container background color
+    tables: [orders, products] # List of table IDs
 
-# 2. Tables: Entity definitions
+# 2. Tables: Entity definitions with multi-layer metadata
 tables:
   - id: orders
     name: ORDERS
     appearance:
       type: fact    # fact | dimension | hub | link | satellite
-      icon: 📦      # Any emoji or character
+      # --- Analytics Metadata ---
+      strategy: transaction # transaction | periodic | accumulating | factless
+      scd: null             # type0 | type1 | type2 | type3 | type6 (for Dimensions)
+      icon: 📦      # Custom emoji or character
       color: "#f87171" # Custom theme color for this entity
     
     conceptual:
-      description: "Records of customer purchases"
-      tags: ["WHAT", "WHEN"] # BEAM* methodology tags
+      description: "Sales transaction records"
+      tags: ["WHO", "WHEN", "HOW MUCH"] # BEAM* or Grain identifiers
     
     physical:
-      name: T_ORDERS     # Actual table name in database
-      schema: RAW_SALES  # Database schema name
+      name: STG_ORDERS     # Actual table name in DB
+      schema: ANALYTICS_DB # DB schema/namespace
     
     columns:
       - id: order_id
         logical:
           name: ORDER_ID
-          type: Integer
-          description: "Unique identifier for an order"
+          type: Int
+          description: "Unique identifier"
           isPrimaryKey: true
+          isForeignKey: false
+          isPartitionKey: false
+          # --- Analytics Metadata ---
+          isMetadata: false # Set true for audit columns (🕒 icon)
+          additivity: fully # fully | semi | non (Σ icon)
         physical:
           name: O_ID
           type: NUMBER(38,0)
           constraints: ["NOT NULL"]
       
       - id: customer_id
-        logical:
-          name: CUSTOMER_ID
-          type: Integer
-          isForeignKey: true
+        logical: { name: CUSTOMER_ID, type: Int, isForeignKey: true }
 
-    # 3. Sample Data: Realistic data for storytelling
-    # (Direct 2D array, mapped to logical columns by index)
+    # 3. Sample Data: Storytelling through data
     sampleData:
       - [1001, 501]
       - [1002, 502]
 
-# 4. Relationships: Connections between tables
+# 4. Relationships: Column-level connectivity
 relationships:
   - from: { table: orders, column: customer_id }
     to: { table: customers, column: id }
     type: many-to-one # one-to-one | one-to-many | many-to-many
 
 # 5. Layout: Visual coordinates (Auto-managed)
-# You don't need to write this manually; Modscape updates it on drag.
 layout:
   orders: { x: 100, y: 100, width: 320, height: 400 }
 ```
 
-### Schema Breakdown
-
-| Section | Field | Description |
-| :--- | :--- | :--- |
-| **`domains`** | `color` | Defines the background of the grouping container in the visualizer. |
-| **`appearance`**| `type` | Determines the header icon/color if not specified (Standard: Star Schema or Data Vault). |
-| **`conceptual`**| `tags` | Business context tags. Great for identifying key modeling grains (WHO, WHAT, WHERE). |
-| **`physical`** | `name`/`schema` | Maps the logical entity to your real database objects. |
-| **`columns`** | `isPrimaryKey` | Adds a 🔑 icon and marks the grain of the table. |
-| | `isForeignKey` | Adds a 🔩 icon to indicate a downstream connection. |
-| **`sampleData`**| - | A direct 2D array of rows. Values are mapped to logical columns by index. |
-| **`relationships`**| `type` | Controls the arrowheads and visual style of the connection lines. |
-
 ---
 
 ## Usage
 
-### Development Mode (Interactive Editor)
-Start a local session to edit your YAML and arrange entities.
+### Development Mode (Interactive)
+Edit your YAML and arrange entities visually.
 
 ```bash
-# Point to a directory to manage all models within it
-modscape dev models/
-
-# Or point to a specific file
-modscape dev my-model.yaml
+modscape dev ./models
 ```
-- Opens `http://localhost:5173` automatically.
-- **Persistence**: Drag entities to save positions directly to the source YAML file.
-- **Secure Routing**: Models are accessed via safe slugs, keeping your local paths private.
+- Opens `http://localhost:5173`.
+- **Persistence**: Layout and metadata changes are saved directly to your files.
 
-### Build Mode (Static Site Generation)
-Generate a standalone static website to share your documentation (perfect for GitHub Pages).
+### Build Mode (Static Site)
+Generate a standalone documentation site for your team.
 
 ```bash
-modscape build models/ -o dist-site
+modscape build ./models -o docs-site
 ```
 
-### Export Mode (Static Documentation)
-Generate a comprehensive Markdown document with embedded Mermaid diagrams.
+### Export Mode (Markdown)
+Generate documentation with Mermaid diagrams.
 
 ```bash
-# Print to stdout
-modscape export models/ecommerce.yaml
-
-# Save to a file
-modscape export models/ -o docs/
+modscape export ./models -o docs/ARCHITECTURE.md
 ```
 
 ## AI Agent Integration
 
-Modscape is designed to work alongside AI coding assistants. By running `modscape init`, you get:
-
-- **`.modscape/rules.md`**: The Single Source of Truth for your modeling conventions.
-- **Agent Instructions**: Pre-configured prompts for Gemini, Claude, and Cursor/Codex.
-
-Tell your AI: *"Follow the rules in .modscape/rules.md to add a new billing domain to my model.yaml."*
+Modscape is designed to be **AI-First**. By running `modscape init`, you establish a contract with your AI agent via `.modscape/rules.md`, ensuring consistent modeling patterns (naming conventions, data types, etc.) across your entire project.
 
 ## Credits
 
-Modscape is built upon several incredible open-source projects:
-
-- **[React Flow](https://reactflow.dev/)**: Powering the interactive graph engine.
-- **[Radix UI](https://www.radix-ui.com/)**: Providing accessible UI primitives.
-- **[Lucide](https://lucide.dev/)**: Beautiful, consistent iconography.
-- **[shadcn/ui](https://ui.shadcn.com/)**: Component patterns and design inspiration.
-- **[Express](https://expressjs.com/)**: Serving the local development environment.
+Modscape is built upon:
+- **React Flow**: Interactive graph engine.
+- **Lucide**: Consistent iconography.
+- **Express**: Local dev server.
+- **Commander**: CLI framework.
 
 ## License
 MIT

package/package.json

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

package/src/dev.js

@@ -45,7 +45,8 @@ export async function startDevServer(paths, visualizerPath) {
   const app = express();
   app.use(express.json());
 
-  const modelMap = scanFiles(Array.isArray(paths) ? paths : [paths]);
+  const inputPaths = Array.isArray(paths) ? paths : [paths];
+  let modelMap = scanFiles(inputPaths);
   const distPath = path.resolve(__dirname, '../visualizer-dist');
 
   if (modelMap.size === 0) {
@@ -66,8 +67,9 @@ export async function startDevServer(paths, visualizerPath) {
     return modelMap.values().next().value;
   };
 
-  // API to list all available models
+  // API to list all available models - re-scans on every request
   app.get('/api/files', (req, res) => {
+    modelMap = scanFiles(inputPaths);
     const files = Array.from(modelMap.entries()).map(([slug, fullPath]) => ({
       slug,
       name: slug.charAt(0).toUpperCase() + slug.slice(1).replace(/[-_]/g, ' '),
@@ -148,7 +150,7 @@ export async function startDevServer(paths, visualizerPath) {
     open(url);
   });
 
-  chokidar.watch(Array.from(modelMap.values())).on('change', (changedPath) => {
+  chokidar.watch(inputPaths).on('change', (changedPath) => {
     console.log(`  File changed: ${path.relative(process.cwd(), changedPath)}. Please refresh the browser.`);
   });
 }

package/src/index.js

@@ -15,7 +15,7 @@ const program = new Command();
 program
   .name('modscape')
   .description('A YAML-driven data modeling visualizer CLI')
-  .version('0.8.0');
+  .version('0.9.0');
 
 program
   .command('init')