vibespot 1.0.6 → 1.0.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.js +61 -61
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/ui/docs/docs.css +977 -0
- package/ui/docs/docs.js +268 -0
- package/ui/docs/index.html +1242 -0
- package/ui/index.html +8 -0
- package/ui/styles.css +1 -0
|
@@ -0,0 +1,1242 @@
|
|
|
1
|
+
<!DOCTYPE html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="UTF-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
6
|
+
<title>vibeSpot Documentation</title>
|
|
7
|
+
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
8
|
+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
9
|
+
<link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=Space+Grotesk:wght@400;500;600;700&display=swap" rel="stylesheet">
|
|
10
|
+
<link rel="stylesheet" href="docs.css">
|
|
11
|
+
</head>
|
|
12
|
+
<body>
|
|
13
|
+
|
|
14
|
+
<!-- ================================================================
|
|
15
|
+
Topbar
|
|
16
|
+
================================================================ -->
|
|
17
|
+
<header class="doc-topbar">
|
|
18
|
+
<button class="doc-menu-btn" id="doc-menu-btn">☰</button>
|
|
19
|
+
<a href="#getting-started" class="doc-topbar__logo">
|
|
20
|
+
vibeSpot <span>Docs</span>
|
|
21
|
+
</a>
|
|
22
|
+
<div class="doc-topbar__search">
|
|
23
|
+
<span class="doc-topbar__search-icon">🔍</span>
|
|
24
|
+
<input type="text" id="doc-search-input" placeholder="Search docs..." autocomplete="off">
|
|
25
|
+
<span class="doc-topbar__shortcut">/</span>
|
|
26
|
+
</div>
|
|
27
|
+
<a href="/" class="doc-topbar__back">← Back to App</a>
|
|
28
|
+
</header>
|
|
29
|
+
|
|
30
|
+
<!-- Search Results Dropdown -->
|
|
31
|
+
<div id="doc-search-results" class="doc-search-results"></div>
|
|
32
|
+
|
|
33
|
+
<!-- ================================================================
|
|
34
|
+
Layout: Sidebar + Main
|
|
35
|
+
================================================================ -->
|
|
36
|
+
<div class="doc-layout">
|
|
37
|
+
|
|
38
|
+
<!-- ================================================================
|
|
39
|
+
Sidebar Navigation
|
|
40
|
+
================================================================ -->
|
|
41
|
+
<nav class="doc-sidebar">
|
|
42
|
+
|
|
43
|
+
<div class="doc-nav__section">
|
|
44
|
+
<span class="doc-nav__heading">Getting Started</span>
|
|
45
|
+
<a class="doc-nav__link" href="#getting-started">Overview</a>
|
|
46
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#quick-start">Quick Start</a>
|
|
47
|
+
</div>
|
|
48
|
+
|
|
49
|
+
<div class="doc-nav__section">
|
|
50
|
+
<span class="doc-nav__heading">Setup</span>
|
|
51
|
+
<a class="doc-nav__link" href="#setup">Setup & Configuration</a>
|
|
52
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#ai-engines">AI Engines</a>
|
|
53
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#hubspot-setup">HubSpot Connection</a>
|
|
54
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#config">Configuration File</a>
|
|
55
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#env-vars">Environment Variables</a>
|
|
56
|
+
</div>
|
|
57
|
+
|
|
58
|
+
<div class="doc-nav__section">
|
|
59
|
+
<span class="doc-nav__heading">Using vibeSpot</span>
|
|
60
|
+
<a class="doc-nav__link" href="#editor">The Editor</a>
|
|
61
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#editor-layout">Layout</a>
|
|
62
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#chat-panel">Chat</a>
|
|
63
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#preview-panel">Preview</a>
|
|
64
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#code-editor">Code Editor</a>
|
|
65
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#module-sidebar">Modules</a>
|
|
66
|
+
<a class="doc-nav__link" href="#creating-pages">Creating Pages</a>
|
|
67
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#first-page">Your First Page</a>
|
|
68
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#templates">Templates</a>
|
|
69
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#module-library">Module Library</a>
|
|
70
|
+
</div>
|
|
71
|
+
|
|
72
|
+
<div class="doc-nav__section">
|
|
73
|
+
<span class="doc-nav__heading">AI & Editing</span>
|
|
74
|
+
<a class="doc-nav__link" href="#ai-generation">AI Generation</a>
|
|
75
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#agentic-pipeline">Agentic Pipeline</a>
|
|
76
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#intent-types">Intents</a>
|
|
77
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#prompt-tips">Prompt Tips</a>
|
|
78
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#brand-assets">Brand Assets</a>
|
|
79
|
+
<a class="doc-nav__link" href="#editing">Editing & Customization</a>
|
|
80
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#field-editor">Field Editor</a>
|
|
81
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#design-system">Design System</a>
|
|
82
|
+
</div>
|
|
83
|
+
|
|
84
|
+
<div class="doc-nav__section">
|
|
85
|
+
<span class="doc-nav__heading">Deploy & History</span>
|
|
86
|
+
<a class="doc-nav__link" href="#deploying">Deploying to HubSpot</a>
|
|
87
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#auto-fix">Auto-Fix</a>
|
|
88
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#creating-page-hubspot">Creating a Page</a>
|
|
89
|
+
<a class="doc-nav__link" href="#version-history">Version History</a>
|
|
90
|
+
</div>
|
|
91
|
+
|
|
92
|
+
<div class="doc-nav__section">
|
|
93
|
+
<span class="doc-nav__heading">Reference</span>
|
|
94
|
+
<a class="doc-nav__link" href="#settings">Settings</a>
|
|
95
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#settings-ai">AI Tab</a>
|
|
96
|
+
<a class="doc-nav__link doc-nav__link--sub" href="#settings-hubspot">HubSpot Tab</a>
|
|
97
|
+
<a class="doc-nav__link" href="#cli-commands">CLI Commands</a>
|
|
98
|
+
<a class="doc-nav__link" href="#shortcuts">Shortcuts</a>
|
|
99
|
+
<a class="doc-nav__link" href="#troubleshooting">Troubleshooting</a>
|
|
100
|
+
</div>
|
|
101
|
+
|
|
102
|
+
</nav>
|
|
103
|
+
|
|
104
|
+
<!-- ================================================================
|
|
105
|
+
Main Content
|
|
106
|
+
================================================================ -->
|
|
107
|
+
<main class="doc-main">
|
|
108
|
+
|
|
109
|
+
<!-- ============================================================
|
|
110
|
+
Section 1: Getting Started
|
|
111
|
+
============================================================ -->
|
|
112
|
+
<div class="doc-section" id="getting-started">
|
|
113
|
+
<h1>vibeSpot Documentation</h1>
|
|
114
|
+
<p class="doc-subtitle">The AI-powered HubSpot CMS landing page builder. Describe a page in plain English, preview it live, then deploy to HubSpot in one click.</p>
|
|
115
|
+
|
|
116
|
+
<h2 id="what-is-vibespot">What is vibeSpot? <a href="#what-is-vibespot" class="doc-anchor">#</a></h2>
|
|
117
|
+
<p>vibeSpot is an open-source tool that turns natural language descriptions into fully functional HubSpot CMS themes. It provides a <strong>vibe coding</strong> interface: you type what you want on the left, and a live preview updates on the right. Under the hood, an AI pipeline generates native HubSpot modules complete with HubL templates, <code>fields.json</code>, CSS, and JavaScript — ready to deploy to any HubSpot portal.</p>
|
|
118
|
+
<p>vibeSpot also ships a CLI wizard for converting existing React or Lovable projects into HubSpot CMS themes, and a <code>doctor</code> command to verify your environment is correctly set up.</p>
|
|
119
|
+
|
|
120
|
+
<h3 id="prerequisites">Prerequisites</h3>
|
|
121
|
+
<ul>
|
|
122
|
+
<li><strong>Node.js 18+</strong> — required for the runtime. Run <code>node -v</code> to check.</li>
|
|
123
|
+
<li><strong>Git</strong> — used for version history (auto-commit after each generation). Run <code>git --version</code> to check.</li>
|
|
124
|
+
<li><strong>An AI engine</strong> — at least one of: Claude Code CLI, Anthropic API key, OpenAI API key, Gemini API key, or Gemini/Codex CLI. See <a href="#ai-engines">AI Engines</a> for details.</li>
|
|
125
|
+
</ul>
|
|
126
|
+
|
|
127
|
+
<h3 id="installation">Installation</h3>
|
|
128
|
+
<p>The fastest way to get started is with <code>npx</code>, which downloads and runs vibeSpot without a global install:</p>
|
|
129
|
+
<pre><code>npx vibespot</code></pre>
|
|
130
|
+
<p>For repeated use, install globally:</p>
|
|
131
|
+
<pre><code>npm install -g vibespot
|
|
132
|
+
vibespot</code></pre>
|
|
133
|
+
<p>This starts the web UI on <code>http://localhost:4200</code> and opens your browser automatically.</p>
|
|
134
|
+
|
|
135
|
+
<h3 id="quick-start">Quick Start</h3>
|
|
136
|
+
<ol class="doc-steps">
|
|
137
|
+
<li><strong>Install and launch.</strong> Run <code>npx vibespot</code> in your terminal. The web interface opens at <code>localhost:4200</code>. On first run, vibeSpot detects available AI engines and prompts you to configure one if needed.</li>
|
|
138
|
+
<li><strong>Create a theme.</strong> Click <strong>New Theme</strong> on the setup screen and give it a name (e.g., <code>my-saas-landing</code>). This creates a working directory at <code>~/vibespot-themes/my-saas-landing</code> with the standard HubSpot theme structure.</li>
|
|
139
|
+
<li><strong>Describe your page.</strong> In the chat panel, type a detailed description of the page you want. For example: <em>"Create a SaaS landing page for a project management tool called Taskflow. Include a hero with headline and CTA, a 3-column features grid, customer logos, a pricing table with 3 tiers, testimonials, and a footer."</em></li>
|
|
140
|
+
<li><strong>Watch the pipeline generate.</strong> The agentic pipeline analyzes your intent, designs a CSS system, plans modules, generates each one in parallel, then validates the output. You will see real-time progress cards for each stage. The live preview updates as modules complete.</li>
|
|
141
|
+
<li><strong>Deploy to HubSpot.</strong> Click the <strong>Deploy</strong> button in the topbar. Select your HubSpot account (or add one with a Personal Access Key), and vibeSpot uploads the theme. Once complete, a celebration screen with confetti shows a direct link to create a landing page in your HubSpot portal.</li>
|
|
142
|
+
</ol>
|
|
143
|
+
|
|
144
|
+
<h3 id="features">Key Features</h3>
|
|
145
|
+
<div class="doc-features">
|
|
146
|
+
<div class="doc-feature">
|
|
147
|
+
<div class="doc-feature__icon">⚡</div>
|
|
148
|
+
<div class="doc-feature__title">Agentic Pipeline</div>
|
|
149
|
+
<div class="doc-feature__desc">4-stage AI pipeline: intent analysis, design system, parallel module generation, and quality validation.</div>
|
|
150
|
+
</div>
|
|
151
|
+
<div class="doc-feature">
|
|
152
|
+
<div class="doc-feature__icon">👁</div>
|
|
153
|
+
<div class="doc-feature__title">Live Preview</div>
|
|
154
|
+
<div class="doc-feature__desc">HubL subset renderer with responsive toggles for desktop, tablet, and mobile viewports.</div>
|
|
155
|
+
</div>
|
|
156
|
+
<div class="doc-feature">
|
|
157
|
+
<div class="doc-feature__icon">🔧</div>
|
|
158
|
+
<div class="doc-feature__title">No-Code Field Editor</div>
|
|
159
|
+
<div class="doc-feature__desc">Edit text, images, colors, links, and more with a visual form. Changes reflect instantly in the preview.</div>
|
|
160
|
+
</div>
|
|
161
|
+
<div class="doc-feature">
|
|
162
|
+
<div class="doc-feature__icon">🚀</div>
|
|
163
|
+
<div class="doc-feature__title">One-Click Deploy</div>
|
|
164
|
+
<div class="doc-feature__desc">Upload your theme to HubSpot via API. Auto-fix handles common upload errors automatically.</div>
|
|
165
|
+
</div>
|
|
166
|
+
<div class="doc-feature">
|
|
167
|
+
<div class="doc-feature__icon">🎨</div>
|
|
168
|
+
<div class="doc-feature__title">Multi-Engine AI</div>
|
|
169
|
+
<div class="doc-feature__desc">Works with Anthropic, OpenAI, Gemini, Claude Code, Gemini CLI, and Codex CLI.</div>
|
|
170
|
+
</div>
|
|
171
|
+
<div class="doc-feature">
|
|
172
|
+
<div class="doc-feature__icon">🕒</div>
|
|
173
|
+
<div class="doc-feature__title">Version History</div>
|
|
174
|
+
<div class="doc-feature__desc">Git-based auto-commits after each generation. Browse and restore any previous version.</div>
|
|
175
|
+
</div>
|
|
176
|
+
</div>
|
|
177
|
+
</div>
|
|
178
|
+
|
|
179
|
+
<!-- ============================================================
|
|
180
|
+
Section 2: Setup & Configuration
|
|
181
|
+
============================================================ -->
|
|
182
|
+
<div class="doc-section" id="setup">
|
|
183
|
+
<h2 id="setup-heading">Setup & Configuration <a href="#setup" class="doc-anchor">#</a></h2>
|
|
184
|
+
<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>
|
|
185
|
+
|
|
186
|
+
<h3 id="ai-engines">AI Engines</h3>
|
|
187
|
+
<p>vibeSpot supports seven AI engines. You only need one to get started. The table below compares them:</p>
|
|
188
|
+
|
|
189
|
+
<table>
|
|
190
|
+
<thead>
|
|
191
|
+
<tr><th>Engine</th><th>Type</th><th>Setup</th><th>Cost Model</th><th>Best For</th></tr>
|
|
192
|
+
</thead>
|
|
193
|
+
<tbody>
|
|
194
|
+
<tr><td>Claude Code</td><td>CLI</td><td>Install <code>claude</code> CLI, authenticate</td><td>Included in Claude subscription</td><td>Subscribers who want zero API costs</td></tr>
|
|
195
|
+
<tr><td>Anthropic API</td><td>API</td><td>Add <code>ANTHROPIC_API_KEY</code></td><td>Pay-per-token</td><td>Fastest structured output, reliable</td></tr>
|
|
196
|
+
<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>
|
|
197
|
+
<tr><td>OpenAI API</td><td>API</td><td>Add <code>OPENAI_API_KEY</code></td><td>Pay-per-token</td><td>GPT-4o users, existing OpenAI budget</td></tr>
|
|
198
|
+
<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>
|
|
199
|
+
<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>
|
|
200
|
+
<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>
|
|
201
|
+
</tbody>
|
|
202
|
+
</table>
|
|
203
|
+
|
|
204
|
+
<div class="doc-tabs">
|
|
205
|
+
<div class="doc-tabs__bar">
|
|
206
|
+
<button class="doc-tabs__tab active" data-tab="tab-anthropic">Anthropic API</button>
|
|
207
|
+
<button class="doc-tabs__tab" data-tab="tab-claude-code">Claude Code</button>
|
|
208
|
+
<button class="doc-tabs__tab" data-tab="tab-claude-oauth">Claude OAuth</button>
|
|
209
|
+
<button class="doc-tabs__tab" data-tab="tab-openai">OpenAI API</button>
|
|
210
|
+
<button class="doc-tabs__tab" data-tab="tab-gemini-api">Gemini API</button>
|
|
211
|
+
<button class="doc-tabs__tab" data-tab="tab-gemini-cli">Gemini CLI</button>
|
|
212
|
+
<button class="doc-tabs__tab" data-tab="tab-codex">Codex CLI</button>
|
|
213
|
+
</div>
|
|
214
|
+
<div class="doc-tabs__panel active" id="tab-anthropic">
|
|
215
|
+
<p>The Anthropic API is the recommended engine for the best structured output quality.</p>
|
|
216
|
+
<ol class="doc-steps">
|
|
217
|
+
<li>Sign up at <a href="https://console.anthropic.com/" target="_blank">console.anthropic.com</a> and create an API key.</li>
|
|
218
|
+
<li>In vibeSpot Settings → AI tab, paste the key into the Anthropic API Key field. Or set the environment variable: <code>export ANTHROPIC_API_KEY=sk-ant-...</code></li>
|
|
219
|
+
<li>Select <strong>Anthropic API</strong> as the engine. The default model is <code>claude-sonnet-4-20250514</code>.</li>
|
|
220
|
+
</ol>
|
|
221
|
+
</div>
|
|
222
|
+
<div class="doc-tabs__panel" id="tab-claude-code">
|
|
223
|
+
<p>Claude Code is a CLI tool that runs as a subprocess. It is included in your Claude Pro/Team/Enterprise subscription at no extra API cost.</p>
|
|
224
|
+
<ol class="doc-steps">
|
|
225
|
+
<li>Install the Claude CLI: <code>npm install -g @anthropic-ai/claude-code</code></li>
|
|
226
|
+
<li>Authenticate: <code>claude auth</code></li>
|
|
227
|
+
<li>In vibeSpot Settings → AI tab → CLI Tools section, toggle <strong>Claude Code</strong> on. vibeSpot checks if the CLI is installed and authenticated. Then select <strong>Claude Code</strong> in the Engine section above.</li>
|
|
228
|
+
</ol>
|
|
229
|
+
</div>
|
|
230
|
+
<div class="doc-tabs__panel" id="tab-claude-oauth">
|
|
231
|
+
<p>Claude OAuth lets you use the Anthropic API through your Claude subscription without a separate API key.</p>
|
|
232
|
+
<ol class="doc-steps">
|
|
233
|
+
<li>Make sure the Claude CLI is installed: <code>npm install -g @anthropic-ai/claude-code</code></li>
|
|
234
|
+
<li>Run <code>claude setup-token</code> and follow the browser-based auth flow.</li>
|
|
235
|
+
<li>Copy the token and paste it into vibeSpot Settings → AI tab → Claude OAuth section.</li>
|
|
236
|
+
</ol>
|
|
237
|
+
<div class="doc-callout doc-callout--warning">
|
|
238
|
+
<div class="doc-callout__label">⚠ Token Expiration</div>
|
|
239
|
+
<p>OAuth tokens expire periodically. If you see authentication errors, run <code>claude setup-token</code> again and paste the new token.</p>
|
|
240
|
+
</div>
|
|
241
|
+
</div>
|
|
242
|
+
<div class="doc-tabs__panel" id="tab-openai">
|
|
243
|
+
<p>Use OpenAI's GPT-4o or any compatible model through the OpenAI API.</p>
|
|
244
|
+
<ol class="doc-steps">
|
|
245
|
+
<li>Get an API key from <a href="https://platform.openai.com/api-keys" target="_blank">platform.openai.com</a>.</li>
|
|
246
|
+
<li>Paste the key in Settings → AI tab → OpenAI API Key, or set <code>export OPENAI_API_KEY=sk-...</code></li>
|
|
247
|
+
<li>Select <strong>OpenAI API</strong> as the engine and choose your preferred model.</li>
|
|
248
|
+
</ol>
|
|
249
|
+
</div>
|
|
250
|
+
<div class="doc-tabs__panel" id="tab-gemini-api">
|
|
251
|
+
<p>Google's Gemini API offers a generous free tier suitable for experimentation.</p>
|
|
252
|
+
<ol class="doc-steps">
|
|
253
|
+
<li>Get an API key from <a href="https://aistudio.google.com/apikey" target="_blank">Google AI Studio</a>.</li>
|
|
254
|
+
<li>Paste the key in Settings → AI tab → Google AI API Key, or set <code>export GEMINI_API_KEY=...</code> (or <code>GOOGLE_AI_API_KEY</code>).</li>
|
|
255
|
+
<li>Select <strong>Gemini API</strong> as the engine.</li>
|
|
256
|
+
</ol>
|
|
257
|
+
</div>
|
|
258
|
+
<div class="doc-tabs__panel" id="tab-gemini-cli">
|
|
259
|
+
<p>The Gemini CLI runs as a local subprocess, similar to Claude Code.</p>
|
|
260
|
+
<ol class="doc-steps">
|
|
261
|
+
<li>Install the Gemini CLI: <code>npm install -g @google/gemini-cli</code></li>
|
|
262
|
+
<li>Authenticate with your Google account.</li>
|
|
263
|
+
<li>In vibeSpot Settings → AI tab → CLI Tools section, toggle <strong>Gemini CLI</strong> on. Then select it in the Engine section above.</li>
|
|
264
|
+
</ol>
|
|
265
|
+
</div>
|
|
266
|
+
<div class="doc-tabs__panel" id="tab-codex">
|
|
267
|
+
<p>OpenAI's Codex CLI runs as a subprocess, included in OpenAI subscriptions.</p>
|
|
268
|
+
<ol class="doc-steps">
|
|
269
|
+
<li>Install the Codex CLI: <code>npm install -g @openai/codex</code></li>
|
|
270
|
+
<li>Authenticate with your OpenAI account.</li>
|
|
271
|
+
<li>In vibeSpot Settings → AI tab → CLI Tools section, toggle <strong>Codex CLI</strong> on. Then select it in the Engine section above.</li>
|
|
272
|
+
</ol>
|
|
273
|
+
</div>
|
|
274
|
+
</div>
|
|
275
|
+
|
|
276
|
+
<h3 id="hubspot-setup">HubSpot Connection</h3>
|
|
277
|
+
<p>vibeSpot uploads themes to HubSpot using one of two methods:</p>
|
|
278
|
+
<ul>
|
|
279
|
+
<li><strong>API mode (recommended)</strong> — Uses the HubSpot CMS API directly with a Personal Access Key. Uploads modules in parallel for speed. No HubSpot CLI required.</li>
|
|
280
|
+
<li><strong>CLI mode (legacy)</strong> — Uses the <code>hs</code> CLI tool to upload sequentially. Slower but works if API mode encounters issues.</li>
|
|
281
|
+
</ul>
|
|
282
|
+
<ol class="doc-steps">
|
|
283
|
+
<li><strong>Get a Personal Access Key (PAK).</strong> Go to your HubSpot portal → Settings → Account Setup → Integrations → Private Apps, or visit <code>app.hubspot.com/personal-access-key/{portalId}</code> directly. Create a key with the <strong>Content</strong> scope (Design Manager read/write). Copy the key (starts with <code>pat-na1-</code> or <code>pat-eu1-</code>).</li>
|
|
284
|
+
<li><strong>Add the account in vibeSpot.</strong> Open Settings → HubSpot tab → Add Account. Paste the PAK. vibeSpot validates it and detects your portal ID and data center (NA1 or EU1).</li>
|
|
285
|
+
<li><strong>Select the account.</strong> If you have multiple portals, click the one you want to deploy to. The active account is shown with a green indicator.</li>
|
|
286
|
+
</ol>
|
|
287
|
+
<div class="doc-callout doc-callout--info">
|
|
288
|
+
<div class="doc-callout__label">ℹ Multi-Account Support</div>
|
|
289
|
+
<p>You can add multiple HubSpot accounts (different portals or data centers). Switch between them in Settings → HubSpot tab before uploading. vibeSpot detects EU1 data centers automatically from your PAK prefix.</p>
|
|
290
|
+
</div>
|
|
291
|
+
|
|
292
|
+
<h3 id="config">Configuration File</h3>
|
|
293
|
+
<p>All settings are stored in <code>~/.vibespot/config.json</code>. Here is a reference of all fields:</p>
|
|
294
|
+
<table>
|
|
295
|
+
<thead>
|
|
296
|
+
<tr><th>Field</th><th>Type</th><th>Description</th></tr>
|
|
297
|
+
</thead>
|
|
298
|
+
<tbody>
|
|
299
|
+
<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>
|
|
300
|
+
<tr><td><code>anthropicApiKey</code></td><td>string</td><td>Anthropic API key (starts with <code>sk-ant-</code>)</td></tr>
|
|
301
|
+
<tr><td><code>openaiApiKey</code></td><td>string</td><td>OpenAI API key (starts with <code>sk-</code>)</td></tr>
|
|
302
|
+
<tr><td><code>geminiApiKey</code></td><td>string</td><td>Google AI / Gemini API key</td></tr>
|
|
303
|
+
<tr><td><code>claudeCodeModel</code></td><td>string</td><td>Model override for Claude Code CLI</td></tr>
|
|
304
|
+
<tr><td><code>anthropicApiModel</code></td><td>string</td><td>Anthropic API model (default: <code>claude-sonnet-4-20250514</code>)</td></tr>
|
|
305
|
+
<tr><td><code>openaiApiModel</code></td><td>string</td><td>OpenAI API model (default: <code>gpt-4o</code>)</td></tr>
|
|
306
|
+
<tr><td><code>hubspotAccounts</code></td><td>array</td><td>List of HubSpot accounts with PAK, portal ID, and data center</td></tr>
|
|
307
|
+
<tr><td><code>activeHubSpotAccount</code></td><td>string</td><td>Portal ID of the currently active HubSpot account</td></tr>
|
|
308
|
+
<tr><td><code>hubspotUploadMode</code></td><td>string</td><td><code>"api"</code> (default) or <code>"cli"</code></td></tr>
|
|
309
|
+
<tr><td><code>enabledCLITools</code></td><td>string[]</td><td>Array of enabled CLI tool IDs: <code>["claude-code", "gemini-cli", "codex-cli"]</code>. Only enabled tools are checked on startup.</td></tr>
|
|
310
|
+
<tr><td><code>agenticMode</code></td><td>boolean</td><td>Enable the 4-stage agentic pipeline. <code>undefined</code> on first run (vibeSpot prompts you to choose), then <code>true</code> or <code>false</code>.</td></tr>
|
|
311
|
+
<tr><td><code>agenticConcurrency</code></td><td>number</td><td>Max parallel module generation calls (default: <code>20</code>)</td></tr>
|
|
312
|
+
</tbody>
|
|
313
|
+
</table>
|
|
314
|
+
|
|
315
|
+
<h3 id="env-vars">Environment Variables</h3>
|
|
316
|
+
<p>API keys can also be set as environment variables. The config file takes precedence — environment variables are used as fallbacks when no key is set in the config:</p>
|
|
317
|
+
<table>
|
|
318
|
+
<thead>
|
|
319
|
+
<tr><th>Variable</th><th>Description</th></tr>
|
|
320
|
+
</thead>
|
|
321
|
+
<tbody>
|
|
322
|
+
<tr><td><code>ANTHROPIC_API_KEY</code></td><td>Anthropic API key for Claude models</td></tr>
|
|
323
|
+
<tr><td><code>OPENAI_API_KEY</code></td><td>OpenAI API key for GPT models</td></tr>
|
|
324
|
+
<tr><td><code>GEMINI_API_KEY</code></td><td>Google AI API key for Gemini models</td></tr>
|
|
325
|
+
<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>
|
|
326
|
+
</tbody>
|
|
327
|
+
</table>
|
|
328
|
+
</div>
|
|
329
|
+
|
|
330
|
+
<!-- ============================================================
|
|
331
|
+
Section 3: The Editor
|
|
332
|
+
============================================================ -->
|
|
333
|
+
<div class="doc-section" id="editor">
|
|
334
|
+
<h2 id="editor-heading">The Editor <a href="#editor" class="doc-anchor">#</a></h2>
|
|
335
|
+
<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>
|
|
336
|
+
|
|
337
|
+
<h3 id="editor-layout">Layout Overview</h3>
|
|
338
|
+
<p>The editor has three main panels separated by a draggable resize handle:</p>
|
|
339
|
+
<ul>
|
|
340
|
+
<li><strong>Left panel</strong> (380px default) — 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>
|
|
341
|
+
<li><strong>Resize handle</strong> — 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>
|
|
342
|
+
<li><strong>Right panel</strong> (fills remaining space) — 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>
|
|
343
|
+
</ul>
|
|
344
|
+
|
|
345
|
+
<!-- Editor Layout Mockup -->
|
|
346
|
+
<div class="doc-mockup">
|
|
347
|
+
<div class="mock-topbar">
|
|
348
|
+
<span class="mock-topbar__back">‹</span>
|
|
349
|
+
<span class="mock-topbar__pill">my-startup</span>
|
|
350
|
+
<span class="mock-topbar__spacer"></span>
|
|
351
|
+
<div class="mock-topbar__responsive">
|
|
352
|
+
<span class="active" title="Desktop">□</span><span title="Tablet">▭</span><span title="Mobile">▯</span>
|
|
353
|
+
</div>
|
|
354
|
+
<span class="mock-topbar__spacer"></span>
|
|
355
|
+
<span class="mock-topbar__btn" title="Feedback">💬</span>
|
|
356
|
+
<span class="mock-topbar__btn" title="Theme toggle">☼</span>
|
|
357
|
+
<span class="mock-topbar__btn" title="Version history">🕓</span>
|
|
358
|
+
<span class="mock-topbar__btn mock-topbar__btn--accent">↑ Deploy</span>
|
|
359
|
+
</div>
|
|
360
|
+
<div class="mock-editor">
|
|
361
|
+
<div class="mock-editor__left">
|
|
362
|
+
<div class="mock-modules">
|
|
363
|
+
<div class="mock-modules__header"><span style="display:flex;align-items:center;gap:6px">▦▦ Modules</span> <span class="mock-modules__count">5</span></div>
|
|
364
|
+
<div class="mock-module-item"><span class="mock-module-item__grip">⋮⋮</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">✎</span><span class="mock-module-item__action" title="Delete">×</span></span></div>
|
|
365
|
+
<div class="mock-module-item"><span class="mock-module-item__grip">⋮⋮</span><span class="mock-module-item__name">Hero Banner</span><span class="mock-module-item__actions"><span class="mock-module-item__action">✎</span><span class="mock-module-item__action">×</span></span></div>
|
|
366
|
+
<div class="mock-module-item"><span class="mock-module-item__grip">⋮⋮</span><span class="mock-module-item__name">Features Grid</span><span class="mock-module-item__actions"><span class="mock-module-item__action">✎</span><span class="mock-module-item__action">×</span></span></div>
|
|
367
|
+
<div class="mock-module-item"><span class="mock-module-item__grip">⋮⋮</span><span class="mock-module-item__name">Pricing Cards</span><span class="mock-module-item__actions"><span class="mock-module-item__action">✎</span><span class="mock-module-item__action">×</span></span></div>
|
|
368
|
+
<div class="mock-module-item"><span class="mock-module-item__grip">⋮⋮</span><span class="mock-module-item__name">Footer</span><span class="mock-module-item__actions"><span class="mock-module-item__action">✎</span><span class="mock-module-item__action">×</span></span></div>
|
|
369
|
+
</div>
|
|
370
|
+
<div class="mock-chat">
|
|
371
|
+
<div style="display:flex;align-items:center;justify-content:space-between;padding:8px 10px;border-bottom:1px solid var(--doc-border)">
|
|
372
|
+
<span style="font-size:11px;font-weight:600;color:var(--doc-text-dim)">Chat</span>
|
|
373
|
+
<span style="font-size:10px;color:var(--doc-text-muted)">Claude (OAuth)</span>
|
|
374
|
+
</div>
|
|
375
|
+
<div class="mock-chat__messages">
|
|
376
|
+
<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>
|
|
377
|
+
<div class="mock-chat__msg mock-chat__msg--ai"><span class="mock-chat__avatar">AI</span>
|
|
378
|
+
<div class="mock-chat__pipeline">
|
|
379
|
+
<div class="mock-chat__step">✔ Analyzing your request...</div>
|
|
380
|
+
<div class="mock-chat__step">✔ Creating design system...</div>
|
|
381
|
+
<div class="mock-chat__step">✔ Generating 5 modules...</div>
|
|
382
|
+
<div class="mock-chat__step">✔ Quality check...</div>
|
|
383
|
+
<div class="mock-chat__module-cards">
|
|
384
|
+
<span class="mock-chat__module-card mock-chat__module-card--done">✔ Navigation</span>
|
|
385
|
+
<span class="mock-chat__module-card mock-chat__module-card--done">✔ Hero</span>
|
|
386
|
+
<span class="mock-chat__module-card mock-chat__module-card--done">✔ Features</span>
|
|
387
|
+
<span class="mock-chat__module-card mock-chat__module-card--done">✔ Pricing</span>
|
|
388
|
+
<span class="mock-chat__module-card mock-chat__module-card--done">✔ Footer</span>
|
|
389
|
+
</div>
|
|
390
|
+
<div style="color:var(--doc-green);margin-top:4px;font-size:10px">Generated 5 modules in 42s</div>
|
|
391
|
+
</div>
|
|
392
|
+
</div>
|
|
393
|
+
<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>
|
|
394
|
+
<div class="mock-chat__msg mock-chat__msg--ai"><span class="mock-chat__avatar">AI</span>
|
|
395
|
+
<div class="mock-chat__pipeline">
|
|
396
|
+
<div class="mock-chat__step">✔ Analyzing your request...</div>
|
|
397
|
+
<div class="mock-chat__step mock-chat__step--active">⟳ Generating 1 module...</div>
|
|
398
|
+
<div class="mock-chat__module-cards">
|
|
399
|
+
<span class="mock-chat__module-card mock-chat__module-card--active">Hero Banner generating...</span>
|
|
400
|
+
</div>
|
|
401
|
+
<div style="color:var(--doc-text-muted);margin-top:4px;font-size:10px">14s</div>
|
|
402
|
+
</div>
|
|
403
|
+
</div>
|
|
404
|
+
</div>
|
|
405
|
+
<div class="mock-chat__input">
|
|
406
|
+
<span style="color:var(--doc-text-muted);font-size:13px;cursor:pointer" title="Attach file">📎</span>
|
|
407
|
+
<input class="mock-chat__input-field" placeholder="Describe your landing page..." disabled>
|
|
408
|
+
<span style="color:var(--doc-text-muted);font-size:12px;cursor:pointer" title="Starter templates">▦▦</span>
|
|
409
|
+
<span class="mock-chat__input-btn">▶</span>
|
|
410
|
+
</div>
|
|
411
|
+
</div>
|
|
412
|
+
</div>
|
|
413
|
+
<div class="mock-editor__resize" title="Drag to resize panels"></div>
|
|
414
|
+
<div class="mock-editor__right">
|
|
415
|
+
<div class="mock-preview">
|
|
416
|
+
<div class="mock-preview__tabs"><span class="mock-preview__tab active">Preview</span><span class="mock-preview__tab">Code</span></div>
|
|
417
|
+
<div class="mock-preview__chrome">
|
|
418
|
+
<div class="mock-preview__dots"><span class="mock-preview__dot"></span><span class="mock-preview__dot"></span><span class="mock-preview__dot"></span></div>
|
|
419
|
+
<div class="mock-preview__url">my-startup.vibespot.app</div>
|
|
420
|
+
</div>
|
|
421
|
+
<div class="mock-preview__body">
|
|
422
|
+
<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">
|
|
423
|
+
<span style="font-weight:600;color:var(--doc-text)">WriteAI</span>
|
|
424
|
+
<span style="color:var(--doc-text-muted)">Features · Pricing · About</span>
|
|
425
|
+
</div>
|
|
426
|
+
<div class="mock-preview__section mock-preview__hero">
|
|
427
|
+
<div class="mock-preview__hero-title">Write Better. Faster.</div>
|
|
428
|
+
<div class="mock-preview__hero-sub">AI-powered writing assistant for teams that ship.</div>
|
|
429
|
+
<span class="mock-preview__hero-btn">Start Free Trial</span>
|
|
430
|
+
</div>
|
|
431
|
+
<div class="mock-preview__cards">
|
|
432
|
+
<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>
|
|
433
|
+
<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>
|
|
434
|
+
<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>
|
|
435
|
+
</div>
|
|
436
|
+
</div>
|
|
437
|
+
</div>
|
|
438
|
+
</div>
|
|
439
|
+
</div>
|
|
440
|
+
<div class="mock-statusbar">
|
|
441
|
+
<span>Connected</span>
|
|
442
|
+
<span class="mock-statusbar__spacer"></span>
|
|
443
|
+
<span class="mock-statusbar__dot"></span>
|
|
444
|
+
<span>ALCMST (144870572)</span>
|
|
445
|
+
<span class="mock-statusbar__spacer"></span>
|
|
446
|
+
<span>Claude (OAuth)</span>
|
|
447
|
+
</div>
|
|
448
|
+
</div>
|
|
449
|
+
|
|
450
|
+
<p>The topbar provides access to theme settings, upload, version history, responsive viewport toggle, and the settings gear.</p>
|
|
451
|
+
|
|
452
|
+
<h3 id="chat-panel">Chat Panel</h3>
|
|
453
|
+
<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>
|
|
454
|
+
<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> → <em>generating...</em> → <em>validating...</em> → <em>✔</em> (complete) or <em>✗</em> (failed). If a module fails, it may show <em>retrying...</em> before a second attempt.</p>
|
|
455
|
+
|
|
456
|
+
<h4 id="file-attachments-chat">File Attachments</h4>
|
|
457
|
+
<p>You can attach files to your messages for additional context:</p>
|
|
458
|
+
<ul>
|
|
459
|
+
<li><strong>Images</strong> (up to 10 MB) — PNG, JPEG, SVG, WebP, GIF. The AI can see these via vision and use them as design references.</li>
|
|
460
|
+
<li><strong>Documents</strong> — PDF, DOCX, MD, TXT. Text is extracted and provided to the AI as content context.</li>
|
|
461
|
+
</ul>
|
|
462
|
+
<p>Drag and drop files onto the chat input, or click the attachment button to browse.</p>
|
|
463
|
+
|
|
464
|
+
<h4 id="starter-templates">Starter Templates</h4>
|
|
465
|
+
<p>For quick starts, the chat suggests four starter templates on an empty theme:</p>
|
|
466
|
+
<ul>
|
|
467
|
+
<li><strong>SaaS Landing Page</strong> — Hero, features grid, pricing, testimonials, CTA, footer</li>
|
|
468
|
+
<li><strong>Portfolio</strong> — About section, project gallery, skills, contact form</li>
|
|
469
|
+
<li><strong>Restaurant</strong> — Hero with imagery, menu sections, reservation CTA, location map, hours</li>
|
|
470
|
+
<li><strong>Event / Conference</strong> — Event hero with date, speakers, schedule, sponsors, registration CTA</li>
|
|
471
|
+
</ul>
|
|
472
|
+
|
|
473
|
+
<h3 id="preview-panel">Preview Panel</h3>
|
|
474
|
+
<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>
|
|
475
|
+
<p>Use the responsive toggle buttons in the topbar to switch viewports:</p>
|
|
476
|
+
<ul>
|
|
477
|
+
<li><strong>Desktop</strong> — 100% width</li>
|
|
478
|
+
<li><strong>Tablet</strong> — 768px</li>
|
|
479
|
+
<li><strong>Mobile</strong> — 375px</li>
|
|
480
|
+
</ul>
|
|
481
|
+
<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>
|
|
482
|
+
|
|
483
|
+
<h3 id="code-editor">Code Editor</h3>
|
|
484
|
+
<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>
|
|
485
|
+
<ul>
|
|
486
|
+
<li><code>module.html</code> — The HubL template</li>
|
|
487
|
+
<li><code>module.css</code> — Module-scoped CSS</li>
|
|
488
|
+
<li><code>module.js</code> — Client-side JavaScript</li>
|
|
489
|
+
<li><code>fields.json</code> — Field definitions for the HubSpot content editor</li>
|
|
490
|
+
</ul>
|
|
491
|
+
<p>At the theme level, you also have access to <code>shared.css</code> (design system utilities) and <code>shared.js</code> (scroll animations, shared behaviors).</p>
|
|
492
|
+
<p>The editor uses CodeMirror 6 with syntax highlighting for HTML, CSS, JavaScript, and JSON. Save your changes with <kbd>Cmd</kbd>+<kbd>S</kbd> (or <kbd>Ctrl</kbd>+<kbd>S</kbd> on Windows/Linux) to write to disk and refresh the preview.</p>
|
|
493
|
+
|
|
494
|
+
<h3 id="module-sidebar">Module Sidebar</h3>
|
|
495
|
+
<p>The module sidebar is a <strong>toggleable slideout</strong> panel. Click the <strong>Modules</strong> button (grid icon + count badge) at the top of the left panel to open it. The slideout slides in from the left over the chat area. Click the <strong>×</strong> button or the Modules button again to close it.</p>
|
|
496
|
+
<p>The slideout has two views that swap in place:</p>
|
|
497
|
+
<ul>
|
|
498
|
+
<li><strong>Module List</strong> (default) — Shows all modules in the current template. The header displays the title "Modules", a count badge, a <strong>+</strong> button to add modules from the library, and a close button.</li>
|
|
499
|
+
<li><strong>Field Editor</strong> — Opens when you click the gear icon (⚙) on a module. Shows a back arrow to return to the module list, the module name, and a dynamic form for editing field values.</li>
|
|
500
|
+
</ul>
|
|
501
|
+
<p>Each module item in the list has:</p>
|
|
502
|
+
<ul>
|
|
503
|
+
<li><strong>Drag handle</strong> (⠷) — Grab and drag to reorder modules. The preview updates immediately to reflect the new page order.</li>
|
|
504
|
+
<li><strong>Module name</strong> — The display name of the module (e.g., "Hero Banner").</li>
|
|
505
|
+
<li><strong>Edit fields</strong> (⚙ gear icon, visible on hover) — Switches the slideout to the field editor view for that module.</li>
|
|
506
|
+
<li><strong>Delete</strong> (× icon, visible on hover) — Removes the module from the template after confirmation. If used in other templates, it remains in the library.</li>
|
|
507
|
+
</ul>
|
|
508
|
+
|
|
509
|
+
<h4 id="field-editor-sidebar">Field Editor</h4>
|
|
510
|
+
<p>The field editor renders a dynamic form based on the module's <code>fields.json</code>. Each field type uses a specific HTML control:</p>
|
|
511
|
+
<ul>
|
|
512
|
+
<li><strong>text</strong> — Standard text input (<code><input type="text"></code>)</li>
|
|
513
|
+
<li><strong>richtext</strong> — Multi-line textarea (<code><textarea rows="3"></code>)</li>
|
|
514
|
+
<li><strong>color</strong> — Native color picker paired with a hex text input. Both stay in sync.</li>
|
|
515
|
+
<li><strong>image</strong> — Text input for image URL</li>
|
|
516
|
+
<li><strong>link</strong> — Text input for URL</li>
|
|
517
|
+
<li><strong>number</strong> — Numeric input (<code><input type="number"></code>)</li>
|
|
518
|
+
<li><strong>boolean</strong> — Standard HTML checkbox (<code><input type="checkbox"></code>)</li>
|
|
519
|
+
<li><strong>choice</strong> — Native dropdown select populated from the field's choices array</li>
|
|
520
|
+
<li><strong>group</strong> — A labeled fieldset containing child fields. Groups with <code>"tab": "STYLE"</code> are labeled as style fields.</li>
|
|
521
|
+
</ul>
|
|
522
|
+
<p>All field changes are debounced at 300ms and trigger an automatic preview refresh. No manual save is needed.</p>
|
|
523
|
+
</div>
|
|
524
|
+
|
|
525
|
+
<!-- ============================================================
|
|
526
|
+
Section 4: Creating Pages
|
|
527
|
+
============================================================ -->
|
|
528
|
+
<div class="doc-section" id="creating-pages">
|
|
529
|
+
<h2 id="creating-pages-heading">Creating Pages <a href="#creating-pages" class="doc-anchor">#</a></h2>
|
|
530
|
+
<p>vibeSpot supports multiple ways to start a project, from a blank slate to importing existing work.</p>
|
|
531
|
+
|
|
532
|
+
<h3 id="starting-project">Starting a Project</h3>
|
|
533
|
+
|
|
534
|
+
<!-- Setup Screen Mockup -->
|
|
535
|
+
<div class="doc-mockup">
|
|
536
|
+
<div class="mock-topbar">
|
|
537
|
+
<span style="font-size:16px">✶</span>
|
|
538
|
+
<span class="mock-topbar__title">vibeSpot</span>
|
|
539
|
+
<span class="mock-topbar__spacer"></span>
|
|
540
|
+
<span class="mock-topbar__btn">💬 Feedback</span>
|
|
541
|
+
<span class="mock-topbar__btn" title="Theme toggle">☼</span>
|
|
542
|
+
</div>
|
|
543
|
+
<div class="mock-setup">
|
|
544
|
+
<div class="mock-setup__rail">
|
|
545
|
+
<div class="mock-setup__rail-dot mock-setup__rail-dot--active">M</div>
|
|
546
|
+
<div class="mock-setup__rail-dot">P</div>
|
|
547
|
+
<div class="mock-setup__rail-dot">D</div>
|
|
548
|
+
<div style="flex:1"></div>
|
|
549
|
+
<div style="font-size:9px;color:var(--doc-text-muted);margin-bottom:4px">📖</div>
|
|
550
|
+
<div style="font-size:9px;color:var(--doc-text-muted)">⚙</div>
|
|
551
|
+
</div>
|
|
552
|
+
<div class="mock-setup__main">
|
|
553
|
+
<div style="font-size:36px">✶</div>
|
|
554
|
+
<div class="mock-setup__logo">vibeSpot</div>
|
|
555
|
+
<div class="mock-setup__subtitle">Build HubSpot landing pages with AI</div>
|
|
556
|
+
<div class="mock-setup__actions">
|
|
557
|
+
<div class="mock-setup__action"><div class="mock-setup__action-icon">+</div><div class="mock-setup__action-label">New Theme</div><div class="mock-setup__action-desc">Start from scratch</div></div>
|
|
558
|
+
<div class="mock-setup__action"><div class="mock-setup__action-icon">▶</div><div class="mock-setup__action-label">Continue</div><div class="mock-setup__action-desc">Resume saved project</div></div>
|
|
559
|
+
<div class="mock-setup__action"><div class="mock-setup__action-icon">↓</div><div class="mock-setup__action-label">From HubSpot</div><div class="mock-setup__action-desc">Fetch existing theme</div></div>
|
|
560
|
+
<div class="mock-setup__action"><div class="mock-setup__action-icon">↻</div><div class="mock-setup__action-label">Convert React</div><div class="mock-setup__action-desc">Import React project<br><span style="font-size:9px;color:var(--doc-yellow)">Experimental</span></div></div>
|
|
561
|
+
</div>
|
|
562
|
+
</div>
|
|
563
|
+
</div>
|
|
564
|
+
</div>
|
|
565
|
+
|
|
566
|
+
<p>The setup screen presents four options:</p>
|
|
567
|
+
<ul>
|
|
568
|
+
<li><strong>New Theme</strong> — 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>
|
|
569
|
+
<li><strong>Continue (Resume)</strong> — Reopens an existing project from the sidebar list. Your chat history, modules, and all templates are preserved exactly where you left off.</li>
|
|
570
|
+
<li><strong>From HubSpot (Fetch)</strong> — 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>
|
|
571
|
+
<li><strong>Convert React (Experimental)</strong> — 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>
|
|
572
|
+
</ul>
|
|
573
|
+
|
|
574
|
+
<h3 id="first-page">Your First Page</h3>
|
|
575
|
+
<p>Follow these steps to build your first landing page from scratch:</p>
|
|
576
|
+
<ol class="doc-steps">
|
|
577
|
+
<li><strong>Create a new theme.</strong> Click <strong>New Theme</strong> on the setup screen. Enter a kebab-case name like <code>taskflow-landing</code>. The editor opens with an empty canvas.</li>
|
|
578
|
+
<li><strong>Write a detailed prompt.</strong> The more specific you are, the better the result. Include the page purpose, sections you want, specific content (headlines, feature descriptions), and design preferences (colors, style). For example: <em>"Build a landing page for Taskflow, a project management SaaS. Use a deep blue (#1a365d) and white palette. Include: hero with headline 'Ship Projects Faster', subheadline about team collaboration, and a 'Start Free Trial' CTA button. Then a 3-column features section with icons. Then a pricing table with Free/Pro/Enterprise tiers. End with a testimonial carousel and a minimal footer."</em></li>
|
|
579
|
+
<li><strong>Watch the pipeline work.</strong> The agentic pipeline runs through four stages. You will see: intent analysis (what type of request), design system creation (CSS variables and shared styles), parallel module generation (each module built concurrently), and quality validation (auto-fixing common issues). The live preview populates incrementally as modules complete.</li>
|
|
580
|
+
<li><strong>Refine with follow-up prompts.</strong> After the initial generation, send follow-up messages to modify specific modules: <em>"Change the hero background to a gradient from #1a365d to #2d3748"</em> or <em>"Add a FAQ section with 5 questions about Taskflow"</em>. The pipeline intelligently determines which modules to regenerate and which to keep.</li>
|
|
581
|
+
<li><strong>Edit fields visually.</strong> Click the <strong>Modules</strong> button to open the module slideout, then click the gear icon (⚙) on any module to open the field editor. Change headlines, body text, button labels, colors, and images without writing code. The preview updates in real time (300ms debounce).</li>
|
|
582
|
+
<li><strong>Deploy.</strong> Click the <strong>Deploy</strong> button in the topbar. Select your HubSpot account and watch the upload progress. When complete, click the link to go to your HubSpot portal and create a new landing page using your theme.</li>
|
|
583
|
+
</ol>
|
|
584
|
+
|
|
585
|
+
<div class="doc-callout doc-callout--tip">
|
|
586
|
+
<div class="doc-callout__label">✨ Prompt Examples</div>
|
|
587
|
+
<p><strong>SaaS:</strong> "Create a landing page for CloudSync, a file syncing tool. Hero with animated gradient, features with icons, pricing with toggle for monthly/annual, and footer with social links."</p>
|
|
588
|
+
<p><strong>Agency:</strong> "Build a digital agency portfolio page. Full-bleed hero video placeholder, a services grid (4 services), case studies with image cards, team section, and a contact form."</p>
|
|
589
|
+
<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>
|
|
590
|
+
</div>
|
|
591
|
+
|
|
592
|
+
<h3 id="templates">Templates</h3>
|
|
593
|
+
<p>Each theme can contain multiple templates. Templates define different page layouts that share the same module library and design system.</p>
|
|
594
|
+
<p>Supported page types:</p>
|
|
595
|
+
<ul>
|
|
596
|
+
<li><strong>Landing Page</strong> — The default. Full-width marketing pages.</li>
|
|
597
|
+
<li><strong>Blog Post</strong> — Content-focused layout with sidebar.</li>
|
|
598
|
+
<li><strong>Website Page</strong> — Standard pages for your site (About, Contact, etc.).</li>
|
|
599
|
+
<li><strong>Module Only</strong> — Generate standalone modules without a page template.</li>
|
|
600
|
+
</ul>
|
|
601
|
+
<p>Template operations available:</p>
|
|
602
|
+
<ul>
|
|
603
|
+
<li><strong>Create</strong> — Add a new template to the theme. Each template starts with its own chat history.</li>
|
|
604
|
+
<li><strong>Clone</strong> — Duplicate an existing template, including its module assignments and field values.</li>
|
|
605
|
+
<li><strong>Rename</strong> — Change the template display name.</li>
|
|
606
|
+
<li><strong>Delete</strong> — Remove a template. You can choose whether to also delete modules that are only used in that template, or keep them in the library.</li>
|
|
607
|
+
</ul>
|
|
608
|
+
<p>Each template maintains its own chat history, so you can have separate conversations for different pages in the same theme.</p>
|
|
609
|
+
|
|
610
|
+
<h3 id="module-library">Module Library</h3>
|
|
611
|
+
<p>All generated modules live in a shared library within the theme. The module list shows which templates each module is used in (e.g., "Used in: Landing Page, About Page").</p>
|
|
612
|
+
<ul>
|
|
613
|
+
<li><strong>Add to template</strong> — Browse the library and add any existing module to the current template without regenerating it.</li>
|
|
614
|
+
<li><strong>Preview before adding</strong> — See how a module looks before committing it to a template.</li>
|
|
615
|
+
<li><strong>Cross-template sharing</strong> — A single module (like a navbar or footer) can be used across multiple templates. Changes to the module propagate everywhere.</li>
|
|
616
|
+
<li><strong>Delete from library</strong> — Permanently remove a module and its files. This removes it from all templates that reference it.</li>
|
|
617
|
+
</ul>
|
|
618
|
+
</div>
|
|
619
|
+
|
|
620
|
+
<!-- ============================================================
|
|
621
|
+
Section 5: AI Generation
|
|
622
|
+
============================================================ -->
|
|
623
|
+
<div class="doc-section" id="ai-generation">
|
|
624
|
+
<h2 id="ai-generation-heading">AI Generation <a href="#ai-generation" class="doc-anchor">#</a></h2>
|
|
625
|
+
<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>
|
|
626
|
+
|
|
627
|
+
<h3 id="single-call">Single-Call Mode</h3>
|
|
628
|
+
<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>
|
|
629
|
+
<p>To use single-call mode, disable the agentic pipeline toggle in Settings → AI tab. Single-call mode may be useful for quick single-module additions or when using CLI engines that do not support structured output.</p>
|
|
630
|
+
<div class="doc-callout doc-callout--info">
|
|
631
|
+
<div class="doc-callout__label">ℹ When to use single-call</div>
|
|
632
|
+
<p>Single-call mode is best for simple requests like adding a single module or making a small change. For full page generation, the agentic pipeline produces significantly better results.</p>
|
|
633
|
+
</div>
|
|
634
|
+
|
|
635
|
+
<h3 id="agentic-pipeline">Agentic Pipeline</h3>
|
|
636
|
+
<p>The agentic pipeline breaks page generation into four specialized stages, each optimized for its task. This produces more cohesive designs, better code quality, and more reliable output.</p>
|
|
637
|
+
|
|
638
|
+
<div class="doc-pipeline">
|
|
639
|
+
<div class="doc-pipeline__stage">
|
|
640
|
+
<div class="doc-pipeline__stage-num">1</div>
|
|
641
|
+
<div class="doc-pipeline__stage-label">Intent Analyzer</div>
|
|
642
|
+
<div class="doc-pipeline__stage-desc">Classifies request & plans modules</div>
|
|
643
|
+
<div class="doc-pipeline__tooltip">Analyzes your message to determine the intent (create, modify, add, remove, rearrange, style change, or question). Plans which modules to generate, modify, keep, or reuse. Questions short-circuit the pipeline and return a direct answer.</div>
|
|
644
|
+
</div>
|
|
645
|
+
<div class="doc-pipeline__arrow">→</div>
|
|
646
|
+
<div class="doc-pipeline__stage">
|
|
647
|
+
<div class="doc-pipeline__stage-num">2</div>
|
|
648
|
+
<div class="doc-pipeline__stage-label">Page Architect</div>
|
|
649
|
+
<div class="doc-pipeline__stage-desc">Design system & module specs</div>
|
|
650
|
+
<div class="doc-pipeline__tooltip">Two sequential calls: first creates the design system (CSS custom properties in :root, shared CSS with component styles and responsive rules, shared JS). Then plans each module with a name, description, content brief, and layout notes using the finalized CSS as context.</div>
|
|
651
|
+
</div>
|
|
652
|
+
<div class="doc-pipeline__arrow">→</div>
|
|
653
|
+
<div class="doc-pipeline__stage">
|
|
654
|
+
<div class="doc-pipeline__stage-num">3</div>
|
|
655
|
+
<div class="doc-pipeline__stage-label">Module Developer</div>
|
|
656
|
+
<div class="doc-pipeline__stage-desc">Parallel generation</div>
|
|
657
|
+
<div class="doc-pipeline__tooltip">Generates all planned modules in parallel with a configurable concurrency limit (default: 20). Each module receives the shared CSS, the conversion guide, and HubSpot rules as context. Uses structured JSON output for reliable parsing of module.html, module.css, module.js, and fields.json.</div>
|
|
658
|
+
</div>
|
|
659
|
+
<div class="doc-pipeline__arrow">→</div>
|
|
660
|
+
<div class="doc-pipeline__stage">
|
|
661
|
+
<div class="doc-pipeline__stage-num">4</div>
|
|
662
|
+
<div class="doc-pipeline__stage-label">Quality Check</div>
|
|
663
|
+
<div class="doc-pipeline__stage-desc">Validation & auto-fix</div>
|
|
664
|
+
<div class="doc-pipeline__tooltip">Rule-based validation and automatic repair: fixes unbalanced HubL tags (orphan closers removed, missing closers appended), renames reserved field names (name → item_name, label → section_label), converts deprecated field types (textarea → text), strips CDN @import statements, replaces now() with local_dt, auto-prefixes unprefixed CSS classes with the theme name, updates matching HTML class attributes, and ensures meta.json has all required fields.</div>
|
|
665
|
+
</div>
|
|
666
|
+
</div>
|
|
667
|
+
|
|
668
|
+
<h3 id="intent-types">Intent Types</h3>
|
|
669
|
+
<p>The Intent Analyzer classifies every message into one of seven intents. This determines how the pipeline processes your request:</p>
|
|
670
|
+
<table>
|
|
671
|
+
<thead>
|
|
672
|
+
<tr><th>Intent</th><th>Description</th><th>Example Prompt</th></tr>
|
|
673
|
+
</thead>
|
|
674
|
+
<tbody>
|
|
675
|
+
<tr><td><code>create</code></td><td>Generate a full page from scratch</td><td>"Create a SaaS landing page with hero, features, pricing, and footer"</td></tr>
|
|
676
|
+
<tr><td><code>modify</code></td><td>Change an existing module's content, style, or structure</td><td>"Change the hero background to dark blue and update the headline"</td></tr>
|
|
677
|
+
<tr><td><code>add</code></td><td>Add one or more new modules to the existing page</td><td>"Add a FAQ section after the pricing table"</td></tr>
|
|
678
|
+
<tr><td><code>remove</code></td><td>Delete a module from the page</td><td>"Remove the testimonials section"</td></tr>
|
|
679
|
+
<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>
|
|
680
|
+
<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>
|
|
681
|
+
<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>
|
|
682
|
+
</tbody>
|
|
683
|
+
</table>
|
|
684
|
+
|
|
685
|
+
<h3 id="prompt-tips">Prompt Tips</h3>
|
|
686
|
+
<div class="doc-callout doc-callout--tip">
|
|
687
|
+
<div class="doc-callout__label">✨ Writing Effective Prompts</div>
|
|
688
|
+
<p><strong>Be specific about content.</strong> Instead of "add a features section," write "add a 3-column features section with icons for Speed (rocket icon), Security (shield icon), and Reliability (uptime chart icon), each with a headline and 2-sentence description."</p>
|
|
689
|
+
<p><strong>Reference modules by name.</strong> After initial generation, refer to modules by their names: "modify the <code>hero</code> module to add a background video" or "change the <code>pricing-table</code> to include an Enterprise tier."</p>
|
|
690
|
+
<p><strong>Use "modify X to..." for changes.</strong> Be explicit about what you want changed vs. what should stay the same. The AI preserves unchanged modules when you reference specific ones.</p>
|
|
691
|
+
<p><strong>Provide color values.</strong> If you have a brand palette, include hex codes: "Use #1a365d as the primary color and #e2e8f0 as the light background."</p>
|
|
692
|
+
<p><strong>Describe layout preferences.</strong> Mention grid columns, spacing, alignment: "Use a 2-column layout with the image on the left and text on the right."</p>
|
|
693
|
+
</div>
|
|
694
|
+
<div class="doc-callout doc-callout--warning">
|
|
695
|
+
<div class="doc-callout__label">⚠ Common Pitfalls</div>
|
|
696
|
+
<p><strong>Avoid vague requests.</strong> "Make it look better" gives the AI little to work with. Instead specify what you want improved: "Increase the whitespace between sections and add subtle hover animations to the feature cards."</p>
|
|
697
|
+
<p><strong>Do not overload a single prompt.</strong> If you want to create a full page and then heavily customize multiple modules, do it in steps: first generate, then refine individual modules in follow-up messages.</p>
|
|
698
|
+
</div>
|
|
699
|
+
|
|
700
|
+
<h3 id="brand-assets">Brand Assets</h3>
|
|
701
|
+
<p>Brand assets provide persistent context that the AI uses across all generations. They live in the theme and are sent with every pipeline call.</p>
|
|
702
|
+
<ul>
|
|
703
|
+
<li><strong>Styleguide</strong> — Design system documentation: typography, color palette, spacing scale, component styles. Upload a <code>.md</code> or <code>.txt</code> file, or let the AI extract a styleguide from your existing theme.</li>
|
|
704
|
+
<li><strong>Brand Voice</strong> — Tone and messaging guidelines: formal vs. casual, target audience, key phrases, words to avoid. Ensures the AI writes copy that matches your brand.</li>
|
|
705
|
+
<li><strong>Product Context</strong> — Auto-generated from your rendered theme. The AI analyzes existing modules to understand page structure, content patterns, and design conventions. Updated automatically after each generation.</li>
|
|
706
|
+
<li><strong>Humanify</strong> — A toggle that strips AI-sounding copy patterns from generated content. Removes em dashes, banned words like "delve," "leverage," "cutting-edge," and "game-changing." Eliminates cliche openers like "In today's fast-paced world." Produces more natural, human-sounding text.</li>
|
|
707
|
+
</ul>
|
|
708
|
+
|
|
709
|
+
<h3 id="file-attachments">File Attachments</h3>
|
|
710
|
+
<p>Attach files to your chat messages to give the AI additional context:</p>
|
|
711
|
+
<ul>
|
|
712
|
+
<li><strong>Images as design references</strong> — Upload screenshots, mockups, or design comps. The AI uses vision to analyze the layout, colors, typography, and structure, then generates modules that match. Supported formats: PNG, JPEG, SVG, WebP, GIF. Max 10 MB per file.</li>
|
|
713
|
+
<li><strong>Documents as content context</strong> — Upload product briefs, copy documents, or content spreadsheets. Text is extracted from PDFs and DOCX files and provided to the AI as context for generating accurate, on-brand content. Supported formats: PDF, DOCX, MD, TXT.</li>
|
|
714
|
+
</ul>
|
|
715
|
+
</div>
|
|
716
|
+
|
|
717
|
+
<!-- ============================================================
|
|
718
|
+
Section 6: Editing & Customization
|
|
719
|
+
============================================================ -->
|
|
720
|
+
<div class="doc-section" id="editing">
|
|
721
|
+
<h2 id="editing-heading">Editing & Customization <a href="#editing" class="doc-anchor">#</a></h2>
|
|
722
|
+
<p>After AI generation, you have full control over every aspect of your page. vibeSpot provides three editing paths depending on your needs.</p>
|
|
723
|
+
|
|
724
|
+
<h3 id="field-editor">No-Code Field Editing</h3>
|
|
725
|
+
<p>The fastest way to tweak content. Open the module slideout (click the <strong>Modules</strong> button), then click the gear icon (⚙) 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>
|
|
726
|
+
<div class="doc-callout doc-callout--tip">
|
|
727
|
+
<div class="doc-callout__label">Instant feedback</div>
|
|
728
|
+
<p>All field changes are debounced at 300ms and trigger an automatic preview refresh. No save button needed.</p>
|
|
729
|
+
</div>
|
|
730
|
+
|
|
731
|
+
<h3 id="code-editing">Direct Code Editing</h3>
|
|
732
|
+
<p>For precise control, switch to the <strong>Code</strong> tab in the right panel. The file tree groups files by module, and the editor uses CodeMirror 6 with syntax highlighting for HTML (with HubL), CSS, JavaScript, and JSON.</p>
|
|
733
|
+
<ul>
|
|
734
|
+
<li>Save with <kbd>Cmd</kbd>+<kbd>S</kbd> (or <kbd>Ctrl</kbd>+<kbd>S</kbd>) to write changes to disk and refresh the preview</li>
|
|
735
|
+
<li>A dirty dot (<strong>·</strong>) appears next to the filename when you have unsaved changes</li>
|
|
736
|
+
<li>Editable files: <code>module.html</code>, <code>module.css</code>, <code>module.js</code>, <code>fields.json</code>, plus theme-level <code>shared.css</code> and <code>shared.js</code></li>
|
|
737
|
+
</ul>
|
|
738
|
+
|
|
739
|
+
<h3 id="module-ordering">Reordering Modules</h3>
|
|
740
|
+
<p>Module order in the slideout list equals page order. Open the module slideout and drag items by their grip handle (⠷) to rearrange. The preview updates immediately.</p>
|
|
741
|
+
<p>Recommended landing page flow: Navigation → Hero → Features/Content → Social Proof → CTA/Pricing → Footer.</p>
|
|
742
|
+
|
|
743
|
+
<h3 id="design-system">Design System</h3>
|
|
744
|
+
<p>The agentic pipeline generates a consistent design system stored in the theme's shared CSS:</p>
|
|
745
|
+
<ul>
|
|
746
|
+
<li><strong>CSS custom properties</strong> in <code>:root</code> — colors, typography (clamp-based), spacing scale, border radii, shadows, and transition speeds.</li>
|
|
747
|
+
<li><strong>Theme prefix</strong> — All classes prefixed with the theme name (e.g., <code>.taskflow-hero__title</code>) using BEM naming to avoid HubSpot conflicts.</li>
|
|
748
|
+
<li><strong>Shared CSS</strong> — Reusable utility classes (containers, grids, buttons, cards, section backgrounds, scroll animations) referenced by all modules.</li>
|
|
749
|
+
<li><strong>Shared JS</strong> — IntersectionObserver-based scroll animations with a CSS-only 3-second fallback if JS fails to load.</li>
|
|
750
|
+
</ul>
|
|
751
|
+
</div>
|
|
752
|
+
|
|
753
|
+
<!-- ============================================================
|
|
754
|
+
Section 7: Deploying to HubSpot
|
|
755
|
+
============================================================ -->
|
|
756
|
+
<div class="doc-section" id="deploying">
|
|
757
|
+
<h2 id="deploying-heading">Deploying to HubSpot <a href="#deploying" class="doc-anchor">#</a></h2>
|
|
758
|
+
<p>Once your page looks right in the preview, deploy it to your HubSpot portal in a single click.</p>
|
|
759
|
+
|
|
760
|
+
<h3 id="upload-flow">Upload Flow</h3>
|
|
761
|
+
|
|
762
|
+
<!-- Upload Mockup -->
|
|
763
|
+
<div class="doc-mockup">
|
|
764
|
+
<div class="mock-topbar">
|
|
765
|
+
<span class="mock-topbar__title">Deploying to HubSpot</span>
|
|
766
|
+
<span class="mock-topbar__spacer"></span>
|
|
767
|
+
<span class="mock-topbar__btn">Dismiss</span>
|
|
768
|
+
</div>
|
|
769
|
+
<div class="mock-upload">
|
|
770
|
+
<div class="mock-upload__progress">
|
|
771
|
+
<div class="mock-upload__bar-bg"><div class="mock-upload__bar-fill"></div></div>
|
|
772
|
+
<div class="mock-upload__status">Uploading to HubSpot... <strong>36/50 files (72%)</strong></div>
|
|
773
|
+
</div>
|
|
774
|
+
<div class="mock-upload__log">
|
|
775
|
+
<span class="green">✓</span> Auto-fix: textarea → text in Hero Banner/fields.json<br>
|
|
776
|
+
<span class="green">✓</span> Auto-fix: reserved "name" → "item_name" in FAQ/fields.json<br>
|
|
777
|
+
<span class="accent">↑</span> modules/hero-banner.module/module.html<br>
|
|
778
|
+
<span class="accent">↑</span> modules/hero-banner.module/module.css<br>
|
|
779
|
+
<span class="accent">↑</span> modules/hero-banner.module/fields.json<br>
|
|
780
|
+
<span class="accent">↑</span> modules/features-grid.module/module.html<br>
|
|
781
|
+
<span class="green">✓</span> 36 of 50 files uploaded...
|
|
782
|
+
</div>
|
|
783
|
+
</div>
|
|
784
|
+
</div>
|
|
785
|
+
|
|
786
|
+
<ol class="doc-steps">
|
|
787
|
+
<li><strong>Connect your HubSpot account.</strong> If you have not added an account yet, go to Settings → HubSpot tab and add your Personal Access Key. vibeSpot validates the key and detects your portal.</li>
|
|
788
|
+
<li><strong>Select the target account.</strong> If you have multiple portals, make sure the correct one is active (green indicator in Settings → HubSpot).</li>
|
|
789
|
+
<li><strong>Click Deploy.</strong> The <strong>Deploy</strong> button (orange, top-right of topbar) starts the deployment process. vibeSpot writes files to disk, applies auto-fixes, then uploads the theme structure, shared assets, and all modules.</li>
|
|
790
|
+
<li><strong>Monitor progress.</strong> A progress indicator shows the upload status. In API mode (default), modules upload in parallel for speed. In CLI mode, they upload sequentially.</li>
|
|
791
|
+
<li><strong>Create a page in HubSpot.</strong> When the upload completes, a celebration screen appears with confetti and a direct link to your HubSpot portal. Click it to open HubSpot and create a landing page using your new theme.</li>
|
|
792
|
+
</ol>
|
|
793
|
+
<div class="doc-callout doc-callout--info">
|
|
794
|
+
<div class="doc-callout__label">ℹ API vs. CLI Upload Mode</div>
|
|
795
|
+
<p><strong>API mode</strong> (recommended) uses the HubSpot CMS API directly. It uploads modules in parallel and is significantly faster. Requires a Personal Access Key with CMS scope.</p>
|
|
796
|
+
<p><strong>CLI mode</strong> (legacy) uses the <code>hs upload</code> command from the HubSpot CLI. It uploads files sequentially and is slower but can be useful as a fallback.</p>
|
|
797
|
+
</div>
|
|
798
|
+
|
|
799
|
+
<h3 id="auto-fix">Auto-Fix</h3>
|
|
800
|
+
<div class="doc-callout doc-callout--info">
|
|
801
|
+
<div class="doc-callout__label">Two layers of auto-fix</div>
|
|
802
|
+
<p>The <strong>quality check</strong> (agentic pipeline stage 4) fixes issues before modules reach you — HubL syntax, CSS prefixes, reserved names, meta.json fields. The <strong>upload auto-fix</strong> below runs separately when a HubSpot upload fails, then retries.</p>
|
|
803
|
+
</div>
|
|
804
|
+
<p>When an upload fails, vibeSpot scans the theme files for known HubSpot compatibility issues, applies fixes, and retries (up to 3 attempts):</p>
|
|
805
|
+
<table>
|
|
806
|
+
<thead>
|
|
807
|
+
<tr><th>Issue</th><th>Auto-Fix</th></tr>
|
|
808
|
+
</thead>
|
|
809
|
+
<tbody>
|
|
810
|
+
<tr><td><code>textarea</code> field type</td><td>Replaced with <code>text</code> (HubSpot deprecated <code>textarea</code>)</td></tr>
|
|
811
|
+
<tr><td>Reserved field name <code>name</code></td><td>Renamed to <code>item_name</code></td></tr>
|
|
812
|
+
<tr><td>Reserved field name <code>label</code></td><td>Renamed to <code>section_label</code></td></tr>
|
|
813
|
+
<tr><td><code>now()</code> function call</td><td>Replaced with <code>local_dt</code> (HubL-compatible date variable)</td></tr>
|
|
814
|
+
<tr><td>CDN <code>@import</code> in CSS</td><td>Stripped (HubSpot blocks external CSS imports)</td></tr>
|
|
815
|
+
<tr><td>Invalid link field defaults</td><td>Reset to valid <code>{ url: { href, type }, open_in_new_tab, no_follow }</code> structure</td></tr>
|
|
816
|
+
<tr><td>Invalid color field format</td><td>RGBA/RGB/named colors converted to hex <code>#RRGGBB</code></td></tr>
|
|
817
|
+
<tr><td>HubDB template references</td><td>Files removed (HubDB requires CMS Hub Pro/Enterprise)</td></tr>
|
|
818
|
+
</tbody>
|
|
819
|
+
</table>
|
|
820
|
+
|
|
821
|
+
<h3 id="ai-error-fix">AI Error Fix</h3>
|
|
822
|
+
<p>If auto-fix cannot resolve an upload error, the <strong>"Fix with AI"</strong> button appears. This sends the error messages to Claude, which:</p>
|
|
823
|
+
<ol>
|
|
824
|
+
<li>Scans all module files in the theme for the root cause</li>
|
|
825
|
+
<li>Identifies the specific code that triggered the error</li>
|
|
826
|
+
<li>Applies targeted fixes across all affected modules</li>
|
|
827
|
+
<li>Retries the upload automatically</li>
|
|
828
|
+
</ol>
|
|
829
|
+
<p>This is especially useful for HubL syntax errors, invalid field configurations, or template rendering issues that rule-based auto-fix cannot handle.</p>
|
|
830
|
+
|
|
831
|
+
<h3 id="creating-page-hubspot">Creating a Page in HubSpot</h3>
|
|
832
|
+
<p>After a successful upload, follow these steps in HubSpot to create a live landing page:</p>
|
|
833
|
+
<ol class="doc-steps">
|
|
834
|
+
<li><strong>Go to Content → Landing Pages</strong> in your HubSpot portal.</li>
|
|
835
|
+
<li><strong>Click "Create"</strong> and select "Landing Page."</li>
|
|
836
|
+
<li><strong>Choose your theme</strong> from the template selector. Your vibeSpot theme appears under your portal's themes.</li>
|
|
837
|
+
<li><strong>Select a template</strong> from the templates you created in vibeSpot.</li>
|
|
838
|
+
<li><strong>Drag modules</strong> from the sidebar into the page layout, or use the pre-configured module order from vibeSpot.</li>
|
|
839
|
+
<li><strong>Edit content</strong> using HubSpot's native content editor. All the fields you configured in vibeSpot are editable here.</li>
|
|
840
|
+
<li><strong>Publish</strong> when ready. Your page is live.</li>
|
|
841
|
+
</ol>
|
|
842
|
+
|
|
843
|
+
<h3 id="multi-account">Multi-Account Support</h3>
|
|
844
|
+
<p>vibeSpot supports multiple HubSpot portal connections. This is useful for agencies managing client portals or teams with staging and production environments.</p>
|
|
845
|
+
<ul>
|
|
846
|
+
<li>Add multiple accounts in Settings → HubSpot tab, each with its own Personal Access Key.</li>
|
|
847
|
+
<li>Switch the active account before uploading. The active account is shown with a green indicator.</li>
|
|
848
|
+
<li>vibeSpot detects the data center automatically: keys starting with <code>CiRldTE</code> are EU1, all others are NA1. This ensures the correct regional URL is used (<code>app-eu1.hubspot.com</code> vs. <code>app.hubspot.com</code>).</li>
|
|
849
|
+
<li>Remove accounts you no longer need from the list.</li>
|
|
850
|
+
</ul>
|
|
851
|
+
</div>
|
|
852
|
+
|
|
853
|
+
<!-- ============================================================
|
|
854
|
+
Section 8: Version History
|
|
855
|
+
============================================================ -->
|
|
856
|
+
<div class="doc-section" id="version-history">
|
|
857
|
+
<h2 id="version-history-heading">Version History <a href="#version-history" class="doc-anchor">#</a></h2>
|
|
858
|
+
<p>vibeSpot automatically tracks every generation as a git commit in the theme directory. This gives you a full timeline of changes with the ability to roll back to any previous state.</p>
|
|
859
|
+
|
|
860
|
+
<h3 id="how-version-history-works">How It Works</h3>
|
|
861
|
+
<p>Each time the AI pipeline generates or modifies modules, vibeSpot creates a git commit in the theme's local repository. The commit message describes what changed (e.g., "Generated hero, features, pricing, footer" or "Modified hero: updated headline and background color"). No manual saving is required.</p>
|
|
862
|
+
|
|
863
|
+
<h3 id="browsing-history">Browsing Versions</h3>
|
|
864
|
+
<p>Click the clock icon in the topbar to open the version history panel. You will see a timeline of all versions with:</p>
|
|
865
|
+
<ul>
|
|
866
|
+
<li>Timestamp for each version</li>
|
|
867
|
+
<li>Description of what changed</li>
|
|
868
|
+
<li>Per-template filtering to see changes for a specific template</li>
|
|
869
|
+
</ul>
|
|
870
|
+
|
|
871
|
+
<h3 id="rolling-back">Rolling Back</h3>
|
|
872
|
+
<p>Click any version in the timeline to restore the theme to that point. This is a non-destructive operation: vibeSpot creates a new commit that reverts to the selected state, so you never lose the intermediate history. You can always go forward again to a newer version.</p>
|
|
873
|
+
|
|
874
|
+
<div class="doc-callout doc-callout--tip">
|
|
875
|
+
<div class="doc-callout__label">✨ Tip</div>
|
|
876
|
+
<p>Use version history as an undo system. If an AI generation goes in the wrong direction, roll back to the previous version and try a different prompt.</p>
|
|
877
|
+
</div>
|
|
878
|
+
</div>
|
|
879
|
+
|
|
880
|
+
<!-- ============================================================
|
|
881
|
+
Section 9: Settings Reference
|
|
882
|
+
============================================================ -->
|
|
883
|
+
<div class="doc-section" id="settings">
|
|
884
|
+
<h2 id="settings-heading">Settings Reference <a href="#settings" class="doc-anchor">#</a></h2>
|
|
885
|
+
<p>Open the Settings panel by clicking the gear icon in the topbar. Settings are organized into four tabs.</p>
|
|
886
|
+
|
|
887
|
+
<h3 id="settings-ai">AI Tab</h3>
|
|
888
|
+
|
|
889
|
+
<!-- Settings Mockup -->
|
|
890
|
+
<div class="doc-mockup">
|
|
891
|
+
<div class="mock-settings">
|
|
892
|
+
<div class="mock-settings__tabs">
|
|
893
|
+
<span class="mock-settings__tab active">AI</span>
|
|
894
|
+
<span class="mock-settings__tab">HubSpot</span>
|
|
895
|
+
<span class="mock-settings__tab">GitHub</span>
|
|
896
|
+
<span class="mock-settings__tab">vibeSpot</span>
|
|
897
|
+
</div>
|
|
898
|
+
|
|
899
|
+
<div class="mock-settings__section-title">Engine</div>
|
|
900
|
+
<p style="font-size:10px;color:var(--doc-text-muted);margin:0 0 6px">Choose which AI engine generates your modules. API engines need an API key. CLI engines must be toggled on below first.</p>
|
|
901
|
+
<div class="mock-settings__engines">
|
|
902
|
+
<span class="mock-settings__engine-btn disabled">Claude Code</span>
|
|
903
|
+
<span class="mock-settings__engine-btn">Anthropic API</span>
|
|
904
|
+
<span class="mock-settings__engine-btn active">Claude (OAuth)</span>
|
|
905
|
+
<span class="mock-settings__engine-btn disabled">OpenAI API</span>
|
|
906
|
+
<span class="mock-settings__engine-btn disabled">Gemini API</span>
|
|
907
|
+
<span class="mock-settings__engine-btn disabled">Gemini CLI</span>
|
|
908
|
+
<span class="mock-settings__engine-btn disabled">Codex CLI</span>
|
|
909
|
+
</div>
|
|
910
|
+
|
|
911
|
+
<div class="mock-settings__row">
|
|
912
|
+
<span class="mock-settings__label">Model</span>
|
|
913
|
+
<span class="mock-settings__input" style="display:flex;align-items:center;color:var(--doc-text-dim)">claude-sonnet-4-6 ▾</span>
|
|
914
|
+
</div>
|
|
915
|
+
|
|
916
|
+
<div class="mock-settings__section-title" style="margin-top:12px">Agentic Pipeline</div>
|
|
917
|
+
<div class="mock-settings__row">
|
|
918
|
+
<span style="flex:1;font-size:10px;color:var(--doc-text-dim)">Multi-stage AI generation with parallel module development</span>
|
|
919
|
+
<span class="mock-settings__toggle active"></span>
|
|
920
|
+
<span style="font-size:10px;color:var(--doc-green);min-width:36px">Active</span>
|
|
921
|
+
</div>
|
|
922
|
+
|
|
923
|
+
<div class="mock-settings__section-title" style="margin-top:12px">API Keys</div>
|
|
924
|
+
<div class="mock-settings__key-row">
|
|
925
|
+
<span class="mock-settings__label">Anthropic</span>
|
|
926
|
+
<span style="flex:1"></span>
|
|
927
|
+
<span class="mock-settings__key-status mock-settings__key-status--set">✓ sk-ant-...4f2x</span>
|
|
928
|
+
</div>
|
|
929
|
+
<div class="mock-settings__key-row">
|
|
930
|
+
<span class="mock-settings__label">OpenAI</span>
|
|
931
|
+
<span style="flex:1"></span>
|
|
932
|
+
<span class="mock-settings__key-status mock-settings__key-status--missing">Not configured</span>
|
|
933
|
+
</div>
|
|
934
|
+
<div class="mock-settings__key-row">
|
|
935
|
+
<span class="mock-settings__label">Google AI</span>
|
|
936
|
+
<span style="flex:1"></span>
|
|
937
|
+
<span class="mock-settings__key-status mock-settings__key-status--missing">Not configured</span>
|
|
938
|
+
</div>
|
|
939
|
+
|
|
940
|
+
<div class="mock-settings__section-title" style="margin-top:12px">Claude OAuth</div>
|
|
941
|
+
<p style="font-size:10px;color:var(--doc-text-muted);margin:0 0 6px">Use your Claude Pro/Max subscription. Run <code style="font-size:10px">claude setup-token</code> in your terminal.</p>
|
|
942
|
+
<div class="mock-settings__row">
|
|
943
|
+
<span style="font-size:10px;color:var(--doc-green)">✓ Connected (token expires in 7h)</span>
|
|
944
|
+
<span style="flex:1"></span>
|
|
945
|
+
<span class="mock-topbar__btn" style="font-size:10px;color:var(--doc-red);border-color:rgba(239,68,68,0.3)">Disconnect</span>
|
|
946
|
+
</div>
|
|
947
|
+
|
|
948
|
+
<div class="mock-settings__section-title" style="margin-top:12px">CLI Tools</div>
|
|
949
|
+
<p style="font-size:10px;color:var(--doc-text-muted);margin:0 0 6px">Toggle CLI tools on to check availability. Disabled tools add zero overhead.</p>
|
|
950
|
+
<div class="mock-settings__key-row">
|
|
951
|
+
<span class="mock-settings__toggle"></span>
|
|
952
|
+
<span class="mock-settings__label">Claude Code</span>
|
|
953
|
+
<span style="flex:1"></span>
|
|
954
|
+
<span style="font-size:10px;color:var(--doc-text-muted)">Disabled</span>
|
|
955
|
+
</div>
|
|
956
|
+
<div class="mock-settings__key-row">
|
|
957
|
+
<span class="mock-settings__toggle"></span>
|
|
958
|
+
<span class="mock-settings__label">Gemini CLI</span>
|
|
959
|
+
<span style="flex:1"></span>
|
|
960
|
+
<span style="font-size:10px;color:var(--doc-text-muted)">Disabled</span>
|
|
961
|
+
</div>
|
|
962
|
+
<div class="mock-settings__key-row">
|
|
963
|
+
<span class="mock-settings__toggle"></span>
|
|
964
|
+
<span class="mock-settings__label">Codex CLI</span>
|
|
965
|
+
<span style="flex:1"></span>
|
|
966
|
+
<span style="font-size:10px;color:var(--doc-text-muted)">Disabled</span>
|
|
967
|
+
</div>
|
|
968
|
+
</div>
|
|
969
|
+
</div>
|
|
970
|
+
|
|
971
|
+
<p>The AI tab controls which engine powers the generation pipeline and how it operates.</p>
|
|
972
|
+
<ul>
|
|
973
|
+
<li><strong>Engine selector</strong> — Seven buttons, one for each supported engine. The active engine is highlighted in orange. Unavailable engines are grayed out — API engines require a key, CLI engines must first be toggled on in the CLI Tools section below.</li>
|
|
974
|
+
<li><strong>Model dropdown</strong> — A dynamic model catalog populated from the selected engine's available models. You can also type a custom model identifier for newly released models.</li>
|
|
975
|
+
<li><strong>Agentic pipeline toggle</strong> — An iOS-style toggle switch that enables or disables the 4-stage pipeline. When off, vibeSpot falls back to single-call mode. A sub-label shows the current status (Active, Disabled, or Not configured). On first use, vibeSpot prompts you to choose.</li>
|
|
976
|
+
<li><strong>API keys section</strong> — Input fields for Anthropic, OpenAI, and Google AI API keys. Keys are displayed masked (only last 4 characters visible) after saving.</li>
|
|
977
|
+
<li><strong>Claude OAuth</strong> — A section to paste the OAuth token generated by <code>claude setup-token</code>. Shows the token status (valid/expired).</li>
|
|
978
|
+
<li><strong>CLI tools</strong> — Toggle switches for Claude Code, Gemini CLI, and Codex CLI. CLI tools must be toggled <strong>on</strong> before they appear as selectable engines in the Engine section above. This lazy-detection approach means disabled tools add zero startup overhead. Once toggled on, vibeSpot checks if the CLI is installed and authenticated. If not installed, an install button appears. If installed but not authenticated, an auth button appears.</li>
|
|
979
|
+
</ul>
|
|
980
|
+
|
|
981
|
+
<h3 id="settings-hubspot">HubSpot Tab</h3>
|
|
982
|
+
<ul>
|
|
983
|
+
<li><strong>Upload mode toggle</strong> — Switch between API (recommended) and CLI (legacy) upload modes.</li>
|
|
984
|
+
<li><strong>Account list</strong> — Shows all connected HubSpot accounts with portal ID, account name, and data center. The active account has a green indicator.</li>
|
|
985
|
+
<li><strong>Add account</strong> — Paste a Personal Access Key to connect a new portal. vibeSpot validates the key and detects the portal metadata.</li>
|
|
986
|
+
<li><strong>Switch/remove</strong> — Click an account to make it active. Click the remove button to disconnect it.</li>
|
|
987
|
+
</ul>
|
|
988
|
+
|
|
989
|
+
<h3 id="settings-github">GitHub Tab</h3>
|
|
990
|
+
<p>The GitHub tab configures authentication for source imports (used by the "Convert React" flow).</p>
|
|
991
|
+
<ul>
|
|
992
|
+
<li><strong>GitHub CLI authentication</strong> — Uses <code>gh auth</code> to authenticate with GitHub. Required for cloning private repositories during React-to-HubSpot conversion.</li>
|
|
993
|
+
</ul>
|
|
994
|
+
|
|
995
|
+
<h3 id="settings-vibespot">vibeSpot Tab</h3>
|
|
996
|
+
<ul>
|
|
997
|
+
<li><strong>Theme toggle</strong> — Switch between dark and light mode for the vibeSpot UI.</li>
|
|
998
|
+
<li><strong>About</strong> — Project information, author, and links.</li>
|
|
999
|
+
<li><strong>Version</strong> — The currently installed version of vibeSpot.</li>
|
|
1000
|
+
</ul>
|
|
1001
|
+
</div>
|
|
1002
|
+
|
|
1003
|
+
<!-- ============================================================
|
|
1004
|
+
Section 10: CLI Commands
|
|
1005
|
+
============================================================ -->
|
|
1006
|
+
<div class="doc-section" id="cli-commands">
|
|
1007
|
+
<h2 id="cli-commands-heading">CLI Commands <a href="#cli-commands" class="doc-anchor">#</a></h2>
|
|
1008
|
+
<p>vibeSpot provides several CLI commands for different workflows. The default command (no subcommand) starts the web UI.</p>
|
|
1009
|
+
|
|
1010
|
+
<table>
|
|
1011
|
+
<thead>
|
|
1012
|
+
<tr><th>Command</th><th>Description</th></tr>
|
|
1013
|
+
</thead>
|
|
1014
|
+
<tbody>
|
|
1015
|
+
<tr><td><code>vibespot</code></td><td>Start the web UI (default)</td></tr>
|
|
1016
|
+
<tr><td><code>vibespot wizard</code></td><td>Interactive CLI wizard</td></tr>
|
|
1017
|
+
<tr><td><code>vibespot init</code></td><td>Environment check & setup</td></tr>
|
|
1018
|
+
<tr><td><code>vibespot convert</code></td><td>React-to-HubSpot conversion</td></tr>
|
|
1019
|
+
<tr><td><code>vibespot upload</code></td><td>Upload theme to HubSpot</td></tr>
|
|
1020
|
+
<tr><td><code>vibespot doctor</code></td><td>Diagnostics & health check</td></tr>
|
|
1021
|
+
</tbody>
|
|
1022
|
+
</table>
|
|
1023
|
+
|
|
1024
|
+
<div class="doc-collapse">
|
|
1025
|
+
<button class="doc-collapse__trigger">
|
|
1026
|
+
<span class="doc-collapse__arrow">▶</span>
|
|
1027
|
+
<code>vibespot</code> — Start the Web UI
|
|
1028
|
+
</button>
|
|
1029
|
+
<div class="doc-collapse__content">
|
|
1030
|
+
<p>Starts the HTTP server on port 4200 and opens the browser automatically. This is the main way to use vibeSpot.</p>
|
|
1031
|
+
<pre><code>vibespot</code></pre>
|
|
1032
|
+
<p>The server runs a WebSocket connection for real-time pipeline updates, serves the static UI assets, handles AI requests, and manages sessions. Press <kbd>Ctrl</kbd>+<kbd>C</kbd> to stop the server.</p>
|
|
1033
|
+
</div>
|
|
1034
|
+
</div>
|
|
1035
|
+
|
|
1036
|
+
<div class="doc-collapse">
|
|
1037
|
+
<button class="doc-collapse__trigger">
|
|
1038
|
+
<span class="doc-collapse__arrow">▶</span>
|
|
1039
|
+
<code>vibespot wizard</code> — Interactive CLI Wizard
|
|
1040
|
+
</button>
|
|
1041
|
+
<div class="doc-collapse__content">
|
|
1042
|
+
<p>A guided 6-step terminal wizard for converting React projects into HubSpot themes. Runs entirely in the terminal without a browser.</p>
|
|
1043
|
+
<pre><code>vibespot wizard</code></pre>
|
|
1044
|
+
<p>Steps:</p>
|
|
1045
|
+
<ol>
|
|
1046
|
+
<li><strong>Preflight</strong> — Checks Node.js, Git, AI engine availability, and HubSpot CLI.</li>
|
|
1047
|
+
<li><strong>Source</strong> — Clone a Git repository or select a local directory containing a React project.</li>
|
|
1048
|
+
<li><strong>Theme Setup</strong> — Configure the HubSpot theme name, template type, and target account.</li>
|
|
1049
|
+
<li><strong>Conversion</strong> — AI analyzes React components and generates equivalent HubSpot modules with HubL templates.</li>
|
|
1050
|
+
<li><strong>Upload</strong> — Deploys the generated theme to HubSpot.</li>
|
|
1051
|
+
<li><strong>Next Steps</strong> — Shows links to create pages in HubSpot and tips for further customization.</li>
|
|
1052
|
+
</ol>
|
|
1053
|
+
</div>
|
|
1054
|
+
</div>
|
|
1055
|
+
|
|
1056
|
+
<div class="doc-collapse">
|
|
1057
|
+
<button class="doc-collapse__trigger">
|
|
1058
|
+
<span class="doc-collapse__arrow">▶</span>
|
|
1059
|
+
<code>vibespot init</code> — Environment Check & Setup
|
|
1060
|
+
</button>
|
|
1061
|
+
<div class="doc-collapse__content">
|
|
1062
|
+
<p>Runs the preflight check from the wizard as a standalone command. Verifies all prerequisites and offers to configure missing items.</p>
|
|
1063
|
+
<pre><code>vibespot init</code></pre>
|
|
1064
|
+
<p>Checks: Node.js version, Git installation, available AI engines, API key configuration, HubSpot CLI installation.</p>
|
|
1065
|
+
</div>
|
|
1066
|
+
</div>
|
|
1067
|
+
|
|
1068
|
+
<div class="doc-collapse">
|
|
1069
|
+
<button class="doc-collapse__trigger">
|
|
1070
|
+
<span class="doc-collapse__arrow">▶</span>
|
|
1071
|
+
<code>vibespot convert</code> — React-to-HubSpot Conversion
|
|
1072
|
+
</button>
|
|
1073
|
+
<div class="doc-collapse__content">
|
|
1074
|
+
<p>Converts a React or Lovable project into HubSpot CMS modules without uploading. Useful if you want to review and edit the generated files before deploying.</p>
|
|
1075
|
+
<pre><code>vibespot convert --source ./my-react-app --theme my-hubspot-theme</code></pre>
|
|
1076
|
+
<p>The output is written to <code>~/vibespot-themes/my-hubspot-theme</code>. You can then open it in the web UI for further editing or upload it separately.</p>
|
|
1077
|
+
</div>
|
|
1078
|
+
</div>
|
|
1079
|
+
|
|
1080
|
+
<div class="doc-collapse">
|
|
1081
|
+
<button class="doc-collapse__trigger">
|
|
1082
|
+
<span class="doc-collapse__arrow">▶</span>
|
|
1083
|
+
<code>vibespot upload</code> — Upload Theme to HubSpot
|
|
1084
|
+
</button>
|
|
1085
|
+
<div class="doc-collapse__content">
|
|
1086
|
+
<p>Uploads an existing theme directory to your HubSpot portal. Can be used independently of the web UI.</p>
|
|
1087
|
+
<pre><code>vibespot upload --theme my-hubspot-theme</code></pre>
|
|
1088
|
+
<p>Uses the active HubSpot account from your configuration. The auto-fix system runs automatically if upload errors occur.</p>
|
|
1089
|
+
</div>
|
|
1090
|
+
</div>
|
|
1091
|
+
|
|
1092
|
+
<div class="doc-collapse">
|
|
1093
|
+
<button class="doc-collapse__trigger">
|
|
1094
|
+
<span class="doc-collapse__arrow">▶</span>
|
|
1095
|
+
<code>vibespot doctor</code> — Diagnostics
|
|
1096
|
+
</button>
|
|
1097
|
+
<div class="doc-collapse__content">
|
|
1098
|
+
<p>Read-only diagnostics command that checks your entire environment without making any changes.</p>
|
|
1099
|
+
<pre><code>vibespot doctor</code></pre>
|
|
1100
|
+
<p>Reports on: Node.js version (requires 18+), Git installation, HubSpot CLI status, available AI CLI tools (Claude Code, Gemini CLI, Codex CLI), whether API keys are configured (Anthropic, OpenAI, Gemini — checks presence, not validity), active AI engine, and last-used theme path.</p>
|
|
1101
|
+
</div>
|
|
1102
|
+
</div>
|
|
1103
|
+
</div>
|
|
1104
|
+
|
|
1105
|
+
<!-- ============================================================
|
|
1106
|
+
Section 11: Keyboard Shortcuts
|
|
1107
|
+
============================================================ -->
|
|
1108
|
+
<div class="doc-section" id="shortcuts">
|
|
1109
|
+
<h2 id="shortcuts-heading">Keyboard Shortcuts <a href="#shortcuts" class="doc-anchor">#</a></h2>
|
|
1110
|
+
|
|
1111
|
+
<table>
|
|
1112
|
+
<thead>
|
|
1113
|
+
<tr><th>Shortcut</th><th>Action</th><th>Context</th></tr>
|
|
1114
|
+
</thead>
|
|
1115
|
+
<tbody>
|
|
1116
|
+
<tr><td><kbd>Enter</kbd></td><td>Send message</td><td>Chat input</td></tr>
|
|
1117
|
+
<tr><td><kbd>Shift</kbd>+<kbd>Enter</kbd></td><td>New line</td><td>Chat input</td></tr>
|
|
1118
|
+
<tr><td><kbd>Cmd</kbd>/<kbd>Ctrl</kbd>+<kbd>S</kbd></td><td>Save file</td><td>Code editor</td></tr>
|
|
1119
|
+
<tr><td><kbd>Escape</kbd></td><td>Close modal or dialog</td><td>Any overlay</td></tr>
|
|
1120
|
+
<tr><td><kbd>Escape</kbd></td><td>Close settings panel</td><td>Settings panel</td></tr>
|
|
1121
|
+
<tr><td><kbd>/</kbd></td><td>Focus search</td><td>Documentation</td></tr>
|
|
1122
|
+
</tbody>
|
|
1123
|
+
</table>
|
|
1124
|
+
</div>
|
|
1125
|
+
|
|
1126
|
+
<!-- ============================================================
|
|
1127
|
+
Section 12: Troubleshooting
|
|
1128
|
+
============================================================ -->
|
|
1129
|
+
<div class="doc-section" id="troubleshooting">
|
|
1130
|
+
<h2 id="troubleshooting-heading">Troubleshooting <a href="#troubleshooting" class="doc-anchor">#</a></h2>
|
|
1131
|
+
<p>Common issues and how to resolve them:</p>
|
|
1132
|
+
|
|
1133
|
+
<div class="doc-collapse">
|
|
1134
|
+
<button class="doc-collapse__trigger">
|
|
1135
|
+
<span class="doc-collapse__arrow">▶</span>
|
|
1136
|
+
"No AI engine available"
|
|
1137
|
+
</button>
|
|
1138
|
+
<div class="doc-collapse__content">
|
|
1139
|
+
<p>vibeSpot could not detect any configured AI engine. You need at least one of the following:</p>
|
|
1140
|
+
<ul>
|
|
1141
|
+
<li>Install the Claude Code CLI: <code>npm install -g @anthropic-ai/claude-code</code> then <code>claude auth</code></li>
|
|
1142
|
+
<li>Add an Anthropic API key in Settings → AI tab or via <code>export ANTHROPIC_API_KEY=sk-ant-...</code></li>
|
|
1143
|
+
<li>Add an OpenAI or Gemini API key</li>
|
|
1144
|
+
</ul>
|
|
1145
|
+
<p>Run <code>vibespot doctor</code> to see a full diagnostic of available engines.</p>
|
|
1146
|
+
</div>
|
|
1147
|
+
</div>
|
|
1148
|
+
|
|
1149
|
+
<div class="doc-collapse">
|
|
1150
|
+
<button class="doc-collapse__trigger">
|
|
1151
|
+
<span class="doc-collapse__arrow">▶</span>
|
|
1152
|
+
"Upload failed"
|
|
1153
|
+
</button>
|
|
1154
|
+
<div class="doc-collapse__content">
|
|
1155
|
+
<p>Upload failures are usually caused by one of:</p>
|
|
1156
|
+
<ul>
|
|
1157
|
+
<li><strong>Invalid PAK permissions.</strong> Your Personal Access Key needs the <strong>CMS</strong> scope (Design Manager read/write). Regenerate the key with the correct permissions.</li>
|
|
1158
|
+
<li><strong>HubL syntax errors.</strong> The auto-fix system handles most of these automatically. If it does not, click "Fix with AI" to let Claude diagnose and repair the issue.</li>
|
|
1159
|
+
<li><strong>CLI mode issues.</strong> If using CLI mode, try switching to API mode in Settings → HubSpot tab. API mode is more reliable.</li>
|
|
1160
|
+
</ul>
|
|
1161
|
+
<p>Check the error message in the upload progress panel for specific details.</p>
|
|
1162
|
+
</div>
|
|
1163
|
+
</div>
|
|
1164
|
+
|
|
1165
|
+
<div class="doc-collapse">
|
|
1166
|
+
<button class="doc-collapse__trigger">
|
|
1167
|
+
<span class="doc-collapse__arrow">▶</span>
|
|
1168
|
+
"Rate limited by Anthropic API"
|
|
1169
|
+
</button>
|
|
1170
|
+
<div class="doc-collapse__content">
|
|
1171
|
+
<p>When the Anthropic API returns a rate limit error, vibeSpot automatically retries with exponential backoff. The retry intervals are: 10 seconds, 20 seconds, 40 seconds, 60 seconds, and 120 seconds. In most cases the request succeeds on retry without any action needed.</p>
|
|
1172
|
+
<p>If rate limiting persists, you may be hitting your account's rate cap. Consider upgrading your Anthropic plan or reducing <code>agenticConcurrency</code> in your config to lower the number of parallel API calls.</p>
|
|
1173
|
+
</div>
|
|
1174
|
+
</div>
|
|
1175
|
+
|
|
1176
|
+
<div class="doc-collapse">
|
|
1177
|
+
<button class="doc-collapse__trigger">
|
|
1178
|
+
<span class="doc-collapse__arrow">▶</span>
|
|
1179
|
+
"Claude OAuth session expired"
|
|
1180
|
+
</button>
|
|
1181
|
+
<div class="doc-collapse__content">
|
|
1182
|
+
<p>OAuth tokens have a limited lifespan. When the token expires, generation fails with an authentication error.</p>
|
|
1183
|
+
<p>To fix: run <code>claude setup-token</code> in your terminal, complete the browser-based authentication, and paste the new token into Settings → AI tab → Claude OAuth section.</p>
|
|
1184
|
+
</div>
|
|
1185
|
+
</div>
|
|
1186
|
+
|
|
1187
|
+
<div class="doc-collapse">
|
|
1188
|
+
<button class="doc-collapse__trigger">
|
|
1189
|
+
<span class="doc-collapse__arrow">▶</span>
|
|
1190
|
+
"Module not rendering in preview"
|
|
1191
|
+
</button>
|
|
1192
|
+
<div class="doc-collapse__content">
|
|
1193
|
+
<p>If a module appears blank or broken in the preview, check:</p>
|
|
1194
|
+
<ul>
|
|
1195
|
+
<li><strong>fields.json validity.</strong> Open the module's <code>fields.json</code> in the code editor and verify it is valid JSON. A trailing comma or mismatched bracket will cause parsing failure.</li>
|
|
1196
|
+
<li><strong>HubL syntax.</strong> Look for unbalanced tags (e.g., <code>{% if %}</code> without <code>{% endif %}</code>). The quality check catches most of these, but manual edits can introduce new issues.</li>
|
|
1197
|
+
<li><strong>JavaScript errors.</strong> Open the browser console (<kbd>Cmd</kbd>+<kbd>Option</kbd>+<kbd>J</kbd>) to check for runtime errors in the module's JS.</li>
|
|
1198
|
+
</ul>
|
|
1199
|
+
</div>
|
|
1200
|
+
</div>
|
|
1201
|
+
|
|
1202
|
+
<div class="doc-collapse">
|
|
1203
|
+
<button class="doc-collapse__trigger">
|
|
1204
|
+
<span class="doc-collapse__arrow">▶</span>
|
|
1205
|
+
"CSS not applying"
|
|
1206
|
+
</button>
|
|
1207
|
+
<div class="doc-collapse__content">
|
|
1208
|
+
<p>The most common causes of CSS not applying:</p>
|
|
1209
|
+
<ul>
|
|
1210
|
+
<li><strong>Missing theme prefix.</strong> All CSS classes should be prefixed with the theme name (e.g., <code>.my-theme-hero__title</code>). Without the prefix, styles may conflict with HubSpot's global CSS or be too generic to match.</li>
|
|
1211
|
+
<li><strong>CDN imports stripped.</strong> External <code>@import</code> statements (like Google Fonts) are automatically removed because HubSpot does not allow CDN imports. Use system fonts or self-hosted alternatives.</li>
|
|
1212
|
+
<li><strong>Scoped CSS issues.</strong> The <code>scope_css</code> HubL tag wraps module CSS in a scope. Make sure your selectors work within this scope.</li>
|
|
1213
|
+
</ul>
|
|
1214
|
+
</div>
|
|
1215
|
+
</div>
|
|
1216
|
+
|
|
1217
|
+
<div class="doc-collapse">
|
|
1218
|
+
<button class="doc-collapse__trigger">
|
|
1219
|
+
<span class="doc-collapse__arrow">▶</span>
|
|
1220
|
+
"Blank preview during generation"
|
|
1221
|
+
</button>
|
|
1222
|
+
<div class="doc-collapse__content">
|
|
1223
|
+
<p>Occasionally the preview iframe can get into a stale state during rapid generation cycles. To fix:</p>
|
|
1224
|
+
<ul>
|
|
1225
|
+
<li>Hard refresh the page with <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>R</kbd> (or <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>R</kbd>) to clear the browser cache.</li>
|
|
1226
|
+
<li>If the issue persists, check the browser console for errors. An incomplete WebSocket reconnection can sometimes stall preview updates.</li>
|
|
1227
|
+
</ul>
|
|
1228
|
+
</div>
|
|
1229
|
+
</div>
|
|
1230
|
+
|
|
1231
|
+
<div class="doc-callout doc-callout--danger">
|
|
1232
|
+
<div class="doc-callout__label">⚠ Still stuck?</div>
|
|
1233
|
+
<p>Run <code>vibespot doctor</code> for a full environment diagnostic. If the issue is not listed here, check the <a href="https://github.com/borismichel/vibespot/issues" target="_blank">GitHub Issues</a> page or open a new issue with the error output.</p>
|
|
1234
|
+
</div>
|
|
1235
|
+
</div>
|
|
1236
|
+
|
|
1237
|
+
</main>
|
|
1238
|
+
</div>
|
|
1239
|
+
|
|
1240
|
+
<script src="docs.js"></script>
|
|
1241
|
+
</body>
|
|
1242
|
+
</html>
|