vibespot 1.3.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibespot",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "AI-powered HubSpot CMS landing page builder — vibe coding & React converter",
   "type": "module",
   "bin": {
@@ -19,7 +19,8 @@
     "build": "tsup",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "contact-monitor": "tsx scripts/contact-monitor.ts"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.92.0",

package/ui/dashboard.js

@@ -1292,15 +1292,16 @@ if (humanifyCheckbox) {
 // ---------------------------------------------------------------------------
 
 function switchWorkspaceTab(tabName) {
+  if (tabName === "settings") {
+    if (typeof openSettings === "function") openSettings();
+    return;
+  }
   document.querySelectorAll(".workspace-tab").forEach((btn) => {
     btn.classList.toggle("active", btn.dataset.wsTab === tabName);
   });
   document.querySelectorAll(".workspace-panel").forEach((panel) => {
     panel.classList.toggle("active", panel.dataset.wsPanel === tabName);
   });
-  if (tabName === "settings" && typeof refreshSettings === "function") {
-    refreshSettings();
-  }
   if (tabName === "library") {
     refreshDashboard();
   }

package/ui/docs/index.html

@@ -60,6 +60,7 @@
     <a class="doc-nav__link" href="#editor">The Editor</a>
     <a class="doc-nav__link doc-nav__link--sub" href="#editor-layout">Layout</a>
     <a class="doc-nav__link doc-nav__link--sub" href="#workspace-tabs">Workspace Tabs</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#project-overview">Project Overview</a>
     <a class="doc-nav__link doc-nav__link--sub" href="#chat-panel">Chat</a>
     <a class="doc-nav__link doc-nav__link--sub" href="#preview-panel">Preview</a>
     <a class="doc-nav__link doc-nav__link--sub" href="#code-editor">Code Editor</a>
@@ -71,6 +72,11 @@
     <a class="doc-nav__link doc-nav__link--sub" href="#multi-page">Multi-Page Sites</a>
     <a class="doc-nav__link doc-nav__link--sub" href="#templates">Templates</a>
     <a class="doc-nav__link doc-nav__link--sub" href="#module-library">Module Library</a>
+    <a class="doc-nav__link" href="#first-generation">Your First Generation</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#first-gen-page">Page Workflow</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#first-gen-email">Email Workflow</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#first-gen-editing">Editing with Module Overview</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#first-gen-publish">Publishing to HubSpot</a>
   </div>
 
   <div class="doc-nav__section">
@@ -106,6 +112,12 @@
     <a class="doc-nav__link doc-nav__link--sub" href="#auto-fix">Auto-Fix</a>
     <a class="doc-nav__link doc-nav__link--sub" href="#creating-page-hubspot">Creating a Page</a>
     <a class="doc-nav__link" href="#zip-download">ZIP Download</a>
+    <a class="doc-nav__link" href="#docker-deployment">Docker Deployment</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#docker-quick-start">Quick Start</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#docker-https">HTTPS with Caddy</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#docker-env-vars">Environment Variables</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#docker-persistence">Persistence</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#docker-reverse-proxy">Reverse Proxy &amp; k8s</a>
     <a class="doc-nav__link" href="#marketplace">Marketplace</a>
     <a class="doc-nav__link" href="#version-history">Version History</a>
   </div>
@@ -189,7 +201,7 @@ vibespot</code></pre>
     <div class="doc-feature">
       <div class="doc-feature__icon">&#127912;</div>
       <div class="doc-feature__title">Multi-Engine AI</div>
-      <div class="doc-feature__desc">Works with Anthropic, OpenAI, Gemini, Claude Code, Gemini CLI, and Codex CLI.</div>
+      <div class="doc-feature__desc">Works with Anthropic, OpenAI, Gemini, Langdock, Claude Code, Gemini CLI, and Codex CLI.</div>
     </div>
     <div class="doc-feature">
       <div class="doc-feature__icon">&#128338;</div>
@@ -207,7 +219,7 @@ vibespot</code></pre>
   <p>vibeSpot stores its configuration at <code>~/.vibespot/config.json</code>. You can configure everything through the Settings panel in the web UI, or by editing the config file directly.</p>
 
   <h3 id="ai-engines">AI Engines</h3>
-  <p>vibeSpot supports seven AI engines. You only need one to get started. The table below compares them:</p>
+  <p>vibeSpot supports eight AI engines. You only need one to get started. The table below compares them:</p>
 
   <table>
     <thead>
@@ -219,6 +231,7 @@ vibespot</code></pre>
       <tr><td>Claude OAuth</td><td>API</td><td>Run <code>claude setup-token</code>, paste token</td><td>Included in Claude subscription</td><td>Subscribers without API budget</td></tr>
       <tr><td>OpenAI API</td><td>API</td><td>Add <code>OPENAI_API_KEY</code></td><td>Pay-per-token</td><td>GPT-5.5 users, existing OpenAI budget</td></tr>
       <tr><td>Gemini API</td><td>API</td><td>Add <code>GEMINI_API_KEY</code></td><td>Free tier available</td><td>Cost-conscious users, free quota</td></tr>
+      <tr><td>Langdock</td><td>API</td><td>Add <code>LANGDOCK_API_KEY</code></td><td>Pay-per-token (via Langdock)</td><td>EU data residency, GDPR compliance</td></tr>
       <tr><td>Gemini CLI</td><td>CLI</td><td>Install <code>gemini</code> CLI, authenticate</td><td>Free (with Google account)</td><td>Free option without API keys</td></tr>
       <tr><td>Codex CLI</td><td>CLI</td><td>Install <code>codex</code> CLI, authenticate</td><td>Included in OpenAI subscription</td><td>OpenAI subscribers</td></tr>
     </tbody>
@@ -231,6 +244,7 @@ vibespot</code></pre>
       <button class="doc-tabs__tab" data-tab="tab-claude-oauth">Claude OAuth</button>
       <button class="doc-tabs__tab" data-tab="tab-openai">OpenAI API</button>
       <button class="doc-tabs__tab" data-tab="tab-gemini-api">Gemini API</button>
+      <button class="doc-tabs__tab" data-tab="tab-langdock">Langdock</button>
       <button class="doc-tabs__tab" data-tab="tab-gemini-cli">Gemini CLI</button>
       <button class="doc-tabs__tab" data-tab="tab-codex">Codex CLI</button>
     </div>
@@ -278,6 +292,18 @@ vibespot</code></pre>
         <li>Select <strong>Gemini API</strong> as the engine.</li>
       </ol>
     </div>
+    <div class="doc-tabs__panel" id="tab-langdock">
+      <p>Langdock is an EU-hosted AI gateway based in Frankfurt. It routes Claude requests through an Anthropic-compatible endpoint, so all Anthropic features (prompt caching, structured output, extended thinking) work unchanged. Langdock provides a single GDPR-native DPA covering OpenAI, Anthropic, Mistral, and Google models.</p>
+      <ol class="doc-steps">
+        <li>Sign up at <a href="https://langdock.com" target="_blank">langdock.com</a> and generate an API key.</li>
+        <li>In vibeSpot Settings &rarr; AI tab, paste the key into the Langdock API Key field. Or set the environment variable: <code>export LANGDOCK_API_KEY=...</code></li>
+        <li>Select <strong>Langdock</strong> as the engine. The default model is <code>claude-sonnet-4-20250514</code>. All Claude models are available through the gateway.</li>
+      </ol>
+      <div class="doc-callout doc-callout--info">
+        <div class="doc-callout__label">&#8505; Self-Hosted Deployments</div>
+        <p>For private-cloud or self-hosted Langdock installations, set <code>LANGDOCK_BASE_URL</code> to override the default endpoint (<code>https://api.langdock.com/anthropic</code>). You can also set this in the config file as <code>langdockBaseUrl</code>.</p>
+      </div>
+    </div>
     <div class="doc-tabs__panel" id="tab-gemini-cli">
       <p>The Gemini CLI runs as a local subprocess, similar to Claude Code.</p>
       <ol class="doc-steps">
@@ -319,10 +345,13 @@ vibespot</code></pre>
       <tr><th>Field</th><th>Type</th><th>Description</th></tr>
     </thead>
     <tbody>
-      <tr><td><code>aiEngine</code></td><td>string</td><td>Active AI engine: <code>"anthropic-api"</code>, <code>"claude-code"</code>, <code>"claude-oauth"</code>, <code>"openai-api"</code>, <code>"gemini-api"</code>, <code>"gemini-cli"</code>, <code>"codex-cli"</code></td></tr>
+      <tr><td><code>aiEngine</code></td><td>string</td><td>Active AI engine: <code>"anthropic-api"</code>, <code>"claude-code"</code>, <code>"claude-oauth"</code>, <code>"openai-api"</code>, <code>"gemini-api"</code>, <code>"langdock-api"</code>, <code>"gemini-cli"</code>, <code>"codex-cli"</code></td></tr>
       <tr><td><code>anthropicApiKey</code></td><td>string</td><td>Anthropic API key (starts with <code>sk-ant-</code>)</td></tr>
       <tr><td><code>openaiApiKey</code></td><td>string</td><td>OpenAI API key (starts with <code>sk-</code>)</td></tr>
       <tr><td><code>geminiApiKey</code></td><td>string</td><td>Google AI / Gemini API key</td></tr>
+      <tr><td><code>langdockApiKey</code></td><td>string</td><td>Langdock API key for the EU gateway</td></tr>
+      <tr><td><code>langdockApiModel</code></td><td>string</td><td>Langdock model override (default: <code>claude-sonnet-4-20250514</code>)</td></tr>
+      <tr><td><code>langdockBaseUrl</code></td><td>string</td><td>Override Langdock endpoint for self-hosted/private-cloud deployments (default: <code>https://api.langdock.com/anthropic</code>)</td></tr>
       <tr><td><code>claudeCodeModel</code></td><td>string</td><td>Model override for Claude Code CLI</td></tr>
       <tr><td><code>anthropicApiModel</code></td><td>string</td><td>Anthropic API model (default: <code>claude-sonnet-4-20250514</code>)</td></tr>
       <tr><td><code>openaiApiModel</code></td><td>string</td><td>OpenAI API model (default: <code>gpt-5.5</code>)</td></tr>
@@ -336,7 +365,7 @@ vibespot</code></pre>
   </table>
 
   <h3 id="env-vars">Environment Variables</h3>
-  <p>API keys can also be set as environment variables. The config file takes precedence &mdash; environment variables are used as fallbacks when no key is set in the config:</p>
+  <p>API keys and server settings can be set as environment variables. The config file takes precedence &mdash; environment variables are used as fallbacks when no key is set in the config. In Docker deployments, env vars are the primary configuration method (see <a href="#docker-deployment">Docker Deployment</a>).</p>
   <table>
     <thead>
       <tr><th>Variable</th><th>Description</th></tr>
@@ -346,6 +375,14 @@ vibespot</code></pre>
       <tr><td><code>OPENAI_API_KEY</code></td><td>OpenAI API key for GPT models</td></tr>
       <tr><td><code>GEMINI_API_KEY</code></td><td>Google AI API key for Gemini models</td></tr>
       <tr><td><code>GOOGLE_AI_API_KEY</code></td><td>Alternative name for the Gemini API key (same effect as <code>GEMINI_API_KEY</code>)</td></tr>
+      <tr><td><code>LANGDOCK_API_KEY</code></td><td>Langdock EU gateway key</td></tr>
+      <tr><td><code>LANGDOCK_BASE_URL</code></td><td>Override Langdock endpoint for self-hosted deployments</td></tr>
+      <tr><td><code>HUBSPOT_PERSONAL_ACCESS_KEY</code></td><td>HubSpot PAK &mdash; enables theme upload without configuring through the UI</td></tr>
+      <tr><td><code>FIGMA_TOKEN</code></td><td>Figma personal access token for design import</td></tr>
+      <tr><td><code>VIBESPOT_AI_ENGINE</code></td><td>Default engine: <code>anthropic-api</code>, <code>openai-api</code>, <code>gemini-api</code>, <code>langdock-api</code></td></tr>
+      <tr><td><code>VIBESPOT_AGENTIC_MODE</code></td><td>Set <code>true</code> to enable the multi-stage agentic pipeline</td></tr>
+      <tr><td><code>VIBESPOT_PORT</code></td><td>Override the HTTP server port (default: <code>4200</code>)</td></tr>
+      <tr><td><code>VIBESPOT_NO_OPEN</code></td><td>Set <code>1</code> to suppress auto-opening the browser on startup</td></tr>
     </tbody>
   </table>
 </div>
@@ -372,17 +409,39 @@ vibespot</code></pre>
   <ul>
     <li><strong>Pages</strong> &mdash; Create new pages and manage existing templates. The page tree sidebar shows all templates with type badges (LP, Blog, Web, Sec), labels, and module counts.</li>
     <li><strong>Brand</strong> &mdash; Brand kit (colors, fonts, logo URL) with a live visual preview card showing color swatches, sample text, and logo thumbnail. Also surfaces import analysis results for themes fetched from HubSpot.</li>
-    <li><strong>Library</strong> &mdash; The shared module library across all pages of the active theme. Browse, preview, and add reusable modules to any template.</li>
+    <li><strong>Library</strong> &mdash; Project assets browser showing images, fonts, and scripts in the active theme. Also provides access to the shared module library for adding reusable modules to any template.</li>
     <li><strong>Marketplace</strong> &mdash; Marketplace validation and listing metadata editor.</li>
     <li><strong>Settings</strong> &mdash; Quick access to AI, HubSpot, Figma, GitHub, and vibeSpot configuration.</li>
   </ul>
 
-  <img class="doc-screenshot" src="screenshots/workspace-tabs.png" alt="Workspace tabs — Pages, Brand, Library, Marketplace, and Settings — visible in the editor topbar">
-
-  <img class="doc-screenshot" src="screenshots/editor-full-layout.png" alt="The full editor layout showing chat panel on the left, live preview on the right, and workspace tabs in the topbar">
+  <img class="doc-screenshot" src="screenshots/workspace-tabs.png" alt="The full editor layout showing chat panel on the left, live preview on the right, and workspace tabs (Pages, Brand, Library, Marketplace, Settings) in the topbar">
 
   <p>The topbar provides access to theme settings, upload, version history, responsive viewport toggle, and the settings gear.</p>
 
+  <h3 id="project-overview">Project Overview Table</h3>
+  <p>When you have multiple projects, the Project Home shows a <strong>sortable table</strong> that gives you a bird's-eye view of every project in your workspace:</p>
+  <table>
+    <thead>
+      <tr><th>Column</th><th>What it shows</th></tr>
+    </thead>
+    <tbody>
+      <tr><td><strong>Name</strong></td><td>The project (theme) name. Click to open it in the editor.</td></tr>
+      <tr><td><strong>Pages</strong></td><td>Number of page templates (landing pages, website pages, blog posts).</td></tr>
+      <tr><td><strong>Emails</strong></td><td>Number of email templates in the project.</td></tr>
+      <tr><td><strong>Modules</strong></td><td>Total module count across all templates.</td></tr>
+      <tr><td><strong>Brand Assets</strong></td><td>Whether a brand kit is configured (checkmark or dash).</td></tr>
+    </tbody>
+  </table>
+
+  <h4 id="bulk-operations">Bulk Operations</h4>
+  <p>Select multiple projects using the checkboxes in the leftmost column, or click the header checkbox to select all. A floating toolbar appears with the selection count and two actions:</p>
+  <ul>
+    <li><strong>Duplicate</strong> &mdash; Copies all selected projects (only available for projects with saved sessions).</li>
+    <li><strong>Delete</strong> &mdash; Removes all selected projects. A confirmation dialog asks whether to also delete local theme files from disk.</li>
+  </ul>
+
+  <img class="doc-screenshot" src="screenshots/project-overview-table.png" alt="Project overview table showing multiple projects with pages, emails, modules, and brand asset columns, with two rows selected and the bulk toolbar visible">
+
   <h3 id="chat-panel">Chat Panel</h3>
   <p>The chat panel is your primary way to interact with the AI. Type a message describing what you want and press <kbd>Enter</kbd> to send. Use <kbd>Shift</kbd>+<kbd>Enter</kbd> to insert a new line without sending.</p>
   <p>During generation, the chat panel shows a real-time pipeline progress UI with stage indicators and per-module status cards. Each module progresses through: <em>queued</em> &rarr; <em>generating...</em> &rarr; <em>validating...</em> &rarr; <em>&#10004;</em> (complete) or <em>&#10007;</em> (failed). If a module fails, it may show <em>retrying...</em> before a second attempt.</p>
@@ -396,7 +455,9 @@ vibespot</code></pre>
   <p>Drag and drop files onto the chat input, or click the attachment button to browse.</p>
 
   <h4 id="starter-templates">Starter Templates</h4>
-  <p>For quick starts, the Library tab offers six starter templates that bootstrap a new theme with pre-built modules, shared CSS/JS, and module order &mdash; instant preview with no AI wait:</p>
+  <p>For quick starts, click <strong>From Template</strong> on the Project Home screen (or use the templates icon in the chat input area). Nine starter templates bootstrap a new theme with pre-built modules, shared CSS/JS, and module order &mdash; instant preview with no AI wait:</p>
+
+  <p><strong>Page starters:</strong></p>
   <ul>
     <li><strong>SaaS Landing Page</strong> &mdash; Hero, features grid, pricing, testimonials, CTA, footer</li>
     <li><strong>Portfolio</strong> &mdash; About section, project gallery, skills, contact form</li>
@@ -406,6 +467,13 @@ vibespot</code></pre>
     <li><strong>Blog Content Hub</strong> &mdash; 8-module blog layout with post body, author bio, related posts, sidebar, and navigation</li>
   </ul>
 
+  <p><strong>Email starters:</strong></p>
+  <ul>
+    <li><strong>Welcome Email</strong> &mdash; Logo header, greeting, onboarding steps, CTA button, footer</li>
+    <li><strong>Announcement Email</strong> &mdash; Header, announcement body, feature highlights, CTA</li>
+    <li><strong>Newsletter Email</strong> &mdash; Header, content sections, article cards, footer</li>
+  </ul>
+
   <h4 id="smart-suggestions">Smart Chat Suggestions</h4>
   <p>After each pipeline completion, contextual suggestion chips appear below the assistant message with follow-up actions tailored to your current page. The suggestions are filtered by which modules already exist &mdash; you won't see "Add a pricing section" if you already have one. Click a chip to send it as the next message, or ignore them and type your own prompt.</p>
 
@@ -516,14 +584,17 @@ vibespot</code></pre>
     </div>
   </div>
 
-  <p>The setup screen presents five options:</p>
+  <p>The Project Home screen greets you with a time-of-day message ("Good morning / afternoon / evening") and six <strong>asset-type cards</strong>. Each card scopes the prompt and pipeline to the right content type:</p>
   <ul>
-    <li><strong>New Theme</strong> &mdash; Creates a fresh HubSpot theme directory at <code>~/vibespot-themes/your-theme-name</code>. Initializes the standard folder structure (<code>modules/</code>, <code>templates/</code>, <code>css/</code>, <code>js/</code>) and a git repository for version tracking.</li>
-    <li><strong>Continue (Resume)</strong> &mdash; Reopens an existing project from the sidebar list. Your chat history, modules, and all templates are preserved exactly where you left off.</li>
-    <li><strong>From HubSpot (Fetch)</strong> &mdash; Downloads an existing theme from your HubSpot portal. vibeSpot scans the fetched modules and imports them into a session so you can modify them with AI or by hand.</li>
-    <li><strong>From Figma (Beta)</strong> &mdash; Paste a Figma URL and vibeSpot extracts design tokens, section structure, copy, and image assets, then translates each section into a HubSpot module. See the dedicated <a href="#figma-import">Figma Import</a> section for the full walkthrough.</li>
-    <li><strong>From React (Beta)</strong> &mdash; Clones a React or Lovable project from a Git URL and converts its components into native HubSpot modules. The conversion uses the built-in conversion guide to map React patterns to HubL equivalents.</li>
+    <li><strong>Landing Page</strong> &mdash; Full-width marketing pages with standard HubSpot CMS modules.</li>
+    <li><strong>Email</strong> &mdash; Table-based email templates with inline CSS and MSO/VML conditional structure.</li>
+    <li><strong>Website</strong> &mdash; Standard website pages (About, Contact, Services).</li>
+    <li><strong>Blog Post</strong> &mdash; Blog templates with HubSpot blog variables.</li>
+    <li><strong>From Template</strong> &mdash; Opens the starter template grid (SaaS, Portfolio, Restaurant, Event, Coming Soon, Blog, plus three email starters).</li>
+    <li><strong>Import</strong> &mdash; Shows a source picker: HubSpot (fetch existing theme), Figma (translate a design), or React (convert a project).</li>
   </ul>
+  <p>Clicking an asset-type card reveals a scoped prompt input with an eyebrow label (e.g. "Landing Page") and a per-type placeholder. Enter a project name and your description, then vibeSpot creates the theme directory and opens the editor.</p>
+  <p>You can also reach your existing projects from the sidebar list (&ldquo;Continue&rdquo;) or the <a href="#project-overview">project overview table</a> when you have multiple projects.</p>
 
   <h3 id="onboarding">Onboarding Walkthrough</h3>
   <p>On first launch (no projects, no local themes), vibeSpot shows a <strong>3-step onboarding walkthrough</strong> on the Project Home screen:</p>
@@ -534,8 +605,6 @@ vibespot</code></pre>
   </ol>
   <p>The walkthrough includes back/next/skip controls and progress dots. Once completed, a <code>vibespot:introSeen</code> localStorage flag prevents it from reappearing. After the intro, the existing AI-engine setup walkthrough still triggers if no engine is configured. Force-show with <code>?intro</code> in the URL.</p>
 
-  <img class="doc-screenshot" src="screenshots/onboarding-walkthrough.png" alt="The 3-step onboarding walkthrough shown on first launch, with progress dots and Skip/Next controls">
-
   <h3 id="first-page">Your First Page</h3>
   <p>Follow these steps to build your first landing page from scratch:</p>
   <ol class="doc-steps">
@@ -558,10 +627,10 @@ vibespot</code></pre>
   <p>vibeSpot supports three content types, each with its own pipeline prompts, validation rules, and starter templates:</p>
   <ul>
     <li><strong>Landing Page</strong> &mdash; The default. Full-width marketing pages with standard HubSpot CMS modules.</li>
-    <li><strong>Email</strong> &mdash; HubSpot email templates with table-based layout, inline CSS design tokens, and MSO/VML conditional structure for Outlook compatibility. Select "Email" from the page type dropdown in the web UI, or use <code>vibespot email</code> from the CLI. The pipeline routes through email-specific prompts at every stage (architect, module developer, validator).</li>
+    <li><strong>Email</strong> &mdash; HubSpot email templates with table-based layout, inline CSS design tokens, and MSO/VML conditional structure for Outlook compatibility. Select the <strong>Email</strong> card on the Project Home screen, choose "Email" from the page type dropdown, or use <code>vibespot email</code> from the CLI. The pipeline routes through email-specific prompts at every stage (architect, module developer, validator). A dedicated <strong>email client preview</strong> (envelope icon in the topbar) renders your email as it appears in Gmail, Outlook Desktop, and Apple Mail.</li>
     <li><strong>Blog</strong> &mdash; Blog templates with HubSpot blog variables (<code>content.post_body</code>, <code>content.author</code>, <code>blog_recent_posts</code>, etc.). Blog-specific prompts, validator auto-fix, and a pre-built Blog Content Hub starter template with 8 modules.</li>
   </ul>
-  <p>The intent analyzer detects the content type from your prompt (e.g. "create a welcome email" triggers the email pipeline). You can also set it explicitly via the page type dropdown.</p>
+  <p>The intent analyzer detects the content type from your prompt (e.g. "create a welcome email" triggers the email pipeline). You can also set it explicitly via the asset-type cards on the Project Home screen or the page type dropdown.</p>
 
   <img class="doc-screenshot" src="screenshots/content-type-dropdown.png" alt="Page type dropdown showing Landing Page, Email, Website, and Blog Post options">
 
@@ -606,12 +675,182 @@ vibespot</code></pre>
   </ul>
 </div>
 
+<!-- ============================================================
+     Section 4b: Your First Generation
+     ============================================================ -->
+<div class="doc-section" id="first-generation">
+  <h2 id="first-generation-heading">Your First Generation <a href="#first-generation" class="doc-anchor">#</a></h2>
+  <p class="doc-subtitle">Step-by-step walkthroughs for generating your first landing page, your first email template, editing with the module overview, and publishing to HubSpot.</p>
+
+  <h3 id="first-gen-page">Page Workflow: Landing Page from Scratch</h3>
+  <p>This walkthrough creates a complete landing page and deploys it to HubSpot. Estimated time: 5&ndash;10 minutes.</p>
+  <ol class="doc-steps">
+    <li>
+      <strong>Launch vibeSpot.</strong> Run <code>npx vibespot</code> in your terminal. The web UI opens at <code>localhost:4200</code>.
+    </li>
+    <li>
+      <strong>Pick an asset type.</strong> On Project Home you see six asset-type cards. Click <strong>Landing Page</strong>. A prompt input appears with the eyebrow "Landing Page" and a placeholder hint.
+      <img class="doc-screenshot" src="screenshots/asset-type-cards.png" alt="Six asset-type cards on the Project Home screen: Landing Page, Email, Website, Blog Post, From Template, and Import">
+    </li>
+    <li>
+      <strong>Name your project.</strong> Type a kebab-case name (e.g. <code>acme-launch</code>) and press Enter. vibeSpot creates a theme directory at <code>~/vibespot-themes/acme-launch</code> and opens the editor.
+    </li>
+    <li>
+      <strong>Describe the page.</strong> In the chat panel, write a detailed prompt. Include the page purpose, sections, headlines, and design preferences. Example:
+      <pre><code>Build a SaaS landing page for Acme — a project management tool.
+Use a dark navy (#0f172a) and white palette with orange (#f97316) accents.
+Sections: hero with headline "Ship Projects Faster" and a CTA button,
+3-column features grid with icons, pricing table (Free / Pro / Enterprise),
+testimonial carousel, and a minimal footer with social links.</code></pre>
+    </li>
+    <li>
+      <strong>Watch the pipeline.</strong> The four-stage pipeline runs:
+      <ul>
+        <li><strong>Intent Analyzer</strong> &mdash; classifies your request as <code>create</code> and plans which modules to build.</li>
+        <li><strong>Page Architect</strong> &mdash; creates a CSS design system (<code>:root</code> variables, shared styles) and plans module specs.</li>
+        <li><strong>Module Developer</strong> &mdash; generates all modules in parallel. Each module card in the chat panel shows its status: <em>queued</em> &rarr; <em>generating</em> &rarr; <em>complete</em>.</li>
+        <li><strong>Quality Check</strong> &mdash; validates HubL syntax, field names, and meta.json fields; auto-fixes any issues.</li>
+      </ul>
+      The live preview populates incrementally as modules finish. Skeleton placeholders hold the position of modules still generating.
+      <img class="doc-screenshot" src="screenshots/pipeline-progress.png" alt="Pipeline progress cards in the chat panel showing Intent Analyzer complete, Page Architect complete, and Module Developer generating modules in parallel">
+    </li>
+    <li>
+      <strong>Review in the preview.</strong> Once the pipeline completes, the full page renders in the preview panel. Use the responsive toggles (desktop / tablet / mobile) to check the layout at different breakpoints.
+    </li>
+    <li>
+      <strong>Refine with follow-up prompts.</strong> Send targeted messages to iterate:
+      <ul>
+        <li><em>"Change the hero background to a gradient from #0f172a to #1e293b"</em></li>
+        <li><em>"Add a FAQ section with 5 questions after the pricing table"</em></li>
+        <li><em>"Remove the testimonial carousel"</em></li>
+      </ul>
+      The pipeline only regenerates the affected modules; everything else stays intact.
+    </li>
+    <li>
+      <strong>Deploy.</strong> Click the orange <strong>Deploy</strong> button in the topbar. Select your HubSpot account, monitor the upload progress, and click the link in the celebration screen to create a page in HubSpot. See <a href="#first-gen-publish">Publishing to HubSpot</a> below for the full flow.
+    </li>
+  </ol>
+
+  <h3 id="first-gen-email">Email Workflow: Marketing Email from Scratch</h3>
+  <p>vibeSpot generates HubSpot email templates with table-based layout, inline CSS, and Outlook-compatible MSO/VML conditionals. Estimated time: 5&ndash;10 minutes.</p>
+  <ol class="doc-steps">
+    <li>
+      <strong>Choose Email.</strong> On Project Home, click the <strong>Email</strong> asset-type card. The prompt input shows the eyebrow "Email" and a placeholder: <em>"Describe the email you want to create&hellip;"</em>
+    </li>
+    <li>
+      <strong>Name and describe.</strong> Enter a project name (e.g. <code>acme-welcome</code>), then describe the email:
+      <pre><code>Create a welcome email for Acme. Include:
+- Logo header with brand colors
+- Greeting with the recipient's first name
+- 3-step onboarding guide with icons
+- A large "Get Started" CTA button
+- Footer with unsubscribe link and social icons</code></pre>
+    </li>
+    <li>
+      <strong>Pipeline generates email modules.</strong> The same four-stage pipeline runs, but with email-specific prompts at every stage:
+      <ul>
+        <li>The <strong>Email Architect</strong> plans table-based layouts with inline CSS tokens and MSO conditional structure.</li>
+        <li>The <strong>Module Developer</strong> generates email-safe HubL &mdash; no floats, no flexbox, table cells with inline styles.</li>
+        <li>The <strong>Validator</strong> sets <code>host_template_types: ["EMAIL"]</code> in meta.json and skips CSS-prefix fixes (not needed for email).</li>
+      </ul>
+    </li>
+    <li>
+      <strong>Preview across email clients.</strong> Click the <strong>envelope icon</strong> in the topbar to open the email client preview. This renders your email as it would appear in Gmail, Outlook Desktop, and Apple Mail, with heuristic notes for each client (e.g. "Outlook ignores <code>border-radius</code>").
+      <img class="doc-screenshot" src="screenshots/email-client-preview.png" alt="Email client preview overlay showing Gmail, Outlook Desktop, and Apple Mail tabs with the rendered email and rendering notes">
+    </li>
+    <li>
+      <strong>Iterate.</strong> Use the same chat-based workflow to modify sections: <em>"Make the CTA button larger"</em> or <em>"Add a product screenshot below the onboarding steps."</em>
+    </li>
+    <li>
+      <strong>Deploy to HubSpot.</strong> Click <strong>Deploy</strong>. Email templates upload to your HubSpot portal under the theme&rsquo;s <code>templates/</code> directory. In HubSpot, go to <strong>Marketing &rarr; Email &rarr; Create email</strong> and select your template from the theme.
+    </li>
+  </ol>
+
+  <div class="doc-callout doc-callout--tip">
+    <div class="doc-callout__label">Email starter templates</div>
+    <p>For a faster start, pick <strong>From Template</strong> on the Project Home screen. Three email starters are available: Welcome, Announcement, and Newsletter. Each is a pre-built email bundle you can customize immediately.</p>
+  </div>
+
+  <h3 id="first-gen-editing">Editing with the Module Overview</h3>
+  <p>After generation, the <strong>Module Overview</strong> (click the grid icon at the top of the left panel) is your central hub for reviewing and editing every module on the page. Here is a step-by-step editing workflow using the module overview:</p>
+  <ol class="doc-steps">
+    <li>
+      <strong>Open the module overview.</strong> Click the <strong>Modules</strong> button (grid icon with a count badge) at the top of the left panel. The slideout opens, listing every module in page order.
+      <img class="doc-screenshot" src="screenshots/module-overview-slideout.png" alt="Module overview slideout showing a list of modules (Hero, Features Grid, Pricing, Footer) with drag handles, gear icons, and delete buttons">
+    </li>
+    <li>
+      <strong>Reorder modules.</strong> Grab a module by its drag handle (&#x2837;) and move it up or down. The preview updates instantly to reflect the new page order. Recommended flow for landing pages: Navigation &rarr; Hero &rarr; Features &rarr; Social Proof &rarr; Pricing/CTA &rarr; Footer.
+    </li>
+    <li>
+      <strong>Edit fields.</strong> Click the <strong>gear icon</strong> (&#9881;) on any module to open its field editor. The slideout switches to a form generated from the module's <code>fields.json</code>:
+      <ul>
+        <li><strong>Text fields</strong> &mdash; edit headlines, body copy, button labels directly.</li>
+        <li><strong>Color pickers</strong> &mdash; change background colors, text colors, accents.</li>
+        <li><strong>Image fields</strong> &mdash; swap image URLs.</li>
+        <li><strong>Number fields</strong> &mdash; adjust spacing, font sizes.</li>
+        <li><strong>Boolean toggles</strong> &mdash; show/hide optional elements.</li>
+        <li><strong>Choice dropdowns</strong> &mdash; select from predefined options.</li>
+        <li><strong>Groups</strong> &mdash; expand nested field sets (e.g. "Style" groups for padding and colors).</li>
+      </ul>
+      All changes are <strong>debounced at 300ms</strong> and the preview refreshes automatically. No save button needed.
+    </li>
+    <li>
+      <strong>Delete a module.</strong> Click the <strong>&times;</strong> icon on a module and confirm. The module is removed from the current template. If the module is used in other templates, it stays in the library.
+    </li>
+    <li>
+      <strong>Add from library.</strong> Click the <strong>+</strong> button in the module overview header to browse the module library. Select any existing module to add it to the current template without regenerating it.
+    </li>
+  </ol>
+  <p>This workflow works identically for pages and emails. For emails, the module list shows email-specific modules (email-header, email-body, email-footer, etc.) and the preview renders with table-based layout.</p>
+
+  <h3 id="first-gen-publish">Publishing to HubSpot</h3>
+  <p>Once your page or email looks right in the preview, deploy it to your HubSpot portal. This walkthrough covers the full flow from vibeSpot to a live HubSpot page.</p>
+  <ol class="doc-steps">
+    <li>
+      <strong>Connect your HubSpot account (one-time).</strong> Open <strong>Settings &rarr; HubSpot</strong> and click <strong>Add Account</strong>. Paste a Personal Access Key (PAK) from your HubSpot portal (Settings &rarr; Integrations &rarr; Private Apps &rarr; create a key with <strong>CMS</strong> scope). vibeSpot validates the key and detects your portal ID and data center.
+    </li>
+    <li>
+      <strong>Click Deploy.</strong> The orange <strong>Deploy</strong> button is in the top-right of the topbar. vibeSpot writes all files to disk, runs auto-fix on any known HubSpot compatibility issues, then uploads the entire theme: folder structure, shared CSS/JS, all modules, and templates.
+      <img class="doc-screenshot" src="screenshots/deploy-progress.png" alt="Deploy progress panel showing file upload progress bar at 72% with auto-fix log entries and per-file upload status">
+    </li>
+    <li>
+      <strong>Monitor progress.</strong> A progress panel shows:
+      <ul>
+        <li>A progress bar with file count (e.g. "36/50 files")</li>
+        <li>Auto-fix log entries (e.g. "textarea &rarr; text in Hero/fields.json")</li>
+        <li>Per-file upload status with checkmarks</li>
+      </ul>
+      API mode (default) uploads modules in parallel. CLI mode uploads sequentially.
+    </li>
+    <li>
+      <strong>Celebration screen.</strong> On success, a screen with confetti shows a direct link to your HubSpot portal. Click it to jump straight into creating a page.
+    </li>
+    <li>
+      <strong>Create a page in HubSpot.</strong>
+      <ul>
+        <li><strong>For landing pages:</strong> Go to <strong>Content &rarr; Landing Pages &rarr; Create</strong>. Select your vibeSpot theme, pick the template, and you'll see all your modules pre-configured in HubSpot's page editor. Edit content using HubSpot's native editor, then publish.</li>
+        <li><strong>For emails:</strong> Go to <strong>Marketing &rarr; Email &rarr; Create email</strong>. Choose your vibeSpot email template. Modules appear in HubSpot's drag-and-drop email editor with all fields editable. Customize and send.</li>
+      </ul>
+    </li>
+  </ol>
+
+  <div class="doc-callout doc-callout--warning">
+    <div class="doc-callout__label">Upload errors</div>
+    <p>If the upload fails, vibeSpot's auto-fix system scans for known issues (deprecated field types, reserved names, CDN imports) and retries up to 3 times. If auto-fix cannot resolve the error, click <strong>"Fix with AI"</strong> to let the AI diagnose and repair the issue. See <a href="#auto-fix">Auto-Fix</a> for the full list of handled issues.</p>
+  </div>
+
+  <div class="doc-callout doc-callout--info">
+    <div class="doc-callout__label">Email deploy differences</div>
+    <p>Email templates upload the same way as page themes, but the template file includes HubSpot email-specific metadata: <code>templateType: email</code>, MSO/VML namespaces, and <code>dnd_area</code> references so modules appear in HubSpot's email drag-and-drop editor.</p>
+  </div>
+</div>
+
 <!-- ============================================================
      Section 5: AI Generation
      ============================================================ -->
 <div class="doc-section" id="ai-generation">
   <h2 id="ai-generation-heading">AI Generation <a href="#ai-generation" class="doc-anchor">#</a></h2>
-  <p>vibeSpot offers two generation modes: a simpler single-call mode and a more powerful agentic pipeline. The agentic pipeline is the default and recommended mode.</p>
+  <p>vibeSpot offers two generation modes: a simpler single-call mode and a multi-stage agentic pipeline. The agentic pipeline is the default and recommended mode.</p>
 
   <h3 id="single-call">Single-Call Mode</h3>
   <p>In single-call mode, the AI generates all modules in a single API request. The response contains a <code>vibespot-modules</code> JSON code block with all module definitions. This mode is simpler but less reliable for complex pages because the AI must produce all modules in one shot.</p>
@@ -1010,11 +1249,13 @@ vibespot</code></pre>
   </ol>
   <p>This is especially useful for HubL syntax errors, invalid field configurations, or template rendering issues that rule-based auto-fix cannot handle.</p>
 
-  <h3 id="creating-page-hubspot">Creating a Page in HubSpot</h3>
-  <p>After a successful upload, follow these steps in HubSpot to create a live landing page:</p>
+  <h3 id="creating-page-hubspot">Creating a Page or Email in HubSpot</h3>
+  <p>After a successful upload, follow these steps in HubSpot:</p>
+
+  <h4>Landing Pages &amp; Website Pages</h4>
   <ol class="doc-steps">
-    <li><strong>Go to Content &rarr; Landing Pages</strong> in your HubSpot portal.</li>
-    <li><strong>Click "Create"</strong> and select "Landing Page."</li>
+    <li><strong>Go to Content &rarr; Landing Pages</strong> (or Website Pages) in your HubSpot portal.</li>
+    <li><strong>Click "Create"</strong> and select the page type.</li>
     <li><strong>Choose your theme</strong> from the template selector. Your vibeSpot theme appears under your portal's themes.</li>
     <li><strong>Select a template</strong> from the templates you created in vibeSpot.</li>
     <li><strong>Drag modules</strong> from the sidebar into the page layout, or use the pre-configured module order from vibeSpot.</li>
@@ -1022,6 +1263,15 @@ vibespot</code></pre>
     <li><strong>Publish</strong> when ready. Your page is live.</li>
   </ol>
 
+  <h4>Email Templates</h4>
+  <ol class="doc-steps">
+    <li><strong>Go to Marketing &rarr; Email</strong> in your HubSpot portal.</li>
+    <li><strong>Click "Create email"</strong> and choose Regular or Automated.</li>
+    <li><strong>Select your vibeSpot email template</strong> from the template picker. Your email modules are pre-loaded in the HubSpot drag-and-drop email editor.</li>
+    <li><strong>Edit content</strong> &mdash; text, images, CTAs, and all fields you defined in vibeSpot are editable in HubSpot's email editor.</li>
+    <li><strong>Configure recipients, subject line, and send settings</strong>, then send or schedule.</li>
+  </ol>
+
   <h3 id="multi-account">Multi-Account Support</h3>
   <p>vibeSpot supports multiple HubSpot portal connections. This is useful for agencies managing client portals or teams with staging and production environments.</p>
   <ul>
@@ -1045,6 +1295,76 @@ vibespot</code></pre>
   </div>
 </div>
 
+<!-- ============================================================
+     Section: Docker Deployment
+     ============================================================ -->
+<div class="doc-section" id="docker-deployment">
+  <h2 id="docker-deployment-heading">Docker Deployment <a href="#docker-deployment" class="doc-anchor">#</a></h2>
+  <p>Run vibeSpot as a containerised service for your team. The Docker image bundles the server, UI, and all dependencies &mdash; just add an AI API key.</p>
+
+  <h3 id="docker-quick-start">Quick Start (LAN / VPN) <a href="#docker-quick-start" class="doc-anchor">#</a></h3>
+  <pre><code>cp .env.example .env
+# Edit .env &mdash; set at least one AI API key (e.g. ANTHROPIC_API_KEY)
+docker compose up -d</code></pre>
+  <p>Open <code>http://&lt;host-ip&gt;:4200</code> in a browser. All AI keys, engine selection, and HubSpot credentials are configured via the <code>.env</code> file &mdash; no interactive setup needed.</p>
+
+  <h3 id="docker-https">HTTPS with Caddy <a href="#docker-https" class="doc-anchor">#</a></h3>
+  <p>For public or semi-public deployments, activate the Caddy reverse proxy profile. Caddy auto-provisions a TLS certificate from Let&rsquo;s Encrypt.</p>
+  <pre><code>cp .env.example .env
+# Set VIBESPOT_DOMAIN=vibespot.example.com and your AI key
+docker compose --profile https up -d</code></pre>
+  <p>Caddy binds ports 80 and 443. Point your DNS A record at the host, and HTTPS works automatically.</p>
+
+  <h3 id="docker-env-vars">Environment Variables <a href="#docker-env-vars" class="doc-anchor">#</a></h3>
+  <p>The Docker image reads all configuration from environment variables. The <code>.env.example</code> file documents every option.</p>
+
+  <table>
+    <thead>
+      <tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+    </thead>
+    <tbody>
+      <tr><td><code>VIBESPOT_PORT</code></td><td><code>4200</code></td><td>Port the server listens on inside the container</td></tr>
+      <tr><td><code>VIBESPOT_DOMAIN</code></td><td>&mdash;</td><td>Public domain for the Caddy HTTPS profile</td></tr>
+      <tr><td><code>VIBESPOT_NO_OPEN</code></td><td><code>1</code></td><td>Suppress auto-open browser (set automatically in Docker)</td></tr>
+      <tr><td><code>VIBESPOT_AI_ENGINE</code></td><td>&mdash;</td><td>Default engine: <code>anthropic-api</code>, <code>openai-api</code>, <code>gemini-api</code>, <code>langdock-api</code></td></tr>
+      <tr><td><code>VIBESPOT_AGENTIC_MODE</code></td><td>&mdash;</td><td>Set <code>true</code> to enable the multi-stage agentic pipeline</td></tr>
+      <tr><td><code>ANTHROPIC_API_KEY</code></td><td>&mdash;</td><td>Anthropic Claude API key</td></tr>
+      <tr><td><code>OPENAI_API_KEY</code></td><td>&mdash;</td><td>OpenAI API key</td></tr>
+      <tr><td><code>GEMINI_API_KEY</code></td><td>&mdash;</td><td>Google Gemini API key</td></tr>
+      <tr><td><code>LANGDOCK_API_KEY</code></td><td>&mdash;</td><td>Langdock EU gateway key</td></tr>
+      <tr><td><code>HUBSPOT_PERSONAL_ACCESS_KEY</code></td><td>&mdash;</td><td>HubSpot PAK for theme uploads</td></tr>
+      <tr><td><code>FIGMA_TOKEN</code></td><td>&mdash;</td><td>Figma personal access token for design import</td></tr>
+    </tbody>
+  </table>
+
+  <h3 id="docker-persistence">Persistence <a href="#docker-persistence" class="doc-anchor">#</a></h3>
+  <p>Two named Docker volumes keep data across container restarts:</p>
+  <table>
+    <thead>
+      <tr><th>Volume</th><th>Container path</th><th>Contents</th></tr>
+    </thead>
+    <tbody>
+      <tr><td><code>vibespot-config</code></td><td><code>/home/vibespot/.vibespot</code></td><td>config.json, session data</td></tr>
+      <tr><td><code>vibespot-themes</code></td><td><code>/home/vibespot/vibespot-themes</code></td><td>Generated HubSpot themes</td></tr>
+    </tbody>
+  </table>
+  <p>To back up:</p>
+  <pre><code>docker compose cp vibespot:/home/vibespot/.vibespot ./backup-config
+docker compose cp vibespot:/home/vibespot/vibespot-themes ./backup-themes</code></pre>
+
+  <h3 id="docker-reverse-proxy">Reverse Proxy &amp; Kubernetes <a href="#docker-reverse-proxy" class="doc-anchor">#</a></h3>
+  <p>If you already have a reverse proxy (nginx, Traefik, k8s Ingress), skip the Caddy profile and point your proxy at port 4200. Key requirements:</p>
+  <ul>
+    <li><strong>WebSocket upgrade</strong> &mdash; the chat, pipeline progress, and upload UI all use a persistent WebSocket connection.</li>
+    <li><strong>Timeout &gt; 120s</strong> &mdash; agentic AI generation can run for several minutes. Set read/send timeouts to at least 300s.</li>
+    <li><strong>No buffering</strong> &mdash; for streaming AI responses, disable proxy buffering.</li>
+  </ul>
+  <div class="doc-callout doc-callout--tip">
+    <div class="doc-callout__label">&#128214; Full guide</div>
+    <p>For nginx configs, Kubernetes manifests, security considerations, and troubleshooting, see the complete <a href="https://github.com/borismichel/vibespot/blob/main/docs/docker-deployment.md" target="_blank">Docker Deployment Guide</a>.</p>
+  </div>
+</div>
+
 <!-- ============================================================
      Section: HubSpot Marketplace publication path
      ============================================================ -->