# Generation Guide

> Complete system context for authoring valid storefront source

Canonical URL: https://fa7e86e3d553:3005/resources/generation-guide

## Overview

The **Generation Guide** is the single most important resource in the Storefront MCP. It delivers the complete system context needed to author valid source-format pages.

**URI**: `vibe://docs/generation-guide`  
**Format**: `text/markdown`  
**When to read**: BEFORE generating any page — it must be your first action in any generation workflow.

## What It Contains

The generation guide is a dynamically assembled markdown document with five sections:

### 1. System Prompt

Complete instructions on how to author source-format HTML, including:
- **Output format**: HTML sections with structured `head`, `theme_css`, and `scripts` tool parameters
- **Base styles**: CSS reset and typography already loaded by the renderer
- **CSS variables**: The complete `--lx-*` variable catalog
- **Shared keyframes**: Pre-loaded animations (fadeUp, fadeIn, scaleIn, slideInLeft, slideInRight, marquee, float, shimmer, wordFade, pulseRing)
- **14 generation rules**: Tailwind-first, island embedding protocol, semantic HTML, mobile-first design, performance guidelines, security constraints

### 2. User Prompt (optional)

If the guide was requested with a brand brief or page type, this section provides:
- Page type focus (PDP, landing, homepage, collection)
- Brand tone and industry context
- Relevant products and reference URLs
- Page-specific island recommendations

### 3. Island Catalog

Filtered list of the currently available, non-deprecated islands with:
- Name and category (commerce, social_proof, content, engagement, navigation)
- Usage hint (when and where to use the island)
- HTML embedding example with `<lx-island>` and a JSON script child

The catalog is filtered by page type if specified, otherwise shows all islands.

### 4. Valid Island Names

Comma-separated list generated from the current island catalog for quick
validation. Do not depend on a hardcoded island count.

### 5. Page Source Contract

The complete authoring contract for source HTML, head settings, theme CSS, and
page-level scripts.

## How to Use

**In any generation workflow:**

```typescript
// Step 1: Read the guide (ALWAYS FIRST)
const guide = await readResource("vibe://docs/generation-guide");

// Step 2: Author source-format HTML
const source = await llm.generate({
  systemContext: guide,
  userPrompt: "Create a PDP for hydrating serum"
});

// Step 3: Compile before saving
const validated = await call_tool("lexsis_pages", {
  action: "compile",
  args: {
    source,
    head: { title: "Hydrating Serum" }
  }
});
```

**Key benefits:**
- **Complete context in one read**: No need to fetch schema + islands + rules separately
- **Always current**: Dynamically built from source-of-truth catalogs
- **Page-type optimized**: When you specify a page type, you get filtered islands and focused instructions

## Performance Guidelines from the Guide

The guide enforces several performance constraints:

1. **Use Tailwind classes** for layout, spacing, sizing, responsive behavior,
   and state styling
2. **Use shared keyframes** instead of defining new `@keyframes`
3. **Minimize section JS** — only for animations/observers, no network access
4. **Page scripts for integrations** — use top-level `scripts` array for analytics/widgets
5. **No external dependencies in section CSS** — no `@import`, no `url()` to external resources

## Template Resources

The generation guide can be customized via template resources:

### Section Templates

Search templates before generating a section from scratch. Fetch selected
templates with `lexsis_design` action `get_section`. Its response includes one
complete `source` string per template with HTML plus any section CSS and
JavaScript. A template can contain `<lx-island>` elements, plain HTML, or both.

Template results return complete source-format sections ready to tailor and
pass to `lexsis_pages` action `compile`.

Do not assume template-search metadata is authoritative for `has_js` or
`islands_used`. Fetch the selected artifact and inspect its complete source.

### Individual Skill Guides

**Format**: `text/markdown`

Search with `lexsis_support` action `search_docs`, then read the exact resource URI
returned by that search. Do not construct a `vibe://skills/{name}` URI or rely
on a hard-coded catalog; the search result is the availability check.

**Usage:**
```typescript
// Load the exact URI returned by lexsis_support action search_docs
const guide = await readResource(searchResult.resource_uri);
```

## What It Replaces

The generation guide resource **replaces the deprecated `get_storefront_skills` tool**.

**Migration:**
```typescript
// Old (deprecated)
const guide = await call_tool("get_storefront_skills", {pageType: "pdp"});

// New (preferred)
const guide = await readResource("vibe://docs/generation-guide");
```

## When NOT to Use

Do **not** re-read the generation guide for every section edit or small change. Read it once at the start of a generation session and cache it. For edits:

1. **Section edits**: Use the existing page context + edit instructions
2. **Island prop changes**: Read `vibe://catalog/islands/{name}` for just that island's spec
3. **Schema validation**: Read `vibe://schema/page` for just the schema

The generation guide is comprehensive (3-5kb markdown) — only fetch it when you need the full picture.

## Example Workflow

**New page generation:**
```
1. User: "Create a PDP for vitamin C serum"
2. Agent: readResource("vibe://docs/generation-guide")
3. Agent: LLM authors source-format HTML with guide as system context
4. Agent: call_tool("lexsis_pages", {action: "compile", args: {source, head, theme_css}})
5. Agent: call_tool("lexsis_page_create", {action: "create", args: {source, head, theme_css, slug, publish: false}})
```

**Page edit:**
```
1. User: "Make the hero background gradient"
2. Agent: call_tool("lexsis_pages", {action: "edit_context", args: {page_id}})
3. Agent: call_tool("lexsis_pages", {action: "section_source", args: {page_id, section_id: "hero"}})
4. Agent: edits one source-format section
5. Agent: call_tool("lexsis_drafts", {
     action: "page_patch",
     args: {
       page_id,
       expected_version: editContext.current_version,
       changes: [{operation: "upsert_section", source}]
     }
   })
6. Agent: call_tool("lexsis_pages", {action: "integrity", args: {page_id}})
7. Agent: verifies the preview at 390px, 768px, and 1280px with its browser capability
```

The MCP does not run a shared browser preview service. Browser QA belongs to
the calling agent.

The generation guide is your foundation — read it first, then build on it.