@birdapi/velinstyle 1.2.2 → 1.3.0

package/cli/index.js

@@ -85,170 +85,92 @@ function hasFlag(flag, alias) {
 
 // ── Help ─────────────────────────────────────────────────────────────────────
 
-function help() {
-  console.log(`
-  ${C.bold('VelinStyle CLI')} v${CLI_VERSION}
-
-  ${C.bold('Usage:')}
-    velinstyle init                 Create velinstyle.config.js
-    velinstyle build                Build custom CSS with selected layers
-    velinstyle build --production   Content-aware production output (CSS/JS/themes/icons)
-    velinstyle production [path]    Alias for build --production
-    velinstyle themes               List available themes
-    velinstyle add <name>           Add a single component CSS
-    velinstyle icons <subcommand>   Manage icon providers
-    velinstyle scan [path|file]     Security & accessibility scanner (dir or .html/.css/.js)
-    velinstyle prefix [path]        Add missing velin- prefix (dry-run; use --write)
-    velinstyle blueprint [name]     Print HTML blueprint (run: velinstyle blueprint list)
-    velinstyle blueprint <name> --strict  Fail if emitted classes ∉ CSS
-    velinstyle create <kind> [dir]  Scaffold: landing|dashboard|docs|auth
-    velinstyle serve [dir]          Static preview server (default port 4173)
-    velinstyle doctor               Check dist, icons, config, Windows ESM paths
-    velinstyle transparency <sub>   Transparency Framework: doctor|validate|report|export|migrate
-    velinstyle check [path]         doctor + blueprint --strict + scan + review + transparency
-    velinstyle scaffold "<prompt>"  Plan-first page HTML or recipe fragment
-    velinstyle scaffold --atelier 04,07  Compose Atelier Library ids (beta)
-    velinstyle plan "<prompt>"      Emit page plan JSON (no HTML)
-    velinstyle plan --atelier 04,07 Emit plan JSON for Atelier ids (beta)
-    velinstyle atelier <num|id>     Pull curated Atelier Library showcase
-    velinstyle atelier list         List curated Library numbers/ids
-    velinstyle review [file|html]   Design / a11y / SEO / conversion review gate
-    velinstyle wc api <tag>         Human-readable Web Component API from source
-    velinstyle layout <sub>         Responsive layout audit and fixes
-    velinstyle perf <sub>           Performance audit (images, scripts) with --fix
-    velinstyle tokens build         Generate CSS variables from tokens.json
-    velinstyle tokens validate      Validate tokens.json schema
-    velinstyle docs generate        Auto-generate Markdown API reference
-    velinstyle meta                 Build agent context (velin-agent.json, llms.txt)
-    velinstyle search index         Build JSON search index for VelinSearch
-    velinstyle skills <subcommand>  Registry-first AI skills commands
-    velinstyle workflow <id>        Resolve workflow graph / project workflow
-
-  ${C.bold('Icons subcommands:')}
-    icons list                      Show available icon providers
-    icons add <provider> [--icons a,b] [--variant outline]  Download to icons/svg/
-    icons remove <provider>         Remove provider icons
-    icons build                     Rebuild icon sprite
-
-  ${C.bold('Icons example (multi-provider):')}
-    velinstyle icons add lucide --icons menu,search,check
-    velinstyle icons add heroicons --icons arrow-left --variant outline
-    velinstyle icons build
-
-  ${C.bold('Blueprint:')}
-    velinstyle blueprint list [--strict]  Print ids (strict validates all)
-    velinstyle blueprint <name> [--output, -o <file>] [--strict]
-
-  ${C.bold('Create / serve / doctor / check:')}
-    velinstyle create landing|dashboard|docs|auth [dir] [--theme earth] [--no-copy]
-    velinstyle serve [dir] [--port 4173]
-    velinstyle doctor
-    velinstyle check [path] [--json|--sarif] [--profile marketing|app|docs|fragment|ecommerce]
-    Alias: validate → check · documentation → docs generate help
-
-  ${C.bold('Web Components:')}
-    velinstyle wc api <tag>         e.g. velinstyle wc api velin-toast
-
-  ${C.bold('Scaffold (1.2.0):')}
-    velinstyle scaffold "<prompt>"  Plan → render → review for pages; recipes for fragments
-    velinstyle scaffold list-intents  Show recipe intent keywords
-    velinstyle scaffold "<prompt>" -o out.html [--json]
-    velinstyle scaffold --atelier 04,07 [-o page.html] [--from <library>]  Compose Library showcases (beta)
-
-  ${C.bold('Atelier Library pull (1.2.x):')}
-    velinstyle atelier list
-    velinstyle atelier 36 [-o dir] [--format html|blade|vue|react] [--from <library>] [--base-url <url>]
-    Limitation: blade/vue/react = integration wrappers around vanilla assets (not native rewrites).
-    Native framework blocks / Velin Studio Builder = planned. Atelier ≠ Studio.
-
-  ${C.bold('Plan / Review (1.2.x):')}
-    velinstyle plan "<prompt>" [--json] [-o plan.json]
-    velinstyle plan --atelier 04,07 [-o plan.json]  Atelier compose plan (beta)
-    velinstyle review <file.html> [--json] [--prompt "..."]
-
-  ${C.bold('Transparency (1.2.1):')}
-    velinstyle transparency doctor [path|file] [--policy file] [--json]
-    velinstyle transparency validate [path|file] [--policy file] [--json]
-    velinstyle transparency report [path|file] [--out dir] [--policy file]
-    velinstyle transparency export [path|file] [--format json|json-ld|csv|html] [-o file]
-    velinstyle transparency migrate [path|file] [--apply] [--write] [--policy file]
-    Alias: transparency scan → doctor
-
-  ${C.bold('Layout (0.8.0):')}
-    velinstyle layout audit [path]    Report flex/grid/responsive issues
-    velinstyle layout suggest [path]  Audit with fix suggestions
-    velinstyle layout fix [path]      Apply safe fixes (--dry-run default, --write)
-
-  ${C.bold('Performance (0.9.0):')}
-    velinstyle perf audit [path|file] Report CLS, lazy-load, script defer issues
-    velinstyle perf suggest [path|file] Same as audit with fix hints
-    velinstyle perf fix [path|file]   Apply safe fixes (--write)
-
-  ${C.bold('Production Builder (1.2.2):')}
-    velinstyle build --production [path]
-    velinstyle production [path]
-      --out, -o <dir>          Default: ./dist/velin-production
-      --explain                Show removed CSS/themes/icons + reasons
-      --watch                  Rebuild on content change
-      --report <file>          Write JSON/Markdown report
-      --safelist <list|file>   Extra classes / themes / icons / CSS files
-      --no-js --no-icons --no-themes --no-motion --no-minify
-
-  ${C.bold('Tokens:')}
-    velinstyle tokens build [--input <path>] [--output, -o <file>]
-    velinstyle tokens validate [--input <path>]
-
-  ${C.bold('Docs (0.9.0):')}
-    velinstyle docs generate [--scope all|components|tokens|utilities|cli|rules|a11y|meta] [--out docs/generated]
-    velinstyle meta [--out dist/velin-agent.json] [--llms-out dist/llms.txt] [--base-url URL]
-    velinstyle meta page <file.html> [--write]  Merge curated meta (goals/intent) on --write
-
-  ${C.bold('Search:')}
-    velinstyle search index [--out dist/search-index.json] [--extra-html dir1,dir2]
-
-  ${C.bold('Skills:')}
-    velinstyle skills list [--capability review] [--status beta] [--json]
-    velinstyle skills show <skill-id> [--human]
-    velinstyle skills install <skill-id|pack|bundle:id|project:id> [--target .cursor/skills]
-    velinstyle skills run <skill-id> [--json]
-    velinstyle skills validate
-    velinstyle skills packs|bundles|templates|projects|graphs
-
-  ${C.bold('Workflow:')}
-    velinstyle workflow <graph-id|project:id> [--json]
-
-  ${C.bold('Scan options:')}
-    --fix                           Auto-fix safe issues (writes files)
-    --fix-dry-run                   Show files that would be auto-fixed; no write
-    --fix-lang <code>               Default lang for a11y/html-lang fix (default: de)
-    --severity <level>              Minimum severity: error, warning, info
-    --only <category>               Filter: security, pii, a11y, css, wc, perf
-
-  ${C.bold('Prefix options (velinstyle prefix):')}
-    --write                         Write files (default is dry-run)
-    --bootstrap-display             Map Bootstrap d-* display utilities to Velin names
-    --map <file>                    JSON class map (merged after auto map; see below)
-
-  Prefix also loads ${C.dim('velinstyle-prefix-map.json')} from the migration root (the
-  directory you pass, or the parent of a single file) if that file exists. ${C.dim('--map')}
-  merges on top and overrides duplicate keys.
-
-  ${C.bold('Build options:')}
-    --output, -o <path>             Output file path (default: ./velinstyle-custom.css)
-    --minify                        Minify output
-    --preset lite                   Marketing subset layers (tokens+reset+base+layout+components+utilities)
-
-  ${C.bold('General:')}
-    --help, -h                      Show this help
-`);
+async function help() {
+  const exp = await ensureExperience();
+  console.log(exp.buildHelpFromRegistry(CLI_VERSION));
+}
+
+/** Cached Experience bridge module. */
+let experienceApi = null;
+
+async function ensureExperience() {
+  if (experienceApi) return experienceApi;
+  experienceApi = await import('./experience.js');
+  return experienceApi;
+}
+
+/**
+ * Finish a command through Velin Experience (Contract + Renderer).
+ * Side effects should already be done; this only presents the result.
+ */
+async function emitExperience(commandId, payload = {}) {
+  const exp = await ensureExperience();
+  const meta = exp.getCommand(commandId);
+  const {
+    layout = meta?.layout || 'standard',
+    title = meta?.title || commandId,
+    subtitle = '',
+    status = 'PASS',
+    message = '',
+    project = {},
+    stats = {},
+    items = [],
+    table = null,
+    suggestions = [],
+    diagnostics = [],
+    notifications = [],
+    widgets = null,
+    exitCode,
+  } = payload;
+
+  const noteWidgets = (notifications || []).map((n) => ({
+    id: 'notification',
+    props: typeof n === 'string' ? { tone: 'info', message: n } : n,
+  }));
+
+  const autoWidgets = widgets || [
+    {
+      id: 'hero',
+      props: {
+        slot: 'hero',
+        title,
+        subtitle: subtitle || message || '',
+        eyebrow: 'Velin Experience',
+      },
+    },
+    ...(items.length ? [{ id: 'stats', props: { items } }] : []),
+    ...(table ? [{ id: 'table', props: table }] : []),
+    ...noteWidgets,
+    { id: 'footer', props: { slot: 'footer', text: `velinstyle ${commandId}` } },
+  ];
+
+  await exp.executeExperience({
+    commandId,
+    args,
+    helpers: { getArg, hasFlag },
+    version: CLI_VERSION,
+    layout,
+    run: async () => ({
+      project,
+      result: { status, message: message || subtitle || `${title} · ${status}` },
+      stats,
+      widgets: autoWidgets,
+      suggestions,
+      diagnostics,
+      notifications: (notifications || []).map((n) => (typeof n === 'string' ? { message: n } : n)),
+    }),
+  });
+
+  if (typeof exitCode === 'number') process.exit(exitCode);
 }
 
 // ── Init ─────────────────────────────────────────────────────────────────────
 
-function init() {
+async function init() {
+  const notes = [];
   const configPath = resolve('velinstyle.config.js');
   if (existsSync(configPath)) {
-    console.log('velinstyle.config.js already exists.');
+    notes.push({ tone: 'info', message: 'velinstyle.config.js already exists' });
   } else {
     const config = `// VelinStyle Configuration
 export default {
@@ -276,7 +198,7 @@ export default {
 };
 `;
     writeFileSync(configPath, config);
-    console.log(C.green('Created velinstyle.config.js'));
+    notes.push({ tone: 'ok', message: 'Created velinstyle.config.js' });
   }
 
   const vendorDir = resolve('vendor', 'velinstyle');
@@ -295,9 +217,9 @@ export default {
         if (statSync(src).isFile()) writeFileSync(join(vendorDir, 'themes', name), readFileSync(src));
       }
     }
-    console.log(C.green(`Copied dist assets → ${vendorDir}`));
+    notes.push({ tone: 'ok', message: `Copied dist assets → ${vendorDir}` });
   } else {
-    console.log(C.yellow('Framework dist/ not found — skip vendor copy. Build the framework or copy dist manually into vendor/velinstyle.'));
+    notes.push({ tone: 'warn', message: 'Framework dist/ not found — skip vendor copy' });
   }
 
   const starter = resolve('index.velin-starter.html');
@@ -325,10 +247,19 @@ export default {
 `,
       'utf-8',
     );
-    console.log(C.green('Created index.velin-starter.html'));
-  }
-
-  console.log('Next: velinstyle build  ·  velinstyle serve  ·  velinstyle doctor');
+    notes.push({ tone: 'ok', message: 'Created index.velin-starter.html' });
+  }
+
+  await emitExperience('init', {
+    layout: 'wizard',
+    message: 'Project initialized',
+    notifications: notes,
+    suggestions: [
+      { text: 'velinstyle build' },
+      { text: 'velinstyle serve' },
+      { text: 'velinstyle doctor' },
+    ],
+  });
 }
 
 // ── Build ────────────────────────────────────────────────────────────────────
@@ -401,42 +332,56 @@ async function build() {
       shell: true,
     });
     bundled = true;
-    console.log(C.green(`Built: ${output}`) + ` (layers: ${selectedLayers.join(', ')}${config.theme ? ', theme: ' + config.theme : ''})`);
   } catch {
     writeFileSync(outAbs, css);
-    console.log(C.yellow(`Built (unbundled): ${output}`));
-    console.log(C.yellow('  Install lightningcss-cli in the VelinStyle package (or run build from the framework repo) for minified output.'));
+    bundled = false;
   } finally {
     try { unlinkSync(tmpPath); } catch { /* ignore */ }
   }
 
+  const items = [
+    { label: 'Output', value: output },
+    { label: 'Layers', value: selectedLayers.length },
+    { label: 'Bundle', value: bundled ? 'lightningcss' : 'raw' },
+  ];
+  if (config.theme) items.push({ label: 'Theme', value: config.theme });
   if (preset === 'lite' && existsSync(outAbs)) {
     const liteBytes = statSync(outAbs).size;
     const fullMin = join(PKG_ROOT, 'dist', 'velinstyle.min.css');
+    items.push({ label: 'Size', value: `${(liteBytes / 1024).toFixed(1)} KB` });
     if (existsSync(fullMin)) {
-      const fullBytes = statSync(fullMin).size;
-      const liteKb = (liteBytes / 1024).toFixed(1);
-      const fullKb = (fullBytes / 1024).toFixed(1);
-      console.log(`  Size: lite ${liteKb} KB vs dist/velinstyle.min.css ${fullKb} KB`);
-      if (!bundled || liteBytes >= fullBytes) {
-        console.log(C.yellow(`  Warning: lite output is not smaller than the full min CSS${bundled ? '' : ' (unbundled)'}.`));
-      }
+      items.push({ label: 'Full min', value: `${(statSync(fullMin).size / 1024).toFixed(1)} KB` });
     }
   }
 
+  const notifications = [];
+  if (!bundled) {
+    notifications.push({ tone: 'warn', message: 'Unbundled output — install lightningcss-cli for minify' });
+  }
+
   if (config.scan?.enabled) {
-    console.log(C.dim('\nRunning post-build scan...'));
     const { scan } = await import('./scanner.js');
     scan(resolve('.'), config.scan);
+    notifications.push({ tone: 'info', message: 'Post-build scan ran (config.scan.enabled)' });
   }
+
+  await emitExperience('build', {
+    layout: 'build',
+    status: 'PASS',
+    message: bundled ? `Built ${output}` : `Built (unbundled) ${output}`,
+    subtitle: `layers: ${selectedLayers.join(', ')}`,
+    items,
+    notifications,
+    suggestions: [{ text: 'velinstyle doctor' }, { text: 'velinstyle production . --explain' }],
+  });
 }
 
 // ── Themes ───────────────────────────────────────────────────────────────────
 
-function themes() {
+async function themes() {
   const themesDir = join(PKG_ROOT, 'src', 'themes');
   if (!existsSync(themesDir)) {
-    console.log('No themes directory found.');
+    await emitExperience('themes', { status: 'WARNING', message: 'No themes directory found', exitCode: 1 });
     return;
   }
 
@@ -444,31 +389,44 @@ function themes() {
     .filter(f => f.endsWith('.css'))
     .map(f => f.replace('.css', ''));
 
-  console.log(`\n  ${C.bold('Available VelinStyle Themes:')}\n`);
-  available.forEach(t => console.log(`    - ${t}`));
-  console.log(`\n  Total: ${available.length} themes`);
-  console.log('  Usage: Set theme in velinstyle.config.js or load via:');
-  console.log('    <link rel="stylesheet" href="dist/themes/<name>.min.css">\n');
+  await emitExperience('themes', {
+    message: `${available.length} themes`,
+    table: {
+      columns: ['Theme'],
+      rows: available.map((t) => [t]),
+    },
+    suggestions: [
+      { text: 'Set theme in velinstyle.config.js' },
+      { text: '<link rel="stylesheet" href="dist/themes/<name>.min.css">' },
+    ],
+  });
 }
 
 // ── Add Component ────────────────────────────────────────────────────────────
 
-function add() {
+async function add() {
   const name = args[1];
   if (!name) {
-    console.log('Usage: velinstyle add <component-name>');
-    console.log('Example: velinstyle add button');
+    await emitExperience('add', {
+      status: 'WARNING',
+      message: 'Usage: velinstyle add <component-name>',
+      suggestions: [{ text: 'velinstyle add button' }],
+      exitCode: 1,
+    });
     return;
   }
 
   const filePath = join(PKG_ROOT, 'src', 'components', `${name}.css`);
   if (!existsSync(filePath)) {
-    console.log(C.red(`Component not found: ${name}`));
-    console.log('Available:');
-    readdirSync(join(PKG_ROOT, 'src', 'components'))
+    const available = readdirSync(join(PKG_ROOT, 'src', 'components'))
       .filter(f => f.endsWith('.css'))
-      .map(f => f.replace('.css', ''))
-      .forEach(c => console.log(`  - ${c}`));
+      .map(f => f.replace('.css', ''));
+    await emitExperience('add', {
+      status: 'ERROR',
+      message: `Component not found: ${name}`,
+      table: { columns: ['Available'], rows: available.slice(0, 40).map((c) => [c]) },
+      exitCode: 1,
+    });
     return;
   }
 
@@ -477,7 +435,11 @@ function add() {
   const content = readFileSync(filePath, 'utf-8');
   const outPath = join(outDir, `${name}.css`);
   writeFileSync(outPath, content);
-  console.log(C.green(`Added: ${outPath}`));
+  await emitExperience('add', {
+    message: `Added ${name}`,
+    items: [{ label: 'File', value: outPath }],
+    notifications: [{ tone: 'ok', message: `Wrote ${outPath}` }],
+  });
 }
 
 // ── Icons ────────────────────────────────────────────────────────────────────
@@ -486,47 +448,64 @@ async function icons() {
   const sub = args[1];
 
   if (!sub || sub === 'list') {
-    iconsListCmd();
+    await iconsListCmd();
   } else if (sub === 'add') {
     await iconsAddCmd();
   } else if (sub === 'remove') {
-    iconsRemoveCmd();
+    await iconsRemoveCmd();
   } else if (sub === 'build') {
-    iconsBuildCmd();
+    await iconsBuildCmd();
   } else {
-    console.log(`Unknown icons subcommand: ${sub}`);
-    console.log('Available: list, add, remove, build');
+    await emitExperience('icons', {
+      status: 'WARNING',
+      message: `Unknown icons subcommand: ${sub}`,
+      suggestions: [{ text: 'velinstyle icons list|add|remove|build' }],
+      exitCode: 1,
+    });
   }
 }
 
-function iconsListCmd() {
+async function iconsListCmd() {
   const providers = listProviders();
-  console.log(`\n  ${C.bold('Available Icon Providers:')}\n`);
-  providers.forEach(p => {
-    console.log(`  ${C.cyan(p.key.padEnd(14))} ${p.name} -- ${p.description}`);
-    console.log(`  ${' '.repeat(14)} License: ${p.license} | ${C.dim(p.homepage)}`);
-    if (p.variants.length) console.log(`  ${' '.repeat(14)} Variants: ${p.variants.join(', ')}`);
-    console.log();
-  });
-
   const svgDir = join(PKG_ROOT, 'icons', 'svg');
-  if (existsSync(svgDir)) {
-    const installed = readdirSync(svgDir).filter(f => f.endsWith('.svg'));
-    console.log(`  ${C.bold('Installed icons:')} ${installed.length} in icons/svg/\n`);
-  }
+  const installed = existsSync(svgDir)
+    ? readdirSync(svgDir).filter(f => f.endsWith('.svg')).length
+    : 0;
+  await emitExperience('icons', {
+    subtitle: 'list',
+    message: `${providers.length} providers · ${installed} installed SVGs`,
+    table: {
+      columns: ['Provider', 'Name', 'License'],
+      rows: providers.map((p) => [p.key, p.name, p.license]),
+    },
+    items: [{ label: 'Installed', value: installed }],
+    suggestions: [
+      { text: 'velinstyle icons add lucide --icons menu,search' },
+      { text: 'velinstyle icons build' },
+    ],
+  });
 }
 
 async function iconsAddCmd() {
   const provider = args[2];
   if (!provider) {
-    console.log('Usage: velinstyle icons add <provider> [--icons name1,name2] [--variant outline]');
-    console.log('Providers: ' + Object.keys(PROVIDERS).join(', '));
+    await emitExperience('icons', {
+      status: 'WARNING',
+      subtitle: 'add',
+      message: 'Usage: velinstyle icons add <provider> [--icons name1,name2] [--variant outline]',
+      suggestions: [{ text: `Providers: ${Object.keys(PROVIDERS).join(', ')}` }],
+      exitCode: 1,
+    });
     return;
   }
 
   if (!PROVIDERS[provider]) {
-    console.log(C.red(`Unknown provider: ${provider}`));
-    console.log('Available: ' + Object.keys(PROVIDERS).join(', '));
+    await emitExperience('icons', {
+      status: 'ERROR',
+      message: `Unknown provider: ${provider}`,
+      suggestions: [{ text: `Available: ${Object.keys(PROVIDERS).join(', ')}` }],
+      exitCode: 1,
+    });
     return;
   }
 
@@ -534,8 +513,12 @@ async function iconsAddCmd() {
   const variant = getArg('--variant');
 
   if (!iconsList) {
-    console.log(C.yellow('Please specify icons to add with --icons name1,name2,...'));
-    console.log(`Example: velinstyle icons add ${provider} --icons heart,star,check`);
+    await emitExperience('icons', {
+      status: 'WARNING',
+      message: 'Specify --icons name1,name2,...',
+      suggestions: [{ text: `velinstyle icons add ${provider} --icons heart,star,check` }],
+      exitCode: 1,
+    });
     return;
   }
 
@@ -545,10 +528,11 @@ async function iconsAddCmd() {
 
   let added = 0;
   let failed = 0;
+  const rows = [];
 
   for (const name of names) {
     const url = getProviderUrl(provider, name, variant);
-    if (!url) { failed++; continue; }
+    if (!url) { failed++; rows.push([name, 'FAIL', 'no url']); continue; }
 
     try {
       const res = await fetch(url);
@@ -558,56 +542,83 @@ async function iconsAddCmd() {
 
       const filename = `${provider}-${name}.svg`;
       writeFileSync(join(svgDir, filename), svg);
-      console.log(C.green(`  + ${filename}`));
+      rows.push([name, 'OK', filename]);
       added++;
     } catch (e) {
-      console.log(C.red(`  x ${name}: ${e.message}`));
+      rows.push([name, 'FAIL', e.message]);
       failed++;
     }
   }
 
-  console.log(`\n  Added: ${added}, Failed: ${failed}`);
-  if (added > 0) {
-    console.log(C.dim('  Run "velinstyle icons build" to rebuild the sprite.'));
-  }
+  await emitExperience('icons', {
+    subtitle: 'add',
+    status: failed && !added ? 'ERROR' : failed ? 'WARNING' : 'PASS',
+    message: `Added ${added}, failed ${failed}`,
+    table: { columns: ['Icon', 'Status', 'Detail'], rows },
+    suggestions: added > 0 ? [{ text: 'velinstyle icons build' }] : [],
+    exitCode: failed && !added ? 1 : undefined,
+  });
 }
 
-function iconsRemoveCmd() {
+async function iconsRemoveCmd() {
   const provider = args[2];
   if (!provider) {
-    console.log('Usage: velinstyle icons remove <provider>');
+    await emitExperience('icons', {
+      status: 'WARNING',
+      message: 'Usage: velinstyle icons remove <provider>',
+      exitCode: 1,
+    });
     return;
   }
 
   const svgDir = join(PKG_ROOT, 'icons', 'svg');
-  if (!existsSync(svgDir)) return;
+  if (!existsSync(svgDir)) {
+    await emitExperience('icons', { status: 'WARNING', message: 'No icons/svg directory' });
+    return;
+  }
 
   const files = readdirSync(svgDir).filter(f => f.startsWith(`${provider}-`) && f.endsWith('.svg'));
   if (files.length === 0) {
-    console.log(C.yellow(`No icons found for provider: ${provider}`));
+    await emitExperience('icons', {
+      status: 'WARNING',
+      message: `No icons found for provider: ${provider}`,
+    });
     return;
   }
 
-  files.forEach(f => {
-    unlinkSync(join(svgDir, f));
-    console.log(C.dim(`  - ${f}`));
+  files.forEach(f => unlinkSync(join(svgDir, f)));
+  await emitExperience('icons', {
+    subtitle: 'remove',
+    message: `Removed ${files.length} icons from ${provider}`,
+    table: { columns: ['Removed'], rows: files.map((f) => [f]) },
+    suggestions: [{ text: 'velinstyle icons build' }],
   });
-  console.log(`\n  Removed ${files.length} icons from "${provider}".`);
-  console.log(C.dim('  Run "velinstyle icons build" to rebuild the sprite.'));
 }
 
-function iconsBuildCmd() {
+async function iconsBuildCmd() {
   const buildScript = join(PKG_ROOT, 'icons', 'build-sprite.js');
   if (!existsSync(buildScript)) {
-    console.log(C.red('icons/build-sprite.js not found.'));
+    await emitExperience('icons', {
+      status: 'ERROR',
+      message: 'icons/build-sprite.js not found',
+      exitCode: 1,
+    });
     return;
   }
 
   try {
     execSync(`node "${buildScript}"`, { stdio: 'inherit', cwd: PKG_ROOT });
-    console.log(C.green('\nIcon sprite rebuilt successfully.'));
+    await emitExperience('icons', {
+      subtitle: 'build',
+      message: 'Icon sprite rebuilt',
+      notifications: [{ tone: 'ok', message: 'Sprite rebuild succeeded' }],
+    });
   } catch {
-    console.log(C.red('Failed to rebuild icon sprite.'));
+    await emitExperience('icons', {
+      status: 'ERROR',
+      message: 'Failed to rebuild icon sprite',
+      exitCode: 1,
+    });
   }
 }
 
@@ -618,13 +629,15 @@ async function blueprintCmd() {
   const strict = hasFlag('--strict');
   const { listBlueprints, emitBlueprint, validateAllBlueprints } = await import('./blueprint.js');
   if (sub === '--help' || sub === '-h') {
-    console.log(`Usage: velinstyle blueprint [list|<name>] [--output|-o <file>] [--strict]
-
-  list                 List blueprint ids
-  list --strict        Validate all blueprints against CSS
-  <name>               Emit HTML (stdout or -o file)
-  <name> --strict      Fail if classes missing from CSS
-`);
+    await emitExperience('blueprint', {
+      status: 'PASS',
+      message: 'Usage: velinstyle blueprint [list|<name>] [--output|-o <file>] [--strict]',
+      items: [
+        { label: 'list', value: 'List blueprint ids' },
+        { label: 'list --strict', value: 'Validate all against CSS' },
+        { label: '<name>', value: 'Emit HTML (stdout or -o)' },
+      ],
+    });
     return;
   }
   if (!sub || sub === 'list') {
@@ -632,30 +645,48 @@ async function blueprintCmd() {
       const results = validateAllBlueprints();
       const bad = results.filter((r) => !r.ok);
       if (bad.length) {
-        for (const r of bad) {
-          console.log(C.red(`${r.id}: ${r.missing?.join(', ') || r.error}`));
-        }
-        process.exit(1);
+        await emitExperience('blueprint', {
+          subtitle: 'strict',
+          status: 'ERROR',
+          message: `${bad.length} blueprint(s) failed`,
+          table: {
+            columns: ['Id', 'Detail'],
+            rows: bad.map((r) => [r.id, r.missing?.join(', ') || r.error || '']),
+          },
+          exitCode: 1,
+        });
+        return;
       }
-      console.log(C.green(`All ${results.length} blueprints pass --strict`));
+      await emitExperience('blueprint', {
+        subtitle: 'strict',
+        message: `All ${results.length} blueprints pass --strict`,
+        notifications: [{ tone: 'ok', message: 'Strict validation passed' }],
+      });
       return;
     }
-    console.log(`\n  ${C.bold('Available blueprints:')}\n`);
-    listBlueprints().forEach((b) => console.log(`    - ${b}`));
-    console.log(`\n  ${C.dim('Example: velinstyle blueprint modal -o snippet.html --strict')}\n`);
+    const list = listBlueprints();
+    await emitExperience('blueprint', {
+      message: `${list.length} blueprints`,
+      table: { columns: ['Blueprint'], rows: list.map((b) => [b]) },
+      suggestions: [{ text: 'velinstyle blueprint modal -o snippet.html --strict' }],
+    });
     return;
   }
   const out = getArg('--output', '-o');
   const r = emitBlueprint(sub, { output: out || null, strict });
   if (!r.ok) {
-    console.log(C.red(r.error));
-    process.exit(1);
+    await emitExperience('blueprint', { status: 'ERROR', message: r.error, exitCode: 1 });
+    return;
   }
   if (r.text) {
+    // Preserve raw HTML for piping when no -o
     console.log(r.text);
-  } else {
-    console.log(C.green(`Wrote blueprint to ${r.path}`));
+    return;
   }
+  await emitExperience('blueprint', {
+    message: `Wrote blueprint to ${r.path}`,
+    items: [{ label: 'Path', value: r.path }, { label: 'Id', value: sub }],
+  });
 }
 
 async function serveCmd() {
@@ -664,50 +695,237 @@ async function serveCmd() {
   const { serveStatic } = await import('./serve.js');
   const result = await serveStatic({ dir: resolve(raw), port });
   if (!result.ok) {
-    console.log(C.red(result.error));
-    process.exit(1);
+    await emitExperience('serve', { status: 'ERROR', message: result.error, exitCode: 1 });
+    return;
   }
-  console.log(C.green(`Serving ${result.dir}`));
-  console.log(`  ${result.url}`);
-  console.log(C.dim('Press Ctrl+C to stop'));
+  await emitExperience('serve', {
+    message: `Serving ${result.dir}`,
+    items: [
+      { label: 'URL', value: result.url },
+      { label: 'Dir', value: result.dir },
+      { label: 'Port', value: String(port) },
+    ],
+    notifications: [{ tone: 'info', message: 'Press Ctrl+C to stop' }],
+  });
 }
 
 async function doctorCmd() {
-  const { runDoctor, formatDoctorReport } = await import('./doctor.js');
+  const exp = await ensureExperience();
   const raw = args[1] && !args[1].startsWith('-') ? resolve(args[1]) : process.cwd();
   let cwd = raw;
   try {
     if (existsSync(raw) && statSync(raw).isFile()) cwd = dirname(raw);
   } catch { /* use raw */ }
-  const report = await runDoctor({ cwd, pkgRoot: PKG_ROOT });
-  console.log(formatDoctorReport(report));
-  process.exit(report.ok ? 0 : 1);
+
+  const { runDoctor } = await import('./doctor.js');
+  const session = await exp.executeExperience({
+    commandId: 'doctor',
+    args,
+    helpers: { getArg, hasFlag },
+    version: CLI_VERSION,
+    cwd,
+    layout: 'doctor',
+    run: async (ctx) => {
+      ctx.emitProgress('Environment', 20);
+      const report = await runDoctor({ cwd, pkgRoot: PKG_ROOT });
+      ctx.emitProgress('Validation', 80);
+      const rows = [
+        ...report.okLines.map((line) => ({ label: line.split(':')[0] || 'Check', status: 'PASS' })),
+        ...report.issues.map((i) => ({
+          label: i.message,
+          status: i.severity === 'error' ? 'FAIL' : i.severity === 'warning' ? 'WARNING' : 'INFO',
+        })),
+      ];
+      const status = report.ok ? (report.summary.warnings ? 'WARNING' : 'PASS') : 'ERROR';
+      return {
+        project: { cwd: report.cwd, name: 'Doctor' },
+        result: {
+          status,
+          message: report.ok
+            ? `Pass (${report.summary.passed} checks, ${report.summary.warnings} warning(s))`
+            : `Fail (${report.summary.errors} error(s), ${report.summary.warnings} warning(s))`,
+        },
+        stats: report.summary,
+        diagnostics: report.issues,
+        widgets: [
+          {
+            id: 'hero',
+            props: { title: 'Doctor', subtitle: 'Environment & install health', eyebrow: 'Velin Experience' },
+          },
+          {
+            id: 'health',
+            props: {
+              title: 'Environment',
+              rows: [
+                { label: 'Node', status: 'PASS' },
+                { label: 'Platform', status: process.platform },
+                { label: 'Config', status: existsSync(join(cwd, 'velinstyle.config.js')) ? 'PASS' : 'WARNING' },
+              ],
+            },
+          },
+          {
+            id: 'table',
+            props: {
+              columns: ['Check', 'Status'],
+              rows: rows.slice(0, 24).map((r) => [r.label.slice(0, 40), r.status]),
+            },
+          },
+          {
+            id: 'footer',
+            props: { text: 'Velin Experience · doctor' },
+          },
+        ],
+        suggestions: report.issues.filter((i) => i.fix).slice(0, 5).map((i) => ({ text: i.fix })),
+      };
+    },
+  });
+  process.exit(session.contract.result.status === 'ERROR' ? 1 : 0);
+}
+
+async function dashboardCmd() {
+  const exp = await ensureExperience();
+  const cwd = process.cwd();
+  await exp.executeExperience({
+    commandId: 'dashboard',
+    args,
+    helpers: { getArg, hasFlag },
+    version: CLI_VERSION,
+    cwd,
+    layout: 'dashboard',
+    run: async (ctx) => {
+      ctx.emitProgress('Doctor', 20);
+      const { runDoctor } = await import('./doctor.js');
+      const doc = await runDoctor({ cwd, pkgRoot: PKG_ROOT });
+
+      let reviewScore = '—';
+      try {
+        ctx.emitProgress('Review', 45);
+        const { reviewHtml } = await import('./review.js');
+        const htmlCandidates = ['index.html', 'index.htm'].map((f) => join(cwd, f));
+        const hit = htmlCandidates.find((p) => existsSync(p));
+        if (hit) {
+          const html = readFileSync(hit, 'utf-8');
+          const report = reviewHtml(html, {});
+          reviewScore = report?.scores?.design != null
+            ? String(report.scores.design)
+            : (report?.gate || '—');
+        }
+      } catch { /* optional */ }
+
+      let scanScore = '—';
+      try {
+        ctx.emitProgress('Scan', 70);
+        const { scan } = await import('./scanner.js');
+        const data = scan(cwd, { severity: 'warning', format: 'json', returnData: true });
+        const errors = (data.issues || []).filter((i) => i.severity === 'error').length;
+        const warnings = (data.issues || []).filter((i) => i.severity === 'warning').length;
+        scanScore = errors ? `FAIL (${errors})` : warnings ? `WARN (${warnings})` : 'PASS';
+      } catch { /* optional */ }
+
+      let productionHint = '—';
+      try {
+        const prodDir = join(cwd, 'dist', 'velin-production');
+        productionHint = existsSync(prodDir) ? 'built' : 'not built';
+      } catch { /* optional */ }
+
+      return {
+        project: { name: cwd.split(/[/\\]/).pop() || 'Project', cwd },
+        result: { status: doc.ok ? 'PASS' : 'WARNING', message: 'Project dashboard' },
+        widgets: [
+          { id: 'hero', props: { slot: 'hero', title: 'Project Dashboard', subtitle: cwd, eyebrow: 'Velin Experience' } },
+          {
+            id: 'score',
+            props: {
+              slot: 'cards',
+              title: 'Health',
+              scores: [
+                { label: 'Doctor', value: doc.ok ? 'PASS' : 'FAIL' },
+                { label: 'Production', value: productionHint },
+                { label: 'Review', value: reviewScore },
+                { label: 'Scan', value: scanScore },
+                { label: 'Accessibility', value: 'AAA' },
+                { label: 'CLI', value: CLI_VERSION },
+              ],
+            },
+          },
+          {
+            id: 'notification',
+            props: { tone: 'info', message: 'Aggregated from doctor · review · scan · production folder' },
+          },
+          { id: 'footer', props: { slot: 'footer', text: 'velinstyle dashboard' } },
+        ],
+        suggestions: [
+          { text: 'velinstyle production . --explain' },
+          { text: 'velinstyle review index.html' },
+          { text: 'velinstyle check .' },
+        ],
+        notifications: [
+          { tone: 'ok', message: 'Velin Experience dashboard aggregates local contracts only (no cloud telemetry).' },
+        ],
+      };
+    },
+  });
+}
+
+async function replayCmd() {
+  const exp = await ensureExperience();
+  const file = args[1];
+  if (!file || file.startsWith('-')) {
+    await emitExperience('replay', {
+      status: 'WARNING',
+      message: 'Usage: velinstyle replay <record.json> [--output standard|json|markdown]',
+      exitCode: 1,
+    });
+    return;
+  }
+  const record = exp.loadRecord(file);
+  const overrides = exp.parseExperienceFlags(args, { getArg, hasFlag });
+  const config = { ...(record.config || {}), ...overrides };
+  exp.printContract(record.contract, config);
 }
 
 async function createCmd() {
   const kind = args[1];
   if (!kind || kind === '--help' || kind === '-h') {
-    console.log(`Usage: velinstyle create <landing|dashboard|docs|auth> [dir] [--theme earth] [--no-copy]`);
-    process.exit(kind ? 0 : 1);
+    await emitExperience('create', {
+      status: kind ? 'PASS' : 'WARNING',
+      message: 'Usage: velinstyle create <landing|dashboard|docs|auth> [dir] [--theme earth] [--no-copy]',
+      exitCode: kind ? 0 : 1,
+    });
+    return;
   }
   const { CREATE_KINDS, createProject } = await import('./create.js');
   if (!CREATE_KINDS.includes(kind)) {
-    console.log(C.red(`Unknown kind "${kind}". Use: ${CREATE_KINDS.join('|')}`));
-    process.exit(1);
+    await emitExperience('create', {
+      status: 'ERROR',
+      message: `Unknown kind "${kind}"`,
+      suggestions: [{ text: `Use: ${CREATE_KINDS.join('|')}` }],
+      exitCode: 1,
+    });
+    return;
   }
   const dir = args[2] && !args[2].startsWith('-') ? args[2] : kind;
   const theme = getArg('--theme') || undefined;
   const copyAssets = !hasFlag('--no-copy');
   const r = createProject({ kind, dir: resolve(dir), pkgRoot: PKG_ROOT, theme, copyAssets });
   if (!r.ok) {
-    console.log(C.red(r.error));
-    process.exit(1);
+    await emitExperience('create', { status: 'ERROR', message: r.error, exitCode: 1 });
+    return;
   }
-  console.log(C.green(`Created ${kind} at ${r.dir}`));
-  console.log(C.dim(`  index: ${r.indexPath}`));
-  if (r.vendorRel) console.log(C.dim(`  vendor: ${r.vendorRel}/`));
-  if (r.vendorCopied?.length) console.log(C.dim(`  copied: ${r.vendorCopied.join(', ')}`));
-  console.log(C.dim(`  Next: velinstyle serve ${dir} · velinstyle check ${dir}`));
+  await emitExperience('create', {
+    layout: 'wizard',
+    message: `Created ${kind}`,
+    items: [
+      { label: 'Dir', value: r.dir },
+      { label: 'Index', value: r.indexPath },
+      ...(r.vendorRel ? [{ label: 'Vendor', value: r.vendorRel }] : []),
+    ],
+    suggestions: [
+      { text: `velinstyle serve ${dir}` },
+      { text: `velinstyle check ${dir}` },
+    ],
+    notifications: [{ tone: 'ok', message: `Created ${kind} at ${r.dir}` }],
+  });
 }
 
 async function tokensBuildCmd() {
@@ -716,12 +934,20 @@ async function tokensBuildCmd() {
   const { buildTokensFromJson } = await import('./tokens-build.js');
   const css = buildTokensFromJson(inputPath);
   if (!css) {
-    console.log(C.red(`Could not read or parse: ${inputPath}`));
+    await emitExperience('tokens', {
+      status: 'ERROR',
+      message: `Could not read or parse: ${inputPath}`,
+      exitCode: 1,
+    });
     return;
   }
   if (outPath) {
     writeFileSync(resolve(outPath), css, 'utf-8');
-    console.log(C.green(`Wrote ${resolve(outPath)}`));
+    await emitExperience('tokens', {
+      subtitle: 'build',
+      message: `Wrote ${resolve(outPath)}`,
+      items: [{ label: 'Input', value: inputPath }, { label: 'Output', value: resolve(outPath) }],
+    });
   } else {
     console.log(css);
   }
@@ -732,12 +958,20 @@ async function tokensValidateCmd() {
   const { validateTokensJson } = await import('./tokens-validate.js');
   const result = validateTokensJson(resolve(input));
   if (result.ok) {
-    console.log(C.green(`Valid: ${resolve(input)}`));
-    process.exit(0);
+    await emitExperience('tokens', {
+      subtitle: 'validate',
+      message: `Valid: ${resolve(input)}`,
+      notifications: [{ tone: 'ok', message: 'Tokens JSON valid' }],
+    });
+    return;
   }
-  console.log(C.red(`Invalid: ${resolve(input)}`));
-  result.errors.forEach((e) => console.log(`  - ${e}`));
-  process.exit(1);
+  await emitExperience('tokens', {
+    subtitle: 'validate',
+    status: 'ERROR',
+    message: `Invalid: ${resolve(input)}`,
+    table: { columns: ['Error'], rows: (result.errors || []).map((e) => [e]) },
+    exitCode: 1,
+  });
 }
 
 async function tokensCmd() {
@@ -747,7 +981,11 @@ async function tokensCmd() {
   } else if (sub === 'validate') {
     await tokensValidateCmd();
   } else {
-    console.log('Usage: velinstyle tokens build|validate [--input tokens.json] [--output, -o <file>]');
+    await emitExperience('tokens', {
+      status: 'WARNING',
+      message: 'Usage: velinstyle tokens build|validate [--input tokens.json] [--output, -o <file>]',
+      exitCode: 1,
+    });
   }
 }
 
@@ -768,13 +1006,21 @@ async function perfCmd() {
       return;
     }
     if (result.changes.length === 0) {
-      console.log(C.green('No safe performance fixes to apply.'));
+      await emitExperience('perf', {
+        subtitle: 'fix',
+        message: 'No safe performance fixes to apply.',
+        notifications: [{ tone: 'ok', message: 'Nothing to change' }],
+      });
       return;
     }
-    for (const c of result.changes) {
-      console.log(`${dryRun ? '[dry-run] ' : ''}${c.file}`);
-      c.changes.forEach((ch) => console.log(C.dim(`  - ${ch}`)));
-    }
+    await emitExperience('perf', {
+      subtitle: 'fix',
+      message: `${dryRun ? '[dry-run] ' : ''}${result.changes.length} file(s)`,
+      table: {
+        columns: ['File', 'Changes'],
+        rows: result.changes.map((c) => [c.file, (c.changes || []).join('; ').slice(0, 60)]),
+      },
+    });
     return;
   }
 
@@ -783,7 +1029,49 @@ async function perfCmd() {
     console.log(JSON.stringify({ files, issues }, null, 2));
     return;
   }
-  console.log(formatTextReport(issues, files));
+
+  const exp = await ensureExperience();
+  const errors = issues.filter((x) => x.severity === 'error').length;
+  const warnings = issues.filter((x) => x.severity === 'warning').length;
+  await exp.executeExperience({
+    commandId: 'perf',
+    args,
+    helpers: { getArg, hasFlag },
+    version: CLI_VERSION,
+    layout: 'audit',
+    run: async () => ({
+      project: { cwd: targetPath, name: 'Perf' },
+      result: {
+        status: errors ? 'ERROR' : warnings ? 'WARNING' : 'PASS',
+        message: `${issues.length} finding(s) across ${files.length} file(s)`,
+      },
+      diagnostics: issues,
+      widgets: [
+        { id: 'hero', props: { slot: 'hero', title: 'Perf audit', subtitle: formatTextReport(issues, files).split('\n')[0] || 'Performance', eyebrow: 'Velin Experience' } },
+        {
+          id: 'stats',
+          props: {
+            slot: 'counts',
+            items: [
+              { label: 'Files', value: files.length },
+              { label: 'Errors', value: errors },
+              { label: 'Warnings', value: warnings },
+            ],
+          },
+        },
+        {
+          id: 'table',
+          props: {
+            slot: 'findings',
+            columns: ['Sev', 'Id', 'Message'],
+            rows: issues.slice(0, 20).map((i) => [i.severity, i.id || '—', String(i.message || '').slice(0, 40)]),
+          },
+        },
+        { id: 'footer', props: { slot: 'footer', text: 'velinstyle perf audit' } },
+      ],
+      suggestions: issues.filter((i) => i.fix).slice(0, 5).map((i) => ({ text: i.fix })),
+    }),
+  });
   process.exit(issues.some((x) => x.severity === 'error') ? 1 : 0);
 }
 
@@ -795,8 +1083,8 @@ async function prefixCmd() {
     const st = statSync(targetPath);
     if (st.isFile()) migrationRoot = dirname(targetPath);
   } catch {
-    console.log(C.red(`Not found: ${targetPath}`));
-    process.exit(1);
+    await emitExperience('prefix', { status: 'ERROR', message: `Not found: ${targetPath}`, exitCode: 1 });
+    return;
   }
 
   const mapArg = getArg('--map');
@@ -804,17 +1092,41 @@ async function prefixCmd() {
   const bootstrapDisplay = hasFlag('--bootstrap-display');
 
   try {
-    const { buildExplicitPrefixMap, prefixCommandMain } = await import('./prefix-classes.js');
+    const { buildExplicitPrefixMap, runPrefixCommand } = await import('./prefix-classes.js');
     const explicitMap = buildExplicitPrefixMap(migrationRoot, mapArg ? resolve(mapArg) : null);
-    prefixCommandMain(targetPath, {
+    const { filesTouched, replacements, paths } = runPrefixCommand(targetPath, {
       write,
       bootstrapAliases: bootstrapDisplay,
       pkgRoot: PKG_ROOT,
       explicitMap,
     });
+    if (filesTouched === 0) {
+      await emitExperience('prefix', {
+        message: 'No class attributes needed prefixing (or no matching files)',
+        notifications: explicitMap?.size
+          ? [{ tone: 'info', message: `Explicit map: ${explicitMap.size} entries` }]
+          : [],
+      });
+      return;
+    }
+    await emitExperience('prefix', {
+      message: `${write ? 'Updated' : 'Would update'} ${filesTouched} file(s), ${replacements} class token(s)`,
+      table: {
+        columns: ['File'],
+        rows: paths.slice(0, 40).map((p) => [p]),
+      },
+      suggestions: write ? [] : [{ text: 'Re-run with --write to apply changes' }],
+      notifications: [
+        ...(explicitMap?.size ? [{ tone: 'info', message: `Explicit map: ${explicitMap.size} entries` }] : []),
+        ...(paths.length > 40 ? [{ tone: 'info', message: `… and ${paths.length - 40} more files` }] : []),
+      ],
+    });
   } catch (e) {
-    console.log(C.red(/** @type {Error} */ (e).message));
-    process.exit(1);
+    await emitExperience('prefix', {
+      status: 'ERROR',
+      message: /** @type {Error} */ (e).message,
+      exitCode: 1,
+    });
   }
 }
 
@@ -826,27 +1138,35 @@ async function atelierCmd() {
   } = await import('./atelier.js');
 
   if (!sub || sub === '--help' || sub === '-h') {
-    console.log(`Usage: velinstyle atelier list
-       velinstyle atelier <num|id> [-o dir] [--format html|blade|vue|react]
-         [--from <library-root>] [--base-url <url>] [--rewrite-vendor <path>]
-
-  Pull a curated Atelier Library showcase (e.g. 36 → 36-calendar).
-  Limitation: --format blade|vue|react writes integration shells only (not native rewrites).
-  Velin Studio Builder and native framework blocks are planned — not shipped.`);
+    await emitExperience('atelier', {
+      message: 'Usage: velinstyle atelier list | <num|id> [-o dir] [--format html|blade|vue|react]',
+      suggestions: [
+        { text: 'velinstyle atelier list' },
+        { text: 'velinstyle atelier 36 -o ./velin-atelier/36-calendar' },
+      ],
+      notifications: [{
+        tone: 'info',
+        message: 'Limitation: blade|vue|react = wrappers; Studio/native rewrites planned.',
+      }],
+    });
     return;
   }
 
   if (sub === 'list') {
     const r = listAtelierEntries();
     if (!r.ok) {
-      console.log(C.red(r.error));
-      process.exit(1);
-    }
-    console.log(`\n  ${C.bold('Atelier Library (curated)')} · ${r.items.length} templates\n`);
-    for (const it of r.items) {
-      console.log(`    ${C.cyan(it.num.padStart(3))}  ${it.id}  ${C.dim(it.title || '')}`);
+      await emitExperience('atelier', { status: 'ERROR', message: r.error, exitCode: 1 });
+      return;
     }
-    console.log(`\n  ${C.dim('Example: velinstyle atelier 36 -o ./velin-atelier/36-calendar')}\n`);
+    await emitExperience('atelier', {
+      subtitle: 'list',
+      message: `Atelier Library · ${r.items.length} templates`,
+      table: {
+        columns: ['#', 'Id', 'Title'],
+        rows: r.items.map((it) => [it.num.padStart(3), it.id, it.title || '']),
+      },
+      suggestions: [{ text: 'velinstyle atelier 36 -o ./velin-atelier/36-calendar' }],
+    });
     return;
   }
 
@@ -864,24 +1184,40 @@ async function atelierCmd() {
     rewriteVendor: rewriteVendor || undefined,
   });
   if (!r.ok) {
-    console.log(C.red(r.error));
-    process.exit(1);
+    await emitExperience('atelier', { status: 'ERROR', message: r.error, exitCode: 1 });
+    return;
   }
-  console.log(C.green(`Pulled ${r.entry.id} → ${r.path} (format: ${r.format})`));
-  console.log(C.dim(`  source: ${r.source}`));
-  console.log(C.dim('  Limitation: blade/vue/react = wrappers; Studio/native rewrites planned.'));
+  await emitExperience('atelier', {
+    message: `Pulled ${r.entry.id} → ${r.path}`,
+    items: [
+      { label: 'Format', value: r.format },
+      { label: 'Source', value: r.source },
+      { label: 'Path', value: r.path },
+    ],
+    notifications: [{
+      tone: 'info',
+      message: 'Limitation: blade/vue/react = wrappers; Studio/native rewrites planned.',
+    }],
+  });
 }
 
 async function scaffoldCmd() {
   const sub = args[1];
   const { scaffoldFromPrompt, listIntents } = await import('./scaffold.js');
   if (sub === 'list-intents') {
-    console.log(`\n  ${C.bold('Scaffold intents:')}\n`);
-    for (const i of listIntents()) {
-      console.log(`    ${C.cyan(i.id)} — ${i.blueprints.join(' + ')}`);
-      console.log(C.dim(`      keywords: ${i.keywords.slice(0, 5).join(', ')}…`));
-    }
-    console.log('');
+    const intents = listIntents();
+    await emitExperience('scaffold', {
+      subtitle: 'list-intents',
+      message: `${intents.length} intents`,
+      table: {
+        columns: ['Id', 'Blueprints', 'Keywords'],
+        rows: intents.map((i) => [
+          i.id,
+          i.blueprints.join(' + '),
+          i.keywords.slice(0, 5).join(', '),
+        ]),
+      },
+    });
     return;
   }
 
@@ -897,8 +1233,8 @@ async function scaffoldCmd() {
       baseUrl: baseUrl || undefined,
     });
     if (!r.ok) {
-      console.log(C.red(r.error));
-      process.exit(1);
+      await emitExperience('scaffold', { status: 'ERROR', message: r.error, exitCode: 1 });
+      return;
     }
     if (hasFlag('--json')) {
       console.log(JSON.stringify({
@@ -908,11 +1244,20 @@ async function scaffoldCmd() {
         entries: r.entries,
         planSections: r.planSections,
       }, null, 2));
-    } else {
-      console.log(C.green(`Wrote Atelier compose (beta) → ${r.path}`));
-      console.log(C.dim(`  ids: ${r.entries.map((e) => e.id).join(', ')}`));
-      console.log(C.dim('  Beta: Library compose — not Velin Studio. Wrappers ≠ native rewrites.'));
+      return;
     }
+    await emitExperience('scaffold', {
+      subtitle: 'atelier compose',
+      message: `Wrote Atelier compose (beta) → ${r.path}`,
+      items: [
+        { label: 'Ids', value: r.entries.map((e) => e.id).join(', ') },
+        { label: 'Mode', value: r.mode || 'compose' },
+      ],
+      notifications: [{
+        tone: 'info',
+        message: 'Beta: Library compose — not Velin Studio. Wrappers ≠ native rewrites.',
+      }],
+    });
     return;
   }
 
@@ -926,14 +1271,21 @@ async function scaffoldCmd() {
   }
   const prompt = promptParts.join(' ').trim() || sub;
   if (!prompt || prompt === 'list-intents') {
-    console.log('Usage: velinstyle scaffold "<description>" [-o file.html] [--json]');
-    console.log('       velinstyle scaffold --atelier 04,07 [-o page.html] [--from <library>]');
+    await emitExperience('scaffold', {
+      status: 'WARNING',
+      message: 'Usage: velinstyle scaffold "<description>" [-o file.html] [--json]',
+      suggestions: [
+        { text: 'velinstyle scaffold --atelier 04,07 -o page.html' },
+        { text: 'velinstyle scaffold list-intents' },
+      ],
+      exitCode: 1,
+    });
     return;
   }
   const r = scaffoldFromPrompt(prompt);
   if (!r.ok) {
-    console.log(C.red(r.error));
-    process.exit(1);
+    await emitExperience('scaffold', { status: 'ERROR', message: r.error, exitCode: 1 });
+    return;
   }
   const out = getArg('--output', '-o');
   const asJson = hasFlag('--json');
@@ -941,13 +1293,21 @@ async function scaffoldCmd() {
     console.log(JSON.stringify(r, null, 2));
   } else if (out) {
     writeFileSync(resolve(out), r.html, 'utf-8');
-    console.log(C.green(`Wrote ${resolve(out)} (intent: ${r.intent}, ${r.confidence}${r.mode ? `, mode: ${r.mode}` : ''})`));
-    if (r.review?.gate) {
-      console.log(C.dim(`  review gate: ${r.review.gate} (promptScore ${r.review.promptScore})`));
-    }
-    if (r.responsiveHints?.length) {
-      console.log(C.yellow(`  ${r.responsiveHints.length} layout hint(s) — run: velinstyle layout suggest ${out}`));
-    }
+    await emitExperience('scaffold', {
+      message: `Wrote ${resolve(out)}`,
+      items: [
+        { label: 'Intent', value: r.intent },
+        { label: 'Confidence', value: String(r.confidence) },
+        ...(r.mode ? [{ label: 'Mode', value: r.mode }] : []),
+        ...(r.review?.gate ? [{ label: 'Review gate', value: `${r.review.gate} (${r.review.promptScore})` }] : []),
+      ],
+      suggestions: r.responsiveHints?.length
+        ? [{ text: `velinstyle layout suggest ${out}` }]
+        : [],
+      notifications: r.responsiveHints?.length
+        ? [{ tone: 'warning', message: `${r.responsiveHints.length} layout hint(s)` }]
+        : [],
+    });
   } else {
     console.log(r.html);
   }
@@ -959,13 +1319,17 @@ async function planCmd() {
     const { planFromAtelierList } = await import('./atelier.js');
     const payload = planFromAtelierList(atelierList, { prompt: args.slice(1).filter((a) => !a.startsWith('-')).join(' ') });
     if (!payload.ok) {
-      console.log(C.red(payload.error));
-      process.exit(1);
+      await emitExperience('plan', { status: 'ERROR', message: payload.error, exitCode: 1 });
+      return;
     }
     const out = getArg('--output', '-o');
     if (out) {
       writeFileSync(resolve(out), JSON.stringify(payload, null, 2), 'utf-8');
-      console.log(C.green(`Wrote Atelier plan (beta) ${resolve(out)} (${payload.plan.sections.length} sections)`));
+      await emitExperience('plan', {
+        subtitle: 'atelier',
+        message: `Wrote Atelier plan (beta) ${resolve(out)}`,
+        items: [{ label: 'Sections', value: String(payload.plan.sections.length) }],
+      });
       return;
     }
     console.log(JSON.stringify(payload, null, 2));
@@ -982,8 +1346,12 @@ async function planCmd() {
   }
   const prompt = promptParts.join(' ').trim();
   if (!prompt) {
-    console.log('Usage: velinstyle plan "<description>" [--json] [-o plan.json]');
-    console.log('       velinstyle plan --atelier 04,07 [-o plan.json]');
+    await emitExperience('plan', {
+      status: 'WARNING',
+      message: 'Usage: velinstyle plan "<description>" [--json] [-o plan.json]',
+      suggestions: [{ text: 'velinstyle plan --atelier 04,07 [-o plan.json]' }],
+      exitCode: 1,
+    });
     return;
   }
   const { analyzePrompt, buildPlan } = await import('./prompt-engine.js');
@@ -993,7 +1361,13 @@ async function planCmd() {
   const out = getArg('--output', '-o');
   if (out) {
     writeFileSync(resolve(out), JSON.stringify(payload, null, 2), 'utf-8');
-    console.log(C.green(`Wrote plan ${resolve(out)} (page: ${plan.page?.id}, sections: ${plan.sections.length})`));
+    await emitExperience('plan', {
+      message: `Wrote plan ${resolve(out)}`,
+      items: [
+        { label: 'Page', value: plan.page?.id || '—' },
+        { label: 'Sections', value: String(plan.sections.length) },
+      ],
+    });
     return;
   }
   console.log(JSON.stringify(payload, null, 2));
@@ -1022,24 +1396,51 @@ async function reviewCmd() {
   const report = reviewHtml(html, { plan, prompt, profile: profile || undefined });
   if (hasFlag('--json')) {
     console.log(JSON.stringify(report, null, 2));
-  } else {
-    console.log(`\n  ${C.bold('Review gate:')} ${report.gate}  ${C.dim(`profile ${report.profile} · promptScore ${report.promptScore}`)}`);
-    console.log(C.dim(`  design ${report.scores.design} · a11y ${report.scores.accessibility} · seo ${report.scores.seo} · perf ${report.scores.performance} · conversion ${report.scores.conversion} · opt ${report.scores.optimization ?? '—'}`));
-    if (report.optimization) {
-      console.log(C.dim(`  optimization · unused themes ${report.optimization.unusedThemes} · WC tags ${report.optimization.componentTags} · class tokens ${report.optimization.classTokens}`));
-    }
-    if (report.issues.length) {
-      console.log(`\n  ${C.bold('Issues:')}`);
-      for (const issue of report.issues) {
-        const color = issue.severity === 'error' ? C.red : C.yellow;
-        console.log(color(`    [${issue.severity}] ${issue.code}: ${issue.message}`));
-        console.log(C.dim(`      fix: ${issue.fix}`));
-      }
-    } else {
-      console.log(C.green('\n  No issues.'));
-    }
-    console.log('');
+    process.exit(report.gate === 'fail' ? 1 : 0);
+    return;
   }
+  const exp = await ensureExperience();
+  await exp.executeExperience({
+    commandId: 'review',
+    args,
+    helpers: { getArg, hasFlag },
+    version: CLI_VERSION,
+    layout: 'review',
+    run: async () => ({
+      project: { file: full },
+      result: {
+        status: report.gate === 'fail' ? 'ERROR' : report.issues.length ? 'WARNING' : 'PASS',
+        message: `gate ${report.gate} · profile ${report.profile}`,
+      },
+      stats: report.scores,
+      diagnostics: report.issues,
+      widgets: [
+        { id: 'hero', props: { title: 'Review', subtitle: full, eyebrow: 'Velin Experience' } },
+        {
+          id: 'score',
+          props: {
+            title: 'Overall',
+            scores: [
+              { label: 'Design', value: report.scores.design },
+              { label: 'Accessibility', value: report.scores.accessibility },
+              { label: 'SEO', value: report.scores.seo },
+              { label: 'Performance', value: report.scores.performance },
+              { label: 'Conversion', value: report.scores.conversion },
+            ],
+          },
+        },
+        {
+          id: 'table',
+          props: {
+            columns: ['Severity', 'Code', 'Message'],
+            rows: (report.issues || []).slice(0, 20).map((i) => [i.severity, i.code, i.message.slice(0, 48)]),
+          },
+        },
+        { id: 'footer', props: { text: 'velinstyle review' } },
+      ],
+      suggestions: (report.issues || []).filter((i) => i.fix).slice(0, 5).map((i) => ({ text: i.fix })),
+    }),
+  });
   process.exit(report.gate === 'fail' ? 1 : 0);
 }
 
@@ -1056,21 +1457,29 @@ async function layoutCmd() {
   if (sub === 'fix') {
     const result = fixPath(targetPath, { write, dryRun });
     if (!result.ok) {
-      console.log(C.red(result.error || 'Fix failed'));
-      process.exit(1);
+      await emitExperience('layout', { status: 'ERROR', message: result.error || 'Fix failed', exitCode: 1 });
+      return;
     }
     if (asJson) {
       console.log(JSON.stringify(result, null, 2));
       return;
     }
     if (result.changes.length === 0) {
-      console.log(C.green('No safe fixes to apply.'));
+      await emitExperience('layout', {
+        subtitle: 'fix',
+        message: 'No safe fixes to apply.',
+        notifications: [{ tone: 'ok', message: 'Nothing to change' }],
+      });
       return;
     }
-    for (const c of result.changes) {
-      console.log(`${dryRun ? '[dry-run] ' : ''}${c.file}`);
-      c.changes.forEach((ch) => console.log(C.dim(`  - ${ch}`)));
-    }
+    await emitExperience('layout', {
+      subtitle: 'fix',
+      message: `${dryRun ? '[dry-run] ' : ''}${result.changes.length} file(s)`,
+      table: {
+        columns: ['File', 'Changes'],
+        rows: result.changes.map((c) => [c.file, (c.changes || []).join('; ').slice(0, 60)]),
+      },
+    });
     return;
   }
 
@@ -1082,17 +1491,48 @@ async function layoutCmd() {
     return;
   }
 
-  console.log(formatTextReport(outIssues, files));
-  if (sub === 'suggest' && issues.length) {
-    console.log(C.bold('Suggested fixes:'));
-    for (const i of outIssues) {
-      console.log(`  [${i.id}] ${i.fix}`);
-      if (i.responsive?.mobile) {
-        console.log(C.dim(`    mobile: ${i.responsive.mobile}`));
-      }
-    }
-    console.log('');
-  }
+  const exp = await ensureExperience();
+  const errors = issues.filter((x) => x.severity === 'error').length;
+  const warnings = issues.filter((x) => x.severity === 'warning').length;
+  await exp.executeExperience({
+    commandId: 'layout',
+    args,
+    helpers: { getArg, hasFlag },
+    version: CLI_VERSION,
+    layout: 'audit',
+    run: async () => ({
+      project: { cwd: targetPath, name: 'Layout' },
+      result: {
+        status: errors ? 'ERROR' : warnings ? 'WARNING' : 'PASS',
+        message: `${outIssues.length} finding(s) · ${sub}`,
+      },
+      diagnostics: outIssues,
+      widgets: [
+        { id: 'hero', props: { slot: 'hero', title: 'Layout audit', subtitle: `Subcommand: ${sub}`, eyebrow: 'Velin Experience' } },
+        {
+          id: 'stats',
+          props: {
+            slot: 'counts',
+            items: [
+              { label: 'Files', value: files.length },
+              { label: 'Findings', value: outIssues.length },
+              { label: 'Errors', value: errors },
+            ],
+          },
+        },
+        {
+          id: 'table',
+          props: {
+            slot: 'findings',
+            columns: ['Sev', 'Id', 'Message'],
+            rows: outIssues.slice(0, 20).map((i) => [i.severity, i.id || '—', String(i.message || i.fix || '').slice(0, 40)]),
+          },
+        },
+        { id: 'footer', props: { slot: 'footer', text: `velinstyle layout ${sub}` } },
+      ],
+      suggestions: outIssues.filter((i) => i.fix).slice(0, 5).map((i) => ({ text: i.fix })),
+    }),
+  });
   process.exit(issues.some((x) => x.severity === 'error') ? 1 : 0);
 }
 
@@ -1104,18 +1544,71 @@ async function docsCmd() {
     const { generateDocs } = await import('./docs-generate.js');
     const result = await generateDocs({ scope, outDir: resolve(out), searchIndex: true });
     if (!result.ok) {
-      console.log(C.red(result.error));
-      process.exit(1);
+      await emitExperience('docs', { status: 'ERROR', message: result.error, exitCode: 1 });
+      return;
     }
-    console.log(C.green(`Generated ${result.written} file(s) → ${resolve(out)}`));
+    await emitExperience('docs', {
+      subtitle: 'generate',
+      message: `Generated ${result.written} file(s)`,
+      items: [
+        { label: 'Scope', value: scope },
+        { label: 'Out', value: resolve(out) },
+      ],
+    });
     return;
   }
-  console.log('Usage: velinstyle docs generate [--scope all|components|tokens|utilities|cli|rules|a11y|meta] [--out <dir>]');
+  await emitExperience('docs', {
+    status: 'WARNING',
+    message: 'Usage: velinstyle docs generate [--scope all|components|tokens|…] [--out <dir>]',
+    exitCode: 1,
+  });
 }
 
 async function metaCmd() {
-  const { metaMain } = await import('./meta.js');
-  await metaMain(process.argv.slice(2));
+  if (args[1] === '--help' || args[1] === '-h') {
+    await emitExperience('meta', {
+      message: 'Usage: velinstyle meta [--out file] [--llms-out file] [--base-url url] [--no-llms]',
+      suggestions: [
+        { text: 'velinstyle meta' },
+        { text: 'velinstyle meta page index.html [--write]' },
+      ],
+    });
+    return;
+  }
+  const { metaPage, buildMeta } = await import('./meta.js');
+  const pageIdx = args.indexOf('page');
+  if (pageIdx !== -1 && args[pageIdx + 1]) {
+    const write = hasFlag('--write');
+    const result = metaPage(args[pageIdx + 1], { write });
+    if (!result.ok) {
+      await emitExperience('meta', { status: 'ERROR', message: result.error, exitCode: 1 });
+      return;
+    }
+    if (write) {
+      await emitExperience('meta', {
+        subtitle: 'page',
+        message: `Updated velin-meta in ${args[pageIdx + 1]}`,
+      });
+    } else {
+      console.log(result.script);
+    }
+    return;
+  }
+
+  const result = await buildMeta({
+    outFile: getArg('--out') ? resolve(getArg('--out')) : undefined,
+    llmsFile: getArg('--llms-out') ? resolve(getArg('--llms-out')) : undefined,
+    baseUrl: getArg('--base-url') || undefined,
+    llms: !hasFlag('--no-llms'),
+  });
+
+  await emitExperience('meta', {
+    message: `Wrote ${result.count} file(s)`,
+    table: {
+      columns: ['File'],
+      rows: (result.written || []).map((p) => [p]),
+    },
+  });
 }
 
 async function searchCmd() {
@@ -1128,42 +1621,280 @@ async function searchCmd() {
       outFile: resolve(out),
       extraHtmlDirs: extra ? extra.split(',').map((p) => resolve(p.trim())) : [],
     });
-    console.log(C.green(`Search index: ${result.count} entries → ${result.outFile}`));
+    await emitExperience('search', {
+      subtitle: 'index',
+      message: `Search index: ${result.count} entries`,
+      items: [{ label: 'Out', value: result.outFile }],
+    });
     return;
   }
-  console.log('Usage: velinstyle search index [--out <file>] [--extra-html dir1,dir2]');
+  await emitExperience('search', {
+    status: 'WARNING',
+    message: 'Usage: velinstyle search index [--out <file>] [--extra-html dir1,dir2]',
+    exitCode: 1,
+  });
 }
 
 async function skillsCmd() {
-  const { skillsCommand } = await import('./skills.js');
-  await skillsCommand(args.slice(1));
+  const sub = args[1];
+  const {
+    skillsList,
+    skillsInstall,
+    skillsRun,
+    skillsValidate,
+    skillsDoctor,
+    skillsIndex,
+    loadSkillRegistry,
+  } = await import('./skills.js');
+
+  if (!sub || sub === '--help' || sub === '-h') {
+    await emitExperience('skills', {
+      message: 'Usage: velinstyle skills <list|show|install|run|validate|doctor|packs|…>',
+      suggestions: [
+        { text: 'velinstyle skills list' },
+        { text: 'velinstyle skills show scaffold.landing --human' },
+      ],
+    });
+    return;
+  }
+
+  if (sub === 'list') {
+    const items = skillsList(args.slice(2), { silent: true });
+    if (hasFlag('--json')) {
+      console.log(JSON.stringify(items, null, 2));
+      return;
+    }
+    await emitExperience('skills', {
+      subtitle: 'list',
+      message: `${items.length} skill(s)`,
+      table: {
+        columns: ['Id', 'Category', 'Priority', 'Status'],
+        rows: items.slice(0, 40).map((item) => [
+          item.id,
+          item.category || '',
+          item.priority || '',
+          item.status || '',
+        ]),
+      },
+    });
+    return;
+  }
+
+  if (sub === 'show') {
+    const skillId = args[2];
+    const { findSkillById } = await import('../packages/skill-engine/src/index.js');
+    const registry = loadSkillRegistry();
+    const skill = findSkillById(registry, skillId);
+    if (!skill) {
+      await emitExperience('skills', { status: 'ERROR', message: `Unknown skill: ${skillId}`, exitCode: 1 });
+      return;
+    }
+    if (hasFlag('--human')) {
+      await emitExperience('skills', {
+        subtitle: skillId,
+        message: skill.title || skillId,
+        items: [
+          { label: 'Category', value: skill.category || '—' },
+          { label: 'Status', value: skill.status || '—' },
+          { label: 'Priority', value: skill.priority || '—' },
+          { label: 'Capabilities', value: (skill.capabilities || []).join(', ') || '—' },
+        ],
+        notifications: skill.summary || skill.description
+          ? [{ tone: 'info', message: skill.summary || skill.description }]
+          : [],
+      });
+      return;
+    }
+    console.log(JSON.stringify(skill, null, 2));
+    return;
+  }
+
+  if (sub === 'install') {
+    if (!args[2]) {
+      await emitExperience('skills', {
+        status: 'WARNING',
+        message: 'Usage: velinstyle skills install <skill-id|pack|bundle:id|project:id>',
+        exitCode: 1,
+      });
+      return;
+    }
+    const result = skillsInstall(args.slice(2), { silent: true });
+    await emitExperience('skills', {
+      subtitle: 'install',
+      status: result.issues?.length ? 'WARNING' : 'PASS',
+      message: `Installed ${(result.installed || []).length} skill(s)`,
+      table: {
+        columns: ['Installed'],
+        rows: (result.installed || []).map((id) => [id]),
+      },
+      notifications: (result.issues || []).map((issue) => ({ tone: 'warning', message: issue })),
+    });
+    return;
+  }
+
+  if (sub === 'run') {
+    const payload = skillsRun(args[2], args.slice(3), { silent: true });
+    if (payload.ok === false) {
+      await emitExperience('skills', {
+        status: 'ERROR',
+        message: 'Skill graph resolve failed',
+        table: { columns: ['Issue'], rows: (payload.issues || []).map((i) => [i]) },
+        exitCode: 1,
+      });
+      return;
+    }
+    if (hasFlag('--json')) {
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+    await emitExperience('skills', {
+      subtitle: 'run',
+      message: `${payload.steps.length} step(s) (dry-run)`,
+      table: {
+        columns: ['Step', 'CLI', 'onlyIf'],
+        rows: payload.steps.map((s) => [
+          s.id,
+          (s.requiresCli || []).join(', '),
+          (s.onlyIf || []).join(', '),
+        ]),
+      },
+    });
+    return;
+  }
+
+  if (sub === 'validate') {
+    const result = skillsValidate({ silent: true });
+    await emitExperience('skills', {
+      subtitle: 'validate',
+      status: result.ok ? 'PASS' : 'ERROR',
+      message: result.ok ? 'skills registry valid' : 'skills registry invalid',
+      table: result.errors?.length
+        ? { columns: ['Error'], rows: result.errors.map((e) => [e]) }
+        : null,
+      exitCode: result.ok ? 0 : 1,
+    });
+    return;
+  }
+
+  if (sub === 'doctor') {
+    const result = await skillsDoctor(args.slice(2), { silent: true });
+    if (hasFlag('--json')) {
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(result.ok ? 0 : 1);
+    }
+    await emitExperience('skills', {
+      subtitle: 'doctor',
+      status: result.ok ? 'PASS' : 'ERROR',
+      message: result.ok
+        ? `skills doctor OK (${result.checked} paths)`
+        : `skills doctor FAILED (${result.errors.length} missing)`,
+      table: result.errors?.length
+        ? { columns: ['Missing'], rows: result.errors.map((e) => [e]) }
+        : null,
+      exitCode: result.ok ? 0 : 1,
+    });
+    return;
+  }
+
+  if (['packs', 'bundles', 'templates', 'projects', 'graphs'].includes(sub)) {
+    const out = skillsIndex(sub, { silent: true });
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
+
+  await emitExperience('skills', {
+    status: 'ERROR',
+    message: `Unknown skills subcommand: ${sub}`,
+    exitCode: 1,
+  });
 }
 
 async function workflowCmd() {
-  const { workflowCommand } = await import('./workflow.js');
-  await workflowCommand(args.slice(1));
+  const { workflowResolve } = await import('./workflow.js');
+  const workflowId = args[1];
+  if (!workflowId || workflowId === '--help' || workflowId === '-h') {
+    await emitExperience('workflow', {
+      message: 'Usage: velinstyle workflow <graph-id|project:id> [--json]',
+      suggestions: [
+        { text: 'velinstyle workflow landingpage' },
+        { text: 'velinstyle workflow project:marketing-site --json' },
+      ],
+    });
+    return;
+  }
+  const resolved = workflowResolve(workflowId);
+  if (!resolved.ok) {
+    await emitExperience('workflow', {
+      status: 'ERROR',
+      message: resolved.error,
+      table: resolved.issues?.length
+        ? { columns: ['Issue'], rows: resolved.issues.map((i) => [i]) }
+        : null,
+      exitCode: 1,
+    });
+    return;
+  }
+  if (hasFlag('--json')) {
+    console.log(JSON.stringify(resolved.data, null, 2));
+    return;
+  }
+  await emitExperience('workflow', {
+    message: `Workflow steps (${resolved.data.orderedSteps.length})`,
+    table: {
+      columns: ['Step'],
+      rows: resolved.data.orderedSteps.map((step) => [step]),
+    },
+  });
 }
 
 async function wcCmd() {
   const sub = args[1];
   if (sub === 'api' || sub === '--help' || sub === '-h' || !sub) {
     if (sub !== 'api') {
-      console.log(`Usage: velinstyle wc api <tag>\nExample: velinstyle wc api velin-toast`);
-      if (sub === '--help' || sub === '-h' || !sub) process.exit(0);
+      await emitExperience('wc', {
+        status: sub ? 'PASS' : 'WARNING',
+        message: 'Usage: velinstyle wc api <tag>',
+        suggestions: [{ text: 'velinstyle wc api velin-toast' }],
+        exitCode: !sub ? 1 : 0,
+      });
+      return;
     }
     const tag = args[2];
-    const { describeWcApi, formatWcApi } = await import('./wc-api.js');
+    const { describeWcApi } = await import('./wc-api.js');
     const report = describeWcApi(PKG_ROOT, tag);
     if (!report.ok) {
-      console.error(report.error);
-      process.exit(1);
+      await emitExperience('wc', { status: 'ERROR', message: report.error, exitCode: 1 });
+      return;
     }
-    if (hasFlag('--json')) console.log(JSON.stringify(report, null, 2));
-    else console.log(formatWcApi(report));
+    if (hasFlag('--json')) {
+      console.log(JSON.stringify(report, null, 2));
+      return;
+    }
+    const rows = [
+      ...report.observedAttributes.map((a) => ['attr', a]),
+      ...report.methods.map((m) => ['method', `${m}()`]),
+      ...report.events.map((e) => ['event', e]),
+    ];
+    await emitExperience('wc', {
+      subtitle: report.tag,
+      message: `<${report.tag}>`,
+      items: [
+        { label: 'Source', value: report.source },
+        { label: 'Docs', value: report.generatedDoc || '(missing — run docs generate)' },
+        ...(report.showSignature ? [{ label: 'show()', value: report.showSignature }] : []),
+      ],
+      table: rows.length ? { columns: ['Kind', 'Name'], rows } : null,
+      notifications: report.example
+        ? [{ tone: 'info', message: report.example.split('\n')[0] }]
+        : [],
+    });
     return;
   }
-  console.error(`Unknown wc subcommand: ${sub}. Use: velinstyle wc api <tag>`);
-  process.exit(1);
+  await emitExperience('wc', {
+    status: 'ERROR',
+    message: `Unknown wc subcommand: ${sub}. Use: velinstyle wc api <tag>`,
+    exitCode: 1,
+  });
 }
 
 async function scanCmd() {
@@ -1178,15 +1909,81 @@ async function scanCmd() {
   }
   const severity = getArg('--severity') || 'warning';
   const only = getArg('--only');
+  const machine = format === 'json' || format === 'sarif' || hasFlag('--json') || hasFlag('--sarif');
 
   const { scan } = await import('./scanner.js');
-  const exitCode = scan(targetPath, {
-    severity,
-    fix,
-    fixDryRun,
-    fixLang: fixLang || undefined,
-    format,
-    only,
+
+  if (fix || fixDryRun || machine) {
+    const exitCode = scan(targetPath, {
+      severity,
+      fix,
+      fixDryRun,
+      fixLang: fixLang || undefined,
+      format: hasFlag('--json') ? 'json' : hasFlag('--sarif') ? 'sarif' : format,
+      only,
+    });
+    process.exit(exitCode);
+  }
+
+  const exp = await ensureExperience();
+  let exitCode = 0;
+  await exp.executeExperience({
+    commandId: 'scan',
+    args,
+    helpers: { getArg, hasFlag },
+    version: CLI_VERSION,
+    layout: 'audit',
+    run: async (ctx) => {
+      ctx.emitProgress('Analysis', 40);
+      const data = scan(targetPath, {
+        severity,
+        format: 'json',
+        only,
+        returnData: true,
+      });
+      exitCode = data.exitCode || 0;
+      const issues = data.issues || [];
+      const errors = issues.filter((i) => i.severity === 'error').length;
+      const warnings = issues.filter((i) => i.severity === 'warning').length;
+      const status = errors ? 'ERROR' : warnings ? 'WARNING' : 'PASS';
+      return {
+        project: { cwd: targetPath, name: 'Scan' },
+        result: {
+          status,
+          message: errors || warnings
+            ? `${errors} error(s), ${warnings} warning(s)`
+            : 'No issues at selected severity',
+        },
+        stats: { errors, warnings, issues: issues.length },
+        diagnostics: issues,
+        widgets: [
+          { id: 'hero', props: { slot: 'hero', title: 'Scan', subtitle: 'Trust & accessibility audit', eyebrow: 'Velin Experience' } },
+          {
+            id: 'stats',
+            props: {
+              slot: 'counts',
+              items: [
+                { label: 'Errors', value: errors },
+                { label: 'Warnings', value: warnings },
+                { label: 'Issues', value: issues.length },
+              ],
+            },
+          },
+          {
+            id: 'table',
+            props: {
+              slot: 'findings',
+              columns: ['Sev', 'Code', 'Message'],
+              rows: issues.slice(0, 20).map((i) => [i.severity, i.code || '—', String(i.message || '').slice(0, 42)]),
+            },
+          },
+          { id: 'notification', props: { tone: status === 'PASS' ? 'ok' : status === 'ERROR' ? 'err' : 'warn', message: `Scan ${status}` } },
+          { id: 'footer', props: { slot: 'footer', text: 'velinstyle scan' } },
+        ],
+        suggestions: issues.filter((i) => i.fix).slice(0, 5).map((i) => ({ text: i.fix })),
+        notifications: [{ tone: 'info', message: 'Use --fix for safe auto-fixes where available' }],
+      };
+    },
   });
   process.exit(exitCode);
 }
@@ -1287,6 +2084,40 @@ async function checkCmd() {
     steps.push({ step: 'transparency', ok: true, skipped: true, error: String(err.message || err) });
   }
 
+  if (!quiet) console.log(C.bold('\n── motion ──'));
+  try {
+    const { motionCheckStep } = await import('./motion.js');
+    const mx = await motionCheckStep(htmlFile || target, { quiet, C });
+    if (!mx.ok && !mx.skipped) failed += 1;
+    steps.push({ step: 'motion', ok: mx.ok || !!mx.skipped, skipped: mx.skipped, elements: mx.elements });
+  } catch (err) {
+    if (!quiet) console.log(C.yellow(`motion skipped: ${err.message}`));
+    steps.push({ step: 'motion', ok: true, skipped: true, error: String(err.message || err) });
+  }
+
+  if (!quiet) console.log(C.bold('\n── security ──'));
+  try {
+    const { securityCheckStep } = await import('./security.js');
+    let securityRoot = target;
+    try {
+      if (existsSync(target) && statSync(target).isFile()) securityRoot = dirname(target);
+    } catch { /* keep target */ }
+    const sx = await securityCheckStep(securityRoot, { quiet, C });
+    if (!sx.ok && !sx.skipped) failed += 1;
+    steps.push({
+      step: 'security',
+      ok: sx.ok || !!sx.skipped,
+      skipped: sx.skipped,
+      securityScore: sx.securityScore,
+      overall: sx.overall,
+      overallGate: sx.overallGate,
+      findings: sx.findings,
+    });
+  } catch (err) {
+    if (!quiet) console.log(C.yellow(`security skipped: ${err.message}`));
+    steps.push({ step: 'security', ok: true, skipped: true, error: String(err.message || err) });
+  }
+
   const payload = {
     ok: failed === 0,
     failedSteps: failed,
@@ -1333,10 +2164,43 @@ async function checkCmd() {
     console.log(JSON.stringify(sarif, null, 2));
   } else if (asJson) {
     console.log(JSON.stringify(payload, null, 2));
-  } else if (failed) {
-    console.log(C.red(`\ncheck failed (${failed} step(s))`));
   } else {
-    console.log(C.green('\ncheck passed'));
+    const exp = await ensureExperience();
+    await exp.executeExperience({
+      commandId: 'check',
+      args,
+      helpers: { getArg, hasFlag },
+      version: CLI_VERSION,
+      layout: 'dashboard',
+      run: async () => ({
+        project: { target },
+        result: {
+          status: failed ? 'ERROR' : 'PASS',
+          message: failed ? `check failed (${failed} step(s))` : 'Ready',
+        },
+        widgets: [
+          { id: 'hero', props: { title: 'Check', subtitle: 'All engines', eyebrow: 'Velin Experience' } },
+          {
+            id: 'health',
+            props: {
+              title: 'Summary',
+              rows: steps.map((s) => ({
+                label: s.step,
+                status: s.skipped ? 'SKIP' : s.ok ? 'PASS' : 'FAIL',
+              })),
+            },
+          },
+          {
+            id: 'status',
+            props: { label: failed ? 'FAIL' : 'PASS', tone: failed ? 'err' : 'ok' },
+          },
+          { id: 'footer', props: { text: 'Overall · Ready gate' } },
+        ],
+        suggestions: failed
+          ? [{ text: 'Re-run failing steps individually (doctor / scan / review)' }]
+          : [{ text: 'Try velinstyle dashboard for a project overview' }],
+      }),
+    });
   }
 
   process.exit(failed ? 1 : 0);
@@ -1345,8 +2209,9 @@ async function checkCmd() {
 function suggestCommand(unknown) {
   const names = [
     'init', 'build', 'themes', 'add', 'icons', 'blueprint', 'create', 'serve', 'doctor', 'check',
-    'validate', 'tokens', 'scan', 'prefix', 'scaffold', 'plan', 'review', 'transparency', 'layout', 'perf',
+    'validate', 'tokens', 'scan', 'prefix', 'scaffold', 'plan', 'review', 'transparency', 'motion', 'security', 'layout', 'perf',
     'docs', 'documentation', 'meta', 'search', 'skills', 'workflow', 'wc', 'production', 'atelier',
+    'dashboard', 'replay',
   ];
   const q = String(unknown || '').toLowerCase();
   function editDistance(a, b) {
@@ -1392,23 +2257,25 @@ const ALIASES = {
 const resolvedCommand = ALIASES[command] || command;
 
 switch (resolvedCommand) {
-  case 'init': init(); break;
+  case 'init': await init(); break;
   case 'build': await build(); break;
   case 'production': {
     const { runProduction } = await import('./production/run.js');
     await runProduction({ args: args.slice(1), helpers: { getArg, hasFlag, C } });
     break;
   }
-  case 'themes': themes(); break;
-  case 'add': add(); break;
-  case 'icons': icons(); break;
+  case 'themes': await themes(); break;
+  case 'add': await add(); break;
+  case 'icons': await icons(); break;
   case 'blueprint': await blueprintCmd(); break;
   case 'create': await createCmd(); break;
   case 'serve': await serveCmd(); break;
   case 'doctor': await doctorCmd(); break;
+  case 'dashboard': await dashboardCmd(); break;
+  case 'replay': await replayCmd(); break;
   case 'check': await checkCmd(); break;
   case 'tokens': await tokensCmd(); break;
-  case 'scan': scanCmd(); break;
+  case 'scan': await scanCmd(); break;
   case 'prefix': await prefixCmd(); break;
   case 'scaffold': await scaffoldCmd(); break;
   case 'plan': await planCmd(); break;
@@ -1416,7 +2283,17 @@ switch (resolvedCommand) {
   case 'review': await reviewCmd(); break;
   case 'transparency': {
     const { transparencyCmd } = await import('./transparency.js');
-    await transparencyCmd(args.slice(1), { C, getArg, hasFlag });
+    await transparencyCmd(args.slice(1), { C, getArg, hasFlag, emitExperience });
+    break;
+  }
+  case 'motion': {
+    const { motionCmd } = await import('./motion.js');
+    await motionCmd(args.slice(1), { C, getArg, hasFlag, emitExperience });
+    break;
+  }
+  case 'security': {
+    const { securityCmd } = await import('./security.js');
+    await securityCmd(args.slice(1), { C, getArg, hasFlag, emitExperience });
     break;
   }
   case 'layout': await layoutCmd(); break;
@@ -1427,6 +2304,6 @@ switch (resolvedCommand) {
   case 'skills': await skillsCmd(); break;
   case 'workflow': await workflowCmd(); break;
   case 'wc': await wcCmd(); break;
-  case '--help': case '-h': case undefined: help(); break;
+  case '--help': case '-h': case undefined: await help(); break;
   default: unknownCommand(command); break;
 }