modscape 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yujikawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# <img src="./readme_assets/logo.svg" width="32" height="32" align="center" /> Modscape
+
+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".
+
+[sample page](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 accessible in both `dev` and `build` modes.
+  - **Tabs**: Switch between **Editor** (YAML) and **Entities** (Navigation).
+  - **Collapsible**: Collapse the sidebar to maximize your ER diagram viewing area.
+- **Interactive ER Diagram**: Drag-and-drop entities to create the perfect layout.
+- **Diagram Navigation**: Click entities in the sidebar to smoothly focus and zoom in on them.
+- **Sandbox Mode**: Temporary in-memory editing in static builds. Try "What-if" modeling without affecting the source.
+- **Layout Persistence**: Diagram positions (including **Domains**) are automatically saved to your YAML file in dev mode.
+- **CLI-Driven Workflow**:
+  - `modscape dev`: Interactive editor with live updates.
+  - `modscape build`: Package your model into a standalone static site.
+
+## Installation
+
+### Prerequisites
+- Node.js (v18 or higher)
+
+### Global Installation (via GitHub)
+You can install Modscape directly from GitHub to use the `modscape` command anywhere:
+
+```bash
+npm install -g https://github.com/yujikawa/modscape
+```
+
+### Local Setup (for Development)
+```bash
+# Clone the repository
+git clone https://github.com/yujikawa/modscape.git
+cd modscape
+
+# Install dependencies for both CLI and Visualizer
+npm install
+cd visualizer && npm install
+cd ..
+
+# Link the command to your system
+npm link
+```
+
+## Usage
+
+### 0. Initialization (AI Agent Setup)
+Scaffold project-specific modeling rules and configure your favorite AI agents (Gemini, Codex, Claude) to follow them.
+
+```bash
+modscape init
+```
+- Creates `.modscape/rules.md` as your project's "Source of Truth" for modeling.
+- Generates agent-specific configurations (skills, prompts, commands) that point to these rules.
+- **Why?**: This ensures AI agents generate YAML that perfectly matches your organization's standards.
+
+### 1. Development Mode (Interactive Editor)
+Start a local session to edit your YAML and arrange entities.
+
+```bash
+# Point to a directory to manage all models within it
+modscape dev samples/
+
+# Or point to a specific file
+modscape dev my-model.yaml
+```
+- Opens `http://localhost:5173` automatically.
+- **Multi-file Support**: Switch between models using the dropdown in the sidebar.
+- **Secure Routing**: Models are accessed via slugs (e.g., `?model=ecommerce`), keeping your local paths private.
+- **Editor Tab**: Edit YAML with live updates to the diagram.
+- **Entities Tab**: Search and quickly navigate to specific tables or domains.
+- **Persistence**: Drag entities to save positions directly to the source YAML file.
+
+### 2. Static Site Build
+Generate a standalone documentation site from your YAML model.
+
+```bash
+modscape build my-model.yaml -o ./docs-site
+```
+- Generates a `docs-site/` folder with a single-file visualizer.
+- Includes the **Sandbox Mode**, allowing viewers to temporarily edit the model in their browser.
+- Perfect for hosting on **GitHub Pages**, S3, or internal documentation portals.
+
+## YAML Schema Example
+
+```yaml
+tables:
+  - id: hub_customer
+    name: HUB_CUSTOMER
+    appearance: # Optional: Visual style (icon and color)
+      type: "hub" # Predefined: hub, link, satellite, fact, dimension
+      icon: "🌐"  # Optional: Emoji override
+      color: "#fbbf24" # Optional: Hex color override
+    conceptual:
+      description: "Business keys for unique customers."
+      tags: ["HUB", "PARTY"]
+    columns:
+      - id: hk_customer
+        logical: { name: "HK_CUSTOMER", type: "Binary", isPrimaryKey: true }
+        physical: { name: "HK_CUST", type: "BINARY(16)", constraints: ["NOT NULL"] }
+
+domains:
+  - id: customer_domain
+    name: Customer Domain
+    tables: ["hub_customer"]
+    color: "rgba(59, 130, 246, 0.05)"
+
+relationships:
+  - from: { table: hub_customer, column: hk_customer }
+    to: { table: sat_customer_crm, column: hk_customer }
+    type: "one-to-many"
+
+layout: # Automatically managed by the visualizer or AI Agent
+  hub_customer: { x: 100, y: 100 }
+  customer_domain: { x: 50, y: 50, width: 600, height: 400 }
+```
+
+### Key Attributes
+- **appearance**: Controls the node's visual identity. `type` sets a default icon and color (e.g., `hub` is Amber 🌐, `fact` is Red 📊). Use `icon` or `color` to override.
+- **layout**: Stores (x, y) coordinates and dimensions. While the visualizer manages this automatically during drag-and-drop, AI Agents use this to arrange new entities logically.
+
+
+## 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, high-quality primitives for the sidebar.
+- **[Lucide](https://lucide.dev/)**: Beautiful, consistent iconography.
+- **[shadcn/ui](https://ui.shadcn.com/)**: Design inspiration and component patterns.
+- **[Express](https://expressjs.com/)**: Serving the development environment.
+
+## License
+MIT

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "modscape",
+  "version": "0.1.0",
+  "description": "Modscape: A YAML-driven data modeling visualizer CLI",
+  "type": "module",
+  "bin": {
+    "modscape": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "visualizer-dist",
+    "package.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build-ui": "cd visualizer && npm run build && rm -rf ../visualizer-dist && mv dist ../visualizer-dist",
+    "dev": "node src/index.js dev"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.3.0",
+    "chokidar": "^5.0.0",
+    "commander": "^14.0.3",
+    "express": "^5.2.1",
+    "js-yaml": "^4.1.1",
+    "open": "^11.0.0"
+  }
+}

package/src/build.js

@@ -0,0 +1,108 @@
+import path from 'path';
+import fs from 'fs';
+import yaml from 'js-yaml';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function scanFiles(inputPaths) {
+  const modelMap = new Map();
+  inputPaths.forEach(inputPath => {
+    const absolutePath = path.resolve(process.cwd(), inputPath);
+    if (!fs.existsSync(absolutePath)) {
+      console.warn(`  ⚠️ Warning: Path not found: ${inputPath}`);
+      return;
+    }
+
+    const stats = fs.statSync(absolutePath);
+    if (stats.isDirectory()) {
+      const files = fs.readdirSync(absolutePath);
+      files.forEach(file => {
+        if (file.endsWith('.yaml') || file.endsWith('.yml')) {
+          const slug = path.parse(file).name;
+          const fullPath = path.join(absolutePath, file);
+          if (modelMap.has(slug)) {
+            const parentName = path.basename(absolutePath);
+            modelMap.set(`${parentName}-${slug}`, fullPath);
+          } else {
+            modelMap.set(slug, fullPath);
+          }
+        }
+      });
+    } else if (stats.isFile() && (inputPath.endsWith('.yaml') || inputPath.endsWith('.yml'))) {
+      const slug = path.parse(absolutePath).name;
+      modelMap.set(slug, absolutePath);
+    }
+  });
+  return modelMap;
+}
+
+export async function build(paths, visualizerPath, outputDir) {
+  const modelMap = scanFiles(Array.isArray(paths) ? paths : [paths]);
+  const absoluteOutputDir = path.resolve(process.cwd(), outputDir);
+  const distPath = path.resolve(__dirname, '../visualizer-dist');
+
+  if (modelMap.size === 0) {
+    console.error('\n  ❌ Error: No YAML files found in the specified paths.');
+    return;
+  }
+
+  if (!fs.existsSync(distPath)) {
+    console.error('\n  ❌ Error: visualizer-dist not found. Please run "npm run build-ui" first.\n');
+    return;
+  }
+
+  console.log(`\n  📦 Building static site with ${modelMap.size} model(s)...`);
+  
+  // Create output dir and copy all files from visualizer-dist
+  if (!fs.existsSync(absoluteOutputDir)) {
+    fs.mkdirSync(absoluteOutputDir, { recursive: true });
+  }
+
+  // Copy recursive helper
+  const copyDir = (src, dest) => {
+    fs.mkdirSync(dest, { recursive: true });
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    for (let entry of entries) {
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+      if (entry.isDirectory()) {
+        copyDir(srcPath, destPath);
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+      }
+    }
+  };
+
+  copyDir(distPath, absoluteOutputDir);
+
+  // Prepare data for injection
+  const modelsData = [];
+  for (const [slug, absolutePath] of modelMap.entries()) {
+    try {
+      const content = fs.readFileSync(absolutePath, 'utf8');
+      const schema = yaml.load(content);
+      const name = slug.charAt(0).toUpperCase() + slug.slice(1).replace(/[-_]/g, ' ');
+      modelsData.push({ slug, name, schema });
+    } catch (e) {
+      console.warn(`  ⚠️ Warning: Failed to load ${absolutePath}: ${e.message}`);
+    }
+  }
+
+  // Inject data into index.html
+  const indexPath = path.join(absoluteOutputDir, 'index.html');
+  let html = fs.readFileSync(indexPath, 'utf8');
+  
+  const injectionData = {
+    isMultiFile: modelsData.length > 1,
+    models: modelsData
+  };
+
+  html = html.replace(
+    '</head>',
+    `<script>window.__MODSCAPE_DATA__ = ${JSON.stringify(injectionData)}; window.MODSCAPE_CLI_MODE = false;</script></head>`
+  );
+  fs.writeFileSync(indexPath, html, 'utf8');
+
+  console.log(`\n  ✅ Build complete! Static site generated in: ${outputDir}`);
+}

package/src/dev.js

@@ -0,0 +1,154 @@
+import express from 'express';
+import path from 'path';
+import fs from 'fs';
+import yaml from 'js-yaml';
+import chokidar from 'chokidar';
+import open from 'open';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function scanFiles(inputPaths) {
+  const modelMap = new Map();
+  inputPaths.forEach(inputPath => {
+    const absolutePath = path.resolve(process.cwd(), inputPath);
+    if (!fs.existsSync(absolutePath)) {
+      console.warn(`  ⚠️ Warning: Path not found: ${inputPath}`);
+      return;
+    }
+
+    const stats = fs.statSync(absolutePath);
+    if (stats.isDirectory()) {
+      const files = fs.readdirSync(absolutePath);
+      files.forEach(file => {
+        if (file.endsWith('.yaml') || file.endsWith('.yml')) {
+          const slug = path.parse(file).name;
+          const fullPath = path.join(absolutePath, file);
+          if (modelMap.has(slug)) {
+            // Collision handling: append folder name
+            const parentName = path.basename(absolutePath);
+            modelMap.set(`${parentName}-${slug}`, fullPath);
+          } else {
+            modelMap.set(slug, fullPath);
+          }
+        }
+      });
+    } else if (stats.isFile() && (inputPath.endsWith('.yaml') || inputPath.endsWith('.yml'))) {
+      const slug = path.parse(absolutePath).name;
+      modelMap.set(slug, absolutePath);
+    }
+  });
+  return modelMap;
+}
+
+export async function startDevServer(paths, visualizerPath) {
+  const app = express();
+  app.use(express.json());
+
+  const modelMap = scanFiles(Array.isArray(paths) ? paths : [paths]);
+  const distPath = path.resolve(__dirname, '../visualizer-dist');
+
+  if (modelMap.size === 0) {
+    console.error(`\n  ❌ Error: No YAML files found in the specified paths.`);
+    return;
+  }
+
+  if (!fs.existsSync(distPath)) {
+    console.error(`\n  ❌ Error: visualizer-dist not found at ${distPath}`);
+    console.log('  Please run "npm run build-ui" first.\n');
+    return;
+  }
+
+  // Helper to get absolute path from model slug
+  const getModelPath = (slug) => {
+    if (slug) return modelMap.get(slug);
+    // If no slug provided, return the first available model
+    return modelMap.values().next().value;
+  };
+
+  // API to list all available models
+  app.get('/api/files', (req, res) => {
+    const files = Array.from(modelMap.entries()).map(([slug, fullPath]) => ({
+      slug,
+      name: slug.charAt(0).toUpperCase() + slug.slice(1).replace(/[-_]/g, ' '),
+      path: path.relative(process.cwd(), fullPath)
+    }));
+    res.json(files);
+  });
+
+  // API to get current YAML data
+  app.get('/api/model', (req, res) => {
+    const modelPath = getModelPath(req.query.model);
+    if (!modelPath || !fs.existsSync(modelPath)) {
+      return res.status(404).json({ error: 'Model not found' });
+    }
+
+    try {
+      const content = fs.readFileSync(modelPath, 'utf8');
+      res.json(yaml.load(content));
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+
+  // API to save layout changes
+  app.post('/api/layout', (req, res) => {
+    const modelPath = getModelPath(req.query.model);
+    if (!modelPath) return res.status(404).json({ error: 'Model not found' });
+
+    try {
+      const layout = req.body;
+      const content = fs.readFileSync(modelPath, 'utf8');
+      const data = yaml.load(content);
+      data.layout = layout;
+      fs.writeFileSync(modelPath, yaml.dump(data, { indent: 2, lineWidth: -1 }), 'utf8');
+      res.json({ success: true });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+
+  // API to save entire YAML content
+  app.post('/api/save-yaml', (req, res) => {
+    const modelPath = getModelPath(req.query.model);
+    if (!modelPath) return res.status(404).json({ error: 'Model not found' });
+
+    try {
+      const { yaml: yamlContent } = req.body;
+      yaml.load(yamlContent);
+      fs.writeFileSync(modelPath, yamlContent, 'utf8');
+      res.json({ success: true });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+
+  // Serve static files EXCEPT index.html
+  app.use(express.static(distPath, { index: false }));
+
+  // Intercept index.html to inject CLI_MODE flag
+  app.get('{/*path}', (req, res) => {
+    try {
+      let html = fs.readFileSync(path.join(distPath, 'index.html'), 'utf8');
+      html = html.replace(
+        '</head>',
+        '<script>window.MODSCAPE_CLI_MODE = true;</script></head>'
+      );
+      res.send(html);
+    } catch (e) {
+      res.status(500).send('Error loading visualizer');
+    }
+  });
+
+  const port = 5173;
+  app.listen(port, () => {
+    const url = `http://localhost:${port}`;
+    console.log(`\n  🚀 Modscape Visualizer running at: ${url}`);
+    console.log(`  Watching ${modelMap.size} file(s)`);
+    open(url);
+  });
+
+  chokidar.watch(Array.from(modelMap.values())).on('change', (changedPath) => {
+    console.log(`  File changed: ${path.relative(process.cwd(), changedPath)}. Please refresh the browser.`);
+  });
+}

package/src/index.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { startDevServer } from './dev.js';
+import { build } from './build.js';
+import { initProject } from './init.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const VISUALIZER_PATH = path.resolve(__dirname, '../visualizer');
+const program = new Command();
+
+program
+  .name('modscape')
+  .description('A YAML-driven data modeling visualizer CLI')
+  .version('0.1.0');
+
+program
+  .command('init')
+  .description('Initialize project with AI modeling rules')
+  .option('-g, --gemini', 'Scaffold for Gemini CLI')
+  .option('-x, --codex', 'Scaffold for Codex')
+  .option('-c, --claude', 'Scaffold for Claude Code')
+  .option('-a, --all', 'Scaffold for all agents')
+  .action((options) => {
+    initProject(options);
+  });
+
+program
+  .command('dev')
+  .description('Start the development visualizer with local YAML files or directories')
+  .argument('<paths...>', 'paths to YAML model files or directories')
+  .action((paths) => {
+    startDevServer(paths, VISUALIZER_PATH);
+  });
+
+program
+  .command('build')
+  .description('Build a static site from YAML models')
+  .argument('<paths...>', 'paths to YAML model files or directories')
+  .option('-o, --output <dir>', 'output directory', 'dist')
+  .action((paths, options) => {
+    build(paths, VISUALIZER_PATH, options.output);
+  });
+
+program.parse();

package/src/init.js

@@ -0,0 +1,102 @@
+import { confirm } from '@inquirer/prompts';
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+async function safeWriteFile(filePath, content) {
+  const absolutePath = path.resolve(process.cwd(), filePath);
+  const dir = path.dirname(absolutePath);
+
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  if (fs.existsSync(absolutePath)) {
+    const overwrite = await confirm({
+      message: `File ${filePath} already exists. Overwrite?`,
+      default: false,
+    });
+    if (!overwrite) {
+      console.log(`  Skipping ${filePath}`);
+      return;
+    }
+  }
+
+  fs.writeFileSync(absolutePath, content, 'utf8');
+  console.log(`  Created ${filePath}`);
+}
+
+export async function initProject(options = {}) {
+  console.log('\n  🛠️  ModMod Project Initialization\n');
+
+  try {
+    const agents = [];
+
+    // If options are provided via CLI flags, use them
+    if (options.all) {
+      agents.push('gemini', 'codex', 'claude');
+    } else if (options.gemini || options.codex || options.claude) {
+      if (options.gemini) agents.push('gemini');
+      if (options.codex) agents.push('codex');
+      if (options.claude) agents.push('claude');
+    } else {
+      // Otherwise, ask one by one (more robust than checkbox in some terminals)
+      console.log('  Please confirm which AI agents you want to scaffold for:\n');
+      
+      if (await confirm({ message: 'Scaffold for Gemini CLI?', default: false })) {
+        agents.push('gemini');
+      }
+      if (await confirm({ message: 'Scaffold for Codex?', default: false })) {
+        agents.push('codex');
+      }
+      if (await confirm({ message: 'Scaffold for Claude Code?', default: false })) {
+        agents.push('claude');
+      }
+    }
+
+    if (agents.length === 0) {
+      console.log('\n  ⚠️  No agents selected. Only ".modscape/rules.md" will be created.');
+    } else {
+      console.log(`\n  Selected agents: ${agents.join(', ')}`);
+    }
+
+    console.log('\n  Scaffolding modeling rules and commands...');
+
+    // 1. Create .modscape/rules.md
+    const rulesTemplatePath = path.join(__dirname, 'templates/rules.md');
+    const rulesTemplate = fs.readFileSync(rulesTemplatePath, 'utf8');
+    await safeWriteFile('.modscape/rules.md', rulesTemplate);
+
+    // 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/modmod/SKILL.md', skillTemplate);
+      
+      const commandTemplate = fs.readFileSync(path.join(__dirname, 'templates/gemini/command.toml'), 'utf8');
+      await safeWriteFile('.gemini/commands/modmod/modeling.toml', commandTemplate);
+    }
+
+    if (agents.includes('codex')) {
+      const promptTemplate = fs.readFileSync(path.join(__dirname, 'templates/codex/prompt.md'), 'utf8');
+      await safeWriteFile('.codex/prompts/modmod-modeling.md', promptTemplate);
+    }
+
+    if (agents.includes('claude')) {
+      const clauderules = fs.readFileSync(path.join(__dirname, 'templates/claude/clauderules'), 'utf8');
+      await safeWriteFile('.clauderules', clauderules);
+      
+      const commandTemplate = fs.readFileSync(path.join(__dirname, 'templates/claude/command.md'), 'utf8');
+      await safeWriteFile('.claude/commands/modmod/modeling.md', commandTemplate);
+    }
+
+    console.log('\n  ✅ Initialization complete! Customize ".modscape/rules.md" to match your project standards.\n');
+  } catch (error) {
+    if (error.name === 'ExitPromptError') {
+      console.log('\n  Initialization cancelled by user.');
+    } else {
+      console.error('\n  An error occurred during initialization:', error.message);
+    }
+  }
+}

package/src/templates/claude/clauderules

@@ -0,0 +1,9 @@
+You are a professional Data Modeler. Your primary directive is to manage `model.yaml`. 
+
+## COMMAND: /modscape:modeling
+When the user issues this command:
+1. READ `.modscape/rules.md` to understand project strategy and conventions.
+2. ANALYZE `model.yaml` (if present).
+3. INTERACT with the user to gather requirements and update the model strictly following the rules.
+
+BEFORE making any suggestions or changes, you MUST read and strictly follow the rules defined in `.modscape/rules.md`.

package/src/templates/claude/command.md

@@ -0,0 +1,14 @@
+# /modscape:modeling
+
+Start an interactive data modeling session.
+
+## Instructions
+1. FIRST, read `.modscape/rules.md` to understand the project strategy, naming conventions, and YAML schema.
+2. SECOND, analyze the existing `model.yaml` if it exists.
+3. Listen to the user's requirements and propose/apply changes to `model.yaml` strictly following the rules.
+
+## Appearance & Layout
+- **Appearance**: For new tables, include the `appearance: { type: "..." }` block.
+- **Layout**: When creating new entities, always assign initial `x` and `y` coordinates in the `layout` section. Position them logically near their related entities to avoid stacking.
+
+Always prioritize consistency and project-specific standards.

package/src/templates/codex/prompt.md

@@ -0,0 +1,15 @@
+# Data Modeling Instructions
+
+You are a professional Data Modeler. Your primary directive is to manage `model.yaml`. 
+
+## COMMAND: /modscape:modeling
+When the user issues this command:
+1. READ `.modscape/rules.md` to understand project strategy and conventions.
+2. ANALYZE `model.yaml` (if present).
+3. INTERACT with the user to gather requirements and update the model strictly following the rules.
+
+## Appearance & Layout
+- **Appearance**: When creating new tables, include the `appearance` block with an appropriate `type`.
+- **Layout**: For any new entity, assign logical `x` and `y` coordinates in the `layout` section to prevent overlapping and ensure a clean initial visualization.
+
+ALWAYS follow the rules defined in `.modscape/rules.md` for any modeling tasks.

package/src/templates/gemini/SKILL.md

@@ -0,0 +1,20 @@
+# Data Modeling Expert
+
+You are a professional Data Modeler. Your primary directive is to manage `model.yaml`. 
+
+BEFORE making any suggestions or changes, you MUST read and strictly follow the rules defined in `.modscape/rules.md`. 
+
+If a requested change violates these rules, warn the user.
+
+## 📁 Multi-file Awareness
+`modscape dev` supports pointing to a directory (e.g., `modscape dev samples/`).
+-   **Switching Models**: Identify which YAML file you are editing from the directory.
+-   **Domain Separation**: Suggest splitting large models into multiple, domain-specific YAML files to improve organization.
+-   **Slug-based Access**: Be aware that the visualizer identifies models via slugs (filename without extension).
+
+## Layout & Appearance Management
+- **Appearance**: When creating new tables, assign an appropriate `appearance.type` (e.g., `fact`, `hub`) to ensure correct visualization.
+- **Layout**: You are responsible for the initial placement of new entities. Assign logical `x` and `y` coordinates in the `layout` section so they don't overlap existing nodes. The user will fine-tune the layout via the GUI.
+
+## Interactive Modeling
+When the user wants to perform modeling tasks, ensure you are utilizing the strategy and conventions defined in the project rules. You can be triggered via the `/modscape:modeling` command which provides a dedicated workflow.

package/src/templates/gemini/command.toml

@@ -0,0 +1,14 @@
+# /modscape:modeling command definition
+
+description = "Start an interactive data modeling session using project rules"
+
+[prompt]
+instruction = """
+You are now in **Modscape Modeling Mode**. 
+
+1. FIRST, read `.modscape/rules.md` to understand the project strategy, naming conventions, and YAML schema.
+2. SECOND, analyze the existing `model.yaml` if it exists.
+3. Listen to the user's requirements and propose/apply changes to `model.yaml` strictly following the rules.
+
+Stay in this mode until the task is complete. Always prioritize consistency and project-specific standards.
+"""