arkaos 4.15.0 → 4.16.0

package/README.md

@@ -2,7 +2,7 @@
 
 **The Operating System for AI Agent Teams.**
 
-86 agents. 17 departments. 274 skills. Enterprise frameworks. Multi-runtime. One install.
+86 agents. 17 departments. 275 skills. Enterprise frameworks. Multi-runtime. One install.
 
 ```bash
 npx arkaos install
@@ -95,7 +95,7 @@ npx arkaos doctor    # Health check
 
 ### Skill packs, à la carte
 
-The default install ships a curated core so your context window stays lean. Everything else lives in the ArkaOS plugin marketplace: 16 department packs with 205 skills, generated straight from the same sources the core uses. Inside Claude Code:
+The default install ships a curated core so your context window stays lean. Everything else lives in the ArkaOS plugin marketplace: 16 department packs with 206 skills, generated straight from the same sources the core uses. Inside Claude Code:
 
 ```
 /plugin marketplace add andreagroferreira/arka-os

package/VERSION

@@ -1 +1 @@
-4.15.0
+4.16.0

package/arka/SKILL.md

@@ -25,7 +25,7 @@ measures citation compliance per turn.
 # ArkaOS — Main Orchestrator
 
 > **The Operating System for AI Agent Teams**
-> 86 agents. 17 departments. 274 skills. Multi-runtime. Dashboard. Knowledge RAG.
+> 86 agents. 17 departments. 275 skills. Multi-runtime. Dashboard. Knowledge RAG.
 
 ## ⛔ Evidence flow — 4 gates (NON-NEGOTIABLE)
 

package/departments/dev/skills/animated-website/SKILL.md

@@ -0,0 +1,449 @@
+---
+name: dev/animated-website
+description: >
+  Convert an MP4 video into a luxury scroll-animated single-file website:
+  extracts frames to optimized WebP (desktop + mobile), then builds a
+  scroll-driven canvas engine with cinematic dwell pacing, ambient particles,
+  film grain, letter-split hero, glass morphism cards, and parallax gallery.
+  TRIGGER: "animated website", "scroll animation", "video to website",
+  "Apple-style page", "site com scroll do vídeo", "transforma este vídeo num
+  site", "frame animation", "/dev animated-website". SKIP: embedding a plain
+  video player -> just use <video>; regular animated site WITHOUT a video
+  source -> frontend-design skill; video editing/production -> content/video-produce.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch]
+---
+
+# Animated Website Generator
+
+> **ArkaOS frontend mandate:** this is UI work under `excellence-mandate` —
+> load the frontend design skills (frontend-design, ui-ux-pro-max, project
+> design system) at maximum effort, emit the `[arka:design]` evidence marker
+> before editing UI files, and pass visual review against a named benchmark
+> (Apple product pages are the default bar for this skill).
+
+Convert video files into scroll-animated websites with a luxury, cinematic aesthetic. The user provides an MP4 video and a concept brief. You extract frames, optimize for web delivery, and generate a complete website where scrolling plays the video frame-by-frame on a canvas element — with rich overlay text, ambient effects, and gallery sections that elevate it beyond a simple scroll player.
+
+The design language draws from high-end real estate, product launches, and editorial showcases: warm dark palettes, serif/sans-serif type pairing, ambient particles, film grain texture, glass morphism cards, and a scroll-dwell engine that creates natural pacing through content sections.
+
+---
+
+## When This Skill Applies
+
+**This skill IS for:**
+- Converting an MP4 video into a scroll-driven animated website
+- Luxury showcase pages (real estate, architecture, product, portfolio)
+- Apple product page-style frame sequences (scroll to play)
+- Any "video → interactive scroll experience" request
+
+**This skill is NOT for:**
+- Embedding a video player on a page (just use `<video>`)
+- Converting video to GIF or animated WebP
+- Building a regular website without video-based scroll animation
+- CSS-only scroll animations (use the `frontend-design` skill instead)
+
+**Redirect:** If the user wants a regular animated website WITHOUT a video source, use the `frontend-design` skill.
+
+---
+
+## Input: What You Need From the User
+
+**Required:**
+1. **An MP4 video file** — absolute path to the source video
+2. **Website concept** — what the site is about (product, brand, property, portfolio, etc.)
+
+**Optional (skill handles defaults if not provided):**
+- Target frame count (default: auto-calculated from video duration)
+- Brand colors (default: warm-dark luxury palette)
+- Section copy (headlines, body text, CTAs)
+- Brand name and tagline
+
+If the user gives just a video path and a vague concept, ask ONE clarifying question about the content direction, then proceed.
+
+---
+
+## Process
+
+### Step 1: Analyze the Video
+
+Probe the video to understand what you're working with:
+
+```bash
+ffprobe -v quiet -print_format json -show_format -show_streams "/path/to/video.mp4"
+```
+
+Parse and present:
+
+```
+VIDEO ANALYSIS:
+Duration:    12.4s
+Resolution:  3840x2160 (4K)
+Frame Rate:  30fps
+Total Frames: 372
+Codec:       H.264
+```
+
+Then recommend frame count:
+
+| Video Duration | Recommended Frames | Scroll Height |
+|---------------|-------------------|---------------|
+| 0-5s          | 60-90             | 400vh         |
+| 5-15s         | 100-150           | 650vh         |
+| 15-30s        | 150-200           | 800vh         |
+| 30s+          | Cap at 200        | 900vh         |
+
+**Get user confirmation before extracting.** Say: "I recommend extracting {N} frames. Sound good, or want to adjust?"
+
+### Step 2: Extract and Optimize Frames
+
+Run the extraction script bundled with this skill (`scripts/extract_frames.py`, relative to this SKILL.md):
+
+```bash
+python3 scripts/extract_frames.py \
+  --input "/path/to/video.mp4" \
+  --output "animated-sites/{slug}/frames" \
+  --frames {N} \
+  --quality 80
+```
+
+Set `--output` to a folder inside the current working directory.
+
+The script produces:
+- `frames/desktop/` — 1920x1080 WebP frames
+- `frames/mobile/` — 960x540 WebP frames
+- `frames/manifest.json` — metadata (counts, sizes, scroll height)
+
+Show the manifest summary to the user. If payload exceeds budget (>10MB desktop, >5MB mobile), recommend `--quality 60` or fewer frames.
+
+### Step 3: Gather Content
+
+Based on the user's concept, prepare content for 6 scroll-text sections. These overlay the video at different scroll positions, creating a narrative experience. The sections are:
+
+1. **Hero** — Property/product name, tagline, key stats
+2. **Vision** — A quote or aspirational statement about the subject
+3. **Details** — Key specifications or features (with icon list)
+4. **Grid** — 4-6 amenities/features in a glass grid layout
+5. **Context** — Location, availability, or background info
+6. **CTA** — Call to action with buttons and contact info
+
+If the user provides copy, use it. If not, generate content that fits the concept. The content should feel editorial and refined — short sentences, evocative language.
+
+### Step 4: Build the Website
+
+Generate a complete single-file HTML page using the design system below. Save to: `animated-sites/{slug}/index.html`
+
+**Adapt the content and branding to the concept** — the design patterns stay consistent but the palette, copy, and section content should fit the subject matter. A tech product might use cooler blues, a restaurant warmer golds, a real estate listing the warm-neutral default.
+
+### Step 5: Serve and Preview
+
+```bash
+cd "animated-sites/{slug}"
+python3 -m http.server 8080
+```
+
+Then open `http://localhost:8080/index.html` in the browser and take screenshots at different scroll positions to verify.
+
+Common iteration requests:
+- "Slower scroll" → increase animation-section height (650vh → 900vh)
+- "Faster scroll" → decrease height (650vh → 400vh)
+- "Smoother animation" → decrease LERP_FACTOR (0.09 → 0.05)
+- "More responsive" → increase LERP_FACTOR (0.09 → 0.15)
+- "Change text" → edit the scroll-text overlay content
+- "Different colors" → update CSS custom properties in `:root`
+
+---
+
+## Design System
+
+The visual language is warm, dark, and cinematic. Every element serves the animation — surrounding effects (grain, particles, vignette) add depth without competing with the video frames.
+
+### Color Palette (CSS Custom Properties)
+
+```css
+:root {
+  --concrete: #d4cfc8;       /* muted warm gray */
+  --concrete-dim: #9e9890;   /* secondary text */
+  --stone: #706050;          /* decorative accents */
+  --charcoal: #1a1816;       /* card backgrounds */
+  --ink: #0e0d0c;            /* page background */
+  --warm-white: #f4f0ea;     /* primary text */
+  --warm-white-dim: #c8c0b4; /* emphasized secondary */
+  --accent-blue: #4a6aff;    /* accent color - adapt per brand */
+  --accent-blue-glow: rgba(74, 106, 255, 0.35);
+  --accent-blue-soft: rgba(74, 106, 255, 0.08);
+  --sunset-pink: #d4a0b0;    /* secondary accent */
+  --gold-warm: #c89848;      /* tertiary accent */
+  --heading: 'Playfair Display', 'Georgia', serif;
+  --body: 'DM Sans', -apple-system, BlinkMacSystemFont, sans-serif;
+}
+```
+
+Adapt the `--accent-blue` family for different brands. The warm-dark base (`--ink`, `--warm-white`) stays consistent — it makes the video frames pop and creates the luxury atmosphere.
+
+### Typography
+
+- **Headings:** Playfair Display — weight 300 for elegance, italic for emphasis
+- **Body:** DM Sans — weight 300-500, generous letter-spacing
+- **Labels:** DM Sans, 8-9px, weight 500, 0.25-0.35em letter-spacing, uppercase
+- **Hero titles:** clamp(42px, 5.5vw, 76px) — big but light weight
+
+Load from Google Fonts:
+```html
+<link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,wght@0,300;0,400;0,500;0,600;1,300;1,400&family=Playfair+Display:ital,wght@0,300;0,400;0,500;0,600;0,700;1,300;1,400&display=swap" rel="stylesheet">
+```
+
+### Layer Stack (z-index)
+
+The site layers multiple visual effects. Here's the stacking order:
+
+| Z-Index | Element | Purpose |
+|---------|---------|---------|
+| 9999 | Loader | Branded loading screen with progress bar |
+| 9998 | Cursor dot | Custom cursor inner dot (mix-blend-mode: difference) |
+| 9997 | Cursor ring | Custom cursor outer ring (expands on hover) |
+| 100 | Film grain | SVG noise overlay at 3.5% opacity |
+| 99 | Vignette | Radial gradient darkening edges |
+| 50 | Chapter markers | Fixed right-side navigation dots |
+| 15 | Particles | Ambient floating particles canvas |
+| 10 | Scroll text | Content overlays during animation |
+| 5 | Tint overlay | Dynamic color wash per section |
+| 1 | Canvas overlays | Left gradient + bottom gradient for text readability |
+| 0 | Video canvas | The scroll-driven frame animation |
+
+### Ambient Effects
+
+These create the cinematic atmosphere. All are pointer-events: none and purely decorative.
+
+**Film Grain:** SVG feTurbulence fractalNoise, 256px tile, opacity 0.035. Gives the site a filmic texture.
+
+**Vignette:** Radial gradient from transparent (center 50%) to rgba(14,13,12,0.45) at edges. Draws focus to center.
+
+**Ambient Particles:** Fixed canvas, ~40 small dots (0.3-1.8px), slow random drift, warm-white at 5-35% opacity. Creates a living, breathing feel. Wrap at edges so they float continuously.
+
+**Dynamic Tint:** Canvas overlay that shifts hue based on current scroll section. Subtle (6-4% opacity) gradient from accent-blue to sunset-pink. Makes each section feel distinct.
+
+**Custom Cursor (desktop only):** Two-part cursor: a 6px dot with mix-blend-mode: difference (always visible against any background) and a 36px ring that trails the dot with LERP. Ring expands to 56px on hover over interactive elements and gains accent-blue glow. Hide on mobile.
+
+### Scroll Dwell Engine
+
+This is what makes the scroll feel magical instead of mechanical. Rather than mapping scroll position linearly to frames, the dwell engine creates "almost stops" at each content section — the scroll slows down there, giving users time to read, then speeds up between sections.
+
+**How it works:**
+1. Define dwell centers — the scroll positions where content appears (e.g., 0.065, 0.21, 0.365, 0.525, 0.685, 0.89)
+2. At each center, a Gaussian density function peaks — meaning more scroll distance is consumed per unit of effective progress
+3. Build a cumulative integral lookup table (forward mapping)
+4. Invert it for the actual remap function (scroll position → effective progress)
+
+The dwell centers should align with the `data-show-at` values of scroll-text sections. With 6 sections, space them roughly evenly across 0-1 but offset from the edges.
+
+Parameters to tune:
+- `DWELL_WIDTH` (0.045): How wide the slow zone is. Smaller = tighter pause.
+- `DWELL_PEAK` (3.5): How much slower the scroll feels at dwell points. Higher = more dramatic pause.
+- `REMAP_N` (2000): Resolution of the lookup table. 2000 is smooth enough.
+
+### Scroll Text Overlays
+
+Six sections that appear and disappear at specific scroll positions. Each has its own layout and style:
+
+1. **Hero** (positioned left, 6% from edge): Property/product name with letter-split animation, tagline, price/key metric. Has a glass stat bar at bottom with 4-5 key numbers.
+
+2. **Vision** (positioned left): Opening quotation mark as decorative element, italic serif quote, divider line, attribution.
+
+3. **Details** (positioned left): Overline label, serif title, body text, feature list with icon items and subtle borders.
+
+4. **Grid** (positioned left): Overline label, 2-column glass grid of 6 amenity/feature cells with icons and descriptions.
+
+5. **Context** (positioned left): Overline label, serif title, body text, distance/detail list with dotted connecting lines.
+
+6. **CTA** (centered): Large serif title with italic emphasis, subtitle, two buttons (primary filled, secondary outline), and agent/contact card.
+
+Each section fades in with blur(6px→0) and translateX(-20px→0) transitions. The `.visible` class is toggled based on scroll progress matching the `data-show-at` / `data-hide-at` attributes.
+
+### Glass Morphism Cards
+
+Used for stat bars and amenity grids:
+- Background: rgba(244, 240, 234, 0.03)
+- backdrop-filter: blur(20px)
+- Border: 1px solid rgba(244, 240, 234, 0.06)
+- On hover: background brightens to 0.06, border gains accent-blue tint
+
+### Chapter Markers
+
+Fixed right-side vertical navigation showing 6 dots connected by lines. The active dot gets accent-blue glow and the connecting line fills with progress as you scroll through the section. Dots can have labels that appear on hover.
+
+### Gallery Section
+
+Below the scroll animation, a masonry-ish grid of frames from the video. Uses IntersectionObserver for reveal animations and requestAnimationFrame-based parallax transforms (data-parallax attribute with positive/negative px values).
+
+Grid layout: `grid-template-columns: repeat(3, 1fr)` with some items spanning 2 rows via `.tall` class. Images have subtle hover zoom (scale 1.03) with overflow hidden.
+
+Pick 6-7 evenly spaced frames from the video for gallery images.
+
+### Branded Loader
+
+Not just a progress bar — a branded experience:
+- Centered brand mark in uppercase letter-spaced heading font
+- Decorative lines above and below
+- Thin 140px progress bar with gradient fill (accent-blue → sunset-pink)
+- Percentage counter below
+- Exits with opacity 0 + blur(8px) transition
+
+### Footer
+
+Minimal: brand name in heading font, legal line in small body text, dark background slightly lighter than ink.
+
+---
+
+## Code Architecture
+
+The entire site is a single HTML file. Here's the structural order:
+
+```
+HTML:
+  1. Google Fonts link
+  2. <style> with all CSS
+  3. Custom cursor divs (#cursor-dot, #cursor-ring)
+  4. Film grain overlay div
+  5. Vignette overlay div
+  6. Particles canvas (fixed)
+  7. Loader (fixed, z-9999)
+  8. Chapter markers (fixed right)
+  9. Animation section (relative, 650vh)
+     - Canvas container (sticky)
+       - Main canvas
+       - Left gradient overlay
+       - Bottom gradient overlay
+       - Tint overlay
+     - 6 scroll-text overlays (fixed, toggled by JS)
+  10. Gallery section
+  11. Footer
+  12. <script> with all JS
+
+JS order:
+  1. Custom cursor tracking + ring LERP
+  2. Particle system init + animation loop
+  3. Letter-split animation (data-split attribute)
+  4. Scroll dwell/remap engine (LUT construction)
+  5. Frame loading (critical first, then batches)
+  6. Scroll animation loop (remap → LERP → drawFrame)
+  7. Scroll-text visibility toggling
+  8. Chapter marker updates
+  9. Tint overlay updates
+  10. Gallery IntersectionObserver + parallax
+  11. Stat counter animation
+  12. Init: load frames → hide loader → start animation
+```
+
+### Key JavaScript Patterns
+
+**Frame loading with progressive enhancement:**
+```javascript
+// Critical frames first (evenly spaced), then batches
+// Use createImageBitmap for off-thread decode when available
+// Show first frame immediately after critical load
+```
+
+**Scroll-to-frame with dwell remap:**
+```javascript
+function getScrollProgress() {
+  const rect = section.getBoundingClientRect();
+  return Math.max(0, Math.min(1, -rect.top / (rect.height - window.innerHeight)));
+}
+
+function animate() {
+  const rawProgress = getScrollProgress();
+  const remapped = remapProgress(rawProgress);  // dwell engine
+  targetFrame = Math.floor(remapped * (FRAME_COUNT - 1));
+  currentFrame += (targetFrame - currentFrame) * LERP_FACTOR;
+  drawFrame(Math.round(currentFrame));
+  // Also update scroll-text visibility, chapter markers, tint
+  requestAnimationFrame(animate);
+}
+```
+
+**Stat counter animation:**
+```javascript
+// When stat-bar becomes visible, animate numbers from 0 to target
+// Use ease-out cubic easing over ~1.5s
+// Parse target from data-target attribute, handle commas/units
+```
+
+---
+
+## Adapting for Different Concepts
+
+The design system is flexible. Here's how to adapt it:
+
+**Real Estate:** Default palette works perfectly. Use property name as hero title, price and specs in stat bar, architecture details, amenity grid, location distances, viewing CTA.
+
+**Tech Product:** Shift accent to cooler blue (#2563eb) or electric violet (#7c3aed). Hero has product name + tagline, stat bar shows key specs (battery, weight, price), Details lists tech specs, Grid shows features, CTA is "Pre-order" or "Learn More".
+
+**Portfolio/Creative:** Use gold-warm (#c89848) as accent. Hero has creator name + discipline, Vision quotes an artistic statement, Details shows notable works, Grid shows services/capabilities, CTA is "Get in Touch".
+
+**Restaurant/Hospitality:** Warm accent (#c89848 or deep burgundy). Hero is venue name, Vision is a chef quote, Details is cuisine philosophy, Grid is menu highlights or experiences, Context is location/hours.
+
+**Automotive:** Keep accent-blue or shift to silver (#a8a8a8). Hero is vehicle name + starting price, stat bar shows 0-60/HP/range, Details is engineering highlights.
+
+In all cases, the 6-section structure, ambient effects, scroll-dwell engine, and glass morphism cards remain the same — they create the luxury feel regardless of content.
+
+---
+
+## Quality Checklist
+
+Before showing the site to the user, verify:
+
+- [ ] **Smooth at 60fps** — no jank or frame drops during scroll
+- [ ] **First frame visible in <1s** — progressive loading works
+- [ ] **Loading bar accurate** — gradient fill, percentage counter updates
+- [ ] **Desktop payload <10MB** — check manifest.json
+- [ ] **Mobile payload <5MB** — check manifest.json
+- [ ] **Reduced motion handled** — static first frame when prefers-reduced-motion
+- [ ] **No blank frames** — nearest-neighbor fallback fills gaps
+- [ ] **Responsive** — canvas scales on resize, mobile layout works
+- [ ] **Custom cursor works on desktop** — dot tracks instantly, ring trails
+- [ ] **Particles animate** — subtle floating dots visible against dark bg
+- [ ] **Scroll text appears/disappears** — 6 sections at correct scroll positions
+- [ ] **Letter-split hero animates** — characters appear sequentially
+- [ ] **Glass stat bar readable** — blur backdrop works, numbers visible
+- [ ] **Gallery loads** — images from frames directory, parallax on scroll
+- [ ] **Dwell engine feels natural** — scroll slows at content, speeds between
+- [ ] **Chapter markers update** — active dot highlighted, progress lines fill
+
+---
+
+## Output Format
+
+```
+animated-sites/{slug}/
+├── frames/
+│   ├── desktop/              # 1920x1080 WebP
+│   │   ├── frame-0001.webp
+│   │   └── ...
+│   ├── mobile/               # 960x540 WebP
+│   │   ├── frame-0001.webp
+│   │   └── ...
+│   └── manifest.json         # Frame metadata
+└── index.html                # Complete luxury scroll site
+```
+
+To view: `cd` into the output directory and run `python3 -m http.server 8080`, then open `localhost:8080`.
+
+---
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| FFmpeg not found | `brew install ffmpeg` |
+| No libwebp support | `brew reinstall ffmpeg` (includes libwebp by default) |
+| Frames too large (>10MB) | Lower quality: `--quality 60`. Reduce count: `--frames 90` |
+| Animation stutters | Reduce frame count. Check DPR cap is 2. Decrease particles. |
+| White flash between frames | Nearest-frame fallback not finding frames. Check extraction. |
+| Canvas blank on mobile | Verify mobile frames exist. Check FRAME_DIR path switch. |
+| Loading bar stuck | A frame 404'd. Check browser console. Verify frame paths. |
+| Scroll too fast/slow | Adjust animation-section height. 650vh = default. |
+| Dwell feels too sticky | Decrease DWELL_PEAK (3.5 → 2.5) or increase DWELL_WIDTH |
+| Particles too visible | Decrease particles-canvas opacity (0.4 → 0.2) |
+| Custom cursor jittery | Increase ring LERP factor (0.15 → 0.2) |
+| Glass blur not working | Safari needs -webkit-backdrop-filter. Already included in CSS. |
+| CORS error locally | Serve with `python3 -m http.server 8080`. Don't double-click HTML. |
+| Fonts not loading | Check Google Fonts link. Fallback fonts in CSS vars handle it. |

package/departments/dev/skills/animated-website/scripts/extract_frames.py

@@ -0,0 +1,407 @@
+#!/usr/bin/env python3
+"""
+Extract frames from video and convert to optimized WebP for scroll animation.
+
+Extracts evenly-spaced frames from an MP4 video, converts to WebP at dual
+resolutions (desktop + mobile), and generates a manifest.json with metadata.
+
+Usage:
+    python3 extract_frames.py \
+        --input /path/to/video.mp4 \
+        --output animated-sites/my-project/frames
+
+    Custom frame count:        --frames 120
+    Custom quality/resolution: --quality 75 --desktop-res 1920x1080 --mobile-res 960x540
+    Single variant:            --desktop-only  (or --mobile-only)
+
+Environment:
+    Requires ffmpeg and ffprobe installed (brew install ffmpeg).
+"""
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+DESKTOP_BUDGET_MB = 10
+MOBILE_BUDGET_MB = 5
+FFMPEG_TIMEOUT_S = 300
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        description="Extract frames from video for scroll animation"
+    )
+    _add_io_args(parser)
+    _add_encoding_args(parser)
+    return parser.parse_args()
+
+
+def _add_io_args(parser):
+    parser.add_argument("--input", required=True, help="Path to source MP4 video file")
+    parser.add_argument("--output", required=True, help="Output directory for extracted frames")
+    parser.add_argument("--desktop-only", action="store_true", help="Skip mobile frame generation")
+    parser.add_argument("--mobile-only", action="store_true", help="Skip desktop frame generation")
+
+
+def _add_encoding_args(parser):
+    parser.add_argument(
+        "--frames", type=int, default=0,
+        help="Target frame count (default: auto-calculated from video duration)",
+    )
+    parser.add_argument("--quality", type=int, default=80, help="WebP quality 1-100 (default: 80)")
+    parser.add_argument(
+        "--desktop-res", default="1920x1080", help="Desktop frame resolution (default: 1920x1080)"
+    )
+    parser.add_argument(
+        "--mobile-res", default="960x540", help="Mobile frame resolution (default: 960x540)"
+    )
+
+
+def fail(message):
+    """Print an error to stderr and exit 1."""
+    print(f"Error: {message}", file=sys.stderr)
+    sys.exit(1)
+
+
+def validate_dependencies():
+    """Check that ffmpeg and ffprobe are installed."""
+    for cmd in ("ffmpeg", "ffprobe"):
+        if not shutil.which(cmd):
+            fail(f"'{cmd}' not found. Install with: brew install ffmpeg")
+
+
+def validate_input(input_path):
+    """Check the input file exists and looks like a video; return the resolved path."""
+    p = Path(input_path).resolve()
+    if not p.exists():
+        fail(f"File not found: {input_path}")
+    if p.stat().st_size < 1024:
+        fail(f"File too small to be a video: {input_path}")
+    return p
+
+
+def validate_quality(quality):
+    """Enforce the documented WebP quality range (1-100)."""
+    if not 1 <= quality <= 100:
+        fail(f"--quality must be between 1 and 100, got {quality}")
+
+
+def parse_fps(fps_str):
+    """Parse an ffprobe r_frame_rate value ('30/1' or '29.97') into a float."""
+    if "/" in fps_str:
+        num, den = fps_str.split("/")
+        return float(num) / float(den) if float(den) != 0 else 30.0
+    return float(fps_str)
+
+
+def _run_ffprobe(input_path):
+    """Run ffprobe and return the parsed JSON document."""
+    cmd = [
+        "ffprobe", "-v", "quiet", "-print_format", "json",
+        "-show_format", "-show_streams", str(input_path),
+    ]
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+        return json.loads(result.stdout)
+    except subprocess.CalledProcessError as e:
+        fail(f"ffprobe failed: {e.stderr}")
+    except json.JSONDecodeError:
+        fail("Could not parse ffprobe output")
+
+
+def probe_video(input_path):
+    """Probe the video and return duration/resolution/fps/codec metadata."""
+    data = _run_ffprobe(input_path)
+    video_stream = next(
+        (s for s in data.get("streams", []) if s.get("codec_type") == "video"), None
+    )
+    if not video_stream:
+        fail("No video stream found in file")
+
+    fps = parse_fps(video_stream.get("r_frame_rate", "30/1"))
+    duration = float(data.get("format", {}).get("duration", 0))
+    if duration == 0:
+        duration = float(video_stream.get("duration", 0))
+
+    return {
+        "duration": round(duration, 2),
+        "width": int(video_stream.get("width", 1920)),
+        "height": int(video_stream.get("height", 1080)),
+        "fps": round(fps, 2),
+        "codec": video_stream.get("codec_name", "unknown"),
+        "total_frames": round(duration * fps),
+        "filename": Path(input_path).name,
+    }
+
+
+def calculate_optimal_frames(duration, user_override=0):
+    """Calculate optimal frame count and scroll height from video duration.
+
+    Formula: min(200, max(60, duration * 10))
+    - 0-5s videos: 60-90 frames (simple reveals)
+    - 5-15s: 120-150 (standard, the sweet spot)
+    - 15-30s: 150-200 (complex sequences)
+    - 30s+: capped at 200 (increase scroll height instead)
+    """
+    frame_count = user_override if user_override > 0 else min(200, max(60, int(duration * 10)))
+    # Scroll height: ~3.3vh per frame, minimum 300vh, rounded to nearest 50vh
+    scroll_height = round(max(300, int(frame_count * 3.3)) / 50) * 50
+    return frame_count, scroll_height
+
+
+def parse_resolution(res_str):
+    """Parse 'WIDTHxHEIGHT' string into (width, height) tuple."""
+    try:
+        w, h = res_str.lower().split("x")
+        return int(w), int(h)
+    except (ValueError, AttributeError):
+        fail(f"Invalid resolution format: {res_str}. Use WIDTHxHEIGHT.")
+
+
+def has_libwebp():
+    """Check if FFmpeg has libwebp encoder support."""
+    result = subprocess.run(["ffmpeg", "-encoders"], capture_output=True, text=True)
+    return "libwebp" in result.stdout
+
+
+def _probe_duration(input_path):
+    """Return the container duration in seconds (10.0 fallback)."""
+    cmd = [
+        "ffprobe", "-v", "quiet", "-show_entries", "format=duration",
+        "-of", "csv=p=0", str(input_path),
+    ]
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    return float(result.stdout.strip()) if result.stdout.strip() else 10.0
+
+
+def _build_extract_cmd(input_path, output_dir, target_fps, resolution, quality, use_libwebp):
+    """Build the ffmpeg command: single-pass WebP when libwebp exists, else PNG."""
+    w, h = resolution
+    cmd = [
+        "ffmpeg", "-y", "-i", str(input_path),
+        "-vf", f"fps={target_fps:.4f},scale={w}:{h}:flags=lanczos",
+        "-an",
+    ]
+    if use_libwebp:
+        cmd += ["-c:v", "libwebp", "-quality", str(quality), "-compression_level", "6"]
+    ext = "webp" if use_libwebp else "png"
+    return [*cmd, str(output_dir / f"frame-%04d.{ext}")]
+
+
+def _run_ffmpeg(cmd):
+    """Run ffmpeg with a hard timeout; exit 1 on any failure."""
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=FFMPEG_TIMEOUT_S)
+        if result.returncode != 0:
+            fail(f"FFmpeg failed:\n{result.stderr[-500:]}")
+    except subprocess.TimeoutExpired:
+        fail("FFmpeg timed out (5 min limit)")
+
+
+def _convert_pngs_to_webp(output_dir, quality, prefix):
+    """Universal fallback: convert extracted PNGs to WebP via Pillow, then delete them."""
+    try:
+        from PIL import Image as PILImage
+    except ImportError:
+        fail(
+            "Neither libwebp (FFmpeg) nor Pillow is available.\n"
+            "Fix: pip install Pillow  OR  brew reinstall ffmpeg"
+        )
+
+    png_files = sorted(output_dir.glob("frame-*.png"))
+    print(f"{prefix}Converting {len(png_files)} PNGs to WebP via Pillow...", file=sys.stderr)
+    for png_path in png_files:
+        img = PILImage.open(png_path)
+        if img.mode != "RGB":
+            img = img.convert("RGB")
+        img.save(str(png_path.with_suffix(".webp")), "WEBP", quality=quality, method=6)
+        png_path.unlink()  # Remove PNG to save disk space
+
+
+def _measure_frames(output_dir, resolution, prefix):
+    """Count extracted WebP frames and report sizes; exit 1 when none exist."""
+    frames = sorted(output_dir.glob("frame-*.webp"))
+    if not frames:
+        fail(f"No frames extracted to {output_dir}")
+
+    total_bytes = sum(f.stat().st_size for f in frames)
+    avg_bytes = total_bytes // len(frames)
+    print(
+        f"{prefix}{len(frames)} frames extracted "
+        f"({total_bytes / 1024 / 1024:.1f}MB total, {avg_bytes / 1024:.0f}KB avg per frame)",
+        file=sys.stderr,
+    )
+    w, h = resolution
+    return {
+        "count": len(frames),
+        "total_bytes": total_bytes,
+        "avg_bytes": avg_bytes,
+        "resolution": f"{w}x{h}",
+    }
+
+
+def extract_frames(input_path, output_dir, frame_count, resolution, quality, label=""):
+    """Extract evenly-spaced frames from video as WebP.
+
+    Strategy:
+    1. If FFmpeg has libwebp: single-pass extraction to WebP (fastest)
+    2. Otherwise: extract as PNG, then convert to WebP via Pillow (universal)
+    """
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    duration = _probe_duration(input_path)
+    target_fps = max(1, min(60, frame_count / duration))
+
+    prefix = f"  [{label}] " if label else "  "
+    use_libwebp = has_libwebp()
+    encoder = "FFmpeg libwebp" if use_libwebp else "FFmpeg + Pillow"
+    w, h = resolution
+    print(f"{prefix}Extracting {frame_count} frames at {w}x{h} ({encoder})...", file=sys.stderr)
+
+    cmd = _build_extract_cmd(input_path, output_dir, target_fps, resolution, quality, use_libwebp)
+    _run_ffmpeg(cmd)
+    if not use_libwebp:
+        _convert_pngs_to_webp(output_dir, quality, prefix)
+
+    return _measure_frames(output_dir, resolution, prefix)
+
+
+def _variant_summary(info):
+    """Shape one resolution variant's extraction info for the manifest."""
+    return {
+        "resolution": info["resolution"],
+        "actual_count": info["count"],
+        "total_bytes": info["total_bytes"],
+        "avg_frame_bytes": info["avg_bytes"],
+        "total_mb": round(info["total_bytes"] / 1024 / 1024, 2),
+    }
+
+
+def _source_summary(video_info):
+    """Shape the source-video block of the manifest."""
+    return {
+        "filename": video_info["filename"],
+        "duration": video_info["duration"],
+        "resolution": f"{video_info['width']}x{video_info['height']}",
+        "fps": video_info["fps"],
+        "codec": video_info["codec"],
+        "total_source_frames": video_info["total_frames"],
+    }
+
+
+def generate_manifest(output_dir, video_info, frame_count, scroll_height,
+                      quality, desktop_info=None, mobile_info=None):
+    """Generate manifest.json with full metadata."""
+    manifest = {
+        "source": _source_summary(video_info),
+        "frames": {
+            "target_count": frame_count,
+            "format": "webp",
+            "quality": quality,
+            "naming_pattern": "frame-{NNNN}.webp",
+        },
+        "recommended_scroll_height": f"{scroll_height}vh",
+        "created": datetime.now().isoformat(timespec="seconds"),
+    }
+    if desktop_info:
+        manifest["desktop"] = _variant_summary(desktop_info)
+    if mobile_info:
+        manifest["mobile"] = _variant_summary(mobile_info)
+
+    manifest_path = Path(output_dir) / "manifest.json"
+    with open(manifest_path, "w") as f:
+        json.dump(manifest, f, indent=2)
+    print(f"\n  Manifest saved to: {manifest_path}", file=sys.stderr)
+    return manifest
+
+
+def _print_budget_warnings(manifest):
+    """Warn when a variant's payload exceeds its budget."""
+    budgets = (("desktop", DESKTOP_BUDGET_MB), ("mobile", MOBILE_BUDGET_MB))
+    for variant, budget_mb in budgets:
+        total_mb = manifest.get(variant, {}).get("total_mb", 0)
+        if total_mb > budget_mb:
+            print(
+                f"\n  WARNING: {variant.capitalize()} payload ({total_mb}MB) "
+                f"exceeds {budget_mb}MB target.",
+                file=sys.stderr,
+            )
+            print("  Consider: --quality 60 or --frames (lower count)", file=sys.stderr)
+
+
+def print_summary(video_info, frame_count, scroll_height, manifest):
+    """Print a human-readable summary."""
+    err = sys.stderr
+    print("\n" + "=" * 56, file=err)
+    print("  VIDEO ANALYSIS", file=err)
+    print("=" * 56, file=err)
+    print(f"  Source:      {video_info['filename']}", file=err)
+    print(f"  Duration:    {video_info['duration']}s", file=err)
+    print(f"  Resolution:  {video_info['width']}x{video_info['height']}", file=err)
+    print(f"  Frame Rate:  {video_info['fps']}fps", file=err)
+    print(f"  Codec:       {video_info['codec']}", file=err)
+    print(f"  Src Frames:  {video_info['total_frames']}", file=err)
+    print("-" * 56, file=err)
+    print("  EXTRACTION RESULTS", file=err)
+    print("-" * 56, file=err)
+    print(f"  Target:      {frame_count} frames", file=err)
+    print(f"  Scroll:      {scroll_height}vh recommended", file=err)
+    for variant in ("desktop", "mobile"):
+        if variant in manifest:
+            v = manifest[variant]
+            print(
+                f"  {variant.capitalize():<12} {v['actual_count']} frames "
+                f"@ {v['resolution']} ({v['total_mb']}MB)",
+                file=err,
+            )
+    print("=" * 56, file=err)
+    _print_budget_warnings(manifest)
+
+
+def _extract_variants(args, input_path, frame_count):
+    """Extract the desktop and/or mobile frame sets per the CLI flags."""
+    output_dir = Path(args.output)
+    desktop_info = None
+    mobile_info = None
+    if not args.mobile_only:
+        desktop_info = extract_frames(
+            input_path, output_dir / "desktop", frame_count,
+            parse_resolution(args.desktop_res), args.quality, label="desktop",
+        )
+    if not args.desktop_only:
+        mobile_info = extract_frames(
+            input_path, output_dir / "mobile", frame_count,
+            parse_resolution(args.mobile_res), args.quality, label="mobile",
+        )
+    return desktop_info, mobile_info
+
+
+def main():
+    args = parse_args()
+    validate_dependencies()
+    validate_quality(args.quality)
+    input_path = validate_input(args.input)
+
+    print("\nProbing video...", file=sys.stderr)
+    video_info = probe_video(input_path)
+    frame_count, scroll_height = calculate_optimal_frames(video_info["duration"], args.frames)
+
+    Path(args.output).mkdir(parents=True, exist_ok=True)
+    desktop_info, mobile_info = _extract_variants(args, input_path, frame_count)
+
+    manifest = generate_manifest(
+        args.output, video_info, frame_count, scroll_height,
+        args.quality, desktop_info, mobile_info,
+    )
+    print_summary(video_info, frame_count, scroll_height, manifest)
+    # Machine-readable output on stdout for the calling agent to parse
+    print(json.dumps(manifest, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/knowledge/skills-manifest.json

@@ -1,7 +1,7 @@
 {
   "_meta": {
     "generator": "scripts/marketplace_gen.py",
-    "version": "4.15.0",
+    "version": "4.16.0",
     "marketplace": "arkaos"
   },
   "structural": {
@@ -177,6 +177,16 @@
       ],
       "collision": false
     },
+    "animated-website": {
+      "depts": [
+        "dev"
+      ],
+      "curated": false,
+      "plugins": [
+        "arkaos-dev@arkaos"
+      ],
+      "collision": false
+    },
     "api-design": {
       "depts": [
         "dev"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "4.15.0",
+  "version": "4.16.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "4.15.0"
+version = "4.16.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}

package/scripts/marketplace_gen.py

@@ -154,7 +154,10 @@ def _emit_skill(src_dir: Path, dest_dir: Path) -> None:
     for resource in _RESOURCE_DIRS:
         src = src_dir / resource
         if src.is_dir():
-            shutil.copytree(src, dest_dir / resource, dirs_exist_ok=True)
+            shutil.copytree(
+                src, dest_dir / resource, dirs_exist_ok=True,
+                ignore=shutil.ignore_patterns("__pycache__", "*.pyc", ".DS_Store"),
+            )
 
 
 def build_plugins() -> dict[str, list[str]]: