@jaimevalasek/aioson 1.7.0 → 1.8.0

package/template/.aioson/agents/site-forge.md

@@ -23,10 +23,9 @@ Clone the structure, content, and/or visual design of a real website. Build a Ne
 Load `.aioson/brains/_index.json` on activation — it's ~2KB.
 
 When task involves visual cloning, CSS animation, hover effects, scroll, video, or font extraction:
-
 1. Find matching brain files from index (tag match against task context)
 2. Load those brain files — not all, only relevant
-3. For nodes with `q >= 4`: apply as the default approach (these are validated patterns)
+3. For nodes with `q >= 4`: apply as the default approach
 4. For nodes with `v === "AVOID"`: never implement what's in their `not` field
 5. Traverse `see[]` links to explore connected knowledge
 
@@ -35,40 +34,32 @@ Cross-reference command (run before Phase 2 if task involves animation/interacti
 node .aioson/brains/scripts/query.js --agent site-forge --min-quality 4 --format compact
 ```
 
-**After forging a skill**, record new learnings back into the brain:
-- Add nodes to `.aioson/brains/site-forge/visual-patterns.brain.json`
-- Rate quality 1–5 (be honest — 3 = theoretical, 5 = verified in production)
-- Add `see[]` links to related nodes (Zettelkasten web)
-- Update `_index.json` nodes count and `updated` date
+After forging a skill, record new learnings back into `.aioson/brains/site-forge/visual-patterns.brain.json`. Rate quality 1–5. Add `see[]` links. Update `_index.json`.
 
 ---
 
 ## Project rules, docs & design docs
 
-These directories are **optional**. Check silently — if absent or empty, move on without mentioning it.
+Check silently — if absent or empty, move on without mentioning it.
 
-1. **`.aioson/rules/`** — Read each `.md` file's YAML frontmatter. If `agents:` is absent → load. If `agents:` includes `site-forge` → load. Otherwise skip. Loaded rules override defaults here.
+1. **`.aioson/rules/`** — Load if `agents:` is absent or includes `site-forge`. Loaded rules override defaults here.
 2. **`.aioson/docs/`** — Load only files whose `description` frontmatter is relevant to the current task.
-3. **`.aioson/context/design-doc*.md`** — If `agents:` is absent → load when `scope` matches. If `agents:` includes `site-forge` → load. Otherwise skip.
+3. **`.aioson/context/design-doc*.md`** — Load when `agents:` is absent and `scope` matches, or when `agents:` includes `site-forge`.
 
 ---
 
-## Starting the session — Smart Onboarding
+## Smart Onboarding
 
 **Parse the input first:**
 
 - URL + skill name (explicit) → **Mode A**. Go to Step 0.
 - URL + `--skill-only` or `--no-build` flag → **Mode D**. Go to Step 0.
 - URL + skill name + `--blend` flag → **Mode E**. Ask for blend ratio (default 50%). Go to Step 0.
-- URL only (no skill, no flags) → Run the onboarding questionnaire below.
-- No URL, any input → Run the onboarding questionnaire below.
-
----
+- URL only (no skill, no flags) → Run questionnaire below.
+- No URL, any input → Run questionnaire below.
 
 ### Onboarding questionnaire
 
-Present this when the mode is not unambiguous from the input:
-
 ```
 Olá! Vou te guiar para o modo certo de clonagem.
 
@@ -90,30 +81,23 @@ O que você quer fazer com este site?
 Responda A, B, C ou D.
 ```
 
-**After the user answers, collect missing inputs:**
-
-- **A selected:** Ask for URL (if not yet provided). Then list available skills from `.aioson/installed-skills/` and `.aioson/skills/design/` — ask which to use. → Route to **Mode C** (content-first harvest).
-- **B selected:** Ask for URL (if not yet provided). → Route to **Mode B**.
-- **C selected:** Ask for URL (if not yet provided). → Route to **Mode D** (skill only, no build).
-- **D selected:** Ask for URL (if not yet provided). List available skills — ask which to use. Ask for blend ratio (default 50%). → Route to **Mode E**.
-
-Map user choices to internal modes:
-- User choice A → **Mode C** (emphasizes deep content extraction, applies skill to build)
-- User choice B → **Mode B** (existing faithful clone + skill forge)
-- User choice C → **Mode D** (skill forge only)
-- User choice D → **Mode E** (clone + blend)
+**After user answers:**
+- A selected → collect URL + skill from `.aioson/installed-skills/` or `.aioson/skills/design/` → route to **Mode C**
+- B selected → collect URL → route to **Mode B**
+- C selected → collect URL → route to **Mode D** (skill only)
+- D selected → collect URL + skill + blend ratio (default 50%) → route to **Mode E**
 
-Once all inputs are confirmed, proceed to Step 0.
+Once all inputs confirmed, proceed to Step 0.
 
 ---
 
 ## Step 0 — Preflight
 
-Run all checks BEFORE starting Phase 1. Block on critical failures.
+Run all checks BEFORE Phase 1. Block on critical failures.
 
 ### 0.1 Browser MCP check (CRITICAL)
 
-Attempt a minimal navigation to detect which browser MCP is available. Preference order:
+Attempt minimal navigation to detect available browser MCP. Preference order:
 1. Playwright MCP (`@playwright/mcp`) — preferred
 2. Puppeteer MCP (`@modelcontextprotocol/server-puppeteer`) — fallback
 3. Browserbase MCP — cloud option
@@ -135,10 +119,9 @@ Add it to your Claude Code MCP settings and re-activate /site-forge.
 ```
 Do not proceed past Step 0 if no browser MCP is available.
 
-### 0.2 Mode detection summary
-
-After onboarding, confirm the active mode to the user:
+### 0.2 Mode confirmation
 
+Confirm to the user:
 ```
 Modo ativo: [A | B | C | D | E]
 URL: <url>
@@ -146,1608 +129,153 @@ Skill: <skill-name> (if applicable)
 Blend: <ratio>% (Mode E only)
 ```
 
-**Mode A / C / E — Skill resolution:**
-
-Look for the named skill in this order:
-1. `.aioson/installed-skills/<skill-name>/SKILL.md` — skills from @design-hybrid-forge
-2. `.aioson/skills/design/<skill-name>/SKILL.md` — core AIOSON design skills
+**Mode A / C / E — Skill resolution:** Look in order:
+1. `.aioson/installed-skills/<skill-name>/SKILL.md`
+2. `.aioson/skills/design/<skill-name>/SKILL.md`
 
-**If not found:**
+If not found:
 ```
 ⛔ Skill "<skill-name>" not found.
-
-Skills disponíveis:
-[list from both paths]
-
+Skills disponíveis: [list from both paths]
 Para criar uma nova hybrid skill: /design-hybrid-forge
 ```
 
-**Mode B / D — Skill will be forged during Phase 3B.** No skill needed now.
-
-### 0.3 Output directory detection
+**Mode B / D:** Skill forged during Phase 3B — none needed now.
 
-**Modes A, B, C, E (builds a site):**
+### 0.3 Output directory detection (Modes A, B, C, E)
 
-Check whether a Next.js project exists in the working directory:
-- `package.json` with `"next"` in dependencies, or
-- `next.config.*` file present
+Check for existing Next.js project: `package.json` with `"next"` in dependencies, or `next.config.*` present.
 
-**If Next.js project found:** use it. Warn the user if there are uncommitted changes before modifying files.
+- Found → use it. Warn if uncommitted changes exist.
+- Not found → ask: "No Next.js project found. Should I scaffold one with `create-next-app` (TypeScript + Tailwind + App Router)?"
+  If yes: `npx create-next-app@latest . --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" --no-git`
 
-**If not found:** ask the user before scaffolding:
-> "No Next.js project found. Should I scaffold one with `create-next-app` (TypeScript + Tailwind + App Router)?"
->
-> If yes:
-> ```bash
-> npx create-next-app@latest . --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" --no-git
-> ```
-
-**Mode D (skill only):** Skip this check. No Next.js project needed.
+**Mode D:** Skip — no Next.js project needed.
 
 ### 0.4 Research directories
 
-Create before starting:
+Create before Phase 1:
 - `docs/research/<hostname>/`
 - `docs/research/components/`
 - `public/images/<hostname>/` (Modes A, B, C, E only)
 
 ---
 
-## Phase 1 — Reconnaissance
-
-**Goal:** Capture raw information about the site. All modes run this phase.
-
-### 1.1 Multi-viewport screenshots
-
-Navigate to the URL and capture at three widths:
-- Desktop: 1440px
-- Tablet: 768px
-- Mobile: 390px
-
-Save to `docs/research/<hostname>/screenshots/desktop.png`, `tablet.png`, `mobile.png`.
-
-**Bot protection:** If the page renders blank, shows a CAPTCHA, or redirects to a challenge page, tell the user:
-> "This site has bot protection. Please provide session cookies or a local HAR capture to continue."
-
-### 1.2 Deep asset inventory (CRITICAL — do not skip steps)
-
-**Step A — Trigger lazy loads before extraction:**
-
-```javascript
-// Scroll to trigger lazy-loaded images before extracting
-await page.evaluate(() => {
-  return new Promise(resolve => {
-    let totalHeight = 0;
-    const distance = 300;
-    const timer = setInterval(() => {
-      window.scrollBy(0, distance);
-      totalHeight += distance;
-      if (totalHeight >= document.body.scrollHeight) {
-        clearInterval(timer);
-        window.scrollTo(0, 0);
-        resolve();
-      }
-    }, 100);
-  });
-});
-```
-
-Wait 1 second after scroll for lazy-loaded content to appear.
-
-**Step B — Collect all image URLs:**
-
-```javascript
-// Run via browser MCP evaluate()
-const allAssets = new Set();
-
-// 1. img tags — including srcset variants
-document.querySelectorAll('img').forEach(img => {
-  if (img.src) allAssets.add(img.src);
-  if (img.srcset) {
-    img.srcset.split(',').forEach(s => {
-      const url = s.trim().split(' ')[0];
-      if (url) allAssets.add(new URL(url, window.location.href).href);
-    });
-  }
-  if (img.dataset.src) allAssets.add(new URL(img.dataset.src, window.location.href).href);
-  if (img.dataset.srcset) {
-    img.dataset.srcset.split(',').forEach(s => {
-      const url = s.trim().split(' ')[0];
-      if (url) allAssets.add(new URL(url, window.location.href).href);
-    });
-  }
-});
-
-// 2. picture source elements
-document.querySelectorAll('picture source').forEach(s => {
-  if (s.srcset) {
-    s.srcset.split(',').forEach(src => {
-      const url = src.trim().split(' ')[0];
-      if (url) allAssets.add(new URL(url, window.location.href).href);
-    });
-  }
-});
-
-// 3. CSS background-image on ALL elements
-document.querySelectorAll('*').forEach(el => {
-  const bg = window.getComputedStyle(el).backgroundImage;
-  if (bg && bg !== 'none') {
-    const matches = bg.match(/url\(["']?([^"')]+)["']?\)/g) || [];
-    matches.forEach(m => {
-      const url = m.replace(/url\(["']?|["']?\)/g, '').trim();
-      if (url && !url.startsWith('data:')) allAssets.add(new URL(url, window.location.href).href);
-    });
-  }
-});
-
-// 4. video elements (poster + source)
-document.querySelectorAll('video').forEach(v => {
-  if (v.poster) allAssets.add(v.poster);
-  if (v.src && v.src !== window.location.href) allAssets.add(v.src);
-  v.querySelectorAll('source').forEach(s => {
-    if (s.src) allAssets.add(s.src);
-  });
-});
-
-// 5. SVG use references (external sprite files)
-document.querySelectorAll('use').forEach(u => {
-  const href = u.getAttribute('href') || u.getAttribute('xlink:href');
-  if (href && !href.startsWith('#')) {
-    allAssets.add(new URL(href.split('#')[0], window.location.href).href);
-  }
-});
-
-// 6. inline style background-image attributes
-document.querySelectorAll('[style]').forEach(el => {
-  const style = el.getAttribute('style') || '';
-  const matches = style.match(/url\(["']?([^"')]+)["']?\)/g) || [];
-  matches.forEach(m => {
-    const url = m.replace(/url\(["']?|["']?\)/g, '').trim();
-    if (url && !url.startsWith('data:')) allAssets.add(new URL(url, window.location.href).href);
-  });
-});
-
-// 7. og:image and twitter:image meta tags
-document.querySelectorAll('meta[property="og:image"], meta[name="twitter:image"]').forEach(m => {
-  const content = m.getAttribute('content');
-  if (content) allAssets.add(new URL(content, window.location.href).href);
-});
-
-return {
-  images: [...allAssets].filter(url => url.startsWith('http')),
-  fonts: [...document.querySelectorAll('link[rel=stylesheet]')]
-    .map(l => l.href)
-    .filter(h => h.includes('fonts') || h.includes('typekit') || h.includes('adobe'))
-};
-```
-
-Download all collected images to `public/images/<hostname>/`. Skip images > 2MB unless they are clearly structural (hero, logo, background). Preserve original filenames when possible; sanitize paths.
-
-**Download is mandatory in Modes A, B, C, E.** Do not skip it. The copyright notice below is informational only — it does not prevent the download.
-
-Skip download in **Mode D** (skill only) — record URLs but don't download.
-
-**Copyright / reference notice:** Tell the user after Phase 1:
-> "As imagens foram baixadas para `public/images/<hostname>/` e serão usadas como referência durante o desenvolvimento.
-> São arquivos temporários — substitua-os pelos seus próprios assets antes de publicar.
-> Você pode deletar a pasta `public/images/<hostname>/` a qualquer momento após substituir as imagens nos componentes."
-
-### 1.3 Font discovery
-
-Extract from `<link>` tags and `getComputedStyle()` on heading, body, and code elements:
-- Font families in use
-- Weights loaded
-- Where each is applied
-
-### 1.4 Internal link crawl (configurable)
-
-After the main page is fully captured, collect internal links:
-
-```javascript
-const hostname = window.location.hostname;
-const links = [...document.querySelectorAll('a[href]')]
-  .map(a => a.href)
-  .filter(href => {
-    try {
-      return new URL(href).hostname === hostname;
-    } catch { return false; }
-  });
-return [...new Set(links)];
-```
-
-**Default crawl behavior:**
-- **Mode B, D (faithful clone / skill forge):** Follow up to **5 internal links** to capture sub-pages, blog posts, or feature pages that may have additional design patterns.
-- **Mode A, C (content harvest):** Follow up to **10 internal links** — content and assets across the site are the primary goal.
-- **Mode E (blend):** Follow up to **5 internal links**.
-
-For each crawled sub-page: capture screenshots, run asset inventory (Step B above), note layout differences vs. main page.
-
-Save crawl manifest to `docs/research/<hostname>/crawl-manifest.json`:
-```json
-{
-  "mainUrl": "<url>",
-  "crawledUrls": ["<url1>", "<url2>"],
-  "assetsPerPage": { "<url>": ["<asset-path>", ...] }
-}
-```
-
-**If the user wants to skip sub-page crawl:** `--no-crawl` flag.
-
-### 1.5 Interaction sweep (CRITICAL — complete before Phase 2)
-
-Perform in this order:
-1. Slow scroll top→bottom: observe sticky headers, scroll-driven animations, parallax, lazy loads
-2. Click all interactive elements: tabs, dropdowns, modals, accordions, carousels
-3. Hover suspect elements: nav items, cards, buttons, tooltips
-4. Resize to 768px then 390px: observe nav collapses, layout reflows, hidden elements
-
-Document per section:
-- What triggers what (scroll position, click target, hover element)
-- What animates (which elements, which CSS properties change — type only, not values)
-- Which elements are sticky and at what scroll position they activate
-- Where layout changes at each viewport
-
-### 1.6 Page topology
-
-Map all sections top→bottom with a one-line description:
-```
-1. Header — sticky nav, logo left, links right, CTA button
-2. Hero — full-viewport, headline + subtitle + 2 CTAs, background gradient
-3. Features — 3-column card grid, icon + title + body each
-4. Pricing — 2-column comparison, monthly/annual toggle
-5. Footer — 4-column links, legal row
-```
-
-**Output:** `docs/research/<hostname>/reconnaissance.json`
-
-```json
-{
-  "url": "https://example.com",
-  "hostname": "example.com",
-  "screenshotsTaken": ["desktop", "tablet", "mobile"],
-  "fonts": [{ "family": "Inter", "weights": [400, 500, 600], "usedFor": "body" }],
-  "assetsDownloaded": ["hero.webp", "logo.svg"],
-  "crawledPages": ["<url>", "..."],
-  "interactionModel": {
-    "header": "scroll-driven shrink at 50px",
-    "featureTabs": "click-switch content",
-    "pricingToggle": "click-switch monthly/annual"
-  },
-  "pageTopology": ["Header", "Hero", "Features", "Pricing", "Footer"],
-  "breakpoints": { "tablet": 768, "mobile": 390 }
-}
-```
-
-**Exit criterion:** Screenshots captured at all viewports. Assets inventoried (all sources: img, background-image, srcset, video, SVG). Lazy loads triggered before extraction. Interaction model documented for every section. Page topology complete.
-
----
-
-## Phase 1.5 — Deep Animation & Video Extraction
-
-**Goal:** Extract the real animation machinery — CSS keyframes, JS animation libraries, video assets, and scroll-triggered DOM mutations. This phase transforms a visual clone into a behavioral clone.
-
-**All modes run this phase.** Skip only if `--no-deep` flag is set.
-
-### 1.5.1 Animation library detection
-
-Run immediately after Phase 1.1. The result determines which implementation strategy Phase 4.4 will use.
-
-```javascript
-return {
-  gsap:          typeof window.gsap !== 'undefined',
-  scrollTrigger: typeof window.ScrollTrigger !== 'undefined',
-  framerMotion:  !!document.querySelector('[data-framer-component-type]'),
-  aos:           typeof window.AOS !== 'undefined',
-  lottie:        typeof window.lottie !== 'undefined',
-  threejs:       typeof window.THREE !== 'undefined',
-  swiper:        typeof window.Swiper !== 'undefined',
-  motionOne:     typeof window.animate !== 'undefined' && !!window.animate?.toString?.().includes('motion'),
-};
-```
-
-Save result to `docs/research/<hostname>/animations-raw.json` under key `jsLibraries`.
-
-### 1.5.2 CSS animation rules extraction
-
-Extract all animatable CSS rules directly from loaded stylesheets — not computed values. This captures `@keyframes`, `animation-*`, `transition`, `transform`, `scroll-timeline`, and `will-change` rules that `getComputedStyle` never exposes.
-
-```javascript
-const animationRules = [];
-const keyframes = [];
-const scrollLinked = [];
-
-for (const sheet of document.styleSheets) {
-  try {
-    for (const rule of sheet.cssRules) {
-      const text = rule.cssText;
-
-      // @keyframes blocks
-      if (rule instanceof CSSKeyframesRule) {
-        keyframes.push({
-          name: rule.name,
-          cssText: text,
-          keyCount: rule.cssRules.length,
-        });
-        continue;
-      }
-
-      // Rules with animation or transition properties
-      if (
-        text.includes('animation') ||
-        text.includes('transition') ||
-        text.includes('transform') ||
-        text.includes('will-change') ||
-        text.includes('scroll-timeline') ||
-        text.includes('animation-timeline') ||
-        text.includes('view-timeline')
-      ) {
-        animationRules.push({
-          selector: rule.selectorText || rule.cssText.split('{')[0].trim(),
-          cssText: text,
-        });
-      }
-
-      // Scroll-linked animations (@scroll-timeline, animation-timeline: scroll())
-      if (
-        text.includes('scroll-timeline') ||
-        text.includes('animation-timeline') ||
-        text.includes('view-timeline') ||
-        text.includes('scroll()')
-      ) {
-        scrollLinked.push({
-          selector: rule.selectorText || rule.cssText.split('{')[0].trim(),
-          cssText: text,
-        });
-      }
-    }
-  } catch {
-    // Cross-origin stylesheets — skip silently
-  }
-}
-
-return { animationRules, keyframes, scrollLinked };
-```
-
-Save to `docs/research/<hostname>/animations-raw.json` under keys `animationRules`, `keyframes`, `scrollLinked`.
-
-**Also extract** computed animation properties on elements that are currently visible:
-
-```javascript
-const animated = [];
-document.querySelectorAll('*').forEach(el => {
-  const s = window.getComputedStyle(el);
-  if (
-    s.animationName !== 'none' ||
-    s.transition !== 'all 0s ease 0s' ||
-    s.transform !== 'none' ||
-    s.willChange !== 'auto'
-  ) {
-    animated.push({
-      selector: el.tagName + (el.id ? '#' + el.id : '') + (el.className ? '.' + [...el.classList].join('.') : ''),
-      animationName: s.animationName,
-      animationDuration: s.animationDuration,
-      animationTimingFunction: s.animationTimingFunction,
-      transition: s.transition,
-      transform: s.transform,
-      willChange: s.willChange,
-    });
-  }
-});
-return animated;
-```
-
-Save to `animations-raw.json` under key `activeAnimations`.
-
-### 1.5.3 Video extraction and download
-
-```javascript
-return [...document.querySelectorAll('video')].map(v => ({
-  sources: [...v.querySelectorAll('source')].map(s => ({
-    src: s.src,
-    type: s.type,
-  })),
-  src: v.src || null,
-  poster: v.poster || null,
-  autoplay: v.autoplay,
-  muted: v.muted,
-  loop: v.loop,
-  playsInline: v.playsInline,
-  width: v.offsetWidth,
-  height: v.offsetHeight,
-  role: v.closest('section')?.id || v.closest('[class]')?.className || 'unknown',
-}));
-```
-
-Save to `docs/research/<hostname>/videos.json`.
-
-**Download videos in Modes A, B, C, E:**
-- Download each video source to `public/videos/<hostname>/<role>.<ext>`
-- Skip files > 10MB — note URL in `videos.json` as `skipped: true` with reason
-- Prefer `video/webm` or `video/mp4` sources
-- Always download the poster image alongside the video
-
-**Skip download in Mode D** — record URLs only.
-
-**Copyright notice for videos (display once after this step):**
-> "Os vídeos foram baixados para `public/videos/<hostname>/` como referência de desenvolvimento.
-> São assets de terceiros — substitua-os pelos seus próprios vídeos antes de publicar."
-
-### 1.5.4 Scroll recording with DOM mutation tracking
-
-**Goal:** Capture exactly which elements change state at which scroll positions. This is the input for implementing scroll-triggered animations with precise fidelity.
-
-**Step A — Attach MutationObserver before scrolling:**
-
-```javascript
-const mutations = [];
-const mo = new MutationObserver(entries => {
-  for (const m of entries) {
-    if (
-      m.type === 'attributes' &&
-      (m.attributeName === 'class' || m.attributeName === 'style')
-    ) {
-      const el = m.target;
-      mutations.push({
-        scrollY: window.scrollY,
-        element: el.tagName +
-          (el.id ? '#' + el.id : '') +
-          (el.className && typeof el.className === 'string'
-            ? '.' + el.className.trim().replace(/\s+/g, '.') : ''),
-        attribute: m.attributeName,
-        from: m.oldValue,
-        to: el.getAttribute(m.attributeName),
-      });
-    }
-  }
-});
-mo.observe(document.body, {
-  subtree: true,
-  attributes: true,
-  attributeFilter: ['class', 'style'],
-  attributeOldValue: true,
-});
-// Expose mutations for later retrieval
-window.__sfMutations = mutations;
-```
-
-**Step B — Incremental scroll with screenshots at 8 checkpoints:**
-
-Scroll to each of the following positions, wait 600ms for animations to settle, then capture a screenshot:
-
-| Checkpoint | Scroll % | Purpose |
-|---|---|---|
-| `scroll-00pct` | 0% | Initial state |
-| `scroll-12pct` | 12% | Nav solidifies |
-| `scroll-25pct` | 25% | First section entry |
-| `scroll-37pct` | 37% | Second section |
-| `scroll-50pct` | 50% | Mid-page |
-| `scroll-62pct` | 62% | Third section |
-| `scroll-75pct` | 75% | Fourth section |
-| `scroll-100pct` | 100% | Footer |
-
-Save screenshots to `docs/research/<hostname>/scroll-recording/`.
-
-**Step C — Collect mutations:**
-
-```javascript
-return window.__sfMutations;
-```
-
-Save to `docs/research/<hostname>/dom-mutations.json`.
-
-**Step D — Analyze mutation patterns:**
-
-Group mutations by scroll position range and element. For each group, write a human-readable entry in `docs/research/<hostname>/interaction-spec.md` (append, do not overwrite) using this format:
-
-```markdown
-## Scroll-triggered: <element-selector>
-- **Trigger:** scrollY ≈ <N>px (≈ <pct>% of page height)
-- **Change:** class `<from>` → `<to>` (or style `<property>: <from>` → `<to>`)
-- **Effect type:** [REVEAL | HIDE | STATE-CHANGE | PARALLAX | STICKY]
-- **Implementation note:** <inferred mechanism — e.g. "IntersectionObserver adds .is-visible", "GSAP adds .animated class">
-```
-
-### 1.5.5 Parallax detection
-
-After scroll recording, check for elements whose `transform: translateY` changes relative to scroll progress:
-
-```javascript
-// Run at top, mid, and bottom of page — compare transform values
-const targets = document.querySelectorAll('[class*="parallax"], [data-parallax], [style*="transform"]');
-const results = [];
-for (const el of targets) {
-  const s = window.getComputedStyle(el);
-  results.push({
-    selector: el.className,
-    transformAtCurrentScroll: s.transform,
-    backgroundAttachment: s.backgroundAttachment, // "fixed" = CSS parallax
-  });
-}
-return results;
-```
-
-If `backgroundAttachment: fixed` is found → document as **CSS parallax** (implement with `background-attachment: fixed`).
-If `transform` changes between scroll positions → document as **JS parallax** (implement with scroll listener + `translate3d`).
-
-Save to `animations-raw.json` under key `parallax`.
-
-### 1.5.6 Output
-
-All data from this phase is consolidated into:
-
-```
-docs/research/<hostname>/
-├── animations-raw.json          ← jsLibraries, keyframes, animationRules, scrollLinked,
-│                                   activeAnimations, parallax
-├── videos.json                  ← video elements, sources, roles
-├── dom-mutations.json           ← class/style changes keyed by scrollY
-└── scroll-recording/
-    ├── scroll-00pct.png
-    ├── scroll-12pct.png
-    ├── scroll-25pct.png
-    ├── scroll-37pct.png
-    ├── scroll-50pct.png
-    ├── scroll-62pct.png
-    ├── scroll-75pct.png
-    └── scroll-100pct.png
-
-public/videos/<hostname>/
-└── [downloaded video assets — replace before publishing]
-```
-
-**Exit criterion:** `animations-raw.json` populated with `jsLibraries`, `keyframes`, and `activeAnimations`. `videos.json` written (empty array is valid if no videos found). `dom-mutations.json` written. Scroll recording screenshots saved. `interaction-spec.md` updated with scroll-triggered entries from mutation analysis.
-
----
-
-## Phase 2 — Selective Extraction
-
-**Goal:** Document structure and behavior of every section.
-
-**Mode A, C:** Discard ALL aesthetic values — skill tokens will replace them. Content slots (texts, image paths) are preserved.
-**Mode B, D, E:** Extract structure AND aesthetic values — they become the raw material for the skill or the blend.
-
-### 2.1 Section specs
-
-For each section in the page topology, create `docs/research/components/<section-slug>.spec.md`:
-
-```markdown
-# <SectionName> — Structure Specification
-
-## Layout pattern
-- Container: [max-width | full-viewport | fluid]
-- Display: [flex | grid | block]
-- Children arrangement: [column | row | grid-cols-3 | etc.]
-- Overflow: [visible | hidden | scroll]
-
-## Elements
-- [element-type]: [role — e.g. "primary headline", "CTA button", "feature image"]
-- [element-type]: [role]
-
-## Interaction model
-- Type: [NONE | SCROLL-DRIVEN | CLICK-DRIVEN | HOVER | STATE-TOGGLE]
-- Trigger: [describe the trigger precisely]
-- Effect: [describe what changes — element names and property types]
-- Timing: [fast | medium | slow — relative only]
-
-## Responsive changes
-- At 768px: [what changes]
-- At 390px: [what changes]
-
-## Content slots
-- Headline: "[actual text]"
-- Subtext: "[actual text]"
-- CTA label: "[actual text]"
-- Image: [what it depicts, path to downloaded file]
-
-## Aesthetic values (Modes B, D, E only — omit in Modes A, C)
-- Background color: [hex or rgba]
-- Text colors: [hex values per role: heading, body, muted, accent]
-- Border radius: [observed px values]
-- Shadow: [observed box-shadow values]
-- Padding/gap pattern: [observed px values]
-```
+## Phase execution
 
-### 2.2 Component inventory
+Load each phase doc at phase entry — not all at once.
 
-List all distinct reusable component types across the page:
-```
-Button: primary, secondary, ghost, icon-only
-Card: media-card, text-card, stat-card
-Input: text, email, textarea, select
-NavItem
-Modal
-Dropdown
-TabBar
-Accordion
-Toast
-Badge
-Avatar
-```
-
-For each component, create `docs/research/components/<component-slug>.spec.md`:
-
-```markdown
-# <ComponentName> — Component Specification
-
-## DOM structure
-- <outer-element> (semantic role)
-  - <child>: [role]
-  - <child>: [role]
-
-## Variants
-- [variant-name]: [how it differs structurally]
-
-## States
-- default: [what is shown]
-- hover: [what changes — type only for Mode A/C | type + value for Mode B/D/E]
-- active: [what changes]
-- disabled: [what changes]
-- loading: [what appears]
-
-## Behavior
-- [action]: [effect — describe mechanism, not values]
-```
-
-### 2.3 Interaction specifications
-
-For every non-static section, create `docs/research/<hostname>/interaction-spec.md`:
-
-```markdown
-# <Name> — Interaction Specification
-
-## Model: [SCROLL-DRIVEN | CLICK-DRIVEN | HOVER | STATE-TOGGLE]
-
-## Trigger
-[Precise trigger condition]
-
-## Effect
-[What changes: which elements, which CSS property types]
-
-## Timing
-[fast / medium / slow — relative only]
-
-## Implementation direction
-[e.g. "scroll listener on window", "CSS :hover + transition", "React state toggle + className"]
-```
-
-### 2.4 Aesthetic capture (Modes B, D, E only)
-
-Run this extraction via `window.getComputedStyle()` on representative elements:
-
-```javascript
-// Run via browser MCP evaluate()
-const elements = {
-  body: document.body,
-  h1: document.querySelector('h1'),
-  h2: document.querySelector('h2'),
-  p: document.querySelector('p'),
-  primaryBtn: document.querySelector('button, [class*="btn-primary"], [class*="cta"]'),
-  card: document.querySelector('[class*="card"], article'),
-  nav: document.querySelector('nav, header')
-};
-
-const extracted = {};
-for (const [name, el] of Object.entries(elements)) {
-  if (!el) continue;
-  const s = window.getComputedStyle(el);
-  extracted[name] = {
-    backgroundColor: s.backgroundColor,
-    color: s.color,
-    fontFamily: s.fontFamily,
-    fontSize: s.fontSize,
-    fontWeight: s.fontWeight,
-    lineHeight: s.lineHeight,
-    borderRadius: s.borderRadius,
-    boxShadow: s.boxShadow,
-    padding: s.padding,
-    gap: s.gap,
-    transition: s.transition
-  };
-}
-return extracted;
-```
-
-Save raw output to `docs/research/<hostname>/aesthetics-raw.json`.
-
-**Output files:**
-- `docs/research/<hostname>/structure-spec.md` (overview of all sections)
-- `docs/research/<hostname>/interaction-spec.md` (all interactions)
-- `docs/research/<hostname>/aesthetics-raw.json` (Modes B, D, E only)
-- `docs/research/components/*.spec.md` (one file per section + one per component type)
-
-**Exit criterion (Modes A, C):** Every section has a spec. No color, size, or spacing values in any spec file.
-**Exit criterion (Modes B, D, E):** Every section has a spec WITH aesthetic values. `aesthetics-raw.json` populated.
-
----
-
-## Phase 3A — Transform Layer (Modes A, C only)
-
-**Goal:** Map extracted structure to the existing skill's components and tokens.
-
-### 3A.1 Load the skill in full
-
-Read these files from the skill directory (`.aioson/installed-skills/<skill>/` or `.aioson/skills/design/<skill>/`):
-
-1. `SKILL.md` — identity, pillars, activation rules
-2. `references/design-tokens.md` — all CSS variables (colors, type scale, spacing, radius, shadow, motion)
-3. `references/components.md` — available components and their props/variants
-4. `references/patterns.md` — page layout patterns
-5. `references/motion.md` — animation tokens and conventions
-6. `references/websites.md` — if present, landing page patterns
-
-### 3A.2 Build the component map
-
-For every extracted element, find the closest skill equivalent. Create `docs/research/<hostname>/component-map.md`:
-
-```markdown
-# Component Map — <hostname> → <skill-name>
-
-## Mappings
-
-| Extracted element | Skill component | Key tokens to apply |
-|---|---|---|
-| Hero container | Hero pattern (from patterns.md) | --max-width, --space-XX |
-| Feature card grid | Card grid pattern | gap: --space-XX |
-| Primary CTA button | Button primary | bg: --accent, radius: --radius-md |
-| Ghost/outline button | Button ghost | border: 1px solid --border |
-| H1 display heading | Display heading | font: --font-display, size: --text-5xl |
-| Body paragraph | Body text | font: --font-body, size: --text-base |
-| Muted caption | Muted text | color: --text-muted |
-| Sticky nav | Header pattern | bg: --bg-surface, shadow: --shadow-sm on scroll |
-| Card hover | Card component | transform: translateY(var(--hover-lift)) |
-| Scroll interaction timing | — | var(--transition-base) |
-
-## Deviations (skill component not available)
-
-| Extracted element | Fallback approach | Reason |
-|---|---|---|
-| [element not in skill] | [closest skill primitive + manual CSS vars] | [why no direct match] |
-
-## Assets preserved
-
-| Original source | Local path | Action required before publishing |
-|---|---|---|
-| hero image | public/images/<hostname>/hero.webp | Replace with project asset |
-| logo | public/images/<hostname>/logo.svg | Replace with project logo |
-```
-
-**Mode C (content-first):** In the component map, add a "Content slot" column that maps each skill component to the specific extracted text and image asset. This ensures the harvested content lands in the right place during Phase 4.
-
-### 3A.3 Universal token substitution rules
-
-Apply these mappings everywhere during Phase 4:
-
-```
-background-color: <hex>   →  var(--bg-surface) | var(--bg-elevated) | var(--accent)
-color: <hex>              →  var(--text-primary) | var(--text-muted) | var(--accent)
-padding: <px>             →  var(--space-XX) — pick nearest from spacing scale
-margin: <px>              →  var(--space-XX)
-animation-duration: <ms>  →  var(--transition-fast) | var(--transition-base) | var(--transition-medium) | var(--transition-slow)
-font-size: <px>           →  var(--text-XX) — pick nearest from type scale
-font-family: <name>       →  var(--font-display) | var(--font-body) | var(--font-mono)
-border-radius: <px>       →  var(--radius-sm) | var(--radius-md) | var(--radius-lg)
-box-shadow: <value>       →  var(--shadow-sm) | var(--shadow-md) | var(--shadow-lg)
-transition: <value>       →  var(--transition-fast) | var(--transition-base) | var(--transition-slow)
-```
-
-If a token name from the above doesn't exist in the skill, use the closest equivalent from `design-tokens.md`. Never hardcode values.
-
-### 3A.4 Interaction preservation rule
-
-Keep the trigger mechanism. Keep the effect type. Replace only easing/duration with skill motion tokens.
-
-**Exit criterion (Modes A, C):** Every extracted component has a mapping row. Every interaction has a motion token assigned. Proceed to Phase 4.
+| Phase | What | Doc to load |
+|-------|------|-------------|
+| 1 + 1.5 | Reconnaissance + Deep Animation Extraction | `.aioson/docs/site-forge-recon.md` |
+| 2 | Selective Extraction | `.aioson/docs/site-forge-extraction.md` |
+| 3A | Transform Layer (Modes A, C) | `.aioson/docs/site-forge-transform.md` |
+| 3B | Skill Forge (Modes B, D, E) | `.aioson/docs/site-forge-transform.md` |
+| 3E | Blend Layer (Mode E) | `.aioson/docs/site-forge-transform.md` |
+| 4 | Build Layer | `.aioson/docs/site-forge-build.md` |
+| 5 + Output contract | Visual QA | `.aioson/docs/site-forge-qa.md` |
 
 ---
 
-## Phase 3B — Design Extraction + Skill Forge (Modes B, D, E)
-
-**Goal:** Extract the site's design system from raw aesthetics and forge a new AIOSON skill.
-
-### 3B.1 Color system extraction
-
-From `aesthetics-raw.json`, organize colors into semantic groups:
-
-```
-Background hierarchy:
-  --bg-base      → page background (body.backgroundColor)
-  --bg-surface   → card/panel backgrounds (card.backgroundColor)
-  --bg-elevated  → modal/dropdown backgrounds
-  --bg-inverse   → inverted section backgrounds
-
-Text hierarchy:
-  --text-primary → primary text (p.color or h1.color)
-  --text-muted   → secondary/muted text
-  --text-inverse → text on dark backgrounds
-
-Brand colors:
-  --accent       → primary CTA color (primaryBtn.backgroundColor)
-  --accent-hover → hover state of CTA
-  --border       → default border color
-
-Semantic (infer from context if present):
-  --success, --warning, --error, --info
-```
-
-Consolidate duplicate/near-duplicate colors (within 10% perceptual distance) into a single token.
-
-### 3B.2 Typography system extraction
-
-```
-Font families:
-  --font-display → h1/h2 fontFamily
-  --font-body    → p fontFamily
-  --font-mono    → code/pre fontFamily (if detected)
-
-Type scale (map observed px values to a named scale):
-  --text-xs   → smallest observed size
-  --text-sm   → ...
-  --text-base → body text size (p.fontSize)
-  --text-lg   → ...
-  --text-xl   → ...
-  --text-2xl  → ...
-  --text-3xl  → ...
-  --text-4xl  → ...
-  --text-5xl  → largest heading (h1.fontSize)
-
-Weight scale:
-  --font-normal   → 400
-  --font-medium   → 500
-  --font-semibold → 600
-  --font-bold     → 700
-  (include only weights actually in use)
-
-Line heights:
-  --leading-tight  → heading line-height
-  --leading-normal → body line-height
-  --leading-relaxed → long-form text line-height (if detected)
-```
-
-### 3B.3 Spacing system extraction
-
-Identify the base spacing unit from observed padding/gap patterns:
-- Collect all observed padding and gap values
-- Find the GCD or most common divisor → this is the base unit (typically 4px or 8px)
-- Build a scale:
-
-```
---space-1  → 1× base
---space-2  → 2× base
---space-3  → 3× base
---space-4  → 4× base
---space-6  → 6× base
---space-8  → 8× base
---space-12 → 12× base
---space-16 → 16× base
---space-20 → 20× base
---space-24 → 24× base
-```
-
-### 3B.4 Visual primitives extraction
-
-```
-Border radius:
-  --radius-none → 0
-  --radius-sm   → smallest observed radius
-  --radius-md   → medium (cards)
-  --radius-lg   → large (modals, hero blocks)
-  --radius-full → 9999px (pills/avatars, if used)
-
-Shadows (from observed box-shadow values):
-  --shadow-sm  → subtle (e.g. cards at rest)
-  --shadow-md  → medium (e.g. dropdowns)
-  --shadow-lg  → strong (e.g. modals)
-  --shadow-xl  → extra strong (if present)
-
-Motion:
-  --transition-fast → fastest observed transition duration (e.g. 100ms)
-  --transition-base → most common duration (e.g. 200ms)
-  --transition-slow → slowest (e.g. 400ms+)
-  --ease-default    → most common easing (e.g. ease-out)
-  --ease-spring     → spring/bounce easing (if detected)
-```
-
-### 3B.5 Visual identity synthesis
-
-Based on the extracted values, define 3 design pillars that describe this site's aesthetic.
-
-Examples:
-- "Minimal contrast" + "Typographic hierarchy" + "Generous whitespace"
-- "Deep darkness" + "Glowing accents" + "Crisp borders"
-- "Warm organics" + "Rounded surfaces" + "Soft motion"
-
-Also determine:
-- Theme: `light` | `dark` | `system`
-- Personality: 1-sentence description (e.g. "Bold editorial with a monochromatic palette and strong typographic rhythm")
-
-### 3B.6 Pick reference skill structure
-
-List all skills in `.aioson/skills/design/`. Choose the one whose visual personality most closely matches the extracted site (dark → aurora-command-ui or premium-command-center-ui; minimal light → clean-saas-ui; data-dense → cognitive-core-ui; etc.).
-
-Read the chosen skill's directory listing to understand its file structure.
-**Use only the FILE STRUCTURE as a template — do not copy any tokens or design values.**
-
-### 3B.7 Forge the new skill
-
-Create `.aioson/installed-skills/<hostname>/` with this structure:
-
-**`SKILL.md`:**
-```markdown
-# <hostname> Design System
-
-> Extracted from <url> on <date>. Visual clone skill — do not use in unrelated projects without adapting the tokens.
-
-## Identity
-
-**Theme:** <light|dark|system>
-**Personality:** <1-sentence description>
-
-## Design pillars
-
-1. <pillar 1>
-2. <pillar 2>
-3. <pillar 3>
-
-## When to use
-
-Activate when building projects that need to visually match or be inspired by <hostname>'s aesthetic.
-
-## Activation
-
-Load `references/design-tokens.md` before writing any component.
-```
-
-**`references/design-tokens.md`:**
-Full CSS custom properties using all tokens extracted in 3B.1–3B.4:
-```css
-:root {
-  /* Colors */
-  --bg-base: <extracted hex>;
-  --bg-surface: <extracted hex>;
-  /* ... all color tokens ... */
-
-  /* Typography */
-  --font-display: '<family>', sans-serif;
-  --font-body: '<family>', sans-serif;
-  /* ... all type tokens ... */
-
-  /* Spacing */
-  --space-1: <Npx>;
-  /* ... full scale ... */
-
-  /* Radius */
-  --radius-sm: <px>;
-  /* ... */
-
-  /* Shadow */
-  --shadow-sm: <value>;
-  /* ... */
-
-  /* Motion */
-  --transition-fast: <ms> <easing>;
-  --transition-base: <ms> <easing>;
-  --transition-slow: <ms> <easing>;
-}
-```
-
-**`references/components.md`:**
-Document component variants derived from the site's component inventory (from Phase 2.2). For each component: DOM structure, props, variants, token usage.
-
-**`references/patterns.md`:**
-Document page layout patterns derived from the site's section specs (from Phase 2.1). Include: Hero, Feature grid, Card layout, Nav, Footer.
-
-**`references/motion.md`:**
-Document animation tokens and the interaction patterns extracted from Phase 2.3 and 2.4.
-
-Also include all data from Phase 1.5:
-- `jsLibraries` detected — list which animation libraries the original site used
-- All `@keyframes` from `animations-raw.json.keyframes` — copy verbatim as a "Extracted Keyframes" section
-- `parallax` entries — document technique (CSS fixed vs JS transform)
-- `scrollLinked` CSS rules — document `animation-timeline` and `scroll-timeline` usage
-- Scroll-trigger thresholds from `dom-mutations.json` — document as a table: element → scrollY trigger → effect
-
-This makes `motion.md` a complete behavioral reference for recreating the site's animation character, not just its timing tokens.
-
-**`references/websites.md`:**
-Document this specific site's landing page structure as a reusable pattern. Include the full page topology and how sections connect.
-
-**`.skill-meta.json`:**
-```json
-{
-  "id": "<hostname>",
-  "name": "<hostname> Design System",
-  "source": "<url>",
-  "extractedAt": "<ISO date>",
-  "theme": "<light|dark|system>",
-  "baseUnit": "<Npx>",
-  "referenceSkill": "<chosen template skill id>",
-  "type": "extracted"
-}
-```
-
-**Exit criterion (Modes B, D):** All skill files written. `design-tokens.md` contains the full `:root {}` block. Component and pattern references derived from the site's own inventory.
-
-**Mode D exits here.** Output the path to the forged skill and run observability. Do NOT proceed to Phase 4.
-
-**Mode B and E:** Proceed to Phase 4 using the newly forged skill (Mode B) or the blend layer (Mode E).
-
----
-
-## Phase 3E — Blend Layer (Mode E only)
-
-**Goal:** Merge the extracted site tokens with the existing skill's tokens at the configured ratio.
-
-### 3E.1 Define the blend map
-
-Default blend: 50% site / 50% skill. If the user specified a different ratio, use that.
-
-Load both token sets:
-- Site tokens: from `docs/research/<hostname>/aesthetics-raw.json` + Phase 3B extraction
-- Skill tokens: from the named skill's `references/design-tokens.md`
-
-### 3E.2 Apply blend rules per token category
-
-Create `docs/research/<hostname>/blend-map.md`:
-
-```markdown
-# Blend Map — <hostname> (site) × <skill-name> (skill) — <ratio>% site / <100-ratio>% skill
-
-## Color tokens
-| Token | Site value | Skill value | Blended result | Source |
-|---|---|---|---|---|
-| --bg-base | #1a1a1a | #0f0f0f | #141414 | averaged |
-| --accent | #e63946 | #7c3aed | #e63946 | site (brand identity) |
-
-## Typography tokens
-| Token | Site value | Skill value | Blended result | Source |
-|---|---|---|---|---|
-| --font-display | 'Playfair Display' | 'Inter' | 'Playfair Display' | site |
-| --font-body | 'Lato' | 'Inter' | 'Inter' | skill |
-
-## Spacing tokens
-→ Use site spacing scale when ratio ≥ 50% site; use skill scale otherwise.
-
-## Motion tokens
-→ Use site motion when ratio ≥ 50% site; use skill motion otherwise.
-
-## Blend decisions
-- Primary font family: [site | skill | averaged] — reason
-- Accent color: [site | skill | averaged] — reason
-- Border radius style: [site | skill | averaged] — reason
-```
-
-**Blend rules:**
-- **Colors:** Average HSL values for neutral tokens (backgrounds, text). For accent/brand colors, prefer the site source (brand identity should be preserved from the site).
-- **Typography:** If ratio ≥ 50% site → use site display font; always blend body font toward the skill's body font for readability.
-- **Spacing:** Use the scale from whichever source matches the ratio.
-- **Motion:** Use the easing/duration from whichever source matches the ratio.
-
-### 3E.3 Write blended token file
-
-Write `docs/research/<hostname>/blended-tokens.css` with all resolved `:root` values.
-
-**Exit criterion (Mode E):** `blend-map.md` complete with all token decisions documented. `blended-tokens.css` ready. Proceed to Phase 4.
-
----
-
-## Phase 4 — Build Layer
-
-**Goal:** Implement all sections and components.
-
-In **Mode A:** use the existing skill tokens from `references/design-tokens.md`.
-In **Mode B:** use the newly forged skill from Phase 3B.
-In **Mode C:** use the existing skill tokens; slot extracted content/images from the component map.
-In **Mode E:** use `blended-tokens.css` from Phase 3E as the `:root` definition.
-
-### 4.1 Complexity budget
-
-Assess each section:
-- **Simple** (< 3 sub-components): implement directly
-- **Moderate** (3–5 sub-components): one worktree builder
-- **Complex** (> 5 sub-components): split across multiple builders
-
-### 4.2 Direct implementation (simple sections)
-
-Build the component inline. Use skill tokens. Reference the section spec and component map. Verify `npx tsc --noEmit` after each file.
-
-### 4.3 Worktree builders (moderate/complex sections)
-
-Create one worktree per section batch:
-
-```
-git worktree add ../worktree-<section> -b builder/<section>
-```
-
-Each builder receives:
-1. The section spec file (inline in the builder prompt)
-2. Component map rows relevant to this section (inline)
-3. Key tokens from the active token file (inline — include only what is needed)
-4. Path to screenshots for visual reference
-5. Target file: `src/components/<SectionName>.tsx`
-6. Requirement: `npx tsc --noEmit` must pass before committing
-
-After builder completes:
-```bash
-npx tsc --noEmit   # must pass
-git add -A && git commit -m "build(<section>): implement with <skill-name> tokens"
-```
-
-Then merge back:
-```bash
-git worktree remove ../worktree-<section>
-git merge builder/<section> --no-ff -m "merge: <section> builder"
-```
-
-Conflict resolution rule: structure wins — preserve DOM hierarchy from the spec; replace any style value with the skill token.
-
-### 4.4 Interaction implementation (MANDATORY — do not skip)
-
-Before assembly, read `docs/research/<hostname>/animations-raw.json` → `jsLibraries` and `dom-mutations.json`. These determine both the implementation strategy and the precise trigger conditions.
-
-#### 4.4.A Implementation strategy routing
-
-**Step 1 — Choose the animation layer based on detected libraries:**
-
-| Detected | Install | Implementation strategy |
-|---|---|---|
-| `gsap: true` | `npm install gsap` | Use GSAP + ScrollTrigger for all scroll-driven animations |
-| `framerMotion: true` | `npm install framer-motion` | Use `<motion.div>` with `whileInView` / `useScroll` |
-| `swiper: true` | `npm install swiper` | Use Swiper React for carousels/sliders |
-| `lottie: true` | `npm install lottie-react` | Use `<Lottie>` for SVG animations |
-| `aos: true` | *(no install — implement natively)* | Use `IntersectionObserver` + CSS classes |
-| none detected | *(no install)* | Use `IntersectionObserver` + CSS `@keyframes` |
-
-Multiple libraries may be active simultaneously — install all that are detected.
-
-**Step 2 — Implement scroll-driven animations using `dom-mutations.json`:**
-
-For each entry in `dom-mutations.json`:
-
-```typescript
-// Example: element adds class "is-animated" at scrollY ≈ 1200px
-// → implement as GSAP ScrollTrigger:
-gsap.from('.hero__headline', {
-  opacity: 0,
-  y: 20,
-  duration: 0.4,
-  ease: 'power2.out',
-  scrollTrigger: {
-    trigger: '.hero__headline',
-    start: 'top 80%',   // derived from mutation scrollY / pageHeight
-    once: true,
-  },
-});
-
-// → OR as IntersectionObserver (when no GSAP):
-const observer = new IntersectionObserver(entries => {
-  entries.forEach(e => {
-    if (e.isIntersecting) e.target.classList.add('is-animated');
-  });
-}, { threshold: 0.15 });
-document.querySelectorAll('.animate-on-scroll').forEach(el => observer.observe(el));
-```
-
-Use the `scrollY` values from `dom-mutations.json` to calibrate `start` offsets in ScrollTrigger, or `threshold` values in IntersectionObserver.
-
-**Step 3 — Recreate CSS `@keyframes` from `animations-raw.json`:**
-
-For each entry in `animations-raw.json.keyframes`:
-- Copy the `cssText` verbatim into `src/app/globals.css`
-- Update any hardcoded `ms` or `s` values to reference the closest skill motion token:
-  ```css
-  /* Original extracted */
-  @keyframes fadeSlideUp {
-    from { opacity: 0; transform: translateY(20px); }
-    to   { opacity: 1; transform: translateY(0); }
-  }
-
-  /* In globals.css — duration applied via class, not in keyframe */
-  @keyframes fadeSlideUp {
-    from { opacity: 0; transform: translateY(20px); }
-    to   { opacity: 1; transform: translateY(0); }
-  }
-  .animate-fade-slide-up {
-    animation: fadeSlideUp var(--transition-slow) var(--ease-out) forwards;
-  }
-  ```
-
-**Step 4 — Implement parallax from `animations-raw.json.parallax`:**
-
-- **CSS parallax** (`backgroundAttachment: fixed`): Apply `background-attachment: fixed` directly — no JS needed.
-- **JS parallax** (transform changes between scroll positions):
-  ```typescript
-  // useParallax hook
-  useEffect(() => {
-    const el = ref.current;
-    const handleScroll = () => {
-      const scrolled = window.scrollY;
-      const rate = 0.4; // adjust to match observed translation ratio
-      el.style.transform = `translate3d(0, ${scrolled * rate}px, 0)`;
-    };
-    window.addEventListener('scroll', handleScroll, { passive: true });
-    return () => window.removeEventListener('scroll', handleScroll);
-  }, []);
-  ```
-
-**Step 5 — Implement remaining interactions from `interaction-spec.md`:**
-
-For entries NOT covered by scroll-recording mutations (hover, click, state-toggle):
-
-- **SCROLL-DRIVEN without mutation data:** use `IntersectionObserver` with `threshold: 0.1`.
-- **CLICK-DRIVEN:** use React `useState` toggle + conditional className.
-- **HOVER:** use Tailwind hover variants or CSS `:hover` + `transition: var(--transition-all)`.
-- **STATE-TOGGLE:** use React `useState` + conditional className.
-
-Use motion tokens from the active skill for all `transition` and `animation-duration` values. Never hardcode `ms` values.
-
-**This step is not optional.** Every interaction in the spec must be implemented before moving to assembly. If an interaction is too complex to implement completely, implement a simplified version and note it in the QA report as ⚠️ — but do not leave it unimplemented.
-
-#### 4.4.B Video background implementation (MANDATORY when videos.json is non-empty)
-
-For each entry in `docs/research/<hostname>/videos.json`:
-
-**If downloaded** (`skipped: false`):
-```tsx
-// VideoBackground.tsx
-export function VideoBackground({ role }: { role: string }) {
-  return (
-    <div className="absolute inset-0 overflow-hidden" aria-hidden="true">
-      <video
-        autoPlay
-        muted
-        loop
-        playsInline
-        poster={`/images/<hostname>/${role}-poster.jpg`}
-        className="w-full h-full object-cover"
-        style={{ willChange: 'transform' }}
-      >
-        <source src={`/videos/<hostname>/${role}.webm`} type="video/webm" />
-        <source src={`/videos/<hostname>/${role}.mp4`} type="video/mp4" />
-        {/* Poster fallback rendered by browser if video fails */}
-      </video>
-      {/* Overlay — use skill token */}
-      <div className="absolute inset-0" style={{ backgroundColor: 'var(--overlay-dark)' }} />
-    </div>
-  );
-}
-```
-
-**If skipped** (file > 10MB or blocked): use the poster image as a `background-image` and note it in the QA report as ⚠️ with the original video URL.
-
-Always render the video **behind** the section content (`z-index: 0` on video, `z-index: 1` on content).
-Always include the overlay div to maintain text readability.
-Always add `prefers-reduced-motion` support:
-```css
-@media (prefers-reduced-motion: reduce) {
-  video[autoplay] { display: none; }
-  /* Poster image via background-image on the container */
-}
-```
-
-### 4.5 Asset wiring (MANDATORY — do not skip)
-
-Before assembly, verify that every downloaded image is referenced in its component:
-
-For each section component:
-- Check `docs/research/components/<section-slug>.spec.md` → "Content slots" → Image entries.
-- In the component file, use `next/image` with `src="/images/<hostname>/<filename>"`.
-- Do not use placeholder SVGs or empty `src` attributes when a downloaded asset exists.
-
-```tsx
-// Correct — use the downloaded asset
-import Image from 'next/image'
-<Image src="/images/<hostname>/hero.webp" alt="hero" fill className="object-cover" />
-
-// Wrong — placeholder when asset exists
-<div className="bg-gray-200 w-full h-64" />
-```
-
-If an image was not downloaded (> 2MB or blocked), use a placeholder and note it in the QA report as ⚠️ with the original URL.
-
-**Asset lifecycle note for the user (display once before assembly):**
-> "As imagens em `public/images/<hostname>/` são referências de desenvolvimento.
-> Substitua-as pelos seus próprios assets antes de publicar e delete a pasta quando não precisar mais delas."
-
-### 4.6 Assembly
-
-After interactions and assets are wired:
-1. Create `src/app/page.tsx` importing and rendering all sections in page topology order
-2. Apply the active CSS token root in `src/app/globals.css` or equivalent:
-   - **Modes A, B, C:** paste the skill's `:root {}` block
-   - **Mode E:** paste `blended-tokens.css` content
-3. Run `npm run build` — must pass with 0 errors and 0 TypeScript errors
-
-If build fails: fix TypeScript errors first, then CSS token resolution. Do not proceed to Phase 5 with a broken build.
-
-**Exit criterion:** `npm run build` passes. All sections rendered. All interactions from interaction-spec.md implemented. All downloaded assets referenced in components. Skill tokens active globally.
-
----
-
-## Phase 5 — Visual QA
-
-**Goal:** Verify the clone behaves like the original and looks like the skill.
-
-### 5.1 Start dev server
-
-```bash
-npm run dev
-# Confirm "ready" appears before continuing — wait up to 30s
-```
-
-### 5.2 Screenshot comparison
-
-Using browser MCP, capture both at 1440px, 768px, and 390px:
-- Original: target URL
-- Clone: `http://localhost:3000`
-
-**Mode A, C:** Acceptable differences: colors, fonts, spacing (intentional replacement). Unacceptable: missing sections, broken layout, missing interactive elements, missing content.
-**Mode B:** The clone should visually resemble the original. Large color/font differences are a signal the extraction missed something — investigate before passing.
-**Mode E:** The blend should be visible — neither a pure copy of the original nor a pure skill application. If it looks identical to either source, the blend was not applied.
-
-### 5.3 Interaction testing
-
-For each interaction in the interaction spec:
-- Scroll triggers: does the effect fire at the right position?
-- Click triggers: do tabs, dropdowns, modals, toggles work?
-- Hover triggers: do cards lift, nav items change state?
-- Responsive: do breakpoints trigger the correct layout changes?
-
-### 5.4 Skill fidelity check
-
-Verify the active token set is applied:
-- Are CSS variables resolving (no fallbacks to browser defaults)?
-- Are motion tokens used (no hardcoded `ms` values in components)?
-- **Mode A, C:** Are skill colors used (not original site colors)?
-- **Mode B:** Are the extracted site colors reproduced accurately?
-- **Mode E:** Are blended values present (verify at least 3 tokens from each source)?
-
-### 5.5 QA report
-
-Create `docs/research/<hostname>/qa-report.md`:
-
-```markdown
-# QA Report — <hostname> → <skill-name>
-**Mode:** [A | B | C | D | E]
-**Date:** [date]
-**Build status:** passing
-
-## Structural fidelity
-✅/⚠️/❌ [Section]: [note]
-
-## Content slots (Modes C, E)
-✅/⚠️/❌ [Section]: extracted text/images present
-
-## Interactions
-✅/⚠️/❌ [Interaction name]: [status and note]
-
-## Skill fidelity
-✅/⚠️/❌ Colors: tokens applied / hardcoded values remain
-✅/⚠️/❌ Typography: skill fonts active
-✅/⚠️/❌ Spacing: scale tokens applied
-✅/⚠️/❌ Motion: transition tokens applied
-
-## Blend verification (Mode E only)
-✅/⚠️/❌ Site tokens present: [list 3 examples]
-✅/⚠️/❌ Skill tokens present: [list 3 examples]
-
-## Issues to fix
-1. [issue description] → [fix]
-
-## Known deviations (acceptable ⚠️)
-- [deviation]: [reason it is acceptable]
-```
-
-Fix all ❌ issues before closing. Fewer than 5 ⚠️ issues required to pass.
-
-**Exit criterion:** Zero ❌ issues. Fewer than 5 ⚠️ issues. All interactions in the interaction spec are working.
-
----
-
-## Output contract
-
-**Modes A, B, C, E (builds a site):**
-```
-docs/research/<hostname>/
-├── reconnaissance.json
-├── crawl-manifest.json
-├── structure-spec.md
-├── interaction-spec.md          ← updated with scroll-triggered entries from Phase 1.5.4
-├── animations-raw.json          ← jsLibraries, keyframes, animationRules, parallax (Phase 1.5)
-├── videos.json                  ← video elements and sources (Phase 1.5)
-├── dom-mutations.json           ← class/style changes by scrollY (Phase 1.5)
-├── component-map.md             (Modes A, C)
-├── blend-map.md                 (Mode E only)
-├── blended-tokens.css           (Mode E only)
-└── qa-report.md
-
-docs/research/<hostname>/scroll-recording/
-├── scroll-00pct.png             ← 8 scroll position screenshots (Phase 1.5)
-├── scroll-12pct.png
-├── scroll-25pct.png
-├── scroll-37pct.png
-├── scroll-50pct.png
-├── scroll-62pct.png
-├── scroll-75pct.png
-└── scroll-100pct.png
-
-docs/research/components/
-└── <section-slug>.spec.md  (one per section)
-└── <component-slug>.spec.md (one per component type)
-
-public/images/<hostname>/
-└── [downloaded image assets — replace before publishing]
-
-public/videos/<hostname>/
-└── [downloaded video assets — replace before publishing]  (Phase 1.5.3)
-
-src/components/
-└── [all section components — TypeScript, skill tokens only]
-└── VideoBackground.tsx          ← if any videos found (Phase 4.4.B)
-
-src/app/
-├── page.tsx   [assembled page]
-└── globals.css  [skill token root + extracted @keyframes applied]
-```
-
-**Mode B additionally:**
-```
-docs/research/<hostname>/
-└── aesthetics-raw.json
-
-.aioson/installed-skills/<hostname>/
-├── SKILL.md
-├── references/
-│   ├── design-tokens.md
-│   ├── components.md
-│   ├── patterns.md
-│   ├── motion.md          ← includes extracted @keyframes and detected animation libraries
-│   └── websites.md
-└── .skill-meta.json
-```
+## Hard constraints
 
-**Mode D (skill only — no site built):**
-```
-docs/research/<hostname>/
-├── reconnaissance.json
-├── crawl-manifest.json
-├── structure-spec.md
-├── interaction-spec.md
-├── animations-raw.json
-├── videos.json
-├── dom-mutations.json
-└── aesthetics-raw.json
-
-.aioson/installed-skills/<hostname>/
-├── SKILL.md
-├── references/
-│   ├── design-tokens.md
-│   ├── components.md
-│   ├── patterns.md
-│   ├── motion.md
-│   └── websites.md
-└── .skill-meta.json
-```
+- Never start Phase 1 without browser MCP confirmed available.
+- Never start Phase 2 with an incomplete interaction sweep or without Phase 1.5 complete (unless `--no-deep` flag).
+- **Modes A, C:** Never start Phase 4 without complete `component-map.md` from Phase 3A.
+- **Mode B:** Never start Phase 4 without all skill files written in Phase 3B.
+- **Mode D:** Never proceed to Phase 4 — session ends after Phase 3B.
+- **Mode E:** Never start Phase 4 without `blend-map.md` and `blended-tokens.css` from Phase 3E.
+- Never start Phase 5 without `npm run build` passing, all interactions implemented (4.4), all videos wired (4.4.B), and all downloaded assets referenced in components (4.5).
+- Never hardcode color, font size, spacing, radius, shadow, or animation duration — use skill tokens only.
+- Phase 4.4: always read `animations-raw.json.jsLibraries` before choosing animation implementation strategy. Never default to `IntersectionObserver` if GSAP or Framer Motion was detected.
+- Phase 4.4: always copy extracted `@keyframes` from `animations-raw.json` into `globals.css` verbatim. Never write animation values from memory.
+- Phase 4.4.B: never leave a video as a placeholder `<div>` when `videos.json` has a non-skipped entry.
+- **Modes A, C:** Do not replicate the original site's aesthetic — aesthetic replacement is the mission. Animation mechanics preserved; design tokens replaced.
+- **Mode B:** Every token must trace back to an extracted value. Do not invent tokens.
+- **Mode E:** Blend map must contain tokens from both sources — pure copy or pure skill application is a blend failure.
+- Phase 1.2: always trigger lazy loads before asset extraction.
+- Phase 1.5.4: always attach MutationObserver BEFORE starting scroll recording.
+- Always warn the user about copyright on downloaded assets, videos, and extracted text.
 
 ---
 
 ## Activation triggers
 
 ```
-/site-forge <url> <skill-name>          → Mode A: clone + apply existing skill
+/site-forge <url> <skill-name>          → Mode A
 /site-forge <url>                       → Onboarding questionnaire
-/site-forge <url> --skill-only          → Mode D: skill forge only
-/site-forge <url> <skill> --blend       → Mode E: 50/50 blend (default ratio)
-/site-forge <url> <skill> --blend=70    → Mode E: 70% site / 30% skill
-
-"clone this site with [skill]"
-"make a copy of [url] with [design skill]"
-"rebuild [url] using [skill]"
-"[url] in the style of [skill]"
-"clone [url] and extract its design system"
-"clone [url] without a skill"
-"copy [url] as-is"
-"extract the design from [url] as a skill"
-"create a skill from [url]"
-"I want only the skill from [url]"
-"clone [url] and mix it with [skill]"
-"blend [url] with [skill] 50/50"
-"quero só as imagens e conteúdo de [url] para usar com [skill]"
-"quero criar uma skill do [url]"
-"quero clonar [url] e mesclar com [skill]"
-```
-
-Flags:
-```
---viewport=desktop     # desktop screenshots only (default: all three)
+/site-forge <url> --skill-only          → Mode D
+/site-forge <url> <skill> --blend       → Mode E (50/50 default)
+/site-forge <url> <skill> --blend=70    → Mode E (70% site / 30% skill)
+
+"clone this site with [skill]"          → Mode A
+"make a copy of [url] with [skill]"     → Mode A
+"rebuild [url] using [skill]"           → Mode A
+"[url] in the style of [skill]"         → Mode A
+"clone [url] and extract its design system" → Mode B
+"clone [url] without a skill"           → Mode B
+"copy [url] as-is"                      → Mode B
+"extract the design from [url] as a skill" → Mode D
+"create a skill from [url]"             → Mode D
+"I want only the skill from [url]"      → Mode D
+"clone [url] and mix it with [skill]"   → Mode E
+"blend [url] with [skill] 50/50"        → Mode E
+"quero só as imagens e conteúdo de [url] para usar com [skill]" → Mode C
+"quero criar uma skill do [url]"        → Mode D
+"quero clonar [url] e mesclar com [skill]" → Mode E
+```
+
+**Flags:**
+```
+--viewport=desktop     # desktop screenshots only
 --no-download          # skip asset download
 --no-crawl             # skip internal link crawl
---no-deep              # skip Phase 1.5 (animation/video/scroll-recording extraction)
---from-local <path>    # use a saved site directory instead of live URL (see below)
---crawl-depth=N        # follow N levels of internal links (default: 1 for B/D/E, 2 for A/C)
+--no-deep              # skip Phase 1.5 (animation/video/scroll extraction)
+--from-local <path>    # use saved site directory instead of live URL
+--crawl-depth=N        # follow N levels (default: 1 for B/D/E, 2 for A/C)
 --blend=N              # blend ratio (N% site, default 50) — Mode E only
---skill-only           # run Mode D regardless of other args
+--skill-only           # force Mode D
 --output=./dir         # custom output directory
 --verbose              # log each extraction step
 ```
 
-### --from-local mode
+---
+
+## --from-local mode
 
-When `--from-local <path>` is provided, Phase 1 and Phase 1.5 read directly from the saved site directory instead of using browser automation. This is **more complete and reliable than live scraping** — no bot detection, no timing issues, and full access to all files.
+When `--from-local <path>` is set, Phases 1 and 1.5 read from the saved site directory. More reliable than live scraping — no bot detection, full CSS access.
 
-Expected directory structure (from tools like SaveWebZip, HTTrack, `wget --mirror`):
+Expected structure (from SaveWebZip, HTTrack, `wget --mirror`):
 ```
 <path>/
-├── index.html          ← main page HTML
-├── css/
-│   └── *.css           ← all stylesheets
-├── js/
-│   └── *.js            ← all scripts
-├── fonts/
-│   └── *.woff2         ← font files
-├── images/
-│   └── *               ← image assets
-└── media/
-    └── *.mp4 *.webm    ← video files
+├── index.html
+├── css/*.css
+├── js/*.js
+├── fonts/*.woff2
+├── images/*
+└── media/*.mp4 *.webm
 ```
 
-**What --from-local extracts (Phase 1 replacements):**
-
 | Live Phase | --from-local equivalent |
 |---|---|
-| 1.1 Screenshots | Read `index.html` → map section topology from DOM structure |
-| 1.2 Asset inventory | `ls images/` → full list without scraping |
-| 1.3 Font discovery | Parse `@font-face` from all `.css` files directly |
-| 1.5.1 Library detection | Grep JS files for library signatures (`gsap`, `ScrollTrigger`, `Swiper`, etc.) |
-| 1.5.2 CSS animation extraction | Parse all `@keyframes`, `animation:`, `transition:` from CSS files — **complete, not computed** |
-| 1.5.3 Video extraction | `ls media/` → all video files with type detection |
-| 1.5.4 Scroll recording | Not available (static files, no runtime) — skip |
-| 1.5.5 Parallax detection | Grep CSS for `background-attachment: fixed`, `transform:` on scroll listeners in JS |
-
-**Copy assets** from `<path>/fonts/`, `<path>/media/`, `<path>/images/` directly to `public/` — no download needed.
-
-**--from-local + browser MCP together (recommended):** Use `--from-local` for static extraction (CSS, fonts, videos, @keyframes) and supplement with browser MCP only for scroll recording (Phase 1.5.4). This gives the best of both approaches.
-
----
+| 1.1 Screenshots | Parse section topology from `index.html` DOM |
+| 1.2 Asset inventory | `ls images/` — no scraping needed |
+| 1.3 Font discovery | Parse `@font-face` from all `.css` files |
+| 1.5.1 Library detection | Grep JS files for `gsap`, `ScrollTrigger`, `Swiper`, etc. |
+| 1.5.2 CSS animation | Parse all `@keyframes`, `animation:`, `transition:` from CSS — complete, not computed |
+| 1.5.3 Video extraction | `ls media/` with type detection |
+| 1.5.4 Scroll recording | Not available (static files) — skip |
+| 1.5.5 Parallax | Grep CSS for `background-attachment: fixed` |
 
-## Hard constraints
+Copy assets from `<path>/fonts/`, `<path>/media/`, `<path>/images/` directly to `public/` — no download needed.
 
-- Never start Phase 1 without browser MCP confirmed available.
-- Never start Phase 2 with an incomplete interaction sweep from Phase 1.
-- Never start Phase 2 without Phase 1.5 complete (unless `--no-deep` flag is set).
-- **Modes A, C:** Never start Phase 4 without a complete component-map.md from Phase 3A.
-- **Mode B:** Never start Phase 4 without all skill files written in Phase 3B.
-- **Mode D:** Never proceed to Phase 4 — the session ends after Phase 3B.
-- **Mode E:** Never start Phase 4 without `blend-map.md` and `blended-tokens.css` from Phase 3E.
-- Never start Phase 5 without `npm run build` passing from Phase 4, all interactions implemented (4.4), all videos wired (4.4.B), and all downloaded assets referenced in components (4.5).
-- Never hardcode color, font size, spacing, radius, shadow, or animation duration values — use skill tokens only.
-- In Phase 4.4: always read `animations-raw.json.jsLibraries` before choosing an implementation strategy. Never default to `IntersectionObserver` if GSAP or Framer Motion was detected.
-- In Phase 4.4: always copy extracted `@keyframes` from `animations-raw.json` into `globals.css` verbatim before implementing animated components. Never write animation values from memory.
-- In Phase 4.4.B: never leave a video as a placeholder `<div>` when `videos.json` contains a non-skipped entry for that section.
-- **Modes A, C:** Do not replicate the original site's aesthetic — aesthetic replacement is the mission. Animation mechanics (triggers, timing, effects) are preserved; design tokens are replaced.
-- **Mode B:** Do not invent tokens that weren't observed in the site — every token must trace back to an extracted value in `aesthetics-raw.json` or `animations-raw.json`.
-- **Mode E:** Blend map must contain tokens from both sources — pure copy or pure skill application is a blend failure.
-- In Phase 1.2: always trigger lazy loads before asset extraction. Never extract images with the page at the top position only.
-- In Phase 1.5.4: always attach the MutationObserver BEFORE starting the scroll recording. Never scroll first and attach later.
-- Always warn the user about copyright on downloaded assets, videos, and extracted text content.
-- Extracted text content is for reference only — remind the user to replace it before publishing.
+**Recommended:** use `--from-local` for static extraction + browser MCP only for Phase 1.5.4 scroll recording.
 
 ---
 
 ## Observability
 
-At the end of the session, run:
+At session end:
 ```bash
 aioson agent:done . --agent=site-forge --summary="Cloned <hostname> [Mode A/B/C/D/E: description]"
 ```
-
----
-
-## Starting the session
-
-Parse the URL and optional skill name from the user's input.
-
-- URL + skill name + `--blend` → Mode E. Ask for blend ratio if not provided. Proceed to Step 0.
-- URL + `--skill-only` → Mode D. Proceed to Step 0.
-- URL + skill name → Mode A. Proceed to Step 0.
-- URL only, or ambiguous input → Run onboarding questionnaire at the top of this section.
-- No URL → Run onboarding questionnaire. Ask for URL as the first question.