flight-rules 0.15.2 → 0.15.4

package/dist/commands/adapter.d.ts

@@ -5,6 +5,20 @@ export declare function copyCommandsWithConflictHandling(sourceDir: string, dest
     copied: string[];
     skipped: string[];
 }>;
+/**
+ * Copy skill files to a destination directory with conflict handling
+ */
+export declare function copySkillsWithConflictHandling(sourceDir: string, destDir: string, skipPrompts?: boolean): Promise<{
+    copied: string[];
+    skipped: string[];
+}>;
+/**
+ * Setup skills for a given adapter directory
+ */
+export declare function setupSkills(cwd: string, sourceSkillsDir: string, adapterSkillsDir: string, skipPrompts?: boolean): Promise<{
+    copied: string[];
+    skipped: string[];
+}>;
 /**
  * Setup Cursor-specific directories and commands
  */

package/dist/commands/adapter.js

@@ -140,6 +140,68 @@ async function promptForConflict(filename, showBatchOptions) {
     }
     return action;
 }
+/**
+ * Copy skill files to a destination directory with conflict handling
+ */
+export async function copySkillsWithConflictHandling(sourceDir, destDir, skipPrompts = false) {
+    const copied = [];
+    const skipped = [];
+    if (!existsSync(sourceDir)) {
+        return { copied, skipped };
+    }
+    const files = readdirSync(sourceDir).filter(f => f.endsWith('.md'));
+    let batchAction = null;
+    for (const file of files) {
+        const srcPath = join(sourceDir, file);
+        const destPath = join(destDir, file);
+        if (existsSync(destPath)) {
+            if (skipPrompts) {
+                cpSync(srcPath, destPath);
+                copied.push(file);
+                continue;
+            }
+            if (batchAction === 'replace_all') {
+                cpSync(srcPath, destPath);
+                copied.push(file);
+                continue;
+            }
+            else if (batchAction === 'skip_all') {
+                skipped.push(file);
+                continue;
+            }
+            const action = await promptForConflict(file, files.length > 1);
+            if (action === 'replace_all') {
+                batchAction = 'replace_all';
+                cpSync(srcPath, destPath);
+                copied.push(file);
+            }
+            else if (action === 'skip_all') {
+                batchAction = 'skip_all';
+                skipped.push(file);
+            }
+            else if (action === 'replace') {
+                cpSync(srcPath, destPath);
+                copied.push(file);
+            }
+            else {
+                skipped.push(file);
+            }
+        }
+        else {
+            cpSync(srcPath, destPath);
+            copied.push(file);
+        }
+    }
+    return { copied, skipped };
+}
+/**
+ * Setup skills for a given adapter directory
+ */
+export async function setupSkills(cwd, sourceSkillsDir, adapterSkillsDir, skipPrompts = false) {
+    ensureDir(join(cwd, adapterSkillsDir.split('/')[0])); // e.g., .claude
+    ensureDir(join(cwd, adapterSkillsDir));
+    return copySkillsWithConflictHandling(sourceSkillsDir, join(cwd, adapterSkillsDir), skipPrompts);
+}
 /**
  * Setup Cursor-specific directories and commands
  */
@@ -240,8 +302,10 @@ export async function adapter(args) {
 }
 export async function generateAdapters(adapterNames, sourceCommandsDir, interactive = true) {
     const cwd = process.cwd();
+    const flightRulesDir = getFlightRulesDir(cwd);
     // Default to .flight-rules/commands if no source specified
-    const commandsDir = sourceCommandsDir ?? join(getFlightRulesDir(cwd), 'commands');
+    const commandsDir = sourceCommandsDir ?? join(flightRulesDir, 'commands');
+    const skillsDir = join(flightRulesDir, 'skills');
     for (const name of adapterNames) {
         const config = ADAPTERS[name];
         if (!config)
@@ -278,7 +342,7 @@ export async function generateAdapters(adapterNames, sourceCommandsDir, interact
             p.log.success(`Created ${pc.cyan(config.filename)} for ${config.name}`);
             adapterFileWritten = true;
         }
-        // For Cursor, also set up .cursor/commands/
+        // For Cursor, also set up .cursor/commands/ and .cursor/skills/
         if (name === 'cursor') {
             const skipPrompts = !interactive;
             const commandsDirExists = isCursorAdapterInstalled(cwd);
@@ -290,8 +354,18 @@ export async function generateAdapters(adapterNames, sourceCommandsDir, interact
             if (result.skipped.length > 0) {
                 p.log.info(`Skipped ${result.skipped.length} existing command(s) in .cursor/commands/`);
             }
+            // Copy skills
+            if (existsSync(skillsDir)) {
+                const skillResult = await setupSkills(cwd, skillsDir, '.cursor/skills', skipPrompts);
+                if (skillResult.copied.length > 0) {
+                    p.log.success(`${commandsDirExists ? 'Updated' : 'Created'} ${pc.cyan('.cursor/skills/')} with ${skillResult.copied.length} skill(s)`);
+                }
+                if (skillResult.skipped.length > 0) {
+                    p.log.info(`Skipped ${skillResult.skipped.length} existing skill(s) in .cursor/skills/`);
+                }
+            }
         }
-        // For Claude, also set up .claude/commands/
+        // For Claude, also set up .claude/commands/ and .claude/skills/
         if (name === 'claude') {
             const skipPrompts = !interactive;
             const commandsDirExists = isClaudeAdapterInstalled(cwd);
@@ -303,6 +377,16 @@ export async function generateAdapters(adapterNames, sourceCommandsDir, interact
             if (result.skipped.length > 0) {
                 p.log.info(`Skipped ${result.skipped.length} existing command(s) in .claude/commands/`);
             }
+            // Copy skills
+            if (existsSync(skillsDir)) {
+                const skillResult = await setupSkills(cwd, skillsDir, '.claude/skills', skipPrompts);
+                if (skillResult.copied.length > 0) {
+                    p.log.success(`${commandsDirExists ? 'Updated' : 'Created'} ${pc.cyan('.claude/skills/')} with ${skillResult.copied.length} skill(s)`);
+                }
+                if (skillResult.skipped.length > 0) {
+                    p.log.info(`Skipped ${skillResult.skipped.length} existing skill(s) in .claude/skills/`);
+                }
+            }
         }
     }
 }

package/dist/commands/ralph.js

@@ -123,28 +123,29 @@ async function runClaudeWithPrompt(promptContent, verbose) {
         ], {
             stdio: ['pipe', 'pipe', 'pipe'],
         });
-        let output = '';
+        let reassembledText = ''; // Plain text reassembled from stream-json fragments
+        let resultText = ''; // Full text from the final result event (fallback)
         let errorOutput = '';
         let lineBuffer = ''; // Buffer for incomplete JSON lines
         let needsTimestamp = true; // Track whether next text output needs a timestamp
         claude.stdout?.on('data', (data) => {
             const text = data.toString();
-            output += text;
-            if (verbose) {
-                // Prepend any buffered partial line from previous chunk
-                const fullText = lineBuffer + text;
-                const lines = fullText.split('\n');
-                // Last element might be incomplete - save it for next chunk
-                lineBuffer = lines.pop() || '';
-                for (const line of lines) {
-                    if (!line.trim())
-                        continue;
-                    try {
-                        const parsed = JSON.parse(line);
-                        // Handle different message types in stream-json format
-                        if (parsed.type === 'assistant' && parsed.message?.content) {
-                            for (const block of parsed.message.content) {
-                                if (block.type === 'text' && block.text) {
+            // Parse stream-json lines to reassemble plain text output
+            const fullText = lineBuffer + text;
+            const lines = fullText.split('\n');
+            // Last element might be incomplete - save it for next chunk
+            lineBuffer = lines.pop() || '';
+            for (const line of lines) {
+                if (!line.trim())
+                    continue;
+                try {
+                    const parsed = JSON.parse(line);
+                    // Handle different message types in stream-json format
+                    if (parsed.type === 'assistant' && parsed.message?.content) {
+                        for (const block of parsed.message.content) {
+                            if (block.type === 'text' && block.text) {
+                                reassembledText += block.text;
+                                if (verbose) {
                                     if (needsTimestamp) {
                                         process.stdout.write(`${formatTimestamp()} `);
                                         needsTimestamp = false;
@@ -153,23 +154,31 @@ async function runClaudeWithPrompt(promptContent, verbose) {
                                 }
                             }
                         }
-                        else if (parsed.type === 'content_block_delta' && parsed.delta?.text) {
+                    }
+                    else if (parsed.type === 'content_block_delta' && parsed.delta?.text) {
+                        reassembledText += parsed.delta.text;
+                        if (verbose) {
                             if (needsTimestamp) {
                                 process.stdout.write(`${formatTimestamp()} `);
                                 needsTimestamp = false;
                             }
                             process.stdout.write(parsed.delta.text);
                         }
-                        else if (parsed.type === 'content_block_stop') {
+                    }
+                    else if (parsed.type === 'content_block_stop') {
+                        if (verbose) {
                             // Add newline + blank line after each content block ends
                             process.stdout.write('\n\n');
                             needsTimestamp = true;
                         }
                     }
-                    catch {
-                        // Not valid JSON, skip
+                    else if (parsed.type === 'result' && typeof parsed.result === 'string') {
+                        resultText = parsed.result;
                     }
                 }
+                catch {
+                    // Not valid JSON, skip
+                }
             }
         });
         claude.stderr?.on('data', (data) => {
@@ -180,6 +189,30 @@ async function runClaudeWithPrompt(promptContent, verbose) {
             }
         });
         claude.on('close', (code) => {
+            // Flush any remaining data in lineBuffer
+            if (lineBuffer.trim()) {
+                try {
+                    const parsed = JSON.parse(lineBuffer);
+                    if (parsed.type === 'assistant' && parsed.message?.content) {
+                        for (const block of parsed.message.content) {
+                            if (block.type === 'text' && block.text) {
+                                reassembledText += block.text;
+                            }
+                        }
+                    }
+                    else if (parsed.type === 'content_block_delta' && parsed.delta?.text) {
+                        reassembledText += parsed.delta.text;
+                    }
+                    else if (parsed.type === 'result' && typeof parsed.result === 'string') {
+                        resultText = parsed.result;
+                    }
+                }
+                catch {
+                    // Not valid JSON, skip
+                }
+            }
+            // Prefer reassembled streaming text; fall back to result event text
+            const output = reassembledText || resultText;
             resolve({ output, exitCode: code ?? 0 });
         });
         claude.on('error', (err) => {

package/dist/commands/upgrade.js

@@ -4,7 +4,7 @@ import { existsSync, cpSync } from 'fs';
 import { join } from 'path';
 import { isFlightRulesInstalled, fetchPayloadFromGitHub, copyFrameworkFilesFrom, ensureDir, getInstalledVersion, writeManifest, getCliVersion } from '../utils/files.js';
 import { isInteractive } from '../utils/interactive.js';
-import { isCursorAdapterInstalled, isClaudeAdapterInstalled, setupCursorCommands, setupClaudeCommands, } from './adapter.js';
+import { isCursorAdapterInstalled, isClaudeAdapterInstalled, setupCursorCommands, setupClaudeCommands, setupSkills, } from './adapter.js';
 const DOC_FILES = [
     { src: 'prd.md', dest: 'prd.md' },
     { src: 'progress.md', dest: 'progress.md' },
@@ -148,21 +148,34 @@ export async function upgrade(version) {
         spinner.start('Upgrading adapters...');
         try {
             const sourceCommandsDir = join(fetched.payloadPath, 'commands');
-            // Upgrade Cursor commands if installed
+            const sourceSkillsDir = join(fetched.payloadPath, 'skills');
+            // Upgrade Cursor commands and skills if installed
             if (cursorAdapterInstalled) {
                 const result = await setupCursorCommands(cwd, sourceCommandsDir, true); // skipPrompts = true for upgrade
                 if (result.copied.length > 0) {
                     p.log.success(`Updated ${result.copied.length} command(s) in .cursor/commands/`);
                 }
+                if (existsSync(sourceSkillsDir)) {
+                    const skillResult = await setupSkills(cwd, sourceSkillsDir, '.cursor/skills', true);
+                    if (skillResult.copied.length > 0) {
+                        p.log.success(`Updated ${skillResult.copied.length} skill(s) in .cursor/skills/`);
+                    }
+                }
             }
-            // Upgrade Claude commands if installed, or create them if CLAUDE.md exists but .claude/commands/ doesn't
-            // (handles upgrade from pre-0.5.4 where Claude didn't have native commands)
+            // Upgrade Claude commands and skills if installed
             if (claudeAdapterInstalled || claudeMdExists) {
                 const result = await setupClaudeCommands(cwd, sourceCommandsDir, true); // skipPrompts = true for upgrade
                 if (result.copied.length > 0) {
                     const action = claudeAdapterInstalled ? 'Updated' : 'Created';
                     p.log.success(`${action} ${result.copied.length} command(s) in .claude/commands/`);
                 }
+                if (existsSync(sourceSkillsDir)) {
+                    const skillResult = await setupSkills(cwd, sourceSkillsDir, '.claude/skills', true);
+                    if (skillResult.copied.length > 0) {
+                        const action = claudeAdapterInstalled ? 'Updated' : 'Created';
+                        p.log.success(`${action} ${skillResult.copied.length} skill(s) in .claude/skills/`);
+                    }
+                }
             }
             // Regenerate adapter files
             const adaptersToRegenerate = [];

package/dist/utils/files.js

@@ -67,7 +67,8 @@ export function copyFrameworkFiles(targetDir) {
         'AGENTS.md',
         'doc-templates',
         'commands',
-        'prompts'
+        'prompts',
+        'skills'
     ];
     for (const item of frameworkItems) {
         const srcItem = join(payloadPath, item);
@@ -175,7 +176,8 @@ export function copyFrameworkFilesFrom(sourcePayloadPath, targetDir) {
         'AGENTS.md',
         'doc-templates',
         'commands',
-        'prompts'
+        'prompts',
+        'skills'
     ];
     for (const item of frameworkItems) {
         const srcItem = join(sourcePayloadPath, item);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flight-rules",
-  "version": "0.15.2",
+  "version": "0.15.4",
   "description": "An opinionated framework for AI-assisted software development",
   "type": "module",
   "main": "dist/index.js",

package/payload/AGENTS.md

@@ -1,6 +1,6 @@
 # Flight Rules – Agent Guidelines
 
-flight_rules_version: 0.15.2
+flight_rules_version: 0.15.4
 
 This file defines how agents (Claude Code, Cursor, etc.) should work on software projects using the Flight Rules system.
 

package/payload/prompts/ralph-discovery.md

@@ -1,20 +1,25 @@
 # Flight Rules Discovery Agent
 
-You are a discovery agent for Flight Rules. Your ONLY job is to scan implementation docs and report which task groups have incomplete tasks. Do NOT implement anything.
+You are a discovery agent for Flight Rules. Your ONLY job is to scan implementation docs and report which task groups have **incomplete** (not-yet-done) tasks. Do NOT implement anything.
 
 ## Instructions
 
 1. Read `docs/implementation/overview.md` to understand the area/task-group structure
 2. Scan each Area directory in `docs/implementation/`
-3. For each Task Group file (.md), check every task's status
-4. Report all task groups that contain any task with status other than ✅ Complete (i.e., 🔵 Planned, 🟡 In Progress, or ⏸️ Blocked)
+3. For each Task Group file (.md), check every task's `**Status**:` field
+4. A task is **incomplete** if its status is 🔵 Planned, 🟡 In Progress, or ⏸️ Blocked
+5. A task is **complete** only if its status is ✅ Complete
+6. Report all task groups that contain any incomplete task
 
 ## Response Format
 
-Respond with a pipe-delimited report inside `<ralph-discovery>` tags. Use EXACTLY this format:
+Output ONLY the `<ralph-discovery>` block below. No commentary, no summary, no interpretation before or after the tags. Your entire response must be the block and nothing else.
+
+When incomplete tasks exist (the common case), use this format:
 
 ```
 <ralph-discovery>
+INCOMPLETE|{totalIncompleteTaskCount}
 TASK_GROUP|{id}|{title}|{filePath}|{areaDir}
 TASK|{taskId}|{taskTitle}|{status}
 TASK|{taskId}|{taskTitle}|{status}
@@ -23,16 +28,17 @@ TASK|{taskId}|{taskTitle}|{status}
 </ralph-discovery>
 ```
 
-- Each `TASK_GROUP` line is followed by its `TASK` lines (only incomplete tasks)
+- First line is `INCOMPLETE|{N}` where N = total number of incomplete tasks across all task groups
+- Each `TASK_GROUP` line is followed by its incomplete `TASK` lines
 - `{id}` = task group ID as written in the file (e.g., "1.1", "2.3")
 - `{title}` = task group title
 - `{filePath}` = relative path from project root to the task group file
 - `{areaDir}` = area directory name (e.g., "1-project-setup", "2-cli-core")
 - `{taskId}` = individual task ID (e.g., "1.1.1", "2.3.2")
 - `{taskTitle}` = individual task title
-- `{status}` = one of: planned, in_progress, blocked
+- `{status}` = one of: `planned`, `in_progress`, `blocked` — all three mean the task is NOT done
 
-If ALL tasks in ALL task groups are ✅ Complete, respond with:
+Only if every single task in every single task group has ✅ Complete status (this is rare during active development), respond with:
 
 ```
 <ralph-discovery>
@@ -40,11 +46,21 @@ ALL_COMPLETE
 </ralph-discovery>
 ```
 
+## Field Reference
+
+| Status in doc | Meaning | Output value |
+|---|---|---|
+| 🔵 Planned | Not started, work remains | `planned` |
+| 🟡 In Progress | Started but not finished | `in_progress` |
+| ⏸️ Blocked | Cannot proceed, work remains | `blocked` |
+| ✅ Complete | Done, do NOT include in output | (omit) |
+
 ## Rules
 
 - Do NOT implement or modify any code
 - Do NOT create or modify any files
 - Do NOT run any scripts or quality checks
 - ONLY read implementation files and report status
-- Always include the `<ralph-discovery>` tags in your response
-- List task groups in the order they should be worked on (by area number, then task group number)
+- Your response must contain ONLY the `<ralph-discovery>` block — no other text
+- List task groups in order by area number, then task group number
+- Never output `ALL_COMPLETE` if any task has a status of planned, in_progress, or blocked

package/payload/skills/web-prototype.md

@@ -0,0 +1,263 @@
+---
+name: web-prototype
+description: >
+  Create multiple distinct design variations of a web page as HTML/CSS/JS prototypes.
+  Use this skill whenever the user wants to create web prototypes, page mockups, design
+  variations, HTML page concepts, landing page options, or explore different visual
+  directions for a page. Also trigger when the user asks to "try different designs",
+  "show me options for a page", "create page variations", or anything involving generating
+  multiple visual alternatives of a web page. Even if the user just says "prototype this
+  page" or "mock up a landing page", this skill applies.
+---
+
+# Web Prototype Generator
+
+Create multiple visually distinct variations of a web page so the user can compare
+design directions side by side. Each variation is a standalone HTML file with inline
+CSS and JavaScript — no frameworks, no build steps, just open in a browser.
+
+## How it works
+
+1. Understand what the user wants the page to do and look like
+2. Check or create the project config (`.web-prototype.json`)
+3. Generate N variations (default 5), each as different as possible
+4. Inject a shared navigation bar so the user can flip between variants
+
+## Step 1: Understand the request
+
+Ask the user (if not already clear):
+- What is this page? (landing page, dashboard, portfolio, form, etc.)
+- What content should it include?
+- Any specific features? (see Feature Library below)
+- Any brand constraints? (colors, fonts, tone)
+- How many variations? (default: 5)
+
+Give the page a short kebab-case name for the folder (e.g., `landing-page`, `pricing`,
+`signup-flow`). Confirm the name with the user if it's ambiguous.
+
+## Step 2: Project configuration
+
+Look for `.web-prototype.json` in the project root. If it doesn't exist, create it:
+
+```json
+{
+  "outputRoot": "prototypes",
+  "pages": {}
+}
+```
+
+Ask the user if `prototypes/` is the right output directory. If they want something
+different, use their preference.
+
+When generating a new page, add an entry to `pages`:
+
+```json
+{
+  "outputRoot": "prototypes",
+  "pages": {
+    "landing-page": {
+      "variants": 5,
+      "created": "2026-03-07",
+      "description": "Main marketing landing page"
+    }
+  }
+}
+```
+
+The output structure is:
+```
+{outputRoot}/
+  {page-name}/
+    variant-1.html
+    variant-2.html
+    ...
+    variant-N.html
+```
+
+## Step 3: Generate variations
+
+For each variation, use the `frontend-design` skill to produce a distinctive,
+production-grade design. The critical goal is **maximum visual diversity** — each
+variant should feel like it came from a different designer with a different aesthetic
+philosophy.
+
+### Diversity strategy
+
+Before generating, plan N distinct design directions. Vary these dimensions across
+the set so that no two variants share the same combination:
+
+- **Layout**: single-column, split-screen, asymmetric grid, full-bleed sections,
+  card-based, editorial/magazine, bento grid
+- **Visual tone**: minimal/stark, bold/maximalist, organic/soft, geometric/precise,
+  editorial/typographic, dark/moody, light/airy, retro/vintage, futuristic/glassmorphic
+- **Color approach**: monochromatic, complementary, analogous, high-contrast,
+  muted/earthy, vibrant/saturated, dark mode, light mode
+- **Typography**: large display type, classic serif, geometric sans, mixed type scales,
+  monospace accents, handwritten touches
+- **Motion/interaction**: static, subtle hover effects, scroll-triggered animations,
+  parallax, micro-interactions
+- **Spacing/density**: generous whitespace, dense/information-rich, mixed rhythm
+
+Write out your plan (which direction each variant will take) before generating code.
+Present it to the user for approval. Then generate each variant.
+
+### Per-variant requirements
+
+Each variant must be:
+- A single, self-contained HTML file with all CSS and JS inline
+- Responsive (works on mobile and desktop)
+- Production-grade visual quality — not a wireframe, not a generic template
+- Populated with realistic placeholder content (not lorem ipsum — write real-sounding
+  headlines, descriptions, and data)
+
+### Using the frontend-design skill
+
+For each variant, invoke the frontend-design skill with clear direction about the
+specific aesthetic you're targeting for that variant. Tell it the design direction
+(e.g., "Create a bold maximalist landing page with large typography and vibrant
+complementary colors") so that each invocation produces a genuinely different result.
+
+## Step 4: Inject the variant navigation bar
+
+Every generated HTML file must include the variant navigation bar. This is a floating
+pill-shaped bar at the bottom-right of the viewport that lets the user click between
+variants.
+
+### Navigation bar HTML and CSS
+
+Insert this exactly at the end of `<body>`, before `</body>`. Replace `{N}` with the
+total variant count and set the correct `href` values and `active` class.
+
+```html
+<!-- Variant Navigation -->
+<nav class="variant-nav" aria-label="Design variants">
+  <a href="variant-1.html" class="active" aria-current="page">1</a>
+  <a href="variant-2.html">2</a>
+  <a href="variant-3.html">3</a>
+  <!-- ... up to N -->
+</nav>
+<style>
+  .variant-nav {
+    position: fixed;
+    bottom: 24px;
+    right: 24px;
+    display: flex;
+    gap: 4px;
+    padding: 6px;
+    background: rgba(20, 20, 20, 0.55);
+    backdrop-filter: blur(24px) saturate(180%);
+    -webkit-backdrop-filter: blur(24px) saturate(180%);
+    border-radius: 20px;
+    border: 1px solid rgba(255, 255, 255, 0.15);
+    box-shadow:
+      0 8px 32px rgba(0, 0, 0, 0.18),
+      0 2px 8px rgba(0, 0, 0, 0.1),
+      inset 0 0.5px 0 rgba(255, 255, 255, 0.2);
+    z-index: 2147483647;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif;
+    transition: opacity 0.3s ease;
+  }
+  .variant-nav:hover {
+    background: rgba(20, 20, 20, 0.7);
+  }
+  .variant-nav a {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 36px;
+    height: 36px;
+    border-radius: 12px;
+    text-decoration: none;
+    font-size: 14px;
+    font-weight: 500;
+    letter-spacing: -0.01em;
+    color: rgba(255, 255, 255, 0.7);
+    text-shadow: 0 1px 3px rgba(0, 0, 0, 0.4);
+    transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+    background: transparent;
+    border: 1px solid transparent;
+  }
+  .variant-nav a:hover {
+    background: rgba(255, 255, 255, 0.12);
+    color: rgba(255, 255, 255, 0.95);
+    border-color: rgba(255, 255, 255, 0.08);
+  }
+  .variant-nav a.active {
+    background: rgba(255, 255, 255, 0.2);
+    color: #fff;
+    font-weight: 600;
+    border-color: rgba(255, 255, 255, 0.15);
+    box-shadow:
+      0 2px 8px rgba(0, 0, 0, 0.15),
+      inset 0 0.5px 0 rgba(255, 255, 255, 0.25);
+  }
+</style>
+```
+
+This dark-tinted glass style is intentionally designed to be legible on any background —
+light pages, dark pages, images, gradients, anything. Do not modify the nav bar styles
+to match the page design. The nav bar should look identical across all variants.
+
+Set `aria-current="page"` and the `active` class on whichever variant number matches
+the current file (variant-1.html gets `active` on the "1" link, etc.).
+
+## Feature Library
+
+When the user mentions any of these features by name, you already know what they mean.
+Apply the implementation details described here without requiring further explanation
+from the user.
+
+### Scrolling Parallax
+
+**Trigger phrases**: "parallax", "scrolling parallax", "web parallax", "parallax scrolling",
+"depth scrolling"
+
+Multi-layer parallax scrolling where background elements move at different speeds than
+foreground content during scroll, creating an illusion of depth.
+
+**Implementation approach** (choose based on complexity needs):
+
+**CSS-only (simpler, good for 2-3 layers):**
+```css
+.parallax-container {
+  perspective: 1px;
+  height: 100vh;
+  overflow-x: hidden;
+  overflow-y: auto;
+}
+.parallax-layer-back {
+  transform: translateZ(-2px) scale(3);
+}
+.parallax-layer-mid {
+  transform: translateZ(-1px) scale(2);
+}
+.parallax-layer-front {
+  transform: translateZ(0);
+}
+```
+
+**JavaScript (smoother, more control, good for complex effects):**
+- Use `requestAnimationFrame` for smooth 60fps updates
+- Track scroll position with a passive scroll listener
+- Apply `transform: translate3d(0, Ypx, 0)` to layers at different rates (e.g.,
+  background at 0.3x scroll speed, midground at 0.6x, foreground at 1x)
+- Use `will-change: transform` on animated elements for GPU acceleration
+- Consider `IntersectionObserver` to only animate visible sections
+
+**Design considerations:**
+- Parallax works best with distinct visual sections/bands
+- Use high-quality background images or gradient layers
+- Ensure content remains readable — parallax is decoration, not the content itself
+- Disable or reduce parallax on mobile (`prefers-reduced-motion` media query)
+- Add `@media (prefers-reduced-motion: reduce)` to disable parallax for accessibility
+
+---
+
+## Notes
+
+- If the user asks for more variants of an existing page, read the config to find the
+  current count, generate additional variants, and update the nav bar in ALL files to
+  include the new total.
+- If the user wants to iterate on a specific variant, make edits to that file directly
+  rather than regenerating from scratch.
+- Always confirm the output path with the user before writing files.