flight-rules 0.15.3 → 0.15.6

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/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.3",
+  "version": "0.15.6",
   "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.3
+flight_rules_version: 0.15.6
 
 This file defines how agents (Claude Code, Cursor, etc.) should work on software projects using the Flight Rules system.
 

package/payload/skills/skill-improve.md

@@ -0,0 +1,206 @@
+---
+name: skill-improve
+description: >
+  Research-driven skill improvement. Analyzes an existing skill for weaknesses, then
+  searches the internet extensively for popular similar skills, prompts, and techniques
+  from the community (GitHub repos, awesome-lists, prompt engineering resources, official
+  Anthropic docs) to find ideas worth incorporating. Produces a prioritized improvement
+  report and implements approved changes. Use this skill whenever the user says things like
+  "improve this skill", "make this skill better", "enhance skill", "optimize skill",
+  "research better approaches for this skill", "find ways to improve this skill",
+  "what are other people doing for skills like this", "benchmark this skill against others",
+  or "level up this skill". Also trigger when the user wants to compare their skill against
+  community alternatives or find inspiration from popular skills in the ecosystem.
+---
+
+# Skill Improver
+
+Improve an existing skill by combining internal analysis with extensive internet research.
+The goal is to find concrete, actionable improvements — not generic advice — by studying
+what the best similar skills in the ecosystem actually do.
+
+## How it works
+
+1. **Understand the skill** — Read it deeply, understand its purpose and mechanics
+2. **Analyze internally** — Find structural and content issues
+3. **Research externally** — Search the internet for similar popular skills and techniques
+4. **Compare and synthesize** — Extract the best ideas from what you found
+5. **Report** — Present prioritized recommendations to the user
+6. **Implement** — Apply the approved improvements
+
+## Step 1: Understand the target skill
+
+Ask the user which skill to improve if not already specified. Then read the skill file
+thoroughly. Before doing anything else, write a brief summary of:
+
+- What the skill does
+- How it's structured (sections, flow, resources)
+- What triggers it (the description field)
+- What tools/techniques it uses
+- Any bundled resources (scripts, references, assets)
+
+Share this summary with the user to confirm you understand the skill correctly. Misunderstanding
+the skill's purpose will lead to bad recommendations.
+
+## Step 2: Internal analysis
+
+Examine the skill against these quality dimensions. Be specific — cite line numbers or
+quote passages when noting issues.
+
+### Structure and clarity
+- Is the flow logical? Would someone following it step-by-step get good results?
+- Are instructions clear enough that a model can follow them without guessing?
+- Is there unnecessary repetition or bloat that could be cut?
+- Are there gaps where the model would need to improvise?
+
+### Description quality
+- Does the description cover the right trigger phrases?
+- Is it specific enough to avoid false triggers?
+- Is it "pushy" enough to trigger when it should? (Skills tend to under-trigger)
+
+### Instruction effectiveness
+- Are there heavy-handed MUST/NEVER/ALWAYS directives that could be replaced with
+  explanations of *why* something matters?
+- Are examples included where they'd help?
+- Is the skill explaining the reasoning behind its instructions, or just giving orders?
+
+### Progressive disclosure
+- Is the SKILL.md under 500 lines? If longer, should content move to reference files?
+- Are bundled resources referenced clearly with guidance on when to read them?
+
+### Robustness
+- Does it handle edge cases the user might encounter?
+- Are there implicit assumptions that could fail in different contexts?
+
+Produce a concise internal analysis report organized by dimension.
+
+## Step 3: External research
+
+This is the core differentiator of this skill. Search the internet extensively to find
+popular, well-regarded skills and techniques that address similar problems. The goal is
+to discover ideas, patterns, and approaches the current skill is missing.
+
+### Where to search
+
+Run multiple searches across these categories. Use subagents for parallel research when
+available — this step benefits enormously from breadth.
+
+**Similar skills in the ecosystem:**
+- Search GitHub for skills with similar names or purposes
+  (e.g., `claude skill [topic]`, `awesome claude skills [topic]`)
+- Check curated lists: `awesome-claude-skills`, `awesome-claude-code-toolkit`
+- Look for skills on the Claude Skills directory if available
+- Search for Cursor rules, Windsurf rules, or other AI coding tool configurations
+  that address the same domain
+
+**Prompt engineering techniques:**
+- Search for prompt engineering patterns relevant to the skill's domain
+- Look for academic or blog posts on techniques like chain-of-thought, few-shot
+  examples, self-correction, or structured output formats
+- Check the Anthropic documentation for relevant best practices
+
+**Domain-specific best practices:**
+- If the skill targets a specific domain (e.g., testing, code review, documentation),
+  search for industry best practices in that domain
+- Look for popular tools, linters, or frameworks that encode domain expertise
+
+**Community discussions:**
+- Search for discussions about similar workflows on GitHub issues, forums, or blogs
+- Look for "how I use Claude for X" posts that might reveal techniques
+
+### What to extract from each source
+
+For each relevant source you find, note:
+
+- **Source**: URL and brief description
+- **Key technique or pattern**: What does it do that's interesting?
+- **Relevance**: How does this relate to the skill being improved?
+- **Adoption signal**: Stars, installs, mentions — is this actually popular/proven?
+- **Adaptability**: How easily could this be incorporated into the current skill?
+
+### Research depth
+
+Aim for at least 5-8 distinct sources across the categories above. Quality matters more
+than quantity — a single well-designed skill that solves the same problem is worth more
+than ten tangentially related blog posts.
+
+If the skill's domain is niche and you can't find direct comparables, broaden the search
+to adjacent domains or look for transferable patterns from popular skills in other domains.
+
+## Step 4: Compare and synthesize
+
+Now bring together your internal analysis and external research. For each finding from
+the research, ask:
+
+- Does the current skill already do this? If so, does it do it as well?
+- Would incorporating this idea make the skill meaningfully better?
+- Is this idea compatible with the skill's existing approach, or would it require
+  a significant restructure?
+- Is this a proven pattern (used in multiple popular skills) or a one-off experiment?
+
+Organize your findings into a synthesis that highlights the gaps between the current
+skill and the best practices you found.
+
+## Step 5: Present the improvement report
+
+Present a structured report to the user with three sections:
+
+### High-priority improvements
+Changes that would significantly improve the skill's effectiveness. These are things
+where popular, proven alternatives exist and the current skill is clearly weaker.
+
+### Medium-priority improvements
+Useful enhancements that would make the skill more robust or cover more cases, but
+the current approach isn't broken.
+
+### Low-priority / exploratory ideas
+Interesting techniques spotted in the research that might be worth trying but aren't
+clearly better than the current approach. Include these so the user can decide.
+
+For each recommendation:
+- **What to change**: Specific, actionable description
+- **Why**: What problem it solves or what improvement it brings
+- **Source**: Where you found this idea (with link if from external research)
+- **Effort**: How much work it would take (small tweak vs. significant rewrite)
+
+After presenting the report, ask the user which improvements they'd like to implement.
+
+## Step 6: Implement approved improvements
+
+Apply the changes the user approved. When implementing:
+
+- Make changes incrementally — don't rewrite the entire skill at once
+- Preserve the skill's voice and style unless the user wants a different tone
+- If a change requires restructuring, explain the new structure before doing it
+- After implementing, show a summary of what changed
+
+If the user wants to test the improvements, suggest using the skill-creator's evaluation
+workflow to compare before and after.
+
+## Tips for effective research
+
+**Cast a wide net, then narrow.** Start with broad searches, scan the results for the
+most relevant hits, then dig deep into those. A search for "claude skill code review"
+might surface a skill that has nothing to do with code review but uses a brilliant
+self-correction pattern you can steal.
+
+**Look at structure, not just content.** Sometimes the most valuable thing about a
+popular skill isn't what it says but how it's organized — how it uses progressive
+disclosure, how it sequences instructions, how it handles edge cases.
+
+**Pay attention to what's missing.** If every popular skill in a domain does X and the
+target skill doesn't, that's a strong signal. If no popular skill does Y and the target
+skill does, ask whether Y is genuinely innovative or just unnecessary.
+
+**Check the stars and installs.** A skill with 100K+ installs that does something
+differently is stronger evidence than a blog post with 3 likes. Popularity isn't
+everything, but it's a useful signal for proven approaches.
+
+## Notes
+
+- This skill works best when you have web search capabilities. Without them, the
+  external research step is limited to what's already in your training data.
+- For skills that are part of a larger system (like flight-rules commands), consider
+  how improvements might affect integration with other components.
+- If the skill-creator skill is available, consider using its evaluation workflow
+  after implementing improvements to measure the impact quantitatively.

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.