claudecode-omc 5.6.5 → 5.6.7

package/bundled/upstream/ecc/skills/flox-environments/SKILL.md

@@ -0,0 +1,496 @@
+---
+name: flox-environments
+description: "Create reproducible, cross-platform development environments with Flox — a declarative environment manager built on Nix. ALWAYS use this skill when the user needs to: set up a project with system-level dependencies (compilers, databases, native libraries like openssl, libvips, BLAS, LAPACK); configure reproducible toolchains for Python, Node.js, Rust, Go, C/C++, Java, Ruby, Elixir, PHP, or any language; manage environments that must work identically across macOS and Linux; pin exact package versions for a team; run local services (PostgreSQL, Redis, Kafka) alongside development tools; onboard new developers with a single command; or solve 'works on my machine' problems. Especially valuable for AI-assisted and vibe coding — Flox lets agents install tools into a project-scoped environment without sudo, system pollution, or sandbox restrictions, and the resulting environment is committed to the repo so anyone can reproduce it instantly. Use this skill even if the user doesn't mention Flox — if they describe needing reproducible, declarative, cross-platform dev environments with system packages, this is the right tool. Also use when the user mentions .flox/, manifest.toml, flox activate, or FloxHub."
+origin: Flox
+---
+
+# Flox Environments
+
+Flox creates reproducible development environments defined in a single TOML manifest. Every developer on the team gets identical packages, tools, and configuration — across macOS and Linux — without containers or VMs. Built on Nix with access to over 150,000 packages.
+
+## When to Activate
+
+Use this skill when the user has an environment management problem — even if they haven't mentioned Flox. Flox is the right tool when:
+
+- The project needs **system-level packages** (compilers, databases, CLI tools) alongside language-specific dependencies
+- **Reproducibility matters** — the setup should work identically on a teammate's machine, in CI, or on a fresh laptop
+- The user needs **multiple tools to coexist** — e.g., Python 3.11 + PostgreSQL 16 + Redis + Node.js in one environment
+- **Cross-platform support** is needed (macOS and Linux from the same config)
+- **AI agents need to install tools** — Flox lets agents add packages to a project-scoped environment without sudo, system pollution, or sandbox restrictions
+
+If the user just needs a single language runtime with no system dependencies, standard tooling (nvm, pyenv, rustup alone) may suffice. If they need full OS-level isolation, containers might be more appropriate. Flox sits in the sweet spot: declarative, reproducible environments without container overhead.
+
+**Prerequisite:** Flox must be installed first — see [flox.dev/docs](https://flox.dev/docs/install-flox/install/) for macOS, Linux, and Docker.
+
+## Core Concepts
+
+Flox environments are defined in `.flox/env/manifest.toml` and activated with `flox activate`. The manifest declares packages, environment variables, setup hooks, and shell configuration — everything needed to reproduce the environment anywhere.
+
+**Key paths:**
+- `.flox/env/manifest.toml` — Environment definition (commit this)
+- `$FLOX_ENV` — Runtime path to installed packages (like `/usr` — contains `bin/`, `lib/`, `include/`)
+- `$FLOX_ENV_CACHE` — Persistent local storage for caches, venvs, data (survives rebuilds)
+- `$FLOX_ENV_PROJECT` — Project root directory (where `.flox/` lives)
+
+## Essential Commands
+
+```bash
+flox init                       # Create new environment
+flox search <package> [--all]   # Search for packages
+flox show <package>             # Show available versions
+flox install <package>          # Add a package
+flox list                       # List installed packages
+flox activate                   # Enter environment
+flox activate -- <cmd>          # Run a command in the environment without a subshell
+flox edit                       # Edit manifest interactively
+```
+
+## Manifest Structure
+
+```toml
+# .flox/env/manifest.toml
+
+[install]
+# Packages to install — the core of the environment
+ripgrep.pkg-path = "ripgrep"
+jq.pkg-path = "jq"
+
+[vars]
+# Static environment variables
+DATABASE_URL = "postgres://localhost:5432/myapp"
+
+[hook]
+# Non-interactive setup scripts (run every activation)
+on-activate = """
+  echo "Environment ready"
+"""
+
+[profile]
+# Shell functions and aliases (available in interactive shell)
+common = """
+  alias dev="npm run dev"
+"""
+
+[options]
+# Supported platforms
+systems = ["x86_64-linux", "aarch64-linux", "x86_64-darwin", "aarch64-darwin"]
+```
+
+## Package Installation Patterns
+
+### Basic Installation
+
+```toml
+[install]
+nodejs.pkg-path = "nodejs"
+python.pkg-path = "python311"
+rustup.pkg-path = "rustup"
+```
+
+### Version Pinning
+
+```toml
+[install]
+nodejs.pkg-path = "nodejs"
+nodejs.version = "^20.0"          # Semver range: latest 20.x
+
+postgres.pkg-path = "postgresql"
+postgres.version = "16.2"         # Exact version
+```
+
+### Platform-Specific Packages
+
+```toml
+[install]
+# Linux-only tools
+valgrind.pkg-path = "valgrind"
+valgrind.systems = ["x86_64-linux", "aarch64-linux"]
+
+# macOS frameworks
+Security.pkg-path = "darwin.apple_sdk.frameworks.Security"
+Security.systems = ["x86_64-darwin", "aarch64-darwin"]
+
+# GNU tools on macOS (where BSD defaults differ)
+coreutils.pkg-path = "coreutils"
+coreutils.systems = ["x86_64-darwin", "aarch64-darwin"]
+```
+
+### Resolving Package Conflicts
+
+When two packages install the same binary, use `priority` (lower number wins):
+
+```toml
+[install]
+gcc.pkg-path = "gcc12"
+gcc.priority = 3
+
+clang.pkg-path = "clang_18"
+clang.priority = 5               # gcc wins file conflicts
+```
+
+Use `pkg-group` to group packages that should resolve versions together:
+
+```toml
+[install]
+python.pkg-path = "python311"
+python.pkg-group = "python-stack"
+
+pip.pkg-path = "python311Packages.pip"
+pip.pkg-group = "python-stack"    # Resolves together with python
+```
+
+## Language-Specific Recipes
+
+### Python with uv
+
+```toml
+[install]
+python.pkg-path = "python311"
+uv.pkg-path = "uv"
+
+[vars]
+UV_CACHE_DIR = "$FLOX_ENV_CACHE/uv-cache"
+PIP_CACHE_DIR = "$FLOX_ENV_CACHE/pip-cache"
+
+[hook]
+on-activate = """
+  venv="$FLOX_ENV_CACHE/venv"
+  if [ ! -d "$venv" ]; then
+    uv venv "$venv" --python python3
+  fi
+  if [ -f "$venv/bin/activate" ]; then
+    source "$venv/bin/activate"
+  fi
+
+  if [ -f requirements.txt ] && [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
+    uv pip install --python "$venv/bin/python" -r requirements.txt --quiet
+    touch "$FLOX_ENV_CACHE/.deps_installed"
+  fi
+"""
+```
+
+### Node.js
+
+```toml
+[install]
+nodejs.pkg-path = "nodejs"
+nodejs.version = "^20.0"
+
+[hook]
+on-activate = """
+  if [ -f package.json ] && [ ! -d node_modules ]; then
+    npm install --silent
+  fi
+"""
+```
+
+### Rust
+
+```toml
+[install]
+rustup.pkg-path = "rustup"
+pkg-config.pkg-path = "pkg-config"
+openssl.pkg-path = "openssl"
+
+[vars]
+RUSTUP_HOME = "$FLOX_ENV_CACHE/rustup"
+CARGO_HOME = "$FLOX_ENV_CACHE/cargo"
+
+[profile]
+common = """
+  export PATH="$CARGO_HOME/bin:$PATH"
+"""
+```
+
+### Go
+
+```toml
+[install]
+go.pkg-path = "go"
+gopls.pkg-path = "gopls"
+delve.pkg-path = "delve"
+
+[vars]
+GOPATH = "$FLOX_ENV_CACHE/go"
+GOBIN = "$FLOX_ENV_CACHE/go/bin"
+
+[profile]
+common = """
+  export PATH="$GOBIN:$PATH"
+"""
+```
+
+### C/C++
+
+```toml
+[install]
+gcc.pkg-path = "gcc13"
+gcc.pkg-group = "compilers"
+
+# IMPORTANT: gcc alone doesn't expose libstdc++ headers — you need gcc-unwrapped
+gcc-unwrapped.pkg-path = "gcc-unwrapped"
+gcc-unwrapped.pkg-group = "libraries"
+
+cmake.pkg-path = "cmake"
+cmake.pkg-group = "build"
+
+gnumake.pkg-path = "gnumake"
+gnumake.pkg-group = "build"
+
+gdb.pkg-path = "gdb"
+gdb.systems = ["x86_64-linux", "aarch64-linux"]
+```
+
+## Hooks and Profile
+
+### Hooks — Non-Interactive Setup
+
+Hooks run on every activation. Keep them fast and idempotent. Rule of thumb: **if it should happen automatically, put it in `[hook]`; if the user should be able to type it, put it in `[profile]`.**
+
+```toml
+[hook]
+on-activate = """
+  setup_database() {
+    if [ ! -d "$FLOX_ENV_CACHE/pgdata" ]; then
+      initdb -D "$FLOX_ENV_CACHE/pgdata" --no-locale --encoding=UTF8
+    fi
+  }
+  setup_database
+"""
+```
+
+### Profile — Interactive Shell Configuration
+
+Profile code is available in the user's shell session.
+
+```toml
+[profile]
+common = """
+  dev() { npm run dev; }
+  test() { npm run test -- "$@"; }
+"""
+```
+
+## Anti-Patterns
+
+### Absolute Paths
+
+```toml
+# BAD — breaks on other machines
+[vars]
+PROJECT_DIR = "/home/alice/projects/myapp"
+
+# GOOD — use Flox environment variables
+[vars]
+PROJECT_DIR = "$FLOX_ENV_PROJECT"
+```
+
+### Using exit in Hooks
+
+```toml
+# BAD — kills the shell
+[hook]
+on-activate = """
+  if [ ! -f config.json ]; then
+    echo "Missing config"
+    exit 1
+  fi
+"""
+
+# GOOD — return from hook, don't exit
+[hook]
+on-activate = """
+  if [ ! -f config.json ]; then
+    echo "Missing config — run setup first"
+    return 1
+  fi
+"""
+```
+
+### Storing Secrets in Manifest
+
+```toml
+# BAD — manifest is committed to git
+[vars]
+API_KEY = "<set-at-runtime>"
+
+# GOOD — reference external config or pass at runtime
+# Use: API_KEY="<your-api-key>" flox activate
+[vars]
+API_KEY = "${API_KEY:-}"
+```
+
+### Slow Hooks Without Idempotency Guards
+
+```toml
+# BAD — reinstalls every activation
+[hook]
+on-activate = """
+  pip install -r requirements.txt
+"""
+
+# GOOD — skip if already installed
+[hook]
+on-activate = """
+  if [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
+    uv pip install -r requirements.txt --quiet
+    touch "$FLOX_ENV_CACHE/.deps_installed"
+  fi
+"""
+```
+
+### Putting User Commands in Hooks
+
+```toml
+# BAD — hook functions aren't available in the interactive shell
+[hook]
+on-activate = """
+  deploy() { kubectl apply -f k8s/; }
+"""
+
+# GOOD — use [profile] for user-invokable functions
+[profile]
+common = """
+  deploy() { kubectl apply -f k8s/; }
+"""
+```
+
+## Full-Stack Example
+
+A complete environment for a Python API with PostgreSQL:
+
+```toml
+[install]
+python.pkg-path = "python311"
+uv.pkg-path = "uv"
+postgresql.pkg-path = "postgresql_16"
+redis.pkg-path = "redis"
+jq.pkg-path = "jq"
+curl.pkg-path = "curl"
+
+[vars]
+UV_CACHE_DIR = "$FLOX_ENV_CACHE/uv-cache"
+DATABASE_URL = "postgres://localhost:5432/myapp"
+REDIS_URL = "redis://localhost:6379"
+
+[hook]
+on-activate = """
+  if [ ! -d "$FLOX_ENV_CACHE/pgdata" ]; then
+    initdb -D "$FLOX_ENV_CACHE/pgdata" --no-locale --encoding=UTF8
+  fi
+
+  venv="$FLOX_ENV_CACHE/venv"
+  if [ ! -d "$venv" ]; then
+    uv venv "$venv" --python python3
+  fi
+  if [ -f "$venv/bin/activate" ]; then
+    source "$venv/bin/activate"
+  fi
+
+  if [ -f requirements.txt ] && [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
+    uv pip install --python "$venv/bin/python" -r requirements.txt --quiet
+    touch "$FLOX_ENV_CACHE/.deps_installed"
+  fi
+"""
+
+[profile]
+common = """
+  serve() { uvicorn app.main:app --reload --host 0.0.0.0 --port 8000; }
+  migrate() { alembic upgrade head; }
+"""
+
+[services]
+postgres.command = "postgres -D $FLOX_ENV_CACHE/pgdata -k $FLOX_ENV_CACHE"
+redis.command = "redis-server --port 6379 --daemonize no"
+
+[options]
+systems = ["x86_64-linux", "aarch64-linux", "x86_64-darwin", "aarch64-darwin"]
+```
+
+Activate with services: `flox activate --start-services`
+
+## Environment Sharing
+
+Flox environments are git-native. Commit the `.flox/` directory and every collaborator gets the same environment:
+
+```bash
+git add .flox/
+git commit -m "Add Flox environment"
+# Teammates just run:
+git clone <repo> && cd <repo> && flox activate
+```
+
+For reusable base environments across projects, push to FloxHub:
+
+```bash
+flox push                         # Push environment to FloxHub
+flox activate -r owner/env-name   # Activate remote environment anywhere
+```
+
+Compose environments with `[include]`:
+
+```toml
+[include]
+base.floxhub = "myorg/python-base"
+
+[install]
+# Project-specific additions on top of base
+fastapi.pkg-path = "python311Packages.fastapi"
+```
+
+## AI-Assisted and Vibe Coding
+
+Flox is ideal for AI-assisted development and vibe coding workflows. When an AI agent needs a tool that isn't available in the current environment — a compiler, a database, a linter, a CLI utility — it can add it to the project's Flox manifest without requiring sudo access, polluting system packages, or hitting sandbox restrictions.
+
+**Why this matters for agents:**
+- **No sudo required** — `flox install` works entirely in user space, so agents can add packages without elevated permissions
+- **Project-scoped** — packages are installed into the project environment only, not globally, so different projects can have different versions without conflict
+- **Sandbox-friendly** — agents running in sandboxed or restricted environments can still install the tools they need through Flox
+- **Reversible** — every change is captured in `manifest.toml`, so unwanted packages can be removed cleanly with no system residue
+- **Reproducible** — when an agent sets up an environment, that exact setup is committed to git and works for everyone
+
+**Agent workflow pattern:**
+
+```bash
+# Agent discovers it needs a tool (e.g., jq for JSON processing)
+flox search jq                    # Verify the package exists
+flox install jq                   # Install into project environment
+
+# Or for more control, edit the manifest directly
+tmp_manifest="$(mktemp)"
+flox list -c > "$tmp_manifest"
+# Add the package to [install] section, then apply
+flox edit -f "$tmp_manifest"
+
+# Run a command with the tool available
+flox activate -- jq '.results[]' data.json
+```
+
+This makes Flox a natural fit for any workflow where Claude Code or other AI agents need to bootstrap project tooling on the fly.
+
+## Debugging
+
+```bash
+flox list -c                      # Show raw manifest
+flox activate -- which python     # Check which binary resolves
+flox activate -- env | grep FLOX  # See Flox environment variables
+flox search <package> --all       # Broader package search (case-sensitive)
+```
+
+**Common issues:**
+- **Package not found:** Search is case-sensitive — try `flox search --all`
+- **File conflicts between packages:** Add `priority` to the package that should win
+- **Hook failures:** Use `return` not `exit`; guard with `${FLOX_ENV_CACHE:-}`
+- **Stale dependencies:** Delete the `$FLOX_ENV_CACHE/.deps_installed` flag file
+
+## Related Skills
+
+The following skills are available as part of the [Flox Claude Code plugin](https://github.com/flox/flox-agentic) for deeper integration:
+
+- **flox-services** — Service management, database setup, background processes
+- **flox-builds** — Reproducible builds and packaging with Flox
+- **flox-containers** — Create Docker/OCI containers from Flox environments
+- **flox-sharing** — Environment composition, remote environments, team patterns
+- **flox-cuda** — CUDA and GPU development environments
+
+Learn more and install at [flox.dev/docs](https://flox.dev/docs/install-flox/install/)

package/bundled/upstream/ecc/skills/frontend-design-direction/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: frontend-design-direction
+description: Set an ECC-specific frontend design direction for production UI work. Use when building or improving websites, dashboards, applications, components, landing pages, visual tools, or any web UI that needs stronger product-specific design judgment.
+origin: community
+---
+
+# Frontend Design Direction
+
+Use this skill when the work is not just making UI function, but making it feel
+purposeful, polished, and appropriate to the product domain.
+
+Source: salvaged from stale community PR #1659 by `linus707`.
+
+Note: ECC intentionally does not rebundle the canonical Anthropic
+`frontend-design` skill. Install that from `anthropics/skills` when you want the
+official upstream skill. This skill is the ECC-specific design-direction salvage
+of the useful local guidance from #1659.
+
+## When to Use
+
+- The user asks to build a web page, app, dashboard, artifact, component, or UI.
+- The user asks to make an interface more polished, distinctive, beautiful, or
+  less generic.
+- The implementation needs visual hierarchy, typography, color, motion, layout,
+  and interaction choices.
+- The current UI works but reads as flat, generic, templated, or mismatched to
+  the audience.
+
+## Design Direction
+
+Before coding, choose a specific direction:
+
+1. Purpose: what job does the interface do?
+2. Audience: who repeats this workflow, and what do they need to scan first?
+3. Tone: utilitarian, editorial, playful, industrial, refined, technical,
+   maximal, minimal, dense, calm, or another explicit direction.
+4. Memorable detail: one design idea that makes the result feel intentional.
+5. Constraints: framework, accessibility, performance, responsiveness, and
+   existing design system.
+
+Match the direction to the domain. A SaaS operations tool should usually be
+dense, quiet, and scannable. A portfolio, launch page, game, or editorial piece
+can be more expressive. Do not force a landing-page composition onto a tool that
+needs repeated daily use.
+
+## Implementation Guidance
+
+- Build the actual usable experience as the first screen unless the user
+  explicitly asks for marketing copy.
+- Use existing project components, tokens, icon libraries, and routing patterns
+  before introducing a new visual system.
+- Use real or generated visual assets when the interface depends on images,
+  products, places, people, gameplay, charts, or inspectable media.
+- Prefer contextual typography and spacing over generic oversized hero text.
+- Keep palettes multi-dimensional: avoid a UI dominated by one hue family.
+- Use CSS variables or existing design tokens so the direction remains
+  coherent across states.
+- Design responsive constraints explicitly: grids, aspect ratios, min/max
+  sizes, stable toolbars, and fixed-format controls should not shift when labels
+  or hover states appear.
+- Use motion sparingly but deliberately. Prefer high-signal transitions that
+  clarify state over decorative animation.
+- Verify text fit on mobile and desktop. Long labels must wrap or resize
+  cleanly rather than overflowing.
+
+## Anti-Patterns
+
+- Do not default to common generated patterns: purple gradients, decorative
+  blobs, oversized cards, vague hero copy, or stock-like atmospheric media.
+- Do not add UI cards inside other cards.
+- Do not use a single decorative style everywhere when the domain calls for
+  restraint.
+- Do not hide the primary product, tool, object, or workflow behind generic
+  marketing sections.
+- Do not add a new dependency for a design flourish unless it clearly pays for
+  itself.
+- Do not describe the UI's features inside the UI when the controls can speak
+  for themselves.
+
+## Review Checklist
+
+- The first viewport immediately communicates the product, workflow, or object.
+- The visual hierarchy supports scanning and repeated use.
+- Typography fits the container and does not overlap adjacent content.
+- Color choices have contrast and do not collapse into a one-note palette.
+- Icons are used for familiar tool actions where available.
+- Responsive layout has stable dimensions for boards, grids, toolbars,
+  controls, tiles, and counters.
+- Assets render and carry the subject matter instead of acting as filler.
+- Motion improves orientation and does not mask sluggishness.
+- The result matches the repo's existing frontend conventions unless there is a
+  clear reason to depart.

package/bundled/upstream/ecc/skills/frontend-slides/animation-patterns.md

@@ -0,0 +1,122 @@
+# Animation Patterns Reference
+
+Use this reference when generating presentations. Match animations to the intended feeling.
+
+## Effect-to-Feeling Guide
+
+| Feeling | Animations | Visual Cues |
+|---------|-----------|-------------|
+| **Dramatic / Cinematic** | Slow fade-ins (1-1.5s), large-scale transitions (0.9 to 1), parallax scrolling | Dark backgrounds, spotlight effects, full-bleed images |
+| **Techy / Futuristic** | Neon glow (box-shadow), glitch/scramble text, grid reveals | Particle systems (canvas), grid patterns, monospace accents, cyan/magenta/electric blue |
+| **Playful / Friendly** | Bouncy easing (spring physics), floating/bobbing | Rounded corners, pastel/bright colors, hand-drawn elements |
+| **Professional / Corporate** | Subtle fast animations (200-300ms), clean slides | Navy/slate/charcoal, precise spacing, data visualization focus |
+| **Calm / Minimal** | Very slow subtle motion, gentle fades | High whitespace, muted palette, serif typography, generous padding |
+| **Editorial / Magazine** | Staggered text reveals, image-text interplay | Strong type hierarchy, pull quotes, grid-breaking layouts, serif headlines + sans body |
+
+## Entrance Animations
+
+```css
+/* Fade + Slide Up (most versatile) */
+.reveal {
+    opacity: 0;
+    transform: translateY(30px);
+    transition: opacity 0.6s var(--ease-out-expo),
+                transform 0.6s var(--ease-out-expo);
+}
+.visible .reveal {
+    opacity: 1;
+    transform: translateY(0);
+}
+
+/* Scale In */
+.reveal-scale {
+    opacity: 0;
+    transform: scale(0.9);
+    transition: opacity 0.6s, transform 0.6s var(--ease-out-expo);
+}
+.visible .reveal-scale {
+    opacity: 1;
+    transform: scale(1);
+}
+
+/* Slide from Left */
+.reveal-left {
+    opacity: 0;
+    transform: translateX(-50px);
+    transition: opacity 0.6s, transform 0.6s var(--ease-out-expo);
+}
+.visible .reveal-left {
+    opacity: 1;
+    transform: translateX(0);
+}
+
+/* Blur In */
+.reveal-blur {
+    opacity: 0;
+    filter: blur(10px);
+    transition: opacity 0.8s, filter 0.8s var(--ease-out-expo);
+}
+.visible .reveal-blur {
+    opacity: 1;
+    filter: blur(0);
+}
+```
+
+## Background Effects
+
+```css
+/* Gradient Mesh — layered radial gradients for depth */
+.gradient-bg {
+    background:
+        radial-gradient(ellipse at 20% 80%, rgba(120, 0, 255, 0.3) 0%, transparent 50%),
+        radial-gradient(ellipse at 80% 20%, rgba(0, 255, 200, 0.2) 0%, transparent 50%),
+        var(--bg-primary);
+}
+
+/* Noise Texture — inline SVG for grain */
+.noise-bg {
+    background-image: url("data:image/svg+xml,..."); /* Inline SVG noise */
+}
+
+/* Grid Pattern — subtle structural lines */
+.grid-bg {
+    background-image:
+        linear-gradient(rgba(255,255,255,0.03) 1px, transparent 1px),
+        linear-gradient(90deg, rgba(255,255,255,0.03) 1px, transparent 1px);
+    background-size: 50px 50px;
+}
+```
+
+## Interactive Effects
+
+```javascript
+/* 3D Tilt on Hover — adds depth to cards/panels */
+class TiltEffect {
+    constructor(element) {
+        this.element = element;
+        this.element.style.transformStyle = 'preserve-3d';
+        this.element.style.perspective = '1000px';
+
+        this.element.addEventListener('mousemove', (e) => {
+            const rect = this.element.getBoundingClientRect();
+            const x = (e.clientX - rect.left) / rect.width - 0.5;
+            const y = (e.clientY - rect.top) / rect.height - 0.5;
+            this.element.style.transform = `rotateY(${x * 10}deg) rotateX(${-y * 10}deg)`;
+        });
+
+        this.element.addEventListener('mouseleave', () => {
+            this.element.style.transform = 'rotateY(0) rotateX(0)';
+        });
+    }
+}
+```
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| Fonts not loading | Check Fontshare/Google Fonts URL; ensure font names match in CSS |
+| Animations not triggering | Verify Intersection Observer is running; check `.visible` class is being added |
+| Scroll snap not working | Ensure `scroll-snap-type: y mandatory` on html; each slide needs `scroll-snap-align: start` |
+| Mobile issues | Disable heavy effects at 768px breakpoint; test touch events; reduce particle count |
+| Performance issues | Use `will-change` sparingly; prefer `transform`/`opacity` animations; throttle scroll handlers |