@jaimevalasek/aioson 1.7.2 → 1.8.0

package/template/.aioson/docs/site-forge-recon.md

@@ -0,0 +1,434 @@
+---
+description: "site-forge Phase 1 — Reconnaissance and Phase 1.5 — Deep Animation & Video Extraction"
+agents: [site-forge]
+---
+
+# site-forge: Phase 1 — Reconnaissance
+
+**Goal:** Capture raw information about the site. All modes run this phase.
+
+## 1.1 Multi-viewport screenshots
+
+Navigate to 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 page renders blank, shows CAPTCHA, or redirects to a challenge:
+> "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
+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.
+
+**Step B — Collect all image URLs:**
+
+```javascript
+const allAssets = new Set();
+
+// 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);
+    });
+  }
+});
+
+// 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);
+    });
+  }
+});
+
+// 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);
+    });
+  }
+});
+
+// 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); });
+});
+
+// SVG use references
+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);
+});
+
+// inline style background-image
+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);
+  });
+});
+
+// og:image and twitter:image meta
+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 structural (hero, logo, background). Preserve original filenames; sanitize paths.
+
+**Download is mandatory in Modes A, B, C, E.** Skip in Mode D — record URLs only.
+
+**Copyright notice after Phase 1:**
+> "As imagens foram baixadas para `public/images/<hostname>/` como referência.
+> São arquivos temporários — substitua-os pelos seus próprios assets antes de publicar."
+
+## 1.3 Font discovery
+
+Extract from `<link>` tags and `getComputedStyle()` on heading, body, and code elements: font families, weights loaded, where each is applied.
+
+## 1.4 Internal link crawl
+
+```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 depth:
+- Mode B, D: up to 5 internal links
+- Mode A, C: up to 10 internal links
+- Mode E: up to 5 internal links
+
+Per crawled sub-page: screenshots, asset inventory, note layout differences.
+
+Save `docs/research/<hostname>/crawl-manifest.json`:
+```json
+{
+  "mainUrl": "<url>",
+  "crawledUrls": ["<url1>", "<url2>"],
+  "assetsPerPage": { "<url>": ["<asset-path>"] }
+}
+```
+
+Skip sub-page crawl: `--no-crawl` flag.
+
+## 1.5 Interaction sweep (CRITICAL — complete before Phase 2)
+
+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
+
+Document per section: triggers, what animates, sticky positions, viewport changes.
+
+## 1.6 Page topology
+
+Map all sections top→bottom:
+```
+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
+...
+```
+
+**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": [],
+  "interactionModel": {
+    "header": "scroll-driven shrink at 50px",
+    "featureTabs": "click-switch content"
+  },
+  "pageTopology": ["Header", "Hero", "Features", "Pricing", "Footer"],
+  "breakpoints": { "tablet": 768, "mobile": 390 }
+}
+```
+
+**Exit criterion:** Screenshots at all viewports. Assets inventoried from all sources. Lazy loads triggered before extraction. Interaction model documented. Page topology complete.
+
+---
+
+# site-forge: Phase 1.5 — Deep Animation & Video Extraction
+
+**Goal:** Extract animation machinery — CSS keyframes, JS libraries, video assets, scroll-triggered mutations.
+
+Skip only if `--no-deep` flag is set.
+
+## 1.5.1 Animation library detection
+
+Run immediately after Phase 1.1. Result determines Phase 4.4 implementation strategy.
+
+```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 to `docs/research/<hostname>/animations-raw.json` under key `jsLibraries`.
+
+## 1.5.2 CSS animation rules extraction
+
+```javascript
+const animationRules = [];
+const keyframes = [];
+const scrollLinked = [];
+
+for (const sheet of document.styleSheets) {
+  try {
+    for (const rule of sheet.cssRules) {
+      const text = rule.cssText;
+
+      if (rule instanceof CSSKeyframesRule) {
+        keyframes.push({ name: rule.name, cssText: text, keyCount: rule.cssRules.length });
+        continue;
+      }
+
+      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,
+        });
+      }
+
+      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 `animations-raw.json` under keys `animationRules`, `keyframes`, `scrollLinked`.
+
+Also extract computed animation properties on visible elements:
+
+```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 in Modes A, B, C, E:**
+- `public/videos/<hostname>/<role>.<ext>`
+- Skip files > 10MB — note as `skipped: true`
+- Prefer `video/webm` or `video/mp4`
+- Always download poster alongside video
+
+**Skip in Mode D** — record URLs only.
+
+**Copyright notice (display once):**
+> "Os vídeos foram baixados para `public/videos/<hostname>/` como referência. Substitua-os pelos seus próprios vídeos antes de publicar."
+
+## 1.5.4 Scroll recording with DOM mutation tracking
+
+**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,
+});
+window.__sfMutations = mutations;
+```
+
+**Step B — Scroll to 8 checkpoints, wait 600ms, screenshot each:**
+
+| 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 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 by scroll position range and element. Append to `docs/research/<hostname>/interaction-spec.md`:
+
+```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>
+```
+
+## 1.5.5 Parallax detection
+
+```javascript
+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,
+  });
+}
+return results;
+```
+
+- `backgroundAttachment: fixed` → CSS parallax (implement with `background-attachment: fixed`)
+- `transform` changes between scroll positions → JS parallax (scroll listener + `translate3d`)
+
+Save to `animations-raw.json` under key `parallax`.
+
+## 1.5.6 Phase 1.5 output files
+
+```
+docs/research/<hostname>/
+├── animations-raw.json     ← jsLibraries, keyframes, animationRules, scrollLinked, activeAnimations, parallax
+├── videos.json             ← video elements and sources
+├── dom-mutations.json      ← class/style changes keyed by scrollY
+└── scroll-recording/
+    ├── scroll-00pct.png … scroll-100pct.png
+
+public/videos/<hostname>/
+└── [downloaded video assets]
+```
+
+**Exit criterion:** `animations-raw.json` populated with `jsLibraries`, `keyframes`, `activeAnimations`. `videos.json` written. `dom-mutations.json` written. Scroll screenshots saved. `interaction-spec.md` updated with scroll-triggered entries.

package/template/.aioson/docs/site-forge-transform.md

@@ -0,0 +1,249 @@
+---
+description: "site-forge Phase 3A — Transform Layer (Modes A/C), Phase 3B — Skill Forge (Modes B/D/E), Phase 3E — Blend Layer (Mode E)"
+agents: [site-forge]
+---
+
+# site-forge: 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
+
+Read from `.aioson/installed-skills/<skill>/` or `.aioson/skills/design/<skill>/`:
+1. `SKILL.md` — identity, pillars, activation rules
+2. `references/design-tokens.md` — all CSS variables
+3. `references/components.md` — available components and variants
+4. `references/patterns.md` — page layout patterns
+5. `references/motion.md` — animation tokens and conventions
+6. `references/websites.md` — landing page patterns (if present)
+
+## 3A.2 Build the component map
+
+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 |
+|---|---|---|
+
+## 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):** Add a "Content slot" column mapping each skill component to its extracted text and image asset.
+
+## 3A.3 Universal token substitution rules
+
+Apply 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-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 doesn't exist in the skill, use 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:** Every extracted component has a mapping row. Every interaction has a motion token assigned.
+
+---
+
+# site-forge: 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 into semantic groups:
+```
+Background: --bg-base, --bg-surface, --bg-elevated, --bg-inverse
+Text:        --text-primary, --text-muted, --text-inverse
+Brand:       --accent, --accent-hover, --border
+Semantic:    --success, --warning, --error, --info (if present)
+```
+
+Consolidate near-duplicate colors (within 10% perceptual distance) into a single token.
+
+## 3B.2 Typography system extraction
+
+```
+Font families: --font-display (h1/h2), --font-body (p), --font-mono (code, if detected)
+
+Type scale (map observed px to named scale):
+  --text-xs … --text-5xl (xs=smallest, 5xl=h1.fontSize)
+
+Weight scale (include only weights in use):
+  --font-normal (400), --font-medium (500), --font-semibold (600), --font-bold (700)
+
+Line heights:
+  --leading-tight, --leading-normal, --leading-relaxed
+```
+
+## 3B.3 Spacing system extraction
+
+Collect all observed padding/gap values → find GCD or most common divisor (typically 4px or 8px) → base unit:
+```
+--space-1 … --space-24 (1× to 24× base unit)
+```
+
+## 3B.4 Visual primitives
+
+```
+Border radius: --radius-none, --radius-sm, --radius-md, --radius-lg, --radius-full
+Shadows:       --shadow-sm, --shadow-md, --shadow-lg, --shadow-xl
+Motion:        --transition-fast, --transition-base, --transition-slow, --ease-default, --ease-spring
+```
+
+## 3B.5 Visual identity synthesis
+
+Define 3 design pillars from extracted values. Examples:
+- "Minimal contrast" + "Typographic hierarchy" + "Generous whitespace"
+- "Deep darkness" + "Glowing accents" + "Crisp borders"
+
+Also: Theme (`light | dark | system`), Personality (1-sentence description).
+
+## 3B.6 Pick reference skill structure
+
+List skills in `.aioson/skills/design/`. Choose closest visual match. Read its directory listing.
+**Use only the FILE STRUCTURE as template — do not copy any tokens or design values.**
+
+## 3B.7 Forge the skill
+
+Create `.aioson/installed-skills/<hostname>/` with:
+
+**`SKILL.md`:**
+```markdown
+# <hostname> Design System
+
+> Extracted from <url> on <date>. Visual clone skill — adapt tokens before using in unrelated projects.
+
+## Identity
+**Theme:** <light|dark|system>
+**Personality:** <1-sentence>
+
+## 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 `:root {}` block with all tokens from 3B.1–3B.4.
+
+**`references/components.md`:** Component variants derived from Phase 2.2 inventory. DOM structure, props, variants, token usage per component.
+
+**`references/patterns.md`:** Page layout patterns from Phase 2.1 section specs. Hero, Feature grid, Card layout, Nav, Footer.
+
+**`references/motion.md`:** Animation tokens + interaction patterns from Phase 2.3 and 1.5:
+- `jsLibraries` detected
+- All `@keyframes` from `animations-raw.json` — copy verbatim as "Extracted Keyframes" section
+- `parallax` entries — technique (CSS fixed vs JS transform)
+- `scrollLinked` CSS rules
+- Scroll-trigger thresholds from `dom-mutations.json` as table: element → scrollY trigger → effect
+
+**`references/websites.md`:** This site's landing page structure as reusable pattern. Full page topology and section connections.
+
+**`.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` has full `:root {}` block. Component and pattern references derived from site's inventory.
+
+**Mode D exits here.** Output path to forged skill and run observability.
+
+**Mode B and E:** Proceed to Phase 4 (Mode B uses forged skill; Mode E uses blend layer from 3E).
+
+---
+
+# site-forge: Phase 3E — Blend Layer (Mode E only)
+
+**Goal:** Merge extracted site tokens with existing skill tokens at the configured ratio.
+
+## 3E.1 Define the blend map
+
+Load both token sets:
+- Site: `docs/research/<hostname>/aesthetics-raw.json` + Phase 3B extraction
+- Skill: named skill's `references/design-tokens.md`
+
+Default blend: 50% site / 50% skill. Use user-specified ratio if provided.
+
+## 3E.2 Blend rules per category
+
+Create `docs/research/<hostname>/blend-map.md`:
+
+```markdown
+# Blend Map — <hostname> × <skill-name> — <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 |
+
+## 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 for neutrals; prefer site source for accent/brand colors.
+- Typography: ratio ≥ 50% site → use site display font; always blend body font toward skill for readability.
+- Spacing: use scale from whichever source matches the ratio.
+- Motion: use 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:** `blend-map.md` complete. `blended-tokens.css` ready. Proceed to Phase 4.