@aiworkbench/vibe-cli 0.0.4 → 0.0.6

package/dist/index.js

@@ -2789,6 +2789,9 @@ function isKebabCase(name) {
 function toKebabCase(name) {
   return name.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").replace(/[^a-z0-9-]/gi, "").toLowerCase().replace(/-+/g, "-").replace(/^-|-$/g, "");
 }
+function isValidCustomElementName(name) {
+  return /^[a-z][a-z0-9]*-[a-z0-9-]*$/.test(name);
+}
 function toPascalCase(kebab) {
   return kebab.split("-").map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1)).join("");
 }
@@ -2806,6 +2809,7 @@ function buildTemplateContext(projectName, framework) {
 var __dirname2 = dirname2(fileURLToPath(import.meta.url));
 async function templateDir(framework) {
   const candidates = [
+    resolve(__dirname2, "..", "templates", framework),
     resolve(__dirname2, "..", "..", "..", "..", "templates", framework),
     resolve(__dirname2, "..", "..", "..", "templates", framework)
   ];
@@ -6300,6 +6304,793 @@ this._shadow.appendChild(img);
   }
 }
 
+// src/skills/host-design-system.ts
+function generateHostDesignSystem(config) {
+  const { framework } = config;
+  const stylingApproach = getStylingApproach(framework);
+  return `# Host Design System — USECASE-EDITOR
+
+Your mini-app renders inside the host's content area via \`<VibeHost>\`. The host provides
+the header, sidebar, and scroll container. Your job is to fill the content region with UI
+that looks native to the platform. This guide contains every design token and pattern you
+need.
+
+## Important: Shadow DOM Isolation
+
+Your mini-app lives inside a Shadow DOM boundary. This means:
+- Host Tailwind classes are **NOT available** inside your component
+- CSS custom properties (variables) **DO inherit** through Shadow DOM
+- You must write your own CSS using the values below, not Tailwind utility classes
+- Use \`adoptedStyleSheets\` or \`?inline\` CSS imports to inject styles into the shadow root
+
+## Color System (OKLCH)
+
+The host uses oklch color space exclusively. Use these hardcoded values in your CSS.
+CSS custom properties like \`var(--foreground)\` will inherit from the host through the
+shadow boundary, but having the literal values ensures correct rendering in dev sandbox.
+
+### Light Mode
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| background | \`oklch(1 0 0)\` | Page background |
+| foreground | \`oklch(0.145 0 0)\` | Primary text |
+| card | \`oklch(1 0 0)\` | Card backgrounds |
+| card-foreground | \`oklch(0.145 0 0)\` | Card text |
+| primary | \`oklch(0.205 0 0)\` | Buttons, emphasis |
+| primary-foreground | \`oklch(0.985 0 0)\` | Text on primary |
+| secondary | \`oklch(0.97 0 0)\` | Secondary backgrounds |
+| secondary-foreground | \`oklch(0.205 0 0)\` | Text on secondary |
+| tertiary | \`oklch(0.8544 0.1746 90.88)\` | Accent highlight (yellow-green) |
+| tertiary-foreground | \`oklch(0.145 0 0)\` | Text on tertiary |
+| muted | \`oklch(0.97 0 0)\` | Subdued backgrounds |
+| muted-foreground | \`oklch(0.556 0 0)\` | Subdued text, descriptions |
+| destructive | \`oklch(0.577 0.245 27.325)\` | Error, danger |
+| border | \`oklch(0.922 0 0)\` | Borders, dividers |
+| input | \`oklch(0.922 0 0)\` | Input borders |
+| ring | \`oklch(0.708 0 0)\` | Focus rings |
+
+### Dark Mode
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| background | \`oklch(0.145 0 0)\` | Page background |
+| foreground | \`oklch(0.985 0 0)\` | Primary text |
+| card | \`oklch(0.205 0 0)\` | Card backgrounds |
+| card-foreground | \`oklch(0.985 0 0)\` | Card text |
+| primary | \`oklch(0.922 0 0)\` | Buttons, emphasis |
+| primary-foreground | \`oklch(0.205 0 0)\` | Text on primary |
+| secondary | \`oklch(0.269 0 0)\` | Secondary backgrounds |
+| secondary-foreground | \`oklch(0.985 0 0)\` | Text on secondary |
+| tertiary | \`oklch(0.8544 0.1746 90.88)\` | Same accent (unchanged) |
+| tertiary-foreground | \`oklch(0.145 0 0)\` | Text on tertiary |
+| muted | \`oklch(0.269 0 0)\` | Subdued backgrounds |
+| muted-foreground | \`oklch(0.708 0 0)\` | Subdued text |
+| destructive | \`oklch(0.704 0.191 22.216)\` | Error (lighter in dark) |
+| border | \`oklch(1 0 0 / 10%)\` | Borders (semi-transparent) |
+| input | \`oklch(1 0 0 / 15%)\` | Input borders |
+| ring | \`oklch(0.556 0 0)\` | Focus rings |
+
+### Using Host CSS Variables
+
+CSS custom properties inherit through Shadow DOM. Prefer variables when possible:
+
+\`\`\`css
+.my-card {
+  background: var(--card, oklch(1 0 0));
+  color: var(--card-foreground, oklch(0.145 0 0));
+  border: 1px solid var(--border, oklch(0.922 0 0));
+}
+\`\`\`
+
+The fallback values ensure correct rendering in the dev sandbox where host variables
+are not present.
+
+## Typography
+
+### Fonts
+
+The host loads **Geist** (sans) and **Geist Mono** via Google Fonts, exposed as CSS variables:
+
+\`\`\`css
+font-family: var(--font-geist-sans, system-ui, -apple-system, sans-serif);
+font-family: var(--font-geist-mono, ui-monospace, monospace);
+\`\`\`
+
+These variables inherit through Shadow DOM. Always include system font fallbacks.
+
+### Type Scale
+
+| Element | Size | Weight | Extra |
+|---------|------|--------|-------|
+| Page heading | \`1.125rem\` (text-lg) | \`700\` (bold) | — |
+| Card title | \`1.125rem\` (text-lg) | \`600\` (semibold) | — |
+| Section label | \`0.6875rem\` | \`600\` (semibold) | \`text-transform: uppercase; letter-spacing: 0.1em\` |
+| Body text | \`0.875rem\` (text-sm) | \`400\` (regular) | — |
+| Description | \`0.875rem\` (text-sm) | \`400\` | Color: muted-foreground |
+| Small label | \`0.75rem\` (text-xs) | \`500\` (medium) | — |
+| Badge / pill | \`0.625rem\` (10px) | \`600\` | — |
+
+### Heading Pattern (Section Labels)
+
+The host uses uppercase, letter-spaced, muted headings to label sections:
+
+\`\`\`css
+.section-label {
+  font-size: 0.6875rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  color: oklch(0.556 0 0); /* muted-foreground */
+}
+\`\`\`
+
+## Border Radius
+
+| Token | Value |
+|-------|-------|
+| radius-sm | \`4px\` |
+| radius-md | \`6px\` |
+| radius-lg | \`8px\` (base) |
+| radius-xl | \`12px\` |
+
+- **Cards**: \`border-radius: 12px\` (rounded-xl) for marketplace-style cards, \`8px\` (rounded-lg) for standard cards
+- **Buttons**: \`6px\` (rounded-md)
+- **Badges**: \`6px\` (rounded-md)
+- **Inputs**: \`6px\` (rounded-md)
+
+## Card Patterns
+
+### Standard Card
+
+\`\`\`css
+.card {
+  background: oklch(1 0 0);
+  border: 1px solid oklch(0.922 0 0);
+  border-radius: 8px;
+  padding: 1.5rem;
+  box-shadow: 0 1px 2px oklch(0.145 0 0 / 0.04);
+}
+\`\`\`
+
+### Marketplace Agent Card (Interactive)
+
+\`\`\`css
+.agent-card {
+  display: flex;
+  flex-direction: column;
+  background: oklch(1 0 0);
+  border: 1px solid oklch(0.922 0 0);
+  border-radius: 12px;
+  padding: 1rem;
+  cursor: pointer;
+  transition: box-shadow 180ms ease;
+  overflow: hidden;
+}
+
+.agent-card:hover {
+  box-shadow: 0 2px 6px rgba(0, 0, 0, 0.15);
+}
+\`\`\`
+
+### Builder Card
+
+\`\`\`css
+.builder-card {
+  padding: 1rem;
+  border-radius: 8px;
+  border: 1px solid oklch(0.75 0 0); /* gray-300 equivalent */
+  cursor: pointer;
+  transition: background-color 180ms ease;
+}
+
+.builder-card:hover {
+  background: oklch(0.97 0 0); /* gray-50 equivalent */
+}
+\`\`\`
+
+### Accent-Highlighted Card
+
+Use the tertiary color for feature emphasis:
+
+\`\`\`css
+.card--accent {
+  background: linear-gradient(
+    135deg,
+    oklch(0.8544 0.1746 90.88 / 0.06),
+    oklch(0.8544 0.1746 90.88 / 0.02)
+  );
+  border-color: oklch(0.8544 0.1746 90.88 / 0.3);
+}
+\`\`\`
+
+## Button Patterns
+
+### Primary Button
+
+\`\`\`css
+.btn-primary {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  height: 2.25rem;
+  padding: 0 1rem;
+  border-radius: 6px;
+  font-size: 0.875rem;
+  font-weight: 500;
+  background: oklch(0.205 0 0);
+  color: oklch(0.985 0 0);
+  border: none;
+  cursor: pointer;
+  transition: opacity 150ms ease;
+}
+
+.btn-primary:hover {
+  opacity: 0.9;
+}
+\`\`\`
+
+### Button Sizes
+
+| Size | Height | Padding | Font |
+|------|--------|---------|------|
+| xs | \`1.5rem\` | \`0 0.75rem\` | \`0.75rem\` |
+| sm | \`2rem\` | \`0 0.75rem\` | \`0.875rem\` |
+| default | \`2.25rem\` | \`0 1rem\` | \`0.875rem\` |
+| lg | \`2.5rem\` | \`0 1.5rem\` | \`0.875rem\` |
+
+### Button Variants
+
+| Variant | Background | Text | Border |
+|---------|-----------|------|--------|
+| default | \`oklch(0.205 0 0)\` | \`oklch(0.985 0 0)\` | none |
+| outline | \`oklch(1 0 0)\` | \`oklch(0.205 0 0)\` | \`1px solid oklch(0.922 0 0)\` |
+| secondary | \`oklch(0.97 0 0)\` | \`oklch(0.205 0 0)\` | none |
+| ghost | \`transparent\` | inherit | none (hover: \`oklch(0.97 0 0)\`) |
+| destructive | \`oklch(0.577 0.245 27.325)\` | \`white\` | none |
+| highlight | \`oklch(0.85 0.18 95)\` | \`black\` | none |
+
+### Disabled State
+
+\`\`\`css
+.btn:disabled {
+  pointer-events: none;
+  background: oklch(0.9 0 0);
+  color: oklch(0.556 0 0);
+}
+\`\`\`
+
+## Input Patterns
+
+\`\`\`css
+.input {
+  height: 2.25rem;
+  width: 100%;
+  border-radius: 6px;
+  border: 1px solid oklch(0.922 0 0);
+  background: transparent;
+  padding: 0.25rem 0.75rem;
+  font-size: 0.875rem;
+  transition: box-shadow 150ms ease, border-color 150ms ease;
+}
+
+.input::placeholder {
+  color: oklch(0.556 0 0);
+}
+
+.input:focus-visible {
+  border-color: oklch(0.708 0 0);
+  outline: none;
+  box-shadow: 0 0 0 3px oklch(0.708 0 0 / 0.5);
+}
+\`\`\`
+
+## Badge Patterns
+
+\`\`\`css
+.badge {
+  display: inline-flex;
+  align-items: center;
+  border-radius: 6px;
+  padding: 0.125rem 0.625rem;
+  font-size: 0.75rem;
+  font-weight: 600;
+  border: 1px solid transparent;
+}
+
+.badge--default {
+  background: oklch(0.205 0 0);
+  color: oklch(0.985 0 0);
+}
+
+.badge--secondary {
+  background: oklch(0.97 0 0);
+  color: oklch(0.205 0 0);
+}
+
+.badge--outline {
+  background: transparent;
+  border-color: oklch(0.922 0 0);
+  color: oklch(0.145 0 0);
+}
+\`\`\`
+
+### Version Badge (Small)
+
+Used on marketplace cards for version labels:
+
+\`\`\`css
+.version-badge {
+  font-size: 0.625rem;
+  line-height: 1;
+  padding: 0.125rem 0.375rem;
+  border-radius: 4px;
+  background: oklch(0.97 0 0);
+  color: oklch(0.45 0 0);
+  border: 1px solid oklch(0.922 0 0);
+}
+\`\`\`
+
+## Layout
+
+### Content Container
+
+The host's content area uses responsive horizontal padding and a max-width:
+
+\`\`\`css
+.container {
+  margin: 0 auto;
+  width: 100%;
+  padding-left: 1rem;
+  padding-right: 1rem;
+}
+
+@media (min-width: 1024px) {
+  .container { padding-left: 1.5rem; padding-right: 1.5rem; }
+}
+
+@media (min-width: 1280px) {
+  .container { padding-left: 2rem; padding-right: 2rem; }
+}
+\`\`\`
+
+| Container Size | Max Width |
+|---------------|-----------|
+| sm | \`768px\` |
+| md | \`1440px\` |
+| lg | \`1600px\` |
+| xl | none (full width) |
+
+### Spacing Scale
+
+| Name | Value | Common Usage |
+|------|-------|------|
+| xs | \`0.25rem\` (4px) | Tight gaps |
+| sm | \`0.5rem\` (8px) | Icon gaps, badge padding |
+| md | \`0.75rem\` (12px) | Grid gaps, small card gaps |
+| base | \`1rem\` (16px) | Card padding, component spacing |
+| lg | \`1.5rem\` (24px) | Card content padding, section gaps |
+| xl | \`2rem\` (32px) | Page padding, section margin |
+| 2xl | \`3rem\` (48px) | Large vertical sections |
+
+### Common Layouts
+
+**Card Grid (3 columns)**
+\`\`\`css
+.card-grid {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 1.5rem;
+}
+
+.card-grid > * {
+  flex: 0 0 calc(33.333% - 1rem);
+}
+\`\`\`
+
+**Sidebar + Content**
+\`\`\`css
+.layout-with-sidebar {
+  display: flex;
+  gap: 2rem;
+}
+
+.sidebar {
+  width: 200px;
+  flex-shrink: 0;
+}
+
+.content {
+  flex: 1;
+  min-width: 0;
+}
+\`\`\`
+
+## Shadows
+
+| Level | Value | Usage |
+|-------|-------|-------|
+| xs | \`0 1px 2px oklch(0.145 0 0 / 0.04)\` | Buttons, inputs |
+| sm | \`0 1px 3px oklch(0.145 0 0 / 0.06)\` | Static cards |
+| card-hover | \`0 2px 6px rgba(0, 0, 0, 0.15)\` | Interactive card hover |
+| lg | \`0 10px 15px oklch(0.145 0 0 / 0.1)\` | Dialogs, popovers |
+
+## Focus States
+
+All interactive elements must show a visible focus ring for accessibility:
+
+\`\`\`css
+.interactive:focus-visible {
+  border-color: oklch(0.708 0 0);
+  outline: none;
+  box-shadow: 0 0 0 3px oklch(0.708 0 0 / 0.5);
+}
+\`\`\`
+
+## Transitions
+
+Consistent timing across all interactive elements:
+
+\`\`\`css
+transition: 180ms ease; /* default for hover/shadow/transform */
+transition: 150ms ease; /* faster for opacity/color */
+\`\`\`
+
+## Navigation Routes
+
+The host application has these routes. Use \`bridge.navigation.navigate(path)\` to link:
+
+| Route | Page |
+|-------|------|
+| \`/chat\` | Chat with agents |
+| \`/marketplace\` | Marketplace landing |
+| \`/marketplace/agents?state=PUBLISHED\` | Published agents |
+| \`/playground\` | Prompt playground |
+| \`/builder\` | Agent builder |
+| \`/documents\` | Document library |
+| \`/administration\` | Admin panel (admins only) |
+
+## Dark Mode Support
+
+Dark mode is toggled via the \`.dark\` class on the \`<html>\` element (class-based, not media query).
+Use \`bridge.theme.current()\` to detect and \`bridge.events.on("theme-changed", ...)\` to react.
+
+For CSS-only dark mode in your shadow DOM, use the host's CSS variables with fallbacks:
+
+\`\`\`css
+.card {
+  background: var(--card, oklch(1 0 0));
+  color: var(--card-foreground, oklch(0.145 0 0));
+  border-color: var(--border, oklch(0.922 0 0));
+}
+\`\`\`
+
+When the host toggles dark mode, its CSS variables change automatically and your component
+inherits the new values through the Shadow DOM. No JavaScript needed if you use variables.
+
+For bridge-driven dark mode with separate value sets:
+
+${getDarkModeExample(framework)}
+
+## Icons
+
+The host uses **Lucide React** icons. Mini-apps should NOT depend on Lucide — it adds
+unnecessary bundle size. Instead:
+
+1. **Inline SVG** (preferred) — Copy the SVG paths from [lucide.dev](https://lucide.dev).
+   Use \`viewBox="0 0 24 24"\`, \`fill="none"\`, \`stroke="currentColor"\`, \`stroke-width="2"\`.
+2. **Single icon import** — If you must use Lucide, import individual icons:
+   \`import { Search } from "lucide-react"\` (NOT the barrel \`lucide-react\` import).
+
+## Anti-Patterns
+
+These break visual consistency with the host:
+
+- **Don't use oklch hue for primary UI.** The host is grayscale-first. Color is reserved for the
+  tertiary accent (\`oklch(0.8544 0.1746 90.88)\`), destructive actions, and chart data.
+- **Don't use colored backgrounds for sections.** The host uses white/near-white backgrounds with
+  subtle borders to separate content. Colored section backgrounds look foreign.
+- **Don't use rounded-full on cards.** Cards use \`8px\` or \`12px\` radius, never pill shapes.
+- **Don't add drop shadows to static elements.** The host uses flat design with \`shadow-sm\` at most.
+  Shadows are interactive cues (hover state), not decoration.
+- **Don't use custom fonts.** Stick to the Geist font family inherited from the host.
+- **Don't use thick borders.** The host uses \`1px\` borders exclusively.
+- **Don't use bright/saturated colors for UI chrome.** The grayscale palette is intentional.
+
+${stylingApproach}
+
+## Complete Example: Minimal Card Component
+
+${getCardExample(framework)}
+`;
+}
+function getStylingApproach(framework) {
+  switch (framework) {
+    case "react":
+      return `## Styling Approach (React)
+
+Use the \`?inline\` import pattern with \`adoptedStyleSheets\`:
+
+\`\`\`tsx
+// src/main.tsx
+import styles from "./styles.css?inline";
+
+connectedCallback() {
+  const shadow = this.attachShadow({ mode: "open" });
+  const sheet = new CSSStyleSheet();
+  sheet.replaceSync(styles);
+  shadow.adoptedStyleSheets = [sheet];
+  // ... create container and React root
+}
+\`\`\`
+
+Add a TypeScript declaration for the \`?inline\` import:
+
+\`\`\`ts
+// src/vite-env.d.ts
+declare module "*.css?inline" {
+  const css: string;
+  export default css;
+}
+\`\`\`
+
+Then write plain CSS in \`src/styles.css\` using the token values from this guide.`;
+    case "vue":
+      return `## Styling Approach (Vue)
+
+Vue SFC \`<style>\` blocks are automatically injected into the shadow DOM when using
+\`defineCustomElement\`:
+
+\`\`\`vue
+<style scoped>
+.card {
+  background: var(--card, oklch(1 0 0));
+  border: 1px solid var(--border, oklch(0.922 0 0));
+  border-radius: 8px;
+  padding: 1.5rem;
+}
+</style>
+\`\`\`
+
+Use the oklch token values from this guide in your scoped styles.`;
+    case "vanilla":
+      return `## Styling Approach (Vanilla)
+
+Use adopted stylesheets for best performance:
+
+\`\`\`ts
+const sheet = new CSSStyleSheet();
+sheet.replaceSync(\`
+  .card {
+    background: oklch(1 0 0);
+    border: 1px solid oklch(0.922 0 0);
+    border-radius: 8px;
+    padding: 1.5rem;
+  }
+\`);
+this._shadow.adoptedStyleSheets = [sheet];
+\`\`\`
+
+Or use a separate CSS file with Vite's \`?inline\` import.`;
+    default:
+      return "";
+  }
+}
+function getDarkModeExample(framework) {
+  switch (framework) {
+    case "react":
+      return `\`\`\`tsx
+function App({ bridge }: VibeProps) {
+  const [theme, setTheme] = useState(bridge.theme?.current() ?? "light");
+
+  useEffect(() => {
+    const unsub = bridge.events?.on("theme-changed", (payload) => {
+      setTheme((payload as { theme: string }).theme);
+    });
+    return unsub;
+  }, [bridge]);
+
+  const isDark = theme === "dark";
+  // Use isDark to toggle class names or inline styles
+}
+\`\`\``;
+    case "vue":
+      return `\`\`\`vue
+<script setup lang="ts">
+import { ref, onMounted, onUnmounted } from "vue";
+import type { Bridge } from "@aiworkbench/vibe-types";
+
+const props = defineProps<{ bridge: Bridge }>();
+const theme = ref(props.bridge.theme?.current() ?? "light");
+let unsub: (() => void) | undefined;
+
+onMounted(() => {
+  unsub = props.bridge.events?.on("theme-changed", (payload) => {
+    theme.value = (payload as { theme: string }).theme;
+  });
+});
+onUnmounted(() => unsub?.());
+</script>
+\`\`\``;
+    case "vanilla":
+      return `\`\`\`ts
+set bridge(b: Bridge) {
+  this._bridge = b;
+  this._theme = b.theme?.current() ?? "light";
+
+  this._cleanups.push(
+    b.events?.on("theme-changed", (payload) => {
+      this._theme = (payload as { theme: string }).theme;
+      this.updateTheme();
+    }) ?? (() => {})
+  );
+
+  this.render();
+}
+\`\`\``;
+    default:
+      return "";
+  }
+}
+function getCardExample(framework) {
+  switch (framework) {
+    case "react":
+      return `\`\`\`tsx
+interface CardProps {
+  title: string;
+  description: string;
+  onClick?: () => void;
+}
+
+function Card({ title, description, onClick }: CardProps) {
+  return (
+    <div
+      className="card"
+      role={onClick ? "button" : undefined}
+      tabIndex={onClick ? 0 : undefined}
+      onClick={onClick}
+      onKeyDown={(e) => {
+        if (onClick && (e.key === "Enter" || e.key === " ")) {
+          e.preventDefault();
+          onClick();
+        }
+      }}
+    >
+      <div className="card-title">{title}</div>
+      <div className="card-desc">{description}</div>
+    </div>
+  );
+}
+\`\`\`
+
+\`\`\`css
+/* styles.css */
+.card {
+  background: var(--card, oklch(1 0 0));
+  color: var(--card-foreground, oklch(0.145 0 0));
+  border: 1px solid var(--border, oklch(0.922 0 0));
+  border-radius: 12px;
+  padding: 1rem;
+  cursor: pointer;
+  transition: box-shadow 180ms ease;
+  user-select: none;
+}
+
+.card:hover {
+  box-shadow: 0 2px 6px rgba(0, 0, 0, 0.15);
+}
+
+.card-title {
+  font-size: 1.125rem;
+  font-weight: 600;
+  color: var(--foreground, oklch(0.205 0 0));
+}
+
+.card-desc {
+  margin-top: 0.5rem;
+  font-size: 0.875rem;
+  color: var(--muted-foreground, oklch(0.556 0 0));
+  line-height: 1.5;
+}
+\`\`\``;
+    case "vue":
+      return `\`\`\`vue
+<template>
+  <div
+    class="card"
+    :role="onClick ? 'button' : undefined"
+    :tabindex="onClick ? 0 : undefined"
+    @click="onClick?.()"
+    @keydown.enter.space.prevent="onClick?.()"
+  >
+    <div class="card-title">{{ title }}</div>
+    <div class="card-desc">{{ description }}</div>
+  </div>
+</template>
+
+<script setup lang="ts">
+defineProps<{
+  title: string;
+  description: string;
+  onClick?: () => void;
+}>();
+</script>
+
+<style scoped>
+.card {
+  background: var(--card, oklch(1 0 0));
+  color: var(--card-foreground, oklch(0.145 0 0));
+  border: 1px solid var(--border, oklch(0.922 0 0));
+  border-radius: 12px;
+  padding: 1rem;
+  cursor: pointer;
+  transition: box-shadow 180ms ease;
+  user-select: none;
+}
+
+.card:hover {
+  box-shadow: 0 2px 6px rgba(0, 0, 0, 0.15);
+}
+
+.card-title {
+  font-size: 1.125rem;
+  font-weight: 600;
+}
+
+.card-desc {
+  margin-top: 0.5rem;
+  font-size: 0.875rem;
+  color: var(--muted-foreground, oklch(0.556 0 0));
+  line-height: 1.5;
+}
+</style>
+\`\`\``;
+    case "vanilla":
+      return `\`\`\`ts
+private render() {
+  const sheet = new CSSStyleSheet();
+  sheet.replaceSync(\`
+    .card {
+      background: var(--card, oklch(1 0 0));
+      color: var(--card-foreground, oklch(0.145 0 0));
+      border: 1px solid var(--border, oklch(0.922 0 0));
+      border-radius: 12px;
+      padding: 1rem;
+      cursor: pointer;
+      transition: box-shadow 180ms ease;
+      user-select: none;
+    }
+    .card:hover {
+      box-shadow: 0 2px 6px rgba(0, 0, 0, 0.15);
+    }
+    .card-title {
+      font-size: 1.125rem;
+      font-weight: 600;
+    }
+    .card-desc {
+      margin-top: 0.5rem;
+      font-size: 0.875rem;
+      color: var(--muted-foreground, oklch(0.556 0 0));
+      line-height: 1.5;
+    }
+  \`);
+  this._shadow.adoptedStyleSheets = [sheet];
+
+  const card = document.createElement("div");
+  card.className = "card";
+  card.innerHTML = \`
+    <div class="card-title">\${this.escapeHtml(this.title)}</div>
+    <div class="card-desc">\${this.escapeHtml(this.description)}</div>
+  \`;
+  this._shadow.appendChild(card);
+}
+\`\`\``;
+    default:
+      return "";
+  }
+}
+
 // src/scaffold/write-agent-docs.ts
 var PERMISSION_DOCS = {
   auth: `### auth
@@ -6496,6 +7287,33 @@ cleanups.forEach((fn) => fn());
 | "Unresolved external" build warning | Dependency not in Vite external config | Add to \`rollupOptions.external\` or bundle it |
 | HMR not reflecting changes | Custom element re-registration conflict | Hard refresh the page (Cmd+Shift+R / Ctrl+Shift+R) |
 
+## Skills Reference
+
+This project includes detailed skill guides for specific topics. Skills are **not loaded by
+default** to keep context focused. **Load the relevant skill before writing code** whenever the
+user's request touches that area. When in doubt, load the skill — it's better to have the
+reference than to guess.
+
+| Skill | Load when… |
+|-------|-----------|
+| \`bridge-usage\` | Using any bridge capability (auth, api, storage, events, theme, toast, navigation) |
+| \`component-patterns\` | Creating or modifying components, lifecycle hooks, shadow DOM patterns |
+| \`manifest-guide\` | Editing manifest.json, adding or changing permissions |
+| \`security-rules\` | Reviewing code for policy violations, or unsure if a pattern is allowed |
+| \`vite-config\` | Changing build configuration, adding Vite plugins, optimizing bundles |
+| \`accessibility\` | Adding interactive elements, forms, ARIA attributes, keyboard navigation |
+| \`error-handling\` | Implementing try/catch, error boundaries, or graceful degradation |
+| \`performance\` | Optimizing bundle size, render performance, or memory usage |
+| \`debugging\` | Troubleshooting issues, tracing bridge calls, fixing HMR problems |
+| \`navigation-patterns\` | Building multi-view UIs, tabs, wizards, or steppers (no URL routing) |
+| \`asset-handling\` | Working with images, SVGs, fonts, or other static assets |
+| \`host-design-system\` | Styling components to match the host application's design tokens and visual language |
+${testing ? `| \`testing-guide\` | Writing or modifying tests, mocking the bridge, test setup |
+` : ""}
+**How to use skills:** Read the skill file for the relevant topic before implementing. Multiple
+skills can apply to a single task — for example, building a new form might involve
+\`component-patterns\`, \`accessibility\`, and \`bridge-usage\` (if the form submits via the bridge API).
+
 ## Build & Dev
 - \`bun run dev\`       — Start Vite dev server with hot reload
 - \`bun run build\`     — Production build (ES module, < 50kb gzipped)
@@ -6530,7 +7348,8 @@ function generateEmbeddedSkills(config) {
     { name: "Performance", content: generatePerformance(config) },
     { name: "Debugging", content: generateDebugging(config) },
     { name: "Navigation Patterns", content: generateNavigationPatterns(config) },
-    { name: "Asset Handling", content: generateAssetHandling(config) }
+    { name: "Asset Handling", content: generateAssetHandling(config) },
+    { name: "Host Design System", content: generateHostDesignSystem(config) }
   ];
   if (config.testing) {
     skills.push({ name: "Testing Guide", content: generateTestingGuide(config) });
@@ -6867,6 +7686,11 @@ var SKILL_DEFS = [
     name: "asset-handling",
     description: "Inline SVGs, imported data URLs, and CDN patterns for production assets",
     generate: generateAssetHandling
+  },
+  {
+    name: "host-design-system",
+    description: "Host app design tokens, typography, spacing, colors, and component patterns",
+    generate: generateHostDesignSystem
   }
 ];
 async function writeFolderSkill(baseDir, skill, content) {
@@ -6920,12 +7744,16 @@ function ciWorkflow(registryRepo, githubHost) {
 ` : "";
   return `# Auto-generated by vibe-kit — CI/CD for this mini-app.
 #
-# Required repository secrets:
+# Required repository secrets (dev):
 #   VIBE_STORAGE_ACCOUNT_NAME  — Azure Storage account name
 #   VIBE_STORAGE_ACCOUNT_KEY   — Azure Storage account key
 #   VIBE_STORAGE_CONTAINER_NAME — Azure container for bundles
 #   VIBE_REGISTRY_REPO         — e.g. "${registryRepo}"
 #   VIBE_REGISTRY_TOKEN        — PAT with repo write access to the registry
+#
+# For staging/prod, use environment-scoped secrets (e.g. VIBE_STORAGE_ACCOUNT_KEY_STAGING).
+# Each environment should use separate Azure Storage accounts so that dev credentials
+# cannot write to staging/prod. See vibe-publish docs for the full scoping model.
 ${gheComment}
 name: CI
 
@@ -7122,6 +7950,19 @@ async function createCommand(rawName) {
     }
     projectName = converted;
   }
+  if (!isValidCustomElementName(projectName)) {
+    const suggested = `vibe-${projectName}`;
+    warn(`"${projectName}" is not a valid custom element name (must contain a hyphen).`);
+    const ok = await dist_default3({
+      message: `Use "${suggested}" instead?`,
+      default: true
+    });
+    if (!ok) {
+      error("Aborted.");
+      process.exit(1);
+    }
+    projectName = suggested;
+  }
   const outputDir = resolve2(process.cwd(), projectName);
   if (await dirExists(outputDir)) {
     const overwrite = await dist_default3({