vibespot 1.2.0 → 1.3.0

package/ui/docs/docs.css

@@ -975,3 +975,32 @@ kbd {
   h1 { font-size: 1.5rem; }
   h2 { font-size: 1.2rem; }
 }
+
+/* ================================================================
+   Screenshot Placeholders
+   Shown until real screenshots are added by the UX team.
+   Replace with <img class="doc-screenshot" src="..." alt="...">
+   ================================================================ */
+.doc-screenshot-placeholder {
+  margin: 20px 0 28px;
+  padding: 40px 24px;
+  border: 2px dashed var(--doc-border-strong);
+  border-radius: var(--doc-radius-lg);
+  background: var(--doc-bg-card);
+  text-align: center;
+}
+.doc-screenshot-placeholder p {
+  color: var(--doc-text-muted);
+  font-size: 13px;
+  font-style: italic;
+  margin: 0;
+}
+
+.doc-screenshot {
+  margin: 20px 0 28px;
+  border: 1px solid var(--doc-border-strong);
+  border-radius: var(--doc-radius-lg);
+  max-width: 100%;
+  height: auto;
+  display: block;
+}

package/ui/docs/index.html

@@ -59,12 +59,16 @@
     <span class="doc-nav__heading">Using vibeSpot</span>
     <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="#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>
     <a class="doc-nav__link doc-nav__link--sub" href="#module-sidebar">Modules</a>
     <a class="doc-nav__link" href="#creating-pages">Creating Pages</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#onboarding">Onboarding</a>
     <a class="doc-nav__link doc-nav__link--sub" href="#first-page">Your First Page</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#content-types">Content Types</a>
+    <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>
   </div>
@@ -87,8 +91,12 @@
     <a class="doc-nav__link doc-nav__link--sub" href="#figma-image-modes">Image Modes</a>
     <a class="doc-nav__link doc-nav__link--sub" href="#figma-pipeline">Translation Pipeline</a>
     <a class="doc-nav__link doc-nav__link--sub" href="#figma-tips">Tips &amp; Limits</a>
+    <a class="doc-nav__link" href="#inverse-pipeline">Inverse Pipeline</a>
     <a class="doc-nav__link" href="#editing">Editing &amp; Customization</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#inline-wysiwyg">Inline Editing</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#visual-controls">Visual Controls</a>
     <a class="doc-nav__link doc-nav__link--sub" href="#field-editor">Field Editor</a>
+    <a class="doc-nav__link doc-nav__link--sub" href="#brand-kit">Brand Kit</a>
     <a class="doc-nav__link doc-nav__link--sub" href="#design-system">Design System</a>
   </div>
 
@@ -109,6 +117,7 @@
     <a class="doc-nav__link doc-nav__link--sub" href="#settings-hubspot">HubSpot Tab</a>
     <a class="doc-nav__link doc-nav__link--sub" href="#settings-figma">Figma Tab</a>
     <a class="doc-nav__link" href="#cli-commands">CLI Commands</a>
+    <a class="doc-nav__link" href="#hubspot-glossary">HubSpot Terminology</a>
     <a class="doc-nav__link" href="#shortcuts">Shortcuts</a>
     <a class="doc-nav__link" href="#troubleshooting">Troubleshooting</a>
   </div>
@@ -349,117 +358,28 @@ vibespot</code></pre>
   <p>The vibeSpot editor is a browser-based environment for building HubSpot CMS pages. It combines a chat-driven AI assistant with a live preview and code editing capabilities.</p>
 
   <h3 id="editor-layout">Layout Overview</h3>
+  <p>vibeSpot uses a <strong>two-mode architecture</strong>: <strong>Project Home</strong> for project selection and setup, and <strong>Editor</strong> for building pages. The active mode is controlled by a <code>data-mode</code> attribute and switches automatically when you open a project.</p>
   <p>The editor has three main panels separated by a draggable resize handle:</p>
   <ul>
     <li><strong>Left panel</strong> (380px default) &mdash; Contains a module bar button at the top (click to open the module slideout) and the chat interface below it. The module slideout overlays the chat when open. The chat header shows the template name and active AI engine.</li>
     <li><strong>Resize handle</strong> &mdash; A 4px draggable divider between panels. Turns orange on hover. Drag to resize the left/right split. The left panel has a minimum width of 300px and maximum of 600px.</li>
-    <li><strong>Right panel</strong> (fills remaining space) &mdash; Live preview of the rendered page (default) or the code editor (toggle via the Preview/Code tabs). The preview includes browser chrome with dots and a URL bar.</li>
+    <li><strong>Right panel</strong> (fills remaining space) &mdash; Live preview of the rendered page (default), or toggle between Preview, Split, Plan, and Code views. The preview includes a slim browser chrome bar with dots and a URL display.</li>
   </ul>
+  <p>On <strong>tablet</strong> viewports (768&ndash;1024px), the project rail collapses to a 48px icon-only width, the chat panel narrows, and topbar labels hide to prevent clipping. On viewports <strong>below 768px</strong>, a responsive gate dialog is shown &mdash; the full editor requires a wider screen.</p>
 
-  <!-- Editor Layout Mockup -->
-  <div class="doc-mockup">
-    <div class="mock-topbar">
-      <span class="mock-topbar__back">&lsaquo;</span>
-      <span class="mock-topbar__pill">my-startup</span>
-      <span class="mock-topbar__spacer"></span>
-      <div class="mock-topbar__responsive">
-        <span class="active" title="Desktop">&#9633;</span><span title="Tablet">&#9645;</span><span title="Mobile">&#9647;</span>
-      </div>
-      <span class="mock-topbar__spacer"></span>
-      <span class="mock-topbar__btn" title="Feedback">&#128172;</span>
-      <span class="mock-topbar__btn" title="Theme toggle">&#9788;</span>
-      <span class="mock-topbar__btn" title="Version history">&#128339;</span>
-      <span class="mock-topbar__btn mock-topbar__btn--accent">&#8593; Deploy</span>
-    </div>
-    <div class="mock-editor">
-      <div class="mock-editor__left">
-        <div class="mock-modules">
-          <div class="mock-modules__header"><span style="display:flex;align-items:center;gap:6px">&#9638;&#9638; Modules</span> <span class="mock-modules__count">5</span></div>
-          <div class="mock-module-item"><span class="mock-module-item__grip">&#8942;&#8942;</span><span class="mock-module-item__name">Navigation Bar</span><span class="mock-module-item__actions"><span class="mock-module-item__action" title="Edit fields">&#9998;</span><span class="mock-module-item__action" title="Delete">&times;</span></span></div>
-          <div class="mock-module-item"><span class="mock-module-item__grip">&#8942;&#8942;</span><span class="mock-module-item__name">Hero Banner</span><span class="mock-module-item__actions"><span class="mock-module-item__action">&#9998;</span><span class="mock-module-item__action">&times;</span></span></div>
-          <div class="mock-module-item"><span class="mock-module-item__grip">&#8942;&#8942;</span><span class="mock-module-item__name">Features Grid</span><span class="mock-module-item__actions"><span class="mock-module-item__action">&#9998;</span><span class="mock-module-item__action">&times;</span></span></div>
-          <div class="mock-module-item"><span class="mock-module-item__grip">&#8942;&#8942;</span><span class="mock-module-item__name">Pricing Cards</span><span class="mock-module-item__actions"><span class="mock-module-item__action">&#9998;</span><span class="mock-module-item__action">&times;</span></span></div>
-          <div class="mock-module-item"><span class="mock-module-item__grip">&#8942;&#8942;</span><span class="mock-module-item__name">Footer</span><span class="mock-module-item__actions"><span class="mock-module-item__action">&#9998;</span><span class="mock-module-item__action">&times;</span></span></div>
-        </div>
-        <div class="mock-chat">
-          <div style="display:flex;align-items:center;justify-content:space-between;padding:8px 10px;border-bottom:1px solid var(--doc-border)">
-            <span style="font-size:11px;font-weight:600;color:var(--doc-text-dim)">Chat</span>
-            <span style="font-size:10px;color:var(--doc-text-muted)">Claude (OAuth)</span>
-          </div>
-          <div class="mock-chat__messages">
-            <div class="mock-chat__msg mock-chat__msg--user"><span class="mock-chat__avatar">Y</span><div class="mock-chat__bubble">Build a SaaS landing page for an AI writing tool. Dark theme, modern.</div></div>
-            <div class="mock-chat__msg mock-chat__msg--ai"><span class="mock-chat__avatar">AI</span>
-              <div class="mock-chat__pipeline">
-                <div class="mock-chat__step">&#10004; Analyzing your request...</div>
-                <div class="mock-chat__step">&#10004; Creating design system...</div>
-                <div class="mock-chat__step">&#10004; Generating 5 modules...</div>
-                <div class="mock-chat__step">&#10004; Quality check...</div>
-                <div class="mock-chat__module-cards">
-                  <span class="mock-chat__module-card mock-chat__module-card--done">&#10004; Navigation</span>
-                  <span class="mock-chat__module-card mock-chat__module-card--done">&#10004; Hero</span>
-                  <span class="mock-chat__module-card mock-chat__module-card--done">&#10004; Features</span>
-                  <span class="mock-chat__module-card mock-chat__module-card--done">&#10004; Pricing</span>
-                  <span class="mock-chat__module-card mock-chat__module-card--done">&#10004; Footer</span>
-                </div>
-                <div style="color:var(--doc-green);margin-top:4px;font-size:10px">Generated 5 modules in 42s</div>
-              </div>
-            </div>
-            <div class="mock-chat__msg mock-chat__msg--user"><span class="mock-chat__avatar">Y</span><div class="mock-chat__bubble">Make the hero headline bigger and add a gradient.</div></div>
-            <div class="mock-chat__msg mock-chat__msg--ai"><span class="mock-chat__avatar">AI</span>
-              <div class="mock-chat__pipeline">
-                <div class="mock-chat__step">&#10004; Analyzing your request...</div>
-                <div class="mock-chat__step mock-chat__step--active">&#10227; Generating 1 module...</div>
-                <div class="mock-chat__module-cards">
-                  <span class="mock-chat__module-card mock-chat__module-card--active">Hero Banner generating...</span>
-                </div>
-                <div style="color:var(--doc-text-muted);margin-top:4px;font-size:10px">14s</div>
-              </div>
-            </div>
-          </div>
-          <div class="mock-chat__input">
-            <span style="color:var(--doc-text-muted);font-size:13px;cursor:pointer" title="Attach file">&#128206;</span>
-            <input class="mock-chat__input-field" placeholder="Describe your landing page..." disabled>
-            <span style="color:var(--doc-text-muted);font-size:12px;cursor:pointer" title="Starter templates">&#9638;&#9638;</span>
-            <span class="mock-chat__input-btn">&#9654;</span>
-          </div>
-        </div>
-      </div>
-      <div class="mock-editor__resize" title="Drag to resize panels"></div>
-      <div class="mock-editor__right">
-        <div class="mock-preview">
-          <div class="mock-preview__tabs"><span class="mock-preview__tab active">Preview</span><span class="mock-preview__tab">Plan</span><span class="mock-preview__tab">Code</span></div>
-          <div class="mock-preview__chrome">
-            <div class="mock-preview__dots"><span class="mock-preview__dot"></span><span class="mock-preview__dot"></span><span class="mock-preview__dot"></span></div>
-            <div class="mock-preview__url">my-startup.vibespot.app</div>
-          </div>
-          <div class="mock-preview__body">
-            <div class="mock-preview__section" style="background:rgba(255,255,255,0.02);padding:6px 14px;display:flex;justify-content:space-between;font-size:10px">
-              <span style="font-weight:600;color:var(--doc-text)">WriteAI</span>
-              <span style="color:var(--doc-text-muted)">Features &middot; Pricing &middot; About</span>
-            </div>
-            <div class="mock-preview__section mock-preview__hero">
-              <div class="mock-preview__hero-title">Write Better. Faster.</div>
-              <div class="mock-preview__hero-sub">AI-powered writing assistant for teams that ship.</div>
-              <span class="mock-preview__hero-btn">Start Free Trial</span>
-            </div>
-            <div class="mock-preview__cards">
-              <div class="mock-preview__card"><div class="mock-preview__card-title">Smart Drafts</div><div class="mock-preview__card-text">Generate first drafts in seconds</div></div>
-              <div class="mock-preview__card"><div class="mock-preview__card-title">Team Collab</div><div class="mock-preview__card-text">Real-time editing with your team</div></div>
-              <div class="mock-preview__card"><div class="mock-preview__card-title">Brand Voice</div><div class="mock-preview__card-text">Consistent tone across all content</div></div>
-            </div>
-          </div>
-        </div>
-      </div>
-    </div>
-    <div class="mock-statusbar">
-      <span>Connected</span>
-      <span class="mock-statusbar__spacer"></span>
-      <span class="mock-statusbar__dot"></span>
-      <span>ALCMST (144870572)</span>
-      <span class="mock-statusbar__spacer"></span>
-      <span>Claude (OAuth)</span>
-    </div>
-  </div>
+  <h3 id="workspace-tabs">Workspace Tabs</h3>
+  <p>The Project Home dashboard is organized into workspace tabs, each covering a distinct concern:</p>
+  <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>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">
 
   <p>The topbar provides access to theme settings, upload, version history, responsive viewport toggle, and the settings gear.</p>
 
@@ -476,14 +396,19 @@ 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 chat suggests four starter templates on an empty theme:</p>
+  <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>
   <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>
     <li><strong>Restaurant</strong> &mdash; Hero with imagery, menu sections, reservation CTA, location map, hours</li>
     <li><strong>Event / Conference</strong> &mdash; Event hero with date, speakers, schedule, sponsors, registration CTA</li>
+    <li><strong>Coming Soon</strong> &mdash; Countdown hero, email signup, teaser content</li>
+    <li><strong>Blog Content Hub</strong> &mdash; 8-module blog layout with post body, author bio, related posts, sidebar, and navigation</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>
+
   <h3 id="preview-panel">Preview Panel</h3>
   <p>The preview panel renders your page using a local HubL subset renderer. It supports variables, conditionals, loops, filters, <code>scope_css</code>, and <code>require_css</code>/<code>require_js</code> tags. The preview automatically refreshes when modules are updated.</p>
   <p>Use the responsive toggle buttons in the topbar to switch viewports:</p>
@@ -494,6 +419,19 @@ vibespot</code></pre>
   </ul>
   <p>During AI generation, modules that are being regenerated show a working overlay with a progress indicator. Modules that have already been generated remain visible and interactive.</p>
 
+  <h4 id="split-view">Split View</h4>
+  <p>Click the <strong>Split</strong> button in the view toggle to show the live preview and code editor side by side in a 50/50 CSS grid layout. This is useful when you want to see how code changes affect the preview in real time. Switching between Preview, Split, Plan, and Code views is fully coordinated.</p>
+
+  <img class="doc-screenshot" src="screenshots/split-pane-view.png" alt="Split-pane view with live preview on the left and code editor on the right">
+
+  <h4 id="interact-mode">Interact Mode</h4>
+  <p>The <strong>Interact</strong> toggle in the preview topbar replaces the previous separate Select and Edit modes with a single contextual mode. When active:</p>
+  <ul>
+    <li><strong>Editable elements</strong> (text, images, links) &mdash; get inline WYSIWYG editing. Click to edit directly in the preview; changes persist via the API.</li>
+    <li><strong>Module containers</strong> &mdash; prefill the chat input with a contextual reference so you can describe what you want to change.</li>
+  </ul>
+  <p>Interact mode auto-deactivates during AI generation and uses a crosshair cursor to distinguish it from normal preview interaction.</p>
+
   <h3 id="code-editor">Code Editor</h3>
   <p>Switch to the code editor tab to directly edit module files. The file tree is grouped by module name, and each module contains:</p>
   <ul>
@@ -587,6 +525,17 @@ vibespot</code></pre>
     <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>
   </ul>
 
+  <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>
+  <ol class="doc-steps">
+    <li><strong>What is vibeSpot?</strong> &mdash; A brief intro to the product and what it does.</li>
+    <li><strong>How it maps to HubSpot</strong> &mdash; Sections become modules, design tokens become <code>:root</code> CSS variables, a project becomes a CMS theme.</li>
+    <li><strong>Try it</strong> &mdash; A pre-filled sample prompt lands in the setup textarea so you can start building immediately.</li>
+  </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">
@@ -605,12 +554,36 @@ vibespot</code></pre>
     <p><strong>Event:</strong> "Design a tech conference page for DevSummit 2026. Hero with event date and location, speaker grid with photos, 2-day schedule in tabs, sponsor logos, and early-bird registration CTA."</p>
   </div>
 
+  <h3 id="content-types">Content Types</h3>
+  <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>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>
+
+  <img class="doc-screenshot" src="screenshots/content-type-dropdown.png" alt="Page type dropdown showing Landing Page, Email, Website, and Blog Post options">
+
+  <h3 id="multi-page">Multi-Page Sites</h3>
+  <p>vibeSpot can create full multi-page HubSpot sites from a single prompt. When the intent analyzer detects a site-level request (e.g. "build a 5-page website for a restaurant"), it uses the <code>create_site</code> intent to plan:</p>
+  <ul>
+    <li><strong>Shared modules</strong> &mdash; header and footer modules used across all pages</li>
+    <li><strong>Per-page layouts</strong> &mdash; each page gets its own template with unique modules, a label, page type, and slug</li>
+    <li><strong>Cross-page navigation</strong> &mdash; nav links between pages are validated to ensure they match actual page slugs</li>
+  </ul>
+  <p>In the editor, a <strong>page tree sidebar</strong> replaces the old horizontal tab bar. It shows all templates with type badges (LP, Blog, Web, Sec), labels, and module counts. Click a page to switch to it &mdash; the chat, modules, and preview reload for that template. An inline creation form lets you add new pages with a type selector.</p>
+  <p><strong>Page-scoped chat</strong> means the intent analyzer knows which page you're editing, enabling prompts like "same header as the home page" or "update all pages." The AI context includes <code>activePageLabel</code> and the full list of site pages.</p>
+
+  <img class="doc-screenshot" src="screenshots/multi-page-tree.png" alt="Page tree sidebar showing Landing Page, About Us, and Company Blog with type badges and module counts">
+
   <h3 id="templates">Templates</h3>
   <p>Each theme can contain multiple templates. Templates define different page layouts that share the same module library and design system.</p>
   <p>Supported page types:</p>
   <ul>
     <li><strong>Landing Page</strong> &mdash; The default. Full-width marketing pages.</li>
-    <li><strong>Blog Post</strong> &mdash; Content-focused layout with sidebar.</li>
+    <li><strong>Email</strong> &mdash; Table-based email templates with MSO/VML compatibility.</li>
+    <li><strong>Blog Post</strong> &mdash; Content-focused layout with HubSpot blog variable support.</li>
     <li><strong>Website Page</strong> &mdash; Standard pages for your site (About, Contact, etc.).</li>
     <li><strong>Module Only</strong> &mdash; Generate standalone modules without a page template.</li>
   </ul>
@@ -694,6 +667,7 @@ vibespot</code></pre>
       <tr><td><code>remove</code></td><td>Delete a module from the page</td><td>"Remove the testimonials section"</td></tr>
       <tr><td><code>rearrange</code></td><td>Reorder existing modules without changing their content</td><td>"Move the CTA section above the footer"</td></tr>
       <tr><td><code>style_change</code></td><td>Update the design system or shared CSS without module changes</td><td>"Change the primary color to green and increase font sizes"</td></tr>
+      <tr><td><code>create_site</code></td><td>Generate a full multi-page site with shared modules</td><td>"Build a 5-page restaurant website with Home, Menu, About, Gallery, and Contact"</td></tr>
       <tr><td><code>question</code></td><td>Ask about the page, modules, or HubSpot features (no generation)</td><td>"What modules does this page have?"</td></tr>
     </tbody>
   </table>
@@ -860,12 +834,63 @@ vibespot</code></pre>
   </div>
 </div>
 
+<!-- ============================================================
+     Section: Inverse Pipeline (HubSpot → vibeSpot)
+     ============================================================ -->
+<div class="doc-section" id="inverse-pipeline">
+  <h2 id="inverse-pipeline-heading">Inverse Pipeline (HubSpot &rarr; vibeSpot) <a href="#inverse-pipeline" class="doc-anchor">#</a></h2>
+  <p class="doc-subtitle">Reverse-engineer an imported HubSpot theme so the AI understands its design system, module relationships, and round-trip risks before generating modifications.</p>
+
+  <p>When you import a theme via <strong>From HubSpot</strong>, vibeSpot downloads the files and loads modules into a session. The inverse pipeline goes further: it analyzes the theme's CSS, templates, and field schemas to extract structured context that the AI uses when generating additions or modifications.</p>
+
+  <h3 id="inverse-what">What Gets Analyzed</h3>
+  <ul>
+    <li><strong>Design tokens</strong> &mdash; <code>:root</code> CSS variables, inferred color palette (with usage counts), typography scale (family, size, weight per role), spacing tokens, border radii, and shadows. These are extracted from both the theme-level CSS and per-module stylesheets.</li>
+    <li><strong>Module relationship graph</strong> &mdash; Which modules appear in which templates, shared field patterns across modules, and orphan modules (defined but unused by any template).</li>
+    <li><strong>Field schema flags</strong> &mdash; Patterns that vibeSpot doesn't natively generate: HubDB bindings, deeply nested groups, repeater occurrence limits, custom widget types, conditional visibility rules. These are flagged so the AI avoids breaking them.</li>
+    <li><strong>Round-trip risks</strong> &mdash; HubL macros, <code>{% raw %}</code> blocks, partials outside <code>modules/</code>, custom <code>module.js</code> files, and <code>import_modules.json</code> references. These patterns survive the round-trip but need preservation &mdash; the AI is told not to touch them.</li>
+  </ul>
+
+  <h3 id="inverse-tokens">Design Token Application</h3>
+  <p>If the imported theme has no <code>:root</code> variables (common in older themes), the inverse analyzer can synthesize a <code>:root</code> block from the inferred palette and typography, populating <code>sharedCss</code> so the AI generates new modules that visually match the existing ones. Use the <strong>Apply tokens</strong> action in the UI or <code>vibespot inverse --apply-tokens</code> from the CLI.</p>
+
+  <h3 id="inverse-access">How to Access</h3>
+  <ul>
+    <li><strong>UI</strong> &mdash; After fetching a theme via <strong>From HubSpot</strong>, the import wizard shows the analysis results (tokens, module graph, risks) before you enter the editor.</li>
+    <li><strong>CLI</strong> &mdash; <code>vibespot inverse [--path &lt;theme-dir&gt;] [--json] [--apply-tokens]</code>. Without <code>--path</code>, it uses the active theme.</li>
+    <li><strong>API</strong> &mdash; <code>GET /api/inverse/analyze</code> and <code>POST /api/inverse/apply-tokens</code> routes in the web server.</li>
+  </ul>
+</div>
+
 <!-- ============================================================
      Section 6: Editing & Customization
      ============================================================ -->
 <div class="doc-section" id="editing">
   <h2 id="editing-heading">Editing &amp; Customization <a href="#editing" class="doc-anchor">#</a></h2>
-  <p>After AI generation, you have full control over every aspect of your page. vibeSpot provides three editing paths depending on your needs.</p>
+  <p>After AI generation, you have full control over every aspect of your page. vibeSpot provides multiple editing paths depending on your needs &mdash; from clicking directly in the preview to editing raw code.</p>
+
+  <h3 id="inline-wysiwyg">Inline WYSIWYG Editing</h3>
+  <p>The most direct way to edit your page. With <a href="#interact-mode">Interact mode</a> active, click text, images, or links directly in the live preview to edit them inline:</p>
+  <ul>
+    <li><strong>Text</strong> &mdash; Click any text element to get a contenteditable field. Type your changes and click away to save.</li>
+    <li><strong>Images</strong> &mdash; Click an image to swap the URL.</li>
+    <li><strong>Links</strong> &mdash; Click a link to edit both the text and the href in a popup.</li>
+  </ul>
+  <p>Changes persist via <code>/api/field</code> and refresh the preview automatically. Server-side field annotations (<code>annotateFieldRefs</code>) provide deterministic click-to-field mapping so the correct field is always updated. Interact mode is mutually exclusive with normal preview scrolling and disables during AI generation.</p>
+
+  <img class="doc-screenshot" src="screenshots/inline-wysiwyg-editing.png" alt="Editing a headline directly in the live preview via inline WYSIWYG — the text is selected with a blue highlight">
+
+  <h3 id="visual-controls">Per-Section Visual Controls</h3>
+  <p>Hover over any module section in the preview pane to reveal a floating toolbar with visual controls mapped to the module's fields:</p>
+  <ul>
+    <li><strong>Color picker</strong> &mdash; for color fields (background, text color, accent)</li>
+    <li><strong>Padding/margin sliders</strong> &mdash; for spacing fields</li>
+    <li><strong>Image URL swap</strong> &mdash; for image fields</li>
+    <li><strong>Font size selector</strong> &mdash; for text-size number fields</li>
+  </ul>
+  <p>All changes persist via <code>/api/field</code> with debounced saves and the preview refreshes on popover close. This is the fastest path for visual adjustments without touching a form or code.</p>
+
+  <img class="doc-screenshot" src="screenshots/visual-controls-toolbar.png" alt="Interact mode showing a Click to edit tooltip and dashed selection border over a module section">
 
   <h3 id="field-editor">No-Code Field Editing</h3>
   <p>The fastest way to tweak content. Open the module slideout (click the <strong>Modules</strong> button), then click the gear icon (&#9881;) on any module. The slideout switches to the field editor view with a form generated from the module's <code>fields.json</code>. See <a href="#field-editor-sidebar">Field Editor controls</a> for the full list of supported field types.</p>
@@ -886,6 +911,17 @@ vibespot</code></pre>
   <p>Module order in the slideout list equals page order. Open the module slideout and drag items by their grip handle (&#x2837;) to rearrange. The preview updates immediately.</p>
   <p>Recommended landing page flow: Navigation &rarr; Hero &rarr; Features/Content &rarr; Social Proof &rarr; CTA/Pricing &rarr; Footer.</p>
 
+  <h3 id="brand-kit">Brand Kit</h3>
+  <p>The <strong>Brand</strong> workspace tab provides a structured brand kit that persists as <code>brand-kit.json</code> in <code>.vibespot/</code>. Configure:</p>
+  <ul>
+    <li><strong>Colors</strong> &mdash; primary, secondary, and accent colors via color pickers</li>
+    <li><strong>Fonts</strong> &mdash; heading and body font families</li>
+    <li><strong>Logo URL</strong> &mdash; your logo image reference</li>
+  </ul>
+  <p>A <strong>live preview card</strong> above the form shows color swatches, sample heading and body text rendered with your configured fonts, and a logo thumbnail. Brand kit values are injected as mandatory design constraints into the email architect, email module developer, and page architect prompts. The validator warns on off-brand colors and fonts in generated modules.</p>
+
+  <img class="doc-screenshot" src="screenshots/brand-kit-preview.png" alt="Brand tab showing live preview card with color swatches, sample heading and body text, color inputs, and font selectors">
+
   <h3 id="design-system">Design System</h3>
   <p>The agentic pipeline generates a consistent design system stored in the theme's shared CSS:</p>
   <ul>
@@ -1243,10 +1279,12 @@ vibespot</code></pre>
     </thead>
     <tbody>
       <tr><td><code>vibespot</code></td><td>Start the web UI (default)</td></tr>
+      <tr><td><code>vibespot email</code></td><td>Start in email template mode</td></tr>
       <tr><td><code>vibespot wizard</code></td><td>Interactive CLI wizard</td></tr>
       <tr><td><code>vibespot init</code></td><td>Environment check &amp; setup</td></tr>
       <tr><td><code>vibespot convert</code></td><td>React-to-HubSpot conversion</td></tr>
       <tr><td><code>vibespot upload</code></td><td>Upload theme to HubSpot</td></tr>
+      <tr><td><code>vibespot inverse</code></td><td>Analyze an imported theme (design tokens, module graph, risks)</td></tr>
       <tr><td><code>vibespot marketplace check</code></td><td>Audit a theme against HubSpot Marketplace requirements</td></tr>
       <tr><td><code>vibespot marketplace edit</code></td><td>Edit Marketplace listing metadata (<code>marketplace.json</code>)</td></tr>
       <tr><td><code>vibespot doctor</code></td><td>Diagnostics &amp; health check</td></tr>
@@ -1321,6 +1359,18 @@ vibespot</code></pre>
     </div>
   </div>
 
+  <div class="doc-collapse">
+    <button class="doc-collapse__trigger">
+      <span class="doc-collapse__arrow">&#9654;</span>
+      <code>vibespot inverse</code> &mdash; Analyze Imported Theme
+    </button>
+    <div class="doc-collapse__content">
+      <p>Runs the inverse analyzer on an imported HubSpot theme, extracting design tokens, module relationship graph, field schema flags, and round-trip risks. See <a href="#inverse-pipeline">Inverse Pipeline</a> for details on what gets analyzed.</p>
+      <pre><code>vibespot inverse [--path &lt;theme-dir&gt;] [--json] [--apply-tokens]</code></pre>
+      <p>Without <code>--path</code>, uses the active theme. <code>--json</code> outputs the full report as JSON. <code>--apply-tokens</code> synthesizes a <code>:root</code> CSS block from inferred tokens and writes it to the theme's <code>sharedCss</code>.</p>
+    </div>
+  </div>
+
   <div class="doc-collapse">
     <button class="doc-collapse__trigger">
       <span class="doc-collapse__arrow">&#9654;</span>
@@ -1334,6 +1384,32 @@ vibespot</code></pre>
   </div>
 </div>
 
+<!-- ============================================================
+     Section 10b: HubSpot Glossary
+     ============================================================ -->
+<div class="doc-section" id="hubspot-glossary">
+  <h2 id="hubspot-glossary-heading">HubSpot Terminology <a href="#hubspot-glossary" class="doc-anchor">#</a></h2>
+  <p>vibeSpot generates native HubSpot CMS assets, so most things in the UI map 1:1 to a HubSpot concept. Where a vibeSpot label differs from HubSpot's official vocabulary, this glossary calls it out so you know what to look for inside HubSpot.</p>
+
+  <table>
+    <thead>
+      <tr><th>vibeSpot label</th><th>HubSpot term</th><th>What it is</th></tr>
+    </thead>
+    <tbody>
+      <tr><td>Project</td><td><strong>Theme</strong></td><td>One vibeSpot project produces one HubSpot theme. The theme name in the topbar pill is the folder uploaded to HubSpot's Design Manager.</td></tr>
+      <tr><td>Module / Modules</td><td><strong>Module</strong></td><td>A reusable building block (hero, CTA, pricing table, etc.) with its own <code>fields.json</code>, <code>module.html</code>, and CSS. Earlier vibeSpot copy called these &ldquo;sections&rdquo; &mdash; this is the same thing.</td></tr>
+      <tr><td>Module Library</td><td><strong>Module library</strong> (theme)</td><td>All reusable modules in the active theme. In HubSpot's Design Manager this is the <code>modules/</code> folder.</td></tr>
+      <tr><td>Module Only (page type)</td><td><strong>Section template</strong> / standalone module</td><td>A single-module template &mdash; useful for building one reusable section (e.g. a hero) that can be dropped into any page.</td></tr>
+      <tr><td>Pages</td><td><strong>Templates &amp; Pages</strong></td><td>Each entry under Pages is a HubSpot template (Landing Page, Website Page, Blog Post). Once deployed, you can spin up multiple HubSpot pages from one template.</td></tr>
+      <tr><td>Brand &rarr; Brand Kit</td><td><strong>Brand Kit</strong></td><td>Colors, fonts, and logo applied to every generated module. Mirrors HubSpot's Brand Kit in the portal.</td></tr>
+      <tr><td>Library tab</td><td><strong>Module library</strong></td><td>The Library workspace tab shows reusable modules across all pages of the active theme.</td></tr>
+      <tr><td>Marketplace</td><td><strong>HubSpot Marketplace</strong></td><td>Validates the theme against marketplace requirements before publication.</td></tr>
+      <tr><td>Fields</td><td><strong>Module fields</strong></td><td>The editable inputs on a module (text, image, choice, etc.) backed by <code>fields.json</code>.</td></tr>
+      <tr><td>Deploy</td><td><strong>Upload theme</strong></td><td>Pushes the theme folder to HubSpot's Design Manager via the CMS API.</td></tr>
+    </tbody>
+  </table>
+</div>
+
 <!-- ============================================================
      Section 11: Keyboard Shortcuts
      ============================================================ -->
@@ -1349,6 +1425,8 @@ vibespot</code></pre>
       <tr><td><kbd>Shift</kbd>+<kbd>Enter</kbd></td><td>New line</td><td>Chat input</td></tr>
       <tr><td><kbd>Cmd</kbd>/<kbd>Ctrl</kbd>+<kbd>S</kbd></td><td>Save file</td><td>Code editor</td></tr>
       <tr><td><kbd>Escape</kbd></td><td>Close modal or dialog</td><td>Any overlay</td></tr>
+      <tr><td><kbd>Cmd</kbd>/<kbd>Ctrl</kbd>+<kbd>Z</kbd></td><td>Step back one version</td><td>Editor (not in text fields)</td></tr>
+      <tr><td><kbd>Cmd</kbd>/<kbd>Ctrl</kbd>+<kbd>Y</kbd> or <kbd>Shift</kbd>+<kbd>Z</kbd></td><td>Step forward one version</td><td>Editor (not in text fields)</td></tr>
       <tr><td><kbd>Escape</kbd></td><td>Close settings panel</td><td>Settings panel</td></tr>
       <tr><td><kbd>/</kbd></td><td>Focus search</td><td>Documentation</td></tr>
     </tbody>

package/ui/email-preview.js

@@ -0,0 +1,109 @@
+/**
+ * Email client preview — heuristic rendering for Gmail, Outlook Desktop, Apple Mail.
+ * Only visible in email content mode.
+ */
+
+(function () {
+  const overlay = document.getElementById("email-preview-overlay");
+  const closeBtn = document.getElementById("email-preview-close");
+  const openBtn = document.getElementById("btn-email-preview");
+  const tabsContainer = document.getElementById("email-preview-tabs");
+  const frame = document.getElementById("email-preview-frame");
+  const notesEl = document.getElementById("email-preview-notes");
+
+  if (!overlay || !frame) return;
+
+  let cachedPreviews = null;
+  let activeClient = "gmail";
+
+  function showPreview(client) {
+    activeClient = client;
+    tabsContainer.querySelectorAll(".email-preview-tab").forEach(function (btn) {
+      btn.classList.toggle("active", btn.getAttribute("data-client") === client);
+    });
+
+    if (!cachedPreviews) return;
+    var preview = cachedPreviews.find(function (p) { return p.client === client; });
+    if (!preview) return;
+
+    frame.srcdoc = preview.html;
+
+    if (preview.notes && preview.notes.length > 0) {
+      notesEl.innerHTML = preview.notes
+        .map(function (n) { return '<span class="email-preview-note">' + escapeHtml(n) + '</span>'; })
+        .join("");
+      notesEl.classList.remove("hidden");
+    } else {
+      notesEl.classList.add("hidden");
+    }
+  }
+
+  function escapeHtml(str) {
+    var div = document.createElement("div");
+    div.textContent = str;
+    return div.innerHTML;
+  }
+
+  function openEmailPreview() {
+    overlay.classList.remove("hidden");
+    notesEl.textContent = "Loading previews...";
+    notesEl.classList.remove("hidden");
+
+    fetch("/api/email-preview/render", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    })
+      .then(function (res) { return res.json(); })
+      .then(function (data) {
+        if (data.error) {
+          notesEl.textContent = "Error: " + data.error;
+          return;
+        }
+        cachedPreviews = data.previews;
+        showPreview(activeClient);
+      })
+      .catch(function (err) {
+        notesEl.textContent = "Failed to load previews: " + err.message;
+      });
+  }
+
+  function closeEmailPreview() {
+    overlay.classList.add("hidden");
+    cachedPreviews = null;
+    frame.srcdoc = "";
+  }
+
+  if (openBtn) {
+    openBtn.addEventListener("click", openEmailPreview);
+  }
+
+  if (closeBtn) {
+    closeBtn.addEventListener("click", closeEmailPreview);
+  }
+
+  overlay.addEventListener("click", function (e) {
+    if (e.target === overlay) closeEmailPreview();
+  });
+
+  tabsContainer.addEventListener("click", function (e) {
+    var btn = e.target.closest(".email-preview-tab");
+    if (!btn) return;
+    var client = btn.getAttribute("data-client");
+    if (client) showPreview(client);
+  });
+
+  document.addEventListener("keydown", function (e) {
+    if (e.key === "Escape" && !overlay.classList.contains("hidden")) {
+      closeEmailPreview();
+    }
+  });
+
+  window.showEmailPreviewButton = function () {
+    if (openBtn) openBtn.classList.remove("hidden");
+  };
+
+  window.hideEmailPreviewButton = function () {
+    if (openBtn) openBtn.classList.add("hidden");
+  };
+})();