vibes

• [Pre-Flight Check](#pre-flight-check-connect-status) - Validate Connect setup before coding
• [Core Rules](#core-rules) - Essential guidelines for app generation
• [Generation Process](#generation-process) - Design reasoning and code output
• [Assembly Workflow](#assembly-workflow) - Build the final app
• [UI Style & Theming](#ui-style--theming) - OKLCH colors and design patterns
• [Fireproof API](#fireproof-api) - Database operations and hooks
• [AI Features](#ai-features-optional) - Optional AI integration
• [Common Mistakes](#common-mistakes-to-avoid) - Avoid these pitfalls
• [Deployment Options](#deployment-options) - Where to deploy

---

# Vibes DIY App Generator

Generate React web applications using Fireproof for local-first data persistence.

MANDATORY: Complete these steps BEFORE generating any app code.

Step 0: Check Connect Status

Run this command first to validate all required credentials:

```bash

if test -f "./.env" && \

grep -qE "^VITE_CLERK_PUBLISHABLE_KEY=pk_(test|live)_" ./.env 2>/dev/null && \

grep -qE "^VITE_API_URL=" ./.env 2>/dev/null && \

grep -qE "^VITE_CLOUD_URL=" ./.env 2>/dev/null; then

echo "CONNECT_READY"

else

echo "CONNECT_NOT_READY"

fi

```

If output is "CONNECT_NOT_READY", Connect setup is required. Inform the user:

> Connect with Clerk authentication is required for Vibes apps. Let me guide you through the setup.

Then proceed with Connect setup below.

Connect Setup Steps:

Step 1: Clone Fireproof Repository (if not already present)

```bash

# Check if repo exists

if [ ! -d "./fireproof" ]; then

git clone --branch selem/docker-for-all https://github.com/fireproof-storage/fireproof.git ./fireproof

fi

```

Step 2: Choose Credential Mode

Use AskUserQuestion:

```

Question: "How would you like to set up credentials?"

Header: "Credentials"

Options:

• Label: "Fresh credentials (Recommended)"

Description: "Generate all new session tokens and CA keys. Use this for new projects."

• Label: "Import from file"

Description: "Load credentials from a colleague's exported file. Use for team sharing."

• Label: "Quick local dev"

Description: "Use preset dev tokens. Fastest setup but not for production."

```

Step 3: Gather Clerk Keys

Collect credentials using AskUserQuestion. Users enter values via the "Other" option.

3a. Publishable Key:

```

Question: "Enter your Clerk Publishable Key (paste via 'Other')"

Header: "Publishable"

Options:

• Label: "I need to create a Clerk app first"

Description: "Go to clerk.com → Create application → Configure → API Keys"

```

After receiving via "Other", validate: must start with pk_test_ or pk_live_.

If invalid, inform the user and ask again.

3b. Secret Key:

```

Question: "Enter your Clerk Secret Key (paste via 'Other')"

Header: "Secret Key"

Options:

• Label: "Where do I find this?"

Description: "Clerk Dashboard → Configure → API Keys → Secret keys section"

```

After receiving via "Other", validate: must start with sk_test_ or sk_live_.

If invalid, inform the user and ask again.

3c. JWT URL (Auto-derived):

Extract the Clerk domain from the publishable key - no user input needed:

```javascript

// Publishable key format: pk_test_

const payload = publishableKey.replace(/^pk_(test|live)_/, '');

const domain = atob(payload).replace('$', '');

const jwtUrl = https://${domain}/.well-known/jwks.json;

```

Example: pk_test_aW50ZXJuYWwtZGluZ28tMjguY2xlcmsuYWNjb3VudHMuZGV2JA

→ decodes to internal-dingo-28.clerk.accounts.dev

→ JWT URL: https://internal-dingo-28.clerk.accounts.dev/.well-known/jwks.json

Tell the user what was derived so they can verify it looks correct.

Step 3b: Configure JWT Template

Instruct the user to set up a JWT template in Clerk:

> In your Clerk Dashboard, go to Configure → Sessions → JWT templates.

> Click "Add a new template" and paste this under Claims:

>

> ```json

> {

> "role": "authenticated",

> "params": {

> "last": "{{user.last_name}}",

> "name": "{{user.username}}",

> "email": "{{user.primary_email_address}}",

> "first": "{{user.first_name}}",

> "image_url": "{{user.image_url}}",

> "external_id": "{{user.external_id}}",

> "public_meta": "{{user.public_metadata}}",

> "email_verified": "{{user.email_verified}}"

> },

> "userId": "{{user.id}}"

> }

> ```

>

> Save the template. This ensures Fireproof receives the user info it needs for sync.

Step 4: Run Setup Script

```bash

# Fresh credentials (default)

node "${CLAUDE_PLUGIN_ROOT}/scripts/setup-connect.js" \

--clerk-publishable-key "pk_test_..." \

--clerk-secret-key "sk_test_..." \

--clerk-jwt-url "https://your-app.clerk.accounts.dev" \

--mode fresh

# Import from file

node "${CLAUDE_PLUGIN_ROOT}/scripts/setup-connect.js" \

--clerk-publishable-key "pk_test_..." \

--clerk-secret-key "sk_test_..." \

--clerk-jwt-url "https://your-app.clerk.accounts.dev" \

--mode import --import-file ./team-credentials.txt

# Quick dev (uses preset tokens)

node "${CLAUDE_PLUGIN_ROOT}/scripts/setup-connect.js" \

--clerk-publishable-key "pk_test_..." \

--clerk-secret-key "sk_test_..." \

--clerk-jwt-url "https://your-app.clerk.accounts.dev" \

--mode quick-dev

```

Step 5: Show Docker Instructions

After successful setup, tell the user:

```

Connect setup complete!

To start the Fireproof services:

cd fireproof/core && docker compose up --build

Services will be available at:

- Token API: http://localhost:8080/api/

- Cloud Sync: fpcloud://localhost:8080?protocol=ws

Your .env file has been created. Apps you generate will auto-detect Connect.

```

If Connect IS set up (CONNECT_READY), proceed directly to app generation. The assemble script will populate Connect config from .env.

Platform Name vs User Intent: "Vibes" is the name of this app platform (Vibes DIY). When users say "vibe" or "vibes" in their prompt, interpret it as:

• Their project/brand name ("my vibes tracker")
• A positive descriptor ("good vibes app")
• NOT as "mood/atmosphere" literally

Do not default to ambient mood generators, floating orbs, or meditation apps unless explicitly requested.

Import Map Note: The import map aliases use-fireproof to @necrodome/fireproof-clerk. Your code uses import { useFireproofClerk } from "use-fireproof" and the browser resolves this to the @necrodome/fireproof-clerk package, which provides Clerk authentication integration and cloud sync support. This is intentional—it ensures compatible versions and enables auth when Connect is configured.

• Use JSX - Standard React syntax with Babel transpilation
• Single HTML file - App code assembled into template
• Fireproof for data - Use useFireproofClerk for database + sync
• Auto-detect Connect - Template handles Clerk auth when Connect is configured
• Tailwind for styling - Mobile-first, responsive design

Step 1: Design Reasoning

Before writing code, reason about the design in tags:

```

• What is the core functionality and user flow?
• What OKLCH colors fit this theme? (dark/light, warm/cool, vibrant/muted)
• What layout best serves the content? (cards, list, dashboard, single-focus)
• What micro-interactions would feel satisfying? (hover states, transitions)
• What visual style matches the purpose? (minimal, bold, playful, professional)

```

Step 2: Output Code

After reasoning, output the complete JSX in tags:

```

import React, { useState } from "react";

import { useFireproofClerk } from "use-fireproof";

export default function App() {

const { database, useLiveQuery, useDocument, syncStatus } = useFireproofClerk("app-name-db");

// ... component logic

return (

);

}

```

⚠️ CRITICAL: Fireproof Hook Pattern

The @necrodome/fireproof-clerk package exports ONLY useFireproofClerk. Always use this pattern:

```jsx

// ✅ CORRECT - This is the ONLY pattern that works

import { useFireproofClerk } from "use-fireproof";

const { database, useDocument, useLiveQuery, syncStatus } = useFireproofClerk("my-db");

const { doc, merge } = useDocument({ _id: "doc1" });

// ❌ WRONG - DO NOT USE (old use-vibes API)

import { toCloud, useFireproof } from "use-fireproof"; // WRONG - old API

import { useDocument } from "use-fireproof"; // WRONG - standalone import

const { attach } = useFireproof("db", { attach: toCloud() }); // WRONG - old pattern

```

Sync Status: syncStatus provides the current sync state as a string. Display it for user feedback.

Connect Configuration: Generated apps require Clerk authentication and cloud sync.

The assemble.js script populates window.__VIBES_CONFIG__ from your .env file.

Apps will show a configuration error if credentials are missing.

1. Extract the code from tags and write to app.jsx
2. Optionally save content to design.md for documentation
3. Run assembly:

```bash

node "${CLAUDE_PLUGIN_ROOT}/scripts/assemble.js" app.jsx index.html

```

1. Tell user: "Open index.html in your browser to view your app."

---

> ⚠️ DEPRECATED API: Never use the old useFireproof with toCloud() pattern. See [references/DEPRECATED.md](references/DEPRECATED.md) for migration details if you encounter legacy code.

---

OKLCH Colors (Recommended)

Use OKLCH for predictable, vibrant colors. Unlike RGB/HSL, OKLCH has perceptual lightness - changing L by 10% looks the same across all hues.

```css

oklch(L C H)

/ L = Lightness (0-1): 0 black, 1 white /

/ C = Chroma (0-0.4): 0 gray, higher = more saturated /

/ H = Hue (0-360): color wheel degrees /

```

Theme-appropriate palettes:

```jsx

{/ Dark/moody theme /}

className="bg-[oklch(0.15_0.02_250)]" / Deep blue-black /

{/ Warm/cozy theme /}

className="bg-[oklch(0.25_0.08_30)]" / Warm brown /

{/ Fresh/bright theme /}

className="bg-[oklch(0.95_0.03_150)]" / Mint white /

{/ Vibrant accent /}

className="bg-[oklch(0.7_0.2_145)]" / Vivid green /

```

Better Gradients with OKLCH

Use in oklch for smooth gradients without muddy middle zones:

```jsx

{/ Smooth gradient - no gray middle /}

className="bg-[linear-gradient(in_oklch,oklch(0.6_0.2_250),oklch(0.6_0.2_150))]"

{/ Sunset gradient /}

className="bg-[linear-gradient(135deg_in_oklch,oklch(0.7_0.25_30),oklch(0.5_0.2_330))]"

{/ Dark glass effect /}

className="bg-[linear-gradient(180deg_in_oklch,oklch(0.2_0.05_270),oklch(0.1_0.02_250))]"

```

Neobrute Style (Optional)

For bold, graphic UI:

• Borders: thick 4px, dark border-[#0f172a]
• Shadows: hard offset shadow-[6px_6px_0px_#0f172a]
• Corners: square (0px) OR pill (rounded-full) - no in-between

```jsx

Click Me

```

Glass Morphism (Dark themes)

```jsx

```

Color Modifications

Lighten/darken using L value:

• Hover: increase L by 0.05-0.1
• Active/pressed: decrease L by 0.05
• Disabled: reduce C to near 0

---

Fireproof is a local-first database - no loading or error states required, just empty data states. Data persists across sessions and syncs in real-time when Connect is configured.

Setup

```jsx

import { useFireproofClerk } from "use-fireproof";

const { database, useLiveQuery, useDocument, syncStatus } = useFireproofClerk("my-app-db");

```

Note: When Connect is configured (via .env), the template wraps your App in ClerkFireproofProvider, enabling authenticated cloud sync automatically. Your code just uses useFireproofClerk.

Choosing Your Pattern

useDocument = Form-like editing. Accumulate changes with merge(), then save with submit() or save(). Best for: text inputs, multi-field forms, editing workflows.

database.put() + useLiveQuery = Immediate state changes. Each action writes directly. Best for: counters, toggles, buttons, any single-action updates.

```jsx

// FORM PATTERN: User types, then submits

const { doc, merge, submit } = useDocument({ title: "", body: "", type: "post" });

// merge({ title: "..." }) on each keystroke, submit() when done

// IMMEDIATE PATTERN: Each click is a complete action

const { docs } = useLiveQuery("_id", { key: "counter" });

const count = docs[0]?.value || 0;

const increment = () => database.put({ _id: "counter", value: count + 1 });

```

useDocument - Form State (NOT useState)

IMPORTANT: Don't use useState() for form data. Use merge() and submit() from useDocument. Only use useState for ephemeral UI state (active tabs, open/closed panels).

```jsx

// Create new documents (auto-generated _id recommended)

const { doc, merge, submit, reset } = useDocument({ text: "", type: "item" });

// Edit existing document by known _id

const { doc, merge, save } = useDocument({ _id: "user-profile:abc@example.com" });

// Methods:

// - merge(updates) - update fields: merge({ text: "new value" })

// - submit(e) - save + reset (for forms creating new items)

// - save() - save without reset (for editing existing items)

// - reset() - discard changes

```

useLiveQuery - Real-time Lists

```jsx

// Simple: query by field value

const { docs } = useLiveQuery("type", { key: "item" });

// Recent items (_id is roughly temporal - great for simple sorting)

const { docs } = useLiveQuery("_id", { descending: true, limit: 100 });

// Range query

const { docs } = useLiveQuery("rating", { range: [3, 5] });

```

CRITICAL: Custom index functions are SANDBOXED and CANNOT access external variables. Query all, filter in render:

```jsx

// GOOD: Query all, filter in render

const { docs: allItems } = useLiveQuery("type", { key: "item" });

const filtered = allItems.filter(d => d.category === selectedCategory);

```

Direct Database Operations

```jsx

// Create/update

const { id } = await database.put({ text: "hello", type: "item" });

// Delete

await database.del(item._id);

```

Common Pattern - Form + List

```jsx

import React from "react";

import { useFireproofClerk } from "use-fireproof";

export default function App() {

const { database, useLiveQuery, useDocument, syncStatus } = useFireproofClerk("my-db");

// Form for new items (submit resets for next entry)

const { doc, merge, submit } = useDocument({ text: "", type: "item" });

// Live list of all items of type "item"

const { docs } = useLiveQuery("type", { key: "item" });

return (

);

}

```

---

If the user's prompt suggests AI-powered features (chatbot, summarization, content generation, etc.), the app needs AI capabilities via the useAI hook.

Detecting AI Requirements

Look for these patterns in the user's prompt:

• "chatbot", "chat with AI", "ask AI"
• "summarize", "generate", "write", "create content"
• "analyze", "classify", "recommend"
• "AI-powered", "intelligent", "smart" (in context of features)

Collecting OpenRouter Key

When AI is needed, ask the user:

> This app needs AI capabilities. Please provide your OpenRouter API key.

> Get one at: https://openrouter.ai/keys

Store the key for use with the --ai-key flag during deployment.

Using the useAI Hook

The useAI hook is automatically included in the template when AI features are detected:

```jsx

import React from "react";

import { useFireproofClerk } from "use-fireproof";

export default function App() {

const { database, useLiveQuery, syncStatus } = useFireproofClerk("ai-chat-db");

const { callAI, loading, error } = useAI();

const handleSend = async (message) => {

// Save user message

await database.put({ role: "user", content: message, type: "message" });

// Call AI

const response = await callAI({

model: "anthropic/claude-sonnet-4",

messages: [{ role: "user", content: message }]

});

// Save AI response

const aiMessage = response.choices[0].message.content;

await database.put({ role: "assistant", content: aiMessage, type: "message" });

};

// Handle limit exceeded

if (error?.code === 'LIMIT_EXCEEDED') {

return (

);

}

// ... rest of UI

}

```

useAI API

```jsx

const { callAI, loading, error, clearError } = useAI();

// callAI options

await callAI({

model: "anthropic/claude-sonnet-4", // or other OpenRouter models

messages: [

{ role: "system", content: "You are a helpful assistant." },

{ role: "user", content: "Hello!" }

],

temperature: 0.7, // optional

max_tokens: 1000 // optional

});

// error structure

error = {

code: "LIMIT_EXCEEDED" | "API_ERROR" | "NETWORK_ERROR",

message: "Human-readable error message"

}

```

Deployment with AI

When deploying AI-enabled apps, include the OpenRouter key:

```bash

node "${CLAUDE_PLUGIN_ROOT}/scripts/deploy-exe.js" \

--name myapp \

--file index.html \

--ai-key "sk-or-v1-your-key"

```

---

• DON'T use useState for form fields - use useDocument
• DON'T use Fireproof.fireproof() - use useFireproofClerk() hook
• DON'T use the old useFireproof with toCloud() - use useFireproofClerk instead
• DON'T use white text on light backgrounds
• DON'T use call-ai directly - use useAI hook instead (it handles proxying and limits)

---

After generating your app, you can deploy it:

• exe.dev - VM hosting with nginx. Use /vibes:exe to deploy.
• Local - Just open index.html in your browser. Works offline with Fireproof.

---

After generating and assembling the app, present these options using AskUserQuestion:

```

Question: "Your app is ready! What would you like to do next?"

Header: "Next"

Options:

• Label: "Keep improving this app"

Description: "Continue iterating on what you've built. Add new features, refine the styling, or adjust functionality. Great when you have a clear vision and want to polish it further."

• Label: "Apply a design reference (/design-reference)"

Description: "Have a design.html or mockup file? This skill mechanically transforms your app to match it exactly - pixel-perfect fidelity with your Fireproof data binding preserved."

• Label: "Explore variations (/riff)"

Description: "Not sure if this is the best approach? Riff generates 3-10 completely different interpretations of your idea in parallel. You'll get ranked variations with business model analysis to help you pick the winner."

• Label: "Make it a SaaS (/sell)"

Description: "Ready to monetize? Sell transforms your app into a multi-tenant SaaS with Clerk authentication, subscription billing, and isolated databases per customer. Each user gets their own subdomain."

• Label: "Deploy to exe.dev (/exe)"

Description: "Go live right now. Deploy creates a persistent VM at yourapp.exe.xyz with HTTPS, nginx, and Claude pre-installed for remote development. Your app stays online even when you close your laptop."

• Label: "I'm done for now"

Description: "Wrap up this session. Your files are saved locally - come back anytime to continue."

```

After user responds:

• "Keep improving" → Acknowledge and stay ready for iteration prompts
• "Apply a design reference" → Auto-invoke /vibes:design-reference skill
• "Explore variations" → Auto-invoke /vibes:riff skill
• "Make it a SaaS" → Auto-invoke /vibes:sell skill
• "Deploy" → Auto-invoke /vibes:exe skill
• "I'm done" → Confirm files saved, wish them well

Do NOT proceed to code generation until:

Connect setup is complete with valid Clerk credentials in .env (pre-flight check returns CONNECT_READY).