luxaura 1.0.0 → 1.0.2

package/bin/luxaura.js

@@ -2,8 +2,34 @@
 'use strict';
 
 /**
- * Luxaura CLI
- * Commands: new, run, build, install, generate, format, secure
+ * Luxaura CLI v2.0
+ *
+ * Commands (ALL renamed — nothing similar to React/Vue/Angular/Next CLI):
+ *
+ *   luxaura release <name>        → Create a new project         (was: new)
+ *   luxaura ignite                → Start dev server + live reload (was: run)
+ *   luxaura forge                 → Build for production          (was: build)
+ *   luxaura bring <lib>           → Add external library           (was: install)
+ *   luxaura component <name>      → Scaffold a UI component        (was: generate component)
+ *   luxaura service <name>        → Scaffold a vault service       (was: generate api)
+ *   luxaura module <name>         → Scaffold a shared module       (was: generate page)
+ *   luxaura help_me               → Interactive CLI guide
+ *   luxaura polish                → Auto-format .lux files         (was: format)
+ *   luxaura shield                → Security scan                  (was: secure)
+ *
+ * Project folder hierarchy (ALL renamed):
+ *
+ *   /scenes        → route entry points   (was: /pages  — Next.js-like)
+ *   /craft         → root components live here (was: /modules — Vue-like)
+ *     /craft/<ComponentName>/
+ *       <ComponentName>.lux
+ *       <ComponentName>.paint.css   ← per-component styles
+ *       index.js                    ← optional JS bridge
+ *   /services      → vault/server logic   (was: /server)
+ *   /media         → static assets        (was: /assets)
+ *   /depot         → build output         (was: /dist)
+ *     /depot/public  → client assets      (was: dist/client)
+ *     /depot/vault   → server modules     (was: dist/server)
  */
 
 const { program } = require('commander');
@@ -17,451 +43,866 @@ const { LuxParser }   = require('../src/parser');
 const { LuxCompiler } = require('../src/compiler');
 const { VaultServer } = require('../src/vault/server');
 
-const VERSION = '1.0.0';
+const VERSION = '2.0.0';
 
 // ─── Banner ──────────────────────────────────────────────────────────────────
 
 function banner() {
-  console.log(chalk.cyan(`
+  console.log(chalk.hex('#6c63ff')(`
   ██╗     ██╗   ██╗██╗  ██╗ █████╗ ██╗   ██╗██████╗  █████╗
   ██║     ██║   ██║╚██╗██╔╝██╔══██╗██║   ██║██╔══██╗██╔══██╗
   ██║     ██║   ██║ ╚███╔╝ ███████║██║   ██║██████╔╝███████║
   ██║     ██║   ██║ ██╔██╗ ██╔══██║██║   ██║██╔══██╗██╔══██║
   ███████╗╚██████╔╝██╔╝ ██╗██║  ██║╚██████╔╝██║  ██║██║  ██║
-  ╚══════╝ ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝
-  `));
-  console.log(chalk.gray(`  Intent-Based Web Framework  v${VERSION}\n`));
+  ╚══════╝ ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝`));
+  console.log(chalk.hex('#a8a3ff')(`  The Intent-Driven Full-Stack Web Framework`));
+  console.log(chalk.gray(`  v${VERSION}  ·  Not React. Not Vue. Not Angular. Just Luxaura.\n`));
 }
 
-// ─── Helpers ─────────────────────────────────────────────────────────────────
+// ─── Logging helpers ─────────────────────────────────────────────────────────
 
-function log(msg)     { console.log(chalk.cyan('  ▸'), msg); }
-function success(msg) { console.log(chalk.green('  ✔'), msg); }
-function warn(msg)    { console.log(chalk.yellow('  ⚠'), msg); }
-function error(msg)   { console.error(chalk.red('  ✖'), msg); }
-function info(msg)    { console.log(chalk.gray('  ·'), msg); }
+const log     = (m) => console.log(chalk.hex('#6c63ff')('  ◆'), m);
+const success = (m) => console.log(chalk.greenBright('  ✦'), m);
+const warn    = (m) => console.log(chalk.yellow('  ⚠'), m);
+const error   = (m) => console.error(chalk.redBright('  ✖'), m);
+const info    = (m) => console.log(chalk.gray('  ·'), m);
+const dim     = (m) => console.log(chalk.gray(m));
 
-function compileLuxFile(filePath, options = {}) {
-  const source   = fs.readFileSync(filePath, 'utf8');
-  const filename = path.basename(filePath);
-  const parser   = new LuxParser(source, filename);
-  const ast      = parser.parse();
-  const compiler = new LuxCompiler(ast, options);
-  return compiler.compile();
-}
+// ─── .lux file traversal ─────────────────────────────────────────────────────
 
-function getAllLuxFiles(dir) {
+function allLuxFiles(dir) {
   const results = [];
   function walk(d) {
     if (!fs.existsSync(d)) return;
-    for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
-      const full = path.join(d, entry.name);
-      if (entry.isDirectory() && !['node_modules', 'dist', '.git'].includes(entry.name)) {
-        walk(full);
-      } else if (entry.isFile() && entry.name.endsWith('.lux')) {
-        results.push(full);
-      }
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const full = path.join(d, e.name);
+      if (e.isDirectory() && !['node_modules', 'depot', '.git'].includes(e.name)) walk(full);
+      else if (e.isFile() && e.name.endsWith('.lux')) results.push(full);
     }
   }
   walk(dir);
   return results;
 }
 
-// ─── Command: new ─────────────────────────────────────────────────────────────
+// ─── Command: release ─────────────────────────────────────────────────────────
+// Creates a new Luxaura project with unique folder structure + start page
 
 program
-  .command('new <name>')
-  .description('Create a new Luxaura project')
+  .command('release <name>')
+  .description('Bootstrap a new Luxaura project')
   .action(async (name) => {
     banner();
     const projectDir = path.resolve(process.cwd(), name);
 
     if (fs.existsSync(projectDir)) {
-      error(`Directory "${name}" already exists.`);
-      process.exit(1);
+      error(`"${name}" already exists.`); process.exit(1);
     }
 
-    log(`Creating project: ${chalk.white(name)}`);
+    log(`Releasing project: ${chalk.white(name)}`);
 
-    // Directory structure
-    const dirs = [
+    // ── Unique folder structure ──────────────────────────────────────────────
+    [
       projectDir,
-      path.join(projectDir, 'pages'),
-      path.join(projectDir, 'modules'),
-      path.join(projectDir, 'assets'),
-      path.join(projectDir, 'server'),
-      path.join(projectDir, 'dist', 'client'),
-      path.join(projectDir, 'dist', 'server'),
-    ];
-    dirs.forEach(d => fs.mkdirpSync(d));
-
-    // luxaura.config
+      path.join(projectDir, 'scenes'),          // route entry points (not "pages")
+      path.join(projectDir, 'craft'),            // components root (not "modules")
+      path.join(projectDir, 'craft', 'Ribbon'),  // starter Ribbon nav component
+      path.join(projectDir, 'services'),         // vault/server logic (not "server")
+      path.join(projectDir, 'media'),            // static assets (not "assets")
+      path.join(projectDir, 'depot', 'public'),  // build output client (not "dist/client")
+      path.join(projectDir, 'depot', 'vault'),   // build output server (not "dist/server")
+    ].forEach(d => fs.mkdirpSync(d));
+
+    // ── luxaura.config ───────────────────────────────────────────────────────
     fs.writeFileSync(path.join(projectDir, 'luxaura.config'), `
-# Luxaura Configuration
-app.name: ${name}
-app.version: 1.0.0
+# ┌─────────────────────────────────────────┐
+# │  Luxaura Configuration                  │
+# │  Edit this file to configure your app   │
+# └─────────────────────────────────────────┘
 
-# theme: light | dark
+# App identity
+identity.name:    ${name}
+identity.version: 1.0.0
+identity.author:  You
+
+# Visual theme: light | dark | auto
 theme: light
 
-# mode: full | headless
+# Runtime mode: full | headless
+# full     → Luxaura handles frontend + vault backend
+# headless → frontend only, vault proxies to external API
 mode: full
 
-# Database (optional)
-# db.type: postgres
-# db.url: postgresql://localhost:5432/${name}
+# Database connection (optional — uncomment to activate)
+# db.engine: postgres
+# db.link:   postgresql://localhost:5432/${name}
 
-# Headless proxy (only used when mode: headless)
-# proxy: http://localhost:8080
-`.trim() + '\n');
+# Headless proxy target (only when mode: headless)
+# proxy.target: http://localhost:8080
 
-    // pages/index.lux
-    fs.writeFileSync(path.join(projectDir, 'pages', 'index.lux'), `
-# ${name} — Home Page
-
-props
-    title: String = "Welcome to ${name}"
-
-state
-    count: 0
-
-style
-    self
-        padding: 8
-        background: #ffffff
-
-    Title
-        fontSize: 2xl
-        fontWeight: bold
-        color: #1a1a2e
-
-    Action
-        padding: 4
-        radius: medium
-        background: #6c63ff
-        color: #ffffff
-        cursor: pointer
-
-view
-    Container
-        Title "{title}"
-        Text "You have clicked the button {count} times."
-        Action "Click Me"
-            on click:
-                await server.logClick(count)
+# Port for luxaura ignite (dev server)
+port: 3000
 `.trim() + '\n');
 
-    // modules/Navbar.lux
-    fs.writeFileSync(path.join(projectDir, 'modules', 'Navbar.lux'), `
-# Reusable Navbar Component
+    // ── scenes/index.lux — The start page (rich how-to content) ─────────────
+    fs.writeFileSync(path.join(projectDir, 'scenes', 'index.lux'), buildStartPage(name));
 
-props
+    // ── craft/Ribbon/Ribbon.lux — starter nav component ─────────────────────
+    fs.writeFileSync(path.join(projectDir, 'craft', 'Ribbon', 'Ribbon.lux'), `
+# Ribbon Navigation Component
+# Modify this component to build your own navigation bar.
+
+receive
     brand: String = "${name}"
 
-style
+paint
     self
-        padding: 4
-        background: #1a1a2e
-        shadow: soft
-
-    Title
-        color: #ffffff
-        fontSize: lg
-        fontWeight: bold
-
-view
-    Nav
-        Row
-            Title "{brand}"
-            Row
-                Action "Home"
-                Action "About"
-                Action "Contact"
+        breathe: 4
+        fill: #0d0d1a
+        glow: whisper
+
+    Headline
+        ink: #ffffff
+        size: large
+        weight: strong
+
+    Trigger
+        curve: pill
+        breathe: 3
+        fill: #6c63ff
+        ink: #ffffff
+        pointer: true
+
+canvas
+    Ribbon
+        Strip
+            Headline "<<brand>>"
+            Strip
+                Trigger "Home"
+                Trigger "Docs"
+                Trigger "About"
 `.trim() + '\n');
 
-    // server/index.js
-    fs.writeFileSync(path.join(projectDir, 'server', 'index.js'), `
+    // ── craft/Ribbon/Ribbon.paint.css — component-scoped styles ─────────────
+    fs.writeFileSync(path.join(projectDir, 'craft', 'Ribbon', 'Ribbon.paint.css'),
+      `/* Ribbon component — scoped paint styles */\n/* Add CSS here for fine-grained control */\n`);
+
+    // ── services/index.js — starter vault service ────────────────────────────
+    fs.writeFileSync(path.join(projectDir, 'services', 'index.js'), `
 'use strict';
-// Shared server utilities (imported by compiled server modules)
+/**
+ * Luxaura Vault Service
+ * Functions defined here run ONLY on the server.
+ * They are called from .lux files via:  await vault.functionName(args)
+ */
 
-async function logClick(count) {
-  console.log('[Server] Button clicked, count:', count);
-  return { ok: true, count };
+async function ping() {
+  return { ok: true, message: 'Vault is alive', time: new Date().toISOString() };
 }
 
-module.exports = { logClick };
+module.exports = { ping };
 `);
 
-    // package.json for project
+    // ── package.json ─────────────────────────────────────────────────────────
     fs.writeFileSync(path.join(projectDir, 'package.json'), JSON.stringify({
       name,
       version: '1.0.0',
-      description: `${name} — built with Luxaura`,
+      description: `${name} — crafted with Luxaura`,
       scripts: {
-        dev: 'luxaura run',
-        build: 'luxaura build',
-      },
-      dependencies: {
-        luxaura: `^${VERSION}`,
+        ignite: 'luxaura ignite',
+        forge:  'luxaura forge',
       },
+      dependencies: { luxaura: `^${VERSION}` },
     }, null, 2));
 
-    // .gitignore
-    fs.writeFileSync(path.join(projectDir, '.gitignore'), `node_modules/\ndist/\n.DS_Store\n`);
+    // ── .gitignore ───────────────────────────────────────────────────────────
+    fs.writeFileSync(path.join(projectDir, '.gitignore'), `node_modules/\ndepot/\n.DS_Store\n*.log\n`);
 
-    // Copy UI kit files if they exist (they'll be generated later)
-    const uiKitSrc = path.join(__dirname, '..', 'ui-kit');
-    const uiKitDst = path.join(projectDir, 'dist', 'client');
-    if (fs.existsSync(path.join(uiKitSrc, 'luxaura.min.css'))) {
-      fs.copySync(path.join(uiKitSrc, 'luxaura.min.css'), path.join(uiKitDst, 'luxaura.min.css'));
-      fs.copySync(path.join(uiKitSrc, 'luxaura.min.js'),  path.join(uiKitDst, 'luxaura.min.js'));
+    // ── Copy UI kit to depot/public ──────────────────────────────────────────
+    const kitSrc = path.join(__dirname, '..', 'ui-kit');
+    const kitDst = path.join(projectDir, 'depot', 'public');
+    if (fs.existsSync(path.join(kitSrc, 'luxaura.min.css'))) {
+      fs.copySync(path.join(kitSrc, 'luxaura.min.css'), path.join(kitDst, 'luxaura.min.css'));
+      fs.copySync(path.join(kitSrc, 'luxaura.min.js'),  path.join(kitDst, 'luxaura.min.js'));
     }
 
-    success(`Project "${name}" created!`);
-    info(`\n  cd ${name}`);
-    info(`  luxaura run\n`);
+    success(`Project "${chalk.white(name)}" released!`);
+    dim('');
+    info(`  ${chalk.white('cd ' + name)}`);
+    info(`  ${chalk.white('luxaura ignite')}   ${chalk.gray('→ start dev server')}`);
+    info(`  ${chalk.white('luxaura help_me')}  ${chalk.gray('→ see all commands')}`);
+    dim('');
   });
 
-// ─── Command: run ─────────────────────────────────────────────────────────────
+// ─── Start page builder ───────────────────────────────────────────────────────
+
+function buildStartPage(name) {
+  return `
+# ${name} — Start Scene
+# This is your project's home. Edit it freely.
+# Run:  luxaura help_me   to see all commands.
+
+receive
+    appName: String = "${name}"
+
+signal
+    activeSection: "welcome"
+
+paint
+    self
+        fill: #0d0d1a
+        breathe: 0
+
+    Headline
+        ink: #ffffff
+        weight: heavy
+
+    Body
+        ink: #b0afd0
+
+    Trigger
+        curve: pill
+        glow: soft
+        pointer: true
+
+    Plate
+        fill: #1a1a2e
+        curve: round
+        glow: whisper
+        breathe: 6
+
+    Snippet
+        fill: #0a0920
+        ink: #a8a3ff
+        curve: gentle
+
+canvas
+    Frame
+        Ribbon
+            Strip
+                Headline "<<appName>>"
+                Mark "v1.0"
+            Strip
+                Trigger "Docs"
+                Trigger "GitHub"
+
+        Scene
+            Stack
+
+                Frame
+                    Headline "Welcome to <<appName>>"
+                    Body "Your Luxaura project is alive. This is your start scene — edit scenes/index.lux to make it yours."
+                    Strip
+                        Trigger "Read the Docs"
+                            when click:
+                        Trigger "View on GitHub"
+                            when click:
+
+                Splitter
+
+                Plate
+                    Headline "Luxaura Quick Reference"
+                    Body "Everything is different by design. Here is what you need to know."
+
+                    Mosaic
+
+                        Plate
+                            Headline "Project structure"
+                            Roster
+                                Entry
+                                    Snippet "/scenes"
+                                    Body "Your routes live here. index.lux is this page."
+                                Entry
+                                    Snippet "/craft"
+                                    Body "Your components. Each gets its own folder."
+                                Entry
+                                    Snippet "/services"
+                                    Body "Vault logic — server-only, never exposed."
+                                Entry
+                                    Snippet "/media"
+                                    Body "Images, fonts, static files."
+                                Entry
+                                    Snippet "/depot"
+                                    Body "Build output. Never commit this."
+
+                        Plate
+                            Headline "CLI Commands"
+                            Roster
+                                Entry
+                                    Snippet "luxaura ignite"
+                                    Body "Start the dev server with live reload."
+                                Entry
+                                    Snippet "luxaura forge"
+                                    Body "Build for production."
+                                Entry
+                                    Snippet "luxaura component MyCard"
+                                    Body "Create a new component in /craft/MyCard/."
+                                Entry
+                                    Snippet "luxaura service UserService"
+                                    Body "Create a vault service in /services/."
+                                Entry
+                                    Snippet "luxaura module SharedLogic"
+                                    Body "Create a shared module."
+                                Entry
+                                    Snippet "luxaura bring tailwindcss"
+                                    Body "Pull in an external library."
+                                Entry
+                                    Snippet "luxaura polish"
+                                    Body "Auto-format all .lux files."
+                                Entry
+                                    Snippet "luxaura shield"
+                                    Body "Scan for security issues."
+                                Entry
+                                    Snippet "luxaura help_me"
+                                    Body "Full interactive CLI guide."
+
+                        Plate
+                            Headline ".lux Syntax"
+                            Roster
+                                Entry
+                                    Snippet "receive"
+                                    Body "Inputs passed in from outside."
+                                Entry
+                                    Snippet "signal"
+                                    Body "Reactive data inside this scene."
+                                Entry
+                                    Snippet "vault"
+                                    Body "Server-only logic. Never reaches browser."
+                                Entry
+                                    Snippet "paint"
+                                    Body "Styles using smart token names."
+                                Entry
+                                    Snippet "canvas"
+                                    Body "Your UI tree using Luxaura nodes."
+                                Entry
+                                    Snippet "<<varName>>"
+                                    Body "Bind a signal or receive value."
+                                Entry
+                                    Snippet "when click:"
+                                    Body "Event handler on any node."
+                                Entry
+                                    Snippet "await vault.myAction()"
+                                    Body "Call a server vault action."
+
+                        Plate
+                            Headline "Paint Tokens"
+                            Roster
+                                Entry
+                                    Snippet "breathe: 4"
+                                    Body "Padding — 4 × 4px = 16px."
+                                Entry
+                                    Snippet "push: 4"
+                                    Body "Margin."
+                                Entry
+                                    Snippet "glow: soft"
+                                    Body "Box shadow."
+                                Entry
+                                    Snippet "curve: smooth"
+                                    Body "Border radius — 8px."
+                                Entry
+                                    Snippet "ink: #fff"
+                                    Body "Text color."
+                                Entry
+                                    Snippet "fill: #000"
+                                    Body "Background color."
+                                Entry
+                                    Snippet "size: titan"
+                                    Body "Font size — 3rem."
+                                Entry
+                                    Snippet "weight: heavy"
+                                    Body "Font weight — 900."
+
+                Splitter
+
+                Anchor
+                    Body "Built with Luxaura — the framework that does things differently."
+`.trim() + '\n';
+}
+
+// ─── Command: ignite (was: run) ───────────────────────────────────────────────
 
 program
-  .command('run')
-  .description('Start development server with HMR')
-  .option('-p, --port <port>', 'Port number', '3000')
+  .command('ignite')
+  .description('Start the Luxaura dev server with live reload')
+  .option('-p, --port <port>', 'Port to listen on', '3000')
   .action(async (opts) => {
     banner();
     const rootDir = process.cwd();
-    const port = parseInt(opts.port, 10);
+    const port    = parseInt(opts.port, 10);
 
-    log('Compiling .lux files...');
+    log('Forging scenes and craft...');
     await buildAll(rootDir, { dev: true });
 
-    const vault = new VaultServer({ port, rootDir });
-    const actualPort = await vault.start();
-    success(`Dev server running at ${chalk.white(`http://localhost:${actualPort}`)}`);
-    info('Hot Module Replacement enabled. Watching for changes...\n');
+    const server = new VaultServer({ port, rootDir });
+    const live   = await server.start();
+    success(`Dev server ignited at ${chalk.white(`http://localhost:${live}`)}`);
+    info('Live reload active. Watching /scenes, /craft, /services...\n');
 
-    // Inject HMR client script into index.html
-    _injectHMR(rootDir, actualPort);
+    _injectLiveReload(rootDir, live);
 
     const watcher = chokidar.watch(
-      [path.join(rootDir, 'pages'), path.join(rootDir, 'modules')],
+      [
+        path.join(rootDir, 'scenes'),
+        path.join(rootDir, 'craft'),
+        path.join(rootDir, 'services'),
+      ],
       { ignoreInitial: true }
     );
 
-    watcher.on('change', async (filePath) => {
-      log(`Changed: ${chalk.yellow(path.relative(rootDir, filePath))}`);
+    watcher.on('change', async (fp) => {
+      log(`Changed: ${chalk.yellow(path.relative(rootDir, fp))}`);
       try {
-        await buildFile(filePath, rootDir, { dev: true });
-        vault.triggerHMR(path.relative(rootDir, filePath));
-        success('Rebuilt and reloaded.');
-      } catch (e) {
-        error(`Compile error: ${e.message}`);
-      }
+        if (fp.endsWith('.lux')) await buildFile(fp, rootDir, { dev: true });
+        server.triggerHMR(path.relative(rootDir, fp));
+        success('Rebuilt.');
+      } catch (e) { error(`Build error: ${e.message}`); }
     });
 
-    watcher.on('add', async (filePath) => {
-      log(`New file: ${chalk.yellow(path.relative(rootDir, filePath))}`);
-      await buildFile(filePath, rootDir, { dev: true });
-      vault.triggerHMR('new-file');
+    watcher.on('add', async (fp) => {
+      if (!fp.endsWith('.lux')) return;
+      log(`New: ${chalk.yellow(path.relative(rootDir, fp))}`);
+      await buildFile(fp, rootDir, { dev: true });
+      server.triggerHMR('new-file');
     });
   });
 
-function _injectHMR(rootDir, port) {
-  const indexPath = path.join(rootDir, 'dist', 'client', 'index.html');
-  if (!fs.existsSync(indexPath)) return;
-  let html = fs.readFileSync(indexPath, 'utf8');
-  if (html.includes('__lux_hmr__')) return;
-  const hmrScript = `
-<script id="__lux_hmr__">
+function _injectLiveReload(rootDir, port) {
+  const htmlPath = path.join(rootDir, 'depot', 'public', 'index.html');
+  if (!fs.existsSync(htmlPath)) return;
+  let html = fs.readFileSync(htmlPath, 'utf8');
+  if (html.includes('__lux_live__')) return;
+  const script = `\n<script id="__lux_live__">
 (function(){
-  const ws = new WebSocket('ws://localhost:${port}');
-  ws.onmessage = function(e) {
-    const msg = JSON.parse(e.data);
-    if (msg.type === 'hmr') {
-      console.log('[Luxaura HMR] Reloading:', msg.file);
-      location.reload();
-    }
-  };
-  ws.onclose = function() {
-    console.log('[Luxaura HMR] Connection lost. Reconnecting...');
-    setTimeout(() => location.reload(), 2000);
+  var ws = new WebSocket('ws://localhost:${port}');
+  ws.onmessage = function(e){
+    var m = JSON.parse(e.data);
+    if (m.type === 'hmr') { console.log('[Luxaura Live]', m.file); location.reload(); }
   };
+  ws.onclose = function(){ setTimeout(function(){ location.reload(); }, 2000); };
 })();
 </script>`;
-  html = html.replace('</body>', hmrScript + '</body>');
-  fs.writeFileSync(indexPath, html);
+  html = html.replace('</body>', script + '</body>');
+  fs.writeFileSync(htmlPath, html);
 }
 
-// ─── Command: build ───────────────────────────────────────────────────────────
+// ─── Command: forge (was: build) ─────────────────────────────────────────────
 
 program
-  .command('build')
-  .description('Compile for production (splits client/server)')
+  .command('forge')
+  .description('Forge the production build (splits public + vault)')
   .action(async () => {
     banner();
     const rootDir = process.cwd();
-    log('Building for production...');
-
+    log('Forging production build...');
     const start = Date.now();
     const stats  = await buildAll(rootDir, { dev: false });
-
-    success(`Build complete in ${Date.now() - start}ms`);
-    info(`  Client assets → ${chalk.white('dist/client/')}`);
-    info(`  Server modules → ${chalk.white('dist/server/')}`);
-    info(`  Files compiled: ${stats.count}`);
-    if (stats.errors.length) {
-      stats.errors.forEach(e => error(e));
-    }
+    success(`Forged in ${Date.now() - start}ms — ${stats.count} file(s)`);
+    info(`  Public assets  → ${chalk.white('depot/public/')}`);
+    info(`  Vault modules  → ${chalk.white('depot/vault/')}`);
+    if (stats.errors.length) stats.errors.forEach(e => error(e));
   });
 
-// ─── Command: install ─────────────────────────────────────────────────────────
+// ─── Command: bring (was: install) ───────────────────────────────────────────
 
 program
-  .command('install <lib>')
-  .description('Install and integrate a frontend library')
-  .action(async (lib) => {
+  .command('bring <lib>')
+  .description('Bring in an external library and wire it into the build')
+  .action((lib) => {
     banner();
-    log(`Installing ${chalk.yellow(lib)}...`);
+    log(`Bringing in: ${chalk.yellow(lib)}`);
     try {
       execSync(`npm install ${lib}`, { stdio: 'inherit', cwd: process.cwd() });
-      success(`${lib} installed.`);
-      info('Classes are now available in your .lux files via the class: attribute.');
-    } catch (e) {
-      error(`npm install failed: ${e.message}`);
-    }
+      success(`${lib} is now available.`);
+      info('Use its classes directly in your canvas via the class: attribute.');
+    } catch (e) { error(`npm install failed: ${e.message}`); }
   });
 
-// ─── Command: generate ────────────────────────────────────────────────────────
+// ─── Command: component ───────────────────────────────────────────────────────
+// Creates /craft/<Name>/<Name>.lux + <Name>.paint.css + index.js
+
+program
+  .command('component <name>')
+  .description('Craft a new UI component in /craft/<Name>/')
+  .action((name) => {
+    banner();
+    const rootDir  = process.cwd();
+    const compDir  = path.join(rootDir, 'craft', name);
+
+    if (fs.existsSync(compDir)) {
+      warn(`Component "${name}" already exists at craft/${name}/`);
+      process.exit(0);
+    }
+
+    fs.mkdirpSync(compDir);
 
-const TEMPLATES = {
-  component: (name) => `
+    // ── <Name>.lux — component with a styled big title ───────────────────────
+    fs.writeFileSync(path.join(compDir, `${name}.lux`), `
 # ${name} Component
+# Edit this file to build your component.
 
-props
-    label: String = "${name}"
+receive
+    label: String = "I'm ${name} component !!"
 
-state
+signal
     active: false
 
-style
+paint
     self
-        padding: 4
-        radius: medium
-        shadow: soft
+        breathe: 8
+        fill: #0d0d1a
+        glow: soft
+        curve: round
+
+    Headline
+        ink: #ffffff
+        size: titan
+        weight: heavy
+        align: center
+
+    Body
+        ink: #a8a3ff
+        size: large
+        align: center
+        push: 4
+
+    Mark
+        fill: #6c63ff
+        ink: #ffffff
+        curve: pill
+        push: 2
+
+canvas
+    Frame
+        Stack
+            Headline "<<label>>"
+            Body "I live in craft/${name}/${name}.lux — edit me!"
+            Strip
+                Mark "Luxaura Component"
+                Mark "<<active>>"
+`.trim() + '\n');
 
-view
-    Box
-        Title "{label}"
-        Text "Edit ${name}.lux to get started."
-`.trim() + '\n',
+    // ── <Name>.paint.css — scoped paint styles ───────────────────────────────
+    fs.writeFileSync(path.join(compDir, `${name}.paint.css`), `
+/* ${name} — Component-scoped paint styles */
+/* These styles apply only to this component. */
+/* Use .lux-* classes from luxaura.min.css or write your own. */
 
-  page: (name) => `
-# ${name} Page
+.lux-scene-${name.toLowerCase()} {
+  /* Component root styles */
+}
+`.trim() + '\n');
 
-props
-    title: String = "${name}"
+    // ── index.js — optional JS bridge ───────────────────────────────────────
+    fs.writeFileSync(path.join(compDir, 'index.js'), `
+/**
+ * ${name} — Optional JS bridge
+ * Use this file to export helpers, constants, or sub-components.
+ * The .lux file handles the UI — this is for shared logic only.
+ */
 
-state
-    loading: false
+module.exports = {
+  name: '${name}',
+  version: '1.0.0',
+};
+`);
 
-style
-    self
-        padding: 8
+    success(`Component "${chalk.white(name)}" crafted at ${chalk.white(`craft/${name}/`)}`);
+    info(`  ${chalk.white(`craft/${name}/${name}.lux`)}         ← the component canvas`);
+    info(`  ${chalk.white(`craft/${name}/${name}.paint.css`)}   ← scoped styles`);
+    info(`  ${chalk.white(`craft/${name}/index.js`)}           ← optional JS bridge`);
+  });
 
-view
-    Container
-        Title "{title}"
-        Text "This is the ${name} page."
-`.trim() + '\n',
+// ─── Command: service ────────────────────────────────────────────────────────
+// Creates /services/<Name>.service.js — vault-only, never reaches browser
 
-  api: (name) => `
-# ${name} API Module (server-side only)
-# This file is compiled into dist/server and NEVER sent to the client.
+program
+  .command('service <name>')
+  .description('Create a vault service in /services/ (server-only)')
+  .action((name) => {
+    banner();
+    const rootDir    = process.cwd();
+    const servicesDir = path.join(rootDir, 'services');
+    fs.mkdirpSync(servicesDir);
 
-server
-    import db from "luxaura/db"
+    const filePath = path.join(servicesDir, `${name}.service.js`);
+    if (fs.existsSync(filePath)) {
+      warn(`Service "${name}" already exists.`); process.exit(0);
+    }
 
-    def get${name}(id):
-        return db.query("SELECT * FROM ${name.toLowerCase()}s WHERE id = ?", [id])
+    fs.writeFileSync(filePath, `
+/**
+ * ${name} — Luxaura Vault Service
+ *
+ * ┌─────────────────────────────────────────────────────┐
+ * │  VAULT — This file NEVER reaches the browser.       │
+ * │  All functions here run server-side only.           │
+ * │  Call them from .lux files: await vault.action()    │
+ * └─────────────────────────────────────────────────────┘
+ *
+ * Syntax in .lux files:
+ *
+ *   vault
+ *       pull db from "luxaura/db"
+ *       action get${name}(id):
+ *           return db.query("SELECT * FROM ${name.toLowerCase()}s WHERE id = ?", [id])
+ */
+'use strict';
 
-    def create${name}(data):
-        return db.insert("${name.toLowerCase()}s", data)
+/**
+ * get${name} — Fetch a ${name} by id
+ */
+async function get${name}(id) {
+  // TODO: implement
+  return { id, name: '${name}', fetched: new Date().toISOString() };
+}
 
-    def update${name}(id, data):
-        return db.update("${name.toLowerCase()}s", data, { id })
-`.trim() + '\n',
-};
+/**
+ * create${name} — Create a new ${name}
+ */
+async function create${name}(data) {
+  // TODO: implement
+  return { ok: true, data };
+}
+
+/**
+ * update${name} — Update a ${name}
+ */
+async function update${name}(id, data) {
+  // TODO: implement
+  return { ok: true, id, data };
+}
+
+/**
+ * delete${name} — Delete a ${name}
+ */
+async function delete${name}(id) {
+  // TODO: implement
+  return { ok: true, id };
+}
+
+module.exports = { get${name}, create${name}, update${name}, delete${name} };
+`);
+
+    success(`Service "${chalk.white(name)}" created at ${chalk.white(`services/${name}.service.js`)}`);
+    info('Call its actions from .lux vault blocks:');
+    info(`  ${chalk.white(`await vault.get${name}(id)`)}`);
+  });
+
+// ─── Command: module ─────────────────────────────────────────────────────────
+// Creates a shared logic module — used by multiple scenes or components
 
 program
-  .command('generate <type> <name>')
-  .alias('g')
-  .description('Scaffold component, page, or api file')
-  .action((type, name) => {
+  .command('module <name>')
+  .description('Create a shared module in /craft/<Name>/')
+  .action((name) => {
     banner();
-    const rootDir = process.cwd();
-    const template = TEMPLATES[type];
-    if (!template) {
-      error(`Unknown type "${type}". Use: component, page, api`);
-      process.exit(1);
+    const rootDir  = process.cwd();
+    const modDir   = path.join(rootDir, 'craft', name);
+
+    if (fs.existsSync(modDir)) {
+      warn(`Module "${name}" already exists.`); process.exit(0);
     }
 
-    const dirs = { component: 'modules', page: 'pages', api: 'pages' };
-    const dir = path.join(rootDir, dirs[type]);
-    fs.mkdirpSync(dir);
+    fs.mkdirpSync(modDir);
 
-    const filePath = path.join(dir, `${name}.lux`);
-    if (fs.existsSync(filePath)) {
-      warn(`File already exists: ${path.relative(rootDir, filePath)}`);
-      process.exit(0);
-    }
+    // A module is a .lux scene + a JS utility file — shared, not a route
+    fs.writeFileSync(path.join(modDir, `${name}.lux`), `
+# ${name} — Shared Module
+# This module can be composed into any scene or component.
+
+receive
+    title: String = "${name} Module"
+
+signal
+    ready: true
+
+paint
+    self
+        breathe: 6
+        fill: #1a1a2e
+        curve: smooth
+
+    Headline
+        ink: #6c63ff
+        size: xlarge
+        weight: strong
+
+canvas
+    Frame
+        Stack
+            Headline "<<title>>"
+            Body "I'm the ${name} module — compose me anywhere."
+`.trim() + '\n');
+
+    fs.writeFileSync(path.join(modDir, `${name}.utils.js`), `
+/**
+ * ${name} Module — Shared utilities
+ * Import these helpers into any service or scene.
+ */
+'use strict';
+
+function format${name}(data) {
+  return { ...data, formatted: true, module: '${name}' };
+}
+
+module.exports = { format${name} };
+`);
+
+    success(`Module "${chalk.white(name)}" created at ${chalk.white(`craft/${name}/`)}`);
+    info(`  ${chalk.white(`craft/${name}/${name}.lux`)}        ← composable scene`);
+    info(`  ${chalk.white(`craft/${name}/${name}.utils.js`)}  ← shared utilities`);
+  });
+
+// ─── Command: help_me ────────────────────────────────────────────────────────
+
+program
+  .command('help_me')
+  .description('Interactive CLI guide — everything Luxaura')
+  .action(() => {
+    banner();
 
-    fs.writeFileSync(filePath, template(name));
-    success(`Generated: ${chalk.white(path.relative(rootDir, filePath))}`);
+    console.log(chalk.hex('#6c63ff').bold('  ══════════════════════════════════════════════'));
+    console.log(chalk.hex('#a8a3ff').bold('  LUXAURA CLI — Complete Reference'));
+    console.log(chalk.hex('#6c63ff').bold('  ══════════════════════════════════════════════\n'));
+
+    const section = (title) => {
+      console.log(chalk.hex('#6c63ff').bold(`  ▸ ${title}`));
+    };
+    const cmd = (c, d) => {
+      console.log(`    ${chalk.white(c.padEnd(38))} ${chalk.gray(d)}`);
+    };
+    const note = (t) => console.log(chalk.gray(`      ${t}`));
+    const br = () => console.log('');
+
+    section('PROJECT');
+    cmd('luxaura release <name>',         'Bootstrap a new project');
+    note('Creates /scenes /craft /services /media /depot');
+    note('Generates a rich start scene with full docs at scenes/index.lux');
+    br();
+
+    section('DEVELOPMENT');
+    cmd('luxaura ignite',                 'Start dev server + live reload (port 3000)');
+    cmd('luxaura ignite --port 8080',     'Start on a custom port');
+    cmd('luxaura forge',                  'Build for production → depot/public + depot/vault');
+    br();
+
+    section('SCAFFOLDING');
+    cmd('luxaura component <Name>',       'Create a component → craft/<Name>/');
+    note('Generates: <Name>.lux + <Name>.paint.css + index.js');
+    cmd('luxaura service <Name>',         'Create a vault service → services/<Name>.service.js');
+    note('Vault services run server-side ONLY — never exposed to browser');
+    cmd('luxaura module <Name>',          'Create a shared module → craft/<Name>/');
+    note('Modules are composable — use them across scenes and components');
+    br();
+
+    section('LIBRARIES');
+    cmd('luxaura bring <lib>',            'Pull in an npm library (e.g. luxaura bring gsap)');
+    note('Wires the library into your build automatically');
+    br();
+
+    section('QUALITY');
+    cmd('luxaura polish',                 'Auto-format all .lux files');
+    cmd('luxaura shield',                 'Scan for XSS, SQL injection, vault leaks');
+    br();
+
+    section('HELP');
+    cmd('luxaura help_me',                'Show this guide');
+    cmd('luxaura --version',              'Show framework version');
+    br();
+
+    console.log(chalk.hex('#6c63ff').bold('  ══════════════════════════════════════════════'));
+    console.log(chalk.hex('#a8a3ff')('  .lux Block Reference'));
+    console.log(chalk.hex('#6c63ff').bold('  ══════════════════════════════════════════════\n'));
+
+    const block = (b, d) => console.log(`    ${chalk.white(b.padEnd(12))} ${chalk.gray(d)}`);
+    block('receive',   'Inputs passed in from outside this scene/component');
+    block('signal',    'Reactive data — changes trigger canvas re-render');
+    block('vault',     'Server-only logic — NEVER sent to browser');
+    block('paint',     'Styling using Luxaura smart tokens (breathe/glow/curve/ink...)');
+    block('canvas',    'UI composition tree using Luxaura nodes');
+    br();
+
+    console.log(chalk.hex('#a8a3ff')('  Node Vocabulary (instead of HTML tags):\n'));
+    const node = (n, d) => console.log(`    ${chalk.hex('#6c63ff')(n.padEnd(14))} ${chalk.gray(d)}`);
+    node('Frame',     'Generic block wrapper');
+    node('Scene',     'Max-width centered wrapper (like <main>)');
+    node('Strip',     'Horizontal flex row');
+    node('Stack',     'Vertical flex column');
+    node('Mosaic',    'Auto-responsive grid');
+    node('Ribbon',    'Top navigation bar');
+    node('Drawer',    'Side panel');
+    node('Anchor',    'Footer');
+    node('Crown',     'Page header');
+    node('Headline',  'Auto-selects h1–h6 by nesting depth');
+    node('Body',      'Paragraph text');
+    node('Picture',   'Image (auto-lazy loaded)');
+    node('Trigger',   'Button / clickable action');
+    node('Field',     'Text input');
+    node('Vessel',    'Form wrapper');
+    node('Toggle',    'Checkbox / switch');
+    node('Plate',     'Card surface');
+    node('Mark',      'Badge / tag');
+    node('Roster',    'List (ul)');
+    node('Entry',     'List item (li)');
+    node('Splitter',  'Horizontal divider');
+    node('Snippet',   'Inline code');
+    node('Block',     'Code block');
+    br();
+
+    console.log(chalk.hex('#a8a3ff')('  Paint Smart Tokens:\n'));
+    const token = (t, d) => console.log(`    ${chalk.hex('#6c63ff')(t.padEnd(24))} ${chalk.gray(d)}`);
+    token('breathe: 4',      'padding (4 × 4px = 16px)');
+    token('push: 4',         'margin');
+    token('gap: 4',          'gap between children');
+    token('glow: soft',      'box-shadow (whisper/soft/loud/neon)');
+    token('curve: smooth',   'border-radius (gentle/smooth/round/pill)');
+    token('ink: #color',     'text color');
+    token('fill: #color',    'background color');
+    token('size: titan',     'font-size (tiny/small/base/large/xlarge/huge/titan/mega)');
+    token('weight: heavy',   'font-weight (feather/light/normal/firm/strong/heavy)');
+    token('pointer: true',   'cursor: pointer');
+    token('wide: 200',       'width in px');
+    token('tall: 100',       'height in px');
+    br();
+
+    console.log(chalk.hex('#6c63ff').bold('  ══════════════════════════════════════════════\n'));
   });
 
-// ─── Command: format ──────────────────────────────────────────────────────────
+// ─── Command: polish (was: format) ───────────────────────────────────────────
 
 program
-  .command('format')
-  .description('Auto-fix indentation and style in .lux files')
+  .command('polish')
+  .description('Auto-format all .lux files')
   .action(() => {
     banner();
     const rootDir = process.cwd();
-    const files = getAllLuxFiles(rootDir);
-    let fixed = 0;
+    const files   = allLuxFiles(rootDir);
+    let fixed     = 0;
 
-    files.forEach(filePath => {
+    files.forEach(fp => {
       try {
-        const source  = fs.readFileSync(filePath, 'utf8');
-        const formatted = formatLux(source);
-        if (formatted !== source) {
-          fs.writeFileSync(filePath, formatted);
-          log(`Formatted: ${path.relative(rootDir, filePath)}`);
-          fixed++;
-        }
-      } catch (e) {
-        warn(`Could not format ${filePath}: ${e.message}`);
-      }
+        const src  = fs.readFileSync(fp, 'utf8');
+        const fmtd = formatLux(src);
+        if (fmtd !== src) { fs.writeFileSync(fp, fmtd); log(`Polished: ${path.relative(rootDir, fp)}`); fixed++; }
+      } catch (e) { warn(`Could not polish ${fp}: ${e.message}`); }
     });
 
-    success(`Formatted ${fixed} file(s).`);
+    success(`Polished ${fixed} file(s) out of ${files.length} scanned.`);
   });
 
 function formatLux(source) {
-  const BLOCK_NAMES = ['props', 'state', 'server', 'style', 'view'];
-  const lines = source.split('\n');
-  const out = [];
-  let inBlock = false;
+  const BLOCKS = ['receive', 'signal', 'vault', 'paint', 'canvas'];
+  const lines  = source.split('\n');
+  const out    = [];
+  let inBlock  = false;
 
   for (let i = 0; i < lines.length; i++) {
-    const raw = lines[i];
+    const raw     = lines[i];
     const trimmed = raw.trim();
 
     if (!trimmed) { out.push(''); continue; }
     if (trimmed.startsWith('#')) { out.push(trimmed); continue; }
 
-    if (BLOCK_NAMES.includes(trimmed)) {
+    if (BLOCKS.includes(trimmed)) {
       if (i > 0) out.push('');
       out.push(trimmed);
       inBlock = true;
@@ -469,9 +910,7 @@ function formatLux(source) {
     }
 
     if (inBlock) {
-      // Normalize to 4-space indent per level
-      const indent = raw.match(/^(\s*)/)[1];
-      const spaces = indent.replace(/\t/g, '    ');
+      const spaces = raw.match(/^(\s*)/)[1].replace(/\t/g, '    ');
       const level  = Math.round(spaces.length / 4);
       out.push('    '.repeat(Math.max(1, level)) + trimmed);
     } else {
@@ -482,151 +921,131 @@ function formatLux(source) {
   return out.join('\n').trimEnd() + '\n';
 }
 
-// ─── Command: secure ──────────────────────────────────────────────────────────
+// ─── Command: shield (was: secure) ───────────────────────────────────────────
 
 program
-  .command('secure')
+  .command('shield')
   .description('Scan codebase for security vulnerabilities')
   .action(() => {
     banner();
     const rootDir = process.cwd();
-    const files = getAllLuxFiles(rootDir);
-    let issues = 0;
-
-    const XSS_PATTERNS = [
-      { re: /innerHTML\s*=/g,       msg: 'Unsafe innerHTML assignment (XSS risk)' },
-      { re: /document\.write\s*\(/g, msg: 'document.write() usage (XSS risk)' },
-      { re: /eval\s*\(/g,           msg: 'eval() usage (code injection risk)' },
-    ];
-
-    const SQL_PATTERNS = [
-      { re: /db\.query\s*\(\s*`[^`]*\$\{/g, msg: 'Possible SQL injection: template literal in query. Use parameterized queries.' },
-      { re: /db\.query\s*\(\s*"[^"]*"\s*\+/g, msg: 'Possible SQL injection: string concatenation in query. Use parameterized queries.' },
+    const files   = allLuxFiles(rootDir);
+    let issues    = 0;
+
+    const CHECKS = [
+      { re: /innerHTML\s*=/g,               msg: 'Unsafe innerHTML (XSS risk)' },
+      { re: /document\.write\s*\(/g,        msg: 'document.write() (XSS risk)' },
+      { re: /eval\s*\(/g,                   msg: 'eval() usage (injection risk)' },
+      { re: /db\.query\s*\(`[^`]*\$\{/g,   msg: 'SQL injection: template literal in query — use parameterized queries' },
+      { re: /db\.query\s*\("[^"]*"\s*\+/g,  msg: 'SQL injection: string concat in query — use parameterized queries' },
+      { re: /process\.env\.(DB_PASSWORD|SECRET|API_KEY|TOKEN)/gi, msg: 'Sensitive env var — confirm it stays in vault block' },
     ];
 
-    const SERVER_LEAK = [
-      { re: /process\.env\.(DB_PASSWORD|SECRET|API_KEY)/gi, msg: 'Sensitive env var referenced — verify it is in server block only' },
-    ];
-
-    files.forEach(filePath => {
-      const source  = fs.readFileSync(filePath, 'utf8');
-      const relPath = path.relative(rootDir, filePath);
-
-      const allPatterns = [...XSS_PATTERNS, ...SQL_PATTERNS, ...SERVER_LEAK];
-      allPatterns.forEach(({ re, msg }) => {
-        const matches = source.match(re);
-        if (matches) {
-          warn(`${relPath}: ${msg}`);
-          issues++;
-        }
+    files.forEach(fp => {
+      const src     = fs.readFileSync(fp, 'utf8');
+      const relPath = path.relative(rootDir, fp);
+      CHECKS.forEach(({ re, msg }) => {
+        if (re.test(src)) { warn(`${relPath}: ${msg}`); issues++; }
       });
 
-      // Check for server code outside server block
-      const serverBlockMatch = source.match(/^server$([\s\S]*?)(?=^(?:props|state|style|view)$|\Z)/m);
-      if (!serverBlockMatch) {
-        const dbOutsideServer = /db\.(query|insert|update)/.test(source);
-        if (dbOutsideServer) {
-          error(`${relPath}: db access detected outside server block — this may leak to client`);
-          issues++;
-        }
+      // Detect vault/db code outside vault block
+      if (!src.match(/^vault$/m) && /db\.(query|insert|update)/.test(src)) {
+        error(`${relPath}: db access outside vault block — may leak to browser!`);
+        issues++;
       }
     });
 
-    if (issues === 0) {
-      success(`No issues found. ${files.length} files scanned.`);
-    } else {
-      warn(`Found ${issues} potential issue(s) across ${files.length} files.`);
-    }
+    if (issues === 0) success(`Shield clear. ${files.length} file(s) scanned, 0 issues.`);
+    else warn(`Found ${issues} issue(s) in ${files.length} file(s). Review and fix before deploying.`);
   });
 
-// ─── Build Helpers ─────────────────────────────────────────────────────────────
+// ─── Build helpers ────────────────────────────────────────────────────────────
 
-async function buildAll(rootDir, opts = {}) {
-  const files  = getAllLuxFiles(rootDir);
-  const errors = [];
-  let count    = 0;
+async function buildAll(rootDir, opts) {
+  opts = opts || {};
+  const files    = allLuxFiles(rootDir);
+  const errors   = [];
+  let count      = 0;
 
-  // Copy UI kit
-  const uiKitSrc = path.join(__dirname, '..', 'ui-kit');
-  const clientDir = path.join(rootDir, 'dist', 'client');
-  fs.mkdirpSync(clientDir);
-  fs.mkdirpSync(path.join(rootDir, 'dist', 'server'));
+  // Copy UI kit to depot/public
+  const kitSrc   = path.join(__dirname, '..', 'ui-kit');
+  const publicDir = path.join(rootDir, 'depot', 'public');
+  const vaultDir  = path.join(rootDir, 'depot', 'vault');
+  fs.mkdirpSync(publicDir);
+  fs.mkdirpSync(vaultDir);
 
-  if (fs.existsSync(path.join(uiKitSrc, 'luxaura.min.css'))) {
-    fs.copySync(path.join(uiKitSrc, 'luxaura.min.css'), path.join(clientDir, 'luxaura.min.css'));
-    fs.copySync(path.join(uiKitSrc, 'luxaura.min.js'),  path.join(clientDir, 'luxaura.min.js'));
+  if (fs.existsSync(path.join(kitSrc, 'luxaura.min.css'))) {
+    fs.copySync(path.join(kitSrc, 'luxaura.min.css'), path.join(publicDir, 'luxaura.min.css'));
+    fs.copySync(path.join(kitSrc, 'luxaura.min.js'),  path.join(publicDir, 'luxaura.min.js'));
   }
 
-  // Copy static assets
-  const assetsDir = path.join(rootDir, 'assets');
-  if (fs.existsSync(assetsDir)) {
-    fs.copySync(assetsDir, path.join(clientDir, 'assets'));
-  }
+  // Copy media assets
+  const mediaDir = path.join(rootDir, 'media');
+  if (fs.existsSync(mediaDir)) fs.copySync(mediaDir, path.join(publicDir, 'media'));
 
   for (const f of files) {
-    try {
-      await buildFile(f, rootDir, opts);
-      count++;
-    } catch (e) {
-      errors.push(`${path.relative(rootDir, f)}: ${e.message}`);
-    }
+    try { await buildFile(f, rootDir, opts); count++; }
+    catch (e) { errors.push(`${path.relative(rootDir, f)}: ${e.message}`); }
   }
 
   return { count, errors };
 }
 
-async function buildFile(filePath, rootDir, opts = {}) {
-  const source  = fs.readFileSync(filePath, 'utf8');
+async function buildFile(filePath, rootDir, opts) {
+  opts = opts || {};
+  const source   = fs.readFileSync(filePath, 'utf8');
   const filename = path.basename(filePath);
-  const parser   = new LuxParser(source, filename);
-  const ast      = parser.parse();
-  const compiler = new LuxCompiler(ast);
-  const output   = compiler.compile();
+  const ast      = new LuxParser(source, filename).parse();
+  const output   = new LuxCompiler(ast).compile();
 
-  const clientDir = path.join(rootDir, 'dist', 'client');
-  const serverDir = path.join(rootDir, 'dist', 'server');
-  const name = filename.replace('.lux', '');
+  const publicDir = path.join(rootDir, 'depot', 'public');
+  const vaultDir  = path.join(rootDir, 'depot', 'vault');
+  const name      = filename.replace('.lux', '');
 
-  fs.mkdirpSync(clientDir);
-  fs.mkdirpSync(serverDir);
+  fs.mkdirpSync(publicDir);
+  fs.mkdirpSync(vaultDir);
 
-  // Client JS
-  fs.writeFileSync(path.join(clientDir, `${name}.component.js`), output.clientJS);
+  // Client component JS
+  fs.writeFileSync(path.join(publicDir, `${name}.component.js`), output.clientJS);
 
-  // Server JS (vault)
-  if (output.serverJS && output.serverJS !== `/* Luxaura Vault — ${name} | no server block */\nmodule.exports = {};`) {
-    fs.writeFileSync(path.join(serverDir, `${name}.js`), output.serverJS);
+  // Vault JS (server-only — never served publicly)
+  const emptyVault = `/* Luxaura Vault — ${name} | no vault block */\nmodule.exports = {};`;
+  if (output.vaultJS && output.vaultJS !== emptyVault) {
+    fs.writeFileSync(path.join(vaultDir, `${name}.js`), output.vaultJS);
   }
 
-  // Component CSS
-  if (output.css) {
-    const cssPath = path.join(clientDir, 'styles.css');
-    const existing = fs.existsSync(cssPath) ? fs.readFileSync(cssPath, 'utf8') : '';
-    if (!existing.includes(`/* Luxaura — ${name} Styles */`)) {
-      fs.appendFileSync(cssPath, '\n' + output.css);
-    }
+  // Paint CSS — append per-component styles to global paint.css
+  if (output.paintCSS) {
+    const cssPath = path.join(publicDir, 'paint.css');
+    const exists  = fs.existsSync(cssPath) ? fs.readFileSync(cssPath, 'utf8') : '';
+    const marker  = `/* Luxaura Paint — ${name} */`;
+    if (!exists.includes(marker)) fs.appendFileSync(cssPath, '\n' + output.paintCSS);
   }
 
-  // HTML shell (only for pages)
-  if (filePath.includes('/pages/')) {
-    const htmlPath = path.join(clientDir, name === 'index' ? 'index.html' : `${name}.html`);
+  // HTML shell — only for scenes (route entry points)
+  const isScene = filePath.includes(`${path.sep}scenes${path.sep}`) ||
+                  filePath.replace(/\\/g, '/').includes('/scenes/');
+
+  if (isScene) {
+    const htmlName  = name === 'index' ? 'index.html' : `${name}.html`;
+    const htmlPath  = path.join(publicDir, htmlName);
     fs.writeFileSync(htmlPath, output.html);
 
-    // Bundle app.js
-    const appJsPath = path.join(clientDir, 'app.js');
-    const componentFiles = fs.readdirSync(clientDir)
+    // Bundle app.js from all component JS files
+    const appJsPath = path.join(publicDir, 'app.js');
+    const bundle    = fs.readdirSync(publicDir)
       .filter(f => f.endsWith('.component.js'))
-      .map(f => `// Component: ${f}\n` + fs.readFileSync(path.join(clientDir, f), 'utf8'))
+      .map(f => `/* ── ${f} ── */\n` + fs.readFileSync(path.join(publicDir, f), 'utf8'))
       .join('\n\n');
-    fs.writeFileSync(appJsPath, componentFiles);
+    fs.writeFileSync(appJsPath, bundle);
   }
 }
 
-// ─── Run ─────────────────────────────────────────────────────────────────────
+// ─── Boot ─────────────────────────────────────────────────────────────────────
 
 program
   .name('luxaura')
-  .version(VERSION)
-  .description('Luxaura Framework CLI');
+  .version(VERSION, '-v, --version', 'Show Luxaura version')
+  .description('Luxaura — The Intent-Driven Full-Stack Web Framework');
 
 program.parse(process.argv);