@jaimevalasek/aioson 1.8.0 → 1.9.0

package/template/.aioson/brains/sheldon/architecture-decisions.brain.json

@@ -0,0 +1,79 @@
+{
+  "v": 1,
+  "agent": "sheldon",
+  "domain": "architecture-decisions",
+  "desc": "Architecture and process decisions @sheldon should default to. Captures structural patterns proven in the AIOSON framework itself. Extend after each architectural review.",
+  "updated": "2026-05-07",
+  "nodes": [
+    {
+      "id": "sheldon-001",
+      "title": "workspace/template parity for agent files",
+      "tags": ["aioson", "template", "agents", "sync", "structural"],
+      "q": 5,
+      "v": "BEST_PRACTICE",
+      "s": "Every change to .aioson/agents/*.md must be mirrored in template/.aioson/agents/*.md. The sync direction is template→workspace (sync:agents copies template to workspace), so new content must be propagated to template manually or it is silently lost on next sync.",
+      "p": "// after editing .aioson/agents/X.md, also Edit template/.aioson/agents/X.md\n// verify with: diff -q .aioson/agents/X.md template/.aioson/agents/X.md",
+      "src": "AIOSON audit Lote A (commit 89f7681)",
+      "date": "2026-05-07",
+      "not": "edit only the workspace copy — the template stays stale and the next sync wipes the change",
+      "warn": "some pairs have legitimate preexisting diffs (e.g., qa.md feature:close logic) — review the diff before propagating, do not blindly mirror",
+      "see": ["sheldon-005"]
+    },
+    {
+      "id": "sheldon-002",
+      "title": "classification gates scale process depth",
+      "tags": ["sdd", "classification", "process", "scoping"],
+      "q": 5,
+      "v": "BEST_PRACTICE",
+      "s": "Every project/feature gets a MICRO/SMALL/MEDIUM classification that gates which agents run and which artefacts are produced. MICRO = product→dev. SMALL = product→analyst→dev. MEDIUM = full chain with all gates. Skipping the classification step bloats MICRO work and starves MEDIUM work.",
+      "p": "1. @analyst runs first to classify\n2. The classification routes to the appropriate agent chain\n3. Process depth (artefacts, gates, reviews) follows the classification, not the urgency",
+      "src": "aioson-spec-driven SKILL.md; AIOSON CLAUDE.md",
+      "date": "2026-05-07",
+      "not": "running the full MEDIUM pipeline on every task because 'it's safer' — kills throughput on MICRO work",
+      "warn": "do not let user urgency reclassify down — urgency does not shrink risk surface",
+      "see": ["sheldon-004"]
+    },
+    {
+      "id": "sheldon-003",
+      "title": "strict context sandbox for impartial validators",
+      "tags": ["validator", "sandbox", "impartiality", "verification"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "Agents whose role is to verify (validator, qa) operate best with a strict read-list, not the full conversation context. The Nautilus Pattern: validator reads only harness-contract.json, progress.json, and listed completed_steps — never other agents' artefacts or chat history. Continuity hallucinations vanish.",
+      "p": "// validator reads:\n//   .aioson/plans/{slug}/harness-contract.json\n//   .aioson/plans/{slug}/progress.json\n//   files in progress.json.completed_steps\n//   diagnostic-tool output\n// validator NEVER reads PRDs, requirements, or sibling-agent transcripts",
+      "src": "validator.md Context restrictions",
+      "date": "2026-05-07",
+      "not": "feeding the validator the full conversation history — it starts agreeing with prior agents instead of checking the binary contract",
+      "warn": "rules from .aioson/rules/ may add criteria but never expand the sandbox — validator stays read-restricted",
+      "see": ["sheldon-005"]
+    },
+    {
+      "id": "sheldon-004",
+      "title": "discovery before architecture — never the reverse",
+      "tags": ["sdd", "discovery", "architecture", "ordering", "anti-pattern"],
+      "q": 5,
+      "v": "BEST_PRACTICE",
+      "s": "discovery.md (entities, business rules, constraints) must precede architecture.md (modules, stack choices, file layout). Architecting against assumed entities reliably ships the wrong abstraction.",
+      "p": "@discovery-design-doc → @analyst → discovery.md →\n@architect reads discovery.md → architecture.md →\n@dev reads both → implementation",
+      "src": "AIOSON SDD framework",
+      "date": "2026-05-07",
+      "not": "architect.md written before discovery.md — entities get reverse-engineered from the architecture diagram, business rules get lost",
+      "warn": "in brownfield projects, discovery still comes first but it is reverse discovery (scan code → discovery.md), not greenfield interview",
+      "see": ["sheldon-002"]
+    },
+    {
+      "id": "sheldon-005",
+      "title": "integrate via CLI command, not direct file write",
+      "tags": ["aioson", "cli", "integration", "telemetry", "schema"],
+      "q": 4,
+      "v": "GOOD",
+      "s": "When an agent needs to update a structured artefact (dossier, project-pulse, features.md, current-state.md), prefer the CLI command (dossier:add-finding, pulse:update, feature:close) over hand-editing the file. The CLI enforces schema, updates indices, and emits telemetry the dashboard needs.",
+      "p": "// good\naioson dossier:add-finding . --slug={slug} --section='Agent Trail' --content='...'\n// fallback only when CLI unavailable\n// edit the markdown file by hand, append-only",
+      "src": "AIOSON audit Lote B (discovery-design-doc, validator, tester dossier integration)",
+      "date": "2026-05-07",
+      "not": "rewriting an artefact's whole structure to add one entry — breaks index sync and loses telemetry",
+      "warn": "the CLI fallback path (manual edit) must remain available when CLI is missing — agents that hard-require CLI become unusable in plain Claude Code sessions",
+      "see": ["sheldon-001", "sheldon-003"]
+    }
+  ]
+}

package/template/.aioson/brains/site-forge/visual-patterns.brain.json

@@ -1,205 +1,205 @@
-{
-  "v": 1,
-  "agent": "site-forge",
-  "domain": "visual-patterns",
-  "desc": "CSS/animation/interaction patterns discovered while cloning real sites. Each node is a reusable lesson — quality-scored and anti-pattern aware. Use see[] to traverse related nodes.",
-  "updated": "2026-04-01",
-  "nodes": [
-    {
-      "id": "css-001",
-      "title": "CTA hover: mix-blend-mode:difference",
-      "tags": ["css", "hover", "cta", "button", "animation", "no-js", "blend-mode"],
-      "q": 5,
-      "v": "EXCELLENT",
-      "s": "White ::after pseudo-element with mix-blend-mode:difference creates color inversion on hover. Zero JS. Works on any background color automatically.",
-      "p": ".btn{position:relative;overflow:hidden} .btn::after{content:'';position:absolute;inset:0;background:white;mix-blend-mode:difference;transform:scaleX(0);transform-origin:0;transition:transform .3s cubic-bezier(.645,.045,.355,1)} .btn:hover::after{transform:scaleX(1)}",
-      "src": "pt.squarespace.com",
-      "date": "2026-04-01",
-      "not": "background-color color transition on hover — color swap is weak compared to inversion effect",
-      "warn": "parent needs overflow:hidden; does not work if parent has background:transparent",
-      "see": ["css-002", "css-008"]
-    },
-    {
-      "id": "css-002",
-      "title": "Mobile menu: clip-path polygon() swipe",
-      "tags": ["css", "animation", "mobile", "menu", "drawer", "keyframes", "clip-path"],
-      "q": 5,
-      "v": "EXCELLENT",
-      "s": "Mobile drawer wipes in from right using clip-path polygon animation — more cinematic than translateX slide. Requires @keyframes swipeIn/swipeOut.",
-      "p": "@keyframes swipeIn{0%{clip-path:polygon(101% 0%,100% 0%,101% 100%,116% 100%)}to{clip-path:polygon(0% 0%,101% 0%,101% 101%,0% 101%)}} .menu--open{animation:.6s cubic-bezier(.165,.84,.44,1) forwards swipeIn}",
-      "src": "pt.squarespace.com",
-      "date": "2026-04-01",
-      "not": "transform:translateX(-100%) — generic slide, no visual drama",
-      "warn": "Menu must be position:fixed with full viewport size for clip-path to work correctly",
-      "see": ["css-001", "css-007"]
-    },
-    {
-      "id": "css-003",
-      "title": "Accordion: grid-template-rows 0fr→1fr",
-      "tags": ["css", "accordion", "animation", "no-js", "grid", "mobile"],
-      "q": 5,
-      "v": "EXCELLENT",
-      "s": "CSS grid transition on grid-template-rows animates height without any JS height calculation. Modern and smooth.",
-      "p": ".accordion-content{display:grid;grid-template-rows:0fr;transition:grid-template-rows .7s cubic-bezier(.165,.84,.44,1)} .accordion-content--open{grid-template-rows:1fr} .accordion-inner{overflow:hidden}",
-      "src": "pt.squarespace.com",
-      "date": "2026-04-01",
-      "not": "max-height hack or JS getBoundingClientRect height calculation",
-      "warn": "Inner child needs overflow:hidden for the 0fr collapse to work",
-      "see": ["css-007"]
-    },
-    {
-      "id": "css-004",
-      "title": "Link underline: dual linear-gradient background-position",
-      "tags": ["css", "hover", "link", "underline", "animation", "keyframes"],
-      "q": 5,
-      "v": "EXCELLENT",
-      "s": "Two linear-gradients animated via background-position create a sliding underline that enters from left on hover and exits to right on mouse-leave. Pure CSS.",
-      "p": ".link{background-image:linear-gradient(currentColor,currentColor),linear-gradient(currentColor,currentColor);background-size:100% 1px,0% 1px;background-repeat:no-repeat;background-position:-200% 100%,-100% 100%;animation:.5s cubic-bezier(.645,.045,.355,1) forwards ctaUnderlineSlideOut} .link:hover{animation:.5s cubic-bezier(.645,.045,.355,1) forwards ctaUnderlineSlideIn}",
-      "src": "pt.squarespace.com",
-      "date": "2026-04-01",
-      "not": "text-decoration or border-bottom — no directional animation possible",
-      "warn": "Requires @keyframes ctaUnderlineSlideIn/Out; currentColor inherits from text color automatically",
-      "see": ["css-001", "css-007"]
-    },
-    {
-      "id": "css-005",
-      "title": "Scroll reveal: IntersectionObserver + CSS class toggle",
-      "tags": ["css", "scroll", "reveal", "animation", "no-js-lib", "intersection-observer"],
-      "q": 5,
-      "v": "EXCELLENT",
-      "s": "IntersectionObserver adds .in-view class at 15% threshold; CSS transition handles opacity+translateY. Zero third-party libraries needed.",
-      "p": "// JS: const obs=new IntersectionObserver(entries=>entries.forEach(e=>e.isIntersecting&&e.target.classList.add('in-view')),{threshold:.15}); document.querySelectorAll('.reveal').forEach(el=>obs.observe(el)); // CSS: .reveal{opacity:0;transform:translateY(16px);transition:opacity .8s cubic-bezier(.23,1,.32,1),transform .8s cubic-bezier(.23,1,.32,1)} .reveal.in-view{opacity:1;transform:none}",
-      "src": "pt.squarespace.com",
-      "date": "2026-04-01",
-      "not": "AOS library, ScrollReveal, GSAP ScrollTrigger for basic fade-up reveals — overkill",
-      "warn": "threshold:0.15 is the sweet spot; too low fires too early, too high never fires on short sections",
-      "see": ["css-007", "css-008"]
-    },
-    {
-      "id": "css-006",
-      "title": "Staggered card reveals with nth-child delay",
-      "tags": ["css", "animation", "stagger", "cards", "scroll", "reveal"],
-      "q": 4,
-      "v": "GOOD",
-      "s": "Add transition-delay via nth-child selectors on .reveal-stagger children. 0.1s increments per card.",
-      "p": ".reveal-stagger>*:nth-child(1){transition-delay:0s} .reveal-stagger>*:nth-child(2){transition-delay:.1s} .reveal-stagger>*:nth-child(3){transition-delay:.2s} .reveal-stagger>*:nth-child(4){transition-delay:.3s} .reveal-stagger>*:nth-child(5){transition-delay:.4s}",
-      "src": "pt.squarespace.com",
-      "date": "2026-04-01",
-      "not": null,
-      "warn": "Keep delays short (0.1s increments); longer delays feel sluggish",
-      "see": ["css-005"]
-    },
-    {
-      "id": "css-007",
-      "title": "Squarespace signature easing curves",
-      "tags": ["css", "easing", "animation", "cubic-bezier", "tokens"],
-      "q": 5,
-      "v": "EXCELLENT",
-      "s": "Three distinct easing curves used consistently: reveal=smooth deceleration, cta=power ease, menu=fast-in/slow-out. Gives a unified, professional motion feel.",
-      "p": "--ease-sqsp-reveal:cubic-bezier(.23,1,.32,1); --ease-sqsp-cta:cubic-bezier(.645,.045,.355,1); --ease-sqsp-menu:cubic-bezier(.165,.84,.44,1)",
-      "src": "pt.squarespace.com",
-      "date": "2026-04-01",
-      "not": "ease, ease-in-out, linear — generic curves flatten the personality of the site",
-      "warn": null,
-      "see": ["css-001", "css-002", "css-003", "css-004", "css-005"]
-    },
-    {
-      "id": "css-008",
-      "title": "prefers-reduced-motion global override",
-      "tags": ["css", "accessibility", "animation", "best-practice"],
-      "q": 5,
-      "v": "BEST_PRACTICE",
-      "s": "Global @media prefers-reduced-motion override that collapses all durations to 0.01ms. Always include in globals.css — never skip.",
-      "p": "@media(prefers-reduced-motion:reduce){*,*::before,*::after{animation-duration:.01ms!important;animation-iteration-count:1!important;transition-duration:.01ms!important}}",
-      "src": "pt.squarespace.com",
-      "date": "2026-04-01",
-      "not": null,
-      "warn": null,
-      "see": ["css-005"]
-    },
-    {
-      "id": "css-009",
-      "title": "Video background: autoPlay muted loop playsInline",
-      "tags": ["css", "video", "background", "hero", "mobile"],
-      "q": 4,
-      "v": "GOOD",
-      "s": "Hero video must have all 4 attributes to autoplay cross-browser. WebM first, MP4 fallback. Dark rgba overlay on top. Mobile swap via useEffect.",
-      "p": "<video autoplay muted loop playsinline preload=auto><source src=desktop.webm type=video/webm><source src=desktop.mp4 type=video/mp4></video><div style=position:absolute;inset:0;background:rgba(0,0,0,.52)></div>",
-      "src": "pt.squarespace.com",
-      "date": "2026-04-01",
-      "not": "Using background-image: url() for video — use the real <video> element",
-      "warn": "Card carousel videos use preload=none; only hero is preload=auto",
-      "see": ["css-005"]
-    },
-    {
-      "id": "js-001",
-      "title": "Extract @keyframes via document.styleSheets iteration",
-      "tags": ["js", "extraction", "keyframes", "css", "cloning", "analysis"],
-      "q": 5,
-      "v": "EXCELLENT",
-      "s": "Iterate document.styleSheets and cssRules to extract @keyframes verbatim. This is the ONLY way to get actual @keyframes — getComputedStyle never exposes them.",
-      "p": "const kf=[]; for(const s of document.styleSheets){try{for(const r of s.cssRules){if(r instanceof CSSKeyframesRule){kf.push({name:r.name,css:r.cssText})}}}catch(e){}} console.log(JSON.stringify(kf))",
-      "src": "research — pt.squarespace.com analysis",
-      "date": "2026-04-01",
-      "not": "getComputedStyle(el).animation — returns resolved shorthand, never exposes @keyframes definitions",
-      "warn": "CORS will throw on cross-origin stylesheets — wrap in try/catch per sheet",
-      "see": ["js-002", "js-003"]
-    },
-    {
-      "id": "js-002",
-      "title": "MutationObserver scroll recording for DOM class changes",
-      "tags": ["js", "extraction", "cloning", "scroll", "animation", "mutationobserver"],
-      "q": 5,
-      "v": "EXCELLENT",
-      "s": "Attach MutationObserver BEFORE starting scroll; record mutations at 8 checkpoints (0%, 12%, 25%, 37%, 50%, 62%, 75%, 87%, 100%). Each record: scrollY + changed elements + class diffs.",
-      "p": "const mutations=[]; const obs=new MutationObserver(ms=>ms.forEach(m=>{mutations.push({scrollY:window.scrollY,target:m.target.className,added:[...m.addedNodes].map(n=>n.className),attr:m.attributeName,old:m.oldValue})})); obs.observe(document.body,{subtree:true,attributes:true,attributeOldValue:true,childList:true}); // then scroll to each % checkpoint with 600ms settle",
-      "src": "research — pt.squarespace.com analysis",
-      "date": "2026-04-01",
-      "not": "Manual screenshot comparison — misses class toggles and DOM mutations",
-      "warn": "600ms settle time needed after each scroll to let animations complete",
-      "see": ["js-001", "js-003"]
-    },
-    {
-      "id": "js-003",
-      "title": "AVOID: getComputedStyle for animation detection",
-      "tags": ["js", "extraction", "animation", "anti-pattern"],
-      "q": 1,
-      "v": "AVOID",
-      "s": "getComputedStyle returns resolved property values — it NEVER exposes @keyframes definitions, animation timing functions are partially resolved, clip-path values may differ from source.",
-      "p": "// BAD: getComputedStyle(el).animationName → returns name only, not keyframes // BAD: getComputedStyle(el).clipPath → returns computed polygon(), but not the @keyframes that drives it",
-      "src": "research — pt.squarespace.com analysis",
-      "date": "2026-04-01",
-      "not": null,
-      "warn": "Use document.styleSheets iteration (js-001) to get real @keyframes definitions",
-      "see": ["js-001", "js-002"]
-    },
-    {
-      "id": "js-004",
-      "title": "JS library detection before choosing animation strategy",
-      "tags": ["js", "cloning", "gsap", "framer-motion", "animation", "detection"],
-      "q": 5,
-      "v": "EXCELLENT",
-      "s": "Always check window.gsap, window.ScrollTrigger, data-framer-component-type before choosing animation implementation. Wrong library choice creates double-animation or no-animation bugs.",
-      "p": "const libs={gsap:!!window.gsap,scrollTrigger:!!window.ScrollTrigger,framer:!!document.querySelector('[data-framer-component-type]'),lottie:!!window.lottie,aos:!!window.AOS}",
-      "src": "research — pt.squarespace.com analysis",
-      "date": "2026-04-01",
-      "not": "Defaulting to IntersectionObserver when GSAP is detected on the source site",
-      "warn": "Site not using GSAP does NOT mean IntersectionObserver is the right choice — read the actual @keyframes first",
-      "see": ["js-001", "js-002", "css-005"]
-    },
-    {
-      "id": "font-001",
-      "title": "Proprietary fonts: extract woff2 from saved site, serve locally",
-      "tags": ["font", "typography", "woff2", "cloning", "font-face"],
-      "q": 4,
-      "v": "GOOD",
-      "s": "When site uses proprietary font (CDN-blocked), extract woff2 files from the saved site's fonts/ directory. Serve via @font-face pointing to public/fonts/. Reference assets only — rewrite content.",
-      "p": "@font-face{font-family:'Clarkson';font-weight:300;font-display:swap;src:url('/fonts/clarkson-300.woff2') format('woff2')}",
-      "src": "pt.squarespace.com",
-      "date": "2026-04-01",
-      "not": "Trying to load proprietary fonts from CDN — 403 in production",
-      "warn": "Reference assets only — do not redistribute proprietary font files in public projects",
-      "see": []
-    }
-  ]
-}
+{
+  "v": 1,
+  "agent": "site-forge",
+  "domain": "visual-patterns",
+  "desc": "CSS/animation/interaction patterns discovered while cloning real sites. Each node is a reusable lesson — quality-scored and anti-pattern aware. Use see[] to traverse related nodes.",
+  "updated": "2026-04-01",
+  "nodes": [
+    {
+      "id": "css-001",
+      "title": "CTA hover: mix-blend-mode:difference",
+      "tags": ["css", "hover", "cta", "button", "animation", "no-js", "blend-mode"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "White ::after pseudo-element with mix-blend-mode:difference creates color inversion on hover. Zero JS. Works on any background color automatically.",
+      "p": ".btn{position:relative;overflow:hidden} .btn::after{content:'';position:absolute;inset:0;background:white;mix-blend-mode:difference;transform:scaleX(0);transform-origin:0;transition:transform .3s cubic-bezier(.645,.045,.355,1)} .btn:hover::after{transform:scaleX(1)}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "background-color color transition on hover — color swap is weak compared to inversion effect",
+      "warn": "parent needs overflow:hidden; does not work if parent has background:transparent",
+      "see": ["css-002", "css-008"]
+    },
+    {
+      "id": "css-002",
+      "title": "Mobile menu: clip-path polygon() swipe",
+      "tags": ["css", "animation", "mobile", "menu", "drawer", "keyframes", "clip-path"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "Mobile drawer wipes in from right using clip-path polygon animation — more cinematic than translateX slide. Requires @keyframes swipeIn/swipeOut.",
+      "p": "@keyframes swipeIn{0%{clip-path:polygon(101% 0%,100% 0%,101% 100%,116% 100%)}to{clip-path:polygon(0% 0%,101% 0%,101% 101%,0% 101%)}} .menu--open{animation:.6s cubic-bezier(.165,.84,.44,1) forwards swipeIn}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "transform:translateX(-100%) — generic slide, no visual drama",
+      "warn": "Menu must be position:fixed with full viewport size for clip-path to work correctly",
+      "see": ["css-001", "css-007"]
+    },
+    {
+      "id": "css-003",
+      "title": "Accordion: grid-template-rows 0fr→1fr",
+      "tags": ["css", "accordion", "animation", "no-js", "grid", "mobile"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "CSS grid transition on grid-template-rows animates height without any JS height calculation. Modern and smooth.",
+      "p": ".accordion-content{display:grid;grid-template-rows:0fr;transition:grid-template-rows .7s cubic-bezier(.165,.84,.44,1)} .accordion-content--open{grid-template-rows:1fr} .accordion-inner{overflow:hidden}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "max-height hack or JS getBoundingClientRect height calculation",
+      "warn": "Inner child needs overflow:hidden for the 0fr collapse to work",
+      "see": ["css-007"]
+    },
+    {
+      "id": "css-004",
+      "title": "Link underline: dual linear-gradient background-position",
+      "tags": ["css", "hover", "link", "underline", "animation", "keyframes"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "Two linear-gradients animated via background-position create a sliding underline that enters from left on hover and exits to right on mouse-leave. Pure CSS.",
+      "p": ".link{background-image:linear-gradient(currentColor,currentColor),linear-gradient(currentColor,currentColor);background-size:100% 1px,0% 1px;background-repeat:no-repeat;background-position:-200% 100%,-100% 100%;animation:.5s cubic-bezier(.645,.045,.355,1) forwards ctaUnderlineSlideOut} .link:hover{animation:.5s cubic-bezier(.645,.045,.355,1) forwards ctaUnderlineSlideIn}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "text-decoration or border-bottom — no directional animation possible",
+      "warn": "Requires @keyframes ctaUnderlineSlideIn/Out; currentColor inherits from text color automatically",
+      "see": ["css-001", "css-007"]
+    },
+    {
+      "id": "css-005",
+      "title": "Scroll reveal: IntersectionObserver + CSS class toggle",
+      "tags": ["css", "scroll", "reveal", "animation", "no-js-lib", "intersection-observer"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "IntersectionObserver adds .in-view class at 15% threshold; CSS transition handles opacity+translateY. Zero third-party libraries needed.",
+      "p": "// JS: const obs=new IntersectionObserver(entries=>entries.forEach(e=>e.isIntersecting&&e.target.classList.add('in-view')),{threshold:.15}); document.querySelectorAll('.reveal').forEach(el=>obs.observe(el)); // CSS: .reveal{opacity:0;transform:translateY(16px);transition:opacity .8s cubic-bezier(.23,1,.32,1),transform .8s cubic-bezier(.23,1,.32,1)} .reveal.in-view{opacity:1;transform:none}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "AOS library, ScrollReveal, GSAP ScrollTrigger for basic fade-up reveals — overkill",
+      "warn": "threshold:0.15 is the sweet spot; too low fires too early, too high never fires on short sections",
+      "see": ["css-007", "css-008"]
+    },
+    {
+      "id": "css-006",
+      "title": "Staggered card reveals with nth-child delay",
+      "tags": ["css", "animation", "stagger", "cards", "scroll", "reveal"],
+      "q": 4,
+      "v": "GOOD",
+      "s": "Add transition-delay via nth-child selectors on .reveal-stagger children. 0.1s increments per card.",
+      "p": ".reveal-stagger>*:nth-child(1){transition-delay:0s} .reveal-stagger>*:nth-child(2){transition-delay:.1s} .reveal-stagger>*:nth-child(3){transition-delay:.2s} .reveal-stagger>*:nth-child(4){transition-delay:.3s} .reveal-stagger>*:nth-child(5){transition-delay:.4s}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": null,
+      "warn": "Keep delays short (0.1s increments); longer delays feel sluggish",
+      "see": ["css-005"]
+    },
+    {
+      "id": "css-007",
+      "title": "Squarespace signature easing curves",
+      "tags": ["css", "easing", "animation", "cubic-bezier", "tokens"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "Three distinct easing curves used consistently: reveal=smooth deceleration, cta=power ease, menu=fast-in/slow-out. Gives a unified, professional motion feel.",
+      "p": "--ease-sqsp-reveal:cubic-bezier(.23,1,.32,1); --ease-sqsp-cta:cubic-bezier(.645,.045,.355,1); --ease-sqsp-menu:cubic-bezier(.165,.84,.44,1)",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "ease, ease-in-out, linear — generic curves flatten the personality of the site",
+      "warn": null,
+      "see": ["css-001", "css-002", "css-003", "css-004", "css-005"]
+    },
+    {
+      "id": "css-008",
+      "title": "prefers-reduced-motion global override",
+      "tags": ["css", "accessibility", "animation", "best-practice"],
+      "q": 5,
+      "v": "BEST_PRACTICE",
+      "s": "Global @media prefers-reduced-motion override that collapses all durations to 0.01ms. Always include in globals.css — never skip.",
+      "p": "@media(prefers-reduced-motion:reduce){*,*::before,*::after{animation-duration:.01ms!important;animation-iteration-count:1!important;transition-duration:.01ms!important}}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": null,
+      "warn": null,
+      "see": ["css-005"]
+    },
+    {
+      "id": "css-009",
+      "title": "Video background: autoPlay muted loop playsInline",
+      "tags": ["css", "video", "background", "hero", "mobile"],
+      "q": 4,
+      "v": "GOOD",
+      "s": "Hero video must have all 4 attributes to autoplay cross-browser. WebM first, MP4 fallback. Dark rgba overlay on top. Mobile swap via useEffect.",
+      "p": "<video autoplay muted loop playsinline preload=auto><source src=desktop.webm type=video/webm><source src=desktop.mp4 type=video/mp4></video><div style=position:absolute;inset:0;background:rgba(0,0,0,.52)></div>",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "Using background-image: url() for video — use the real <video> element",
+      "warn": "Card carousel videos use preload=none; only hero is preload=auto",
+      "see": ["css-005"]
+    },
+    {
+      "id": "js-001",
+      "title": "Extract @keyframes via document.styleSheets iteration",
+      "tags": ["js", "extraction", "keyframes", "css", "cloning", "analysis"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "Iterate document.styleSheets and cssRules to extract @keyframes verbatim. This is the ONLY way to get actual @keyframes — getComputedStyle never exposes them.",
+      "p": "const kf=[]; for(const s of document.styleSheets){try{for(const r of s.cssRules){if(r instanceof CSSKeyframesRule){kf.push({name:r.name,css:r.cssText})}}}catch(e){}} console.log(JSON.stringify(kf))",
+      "src": "research — pt.squarespace.com analysis",
+      "date": "2026-04-01",
+      "not": "getComputedStyle(el).animation — returns resolved shorthand, never exposes @keyframes definitions",
+      "warn": "CORS will throw on cross-origin stylesheets — wrap in try/catch per sheet",
+      "see": ["js-002", "js-003"]
+    },
+    {
+      "id": "js-002",
+      "title": "MutationObserver scroll recording for DOM class changes",
+      "tags": ["js", "extraction", "cloning", "scroll", "animation", "mutationobserver"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "Attach MutationObserver BEFORE starting scroll; record mutations at 8 checkpoints (0%, 12%, 25%, 37%, 50%, 62%, 75%, 87%, 100%). Each record: scrollY + changed elements + class diffs.",
+      "p": "const mutations=[]; const obs=new MutationObserver(ms=>ms.forEach(m=>{mutations.push({scrollY:window.scrollY,target:m.target.className,added:[...m.addedNodes].map(n=>n.className),attr:m.attributeName,old:m.oldValue})})); obs.observe(document.body,{subtree:true,attributes:true,attributeOldValue:true,childList:true}); // then scroll to each % checkpoint with 600ms settle",
+      "src": "research — pt.squarespace.com analysis",
+      "date": "2026-04-01",
+      "not": "Manual screenshot comparison — misses class toggles and DOM mutations",
+      "warn": "600ms settle time needed after each scroll to let animations complete",
+      "see": ["js-001", "js-003"]
+    },
+    {
+      "id": "js-003",
+      "title": "AVOID: getComputedStyle for animation detection",
+      "tags": ["js", "extraction", "animation", "anti-pattern"],
+      "q": 1,
+      "v": "AVOID",
+      "s": "getComputedStyle returns resolved property values — it NEVER exposes @keyframes definitions, animation timing functions are partially resolved, clip-path values may differ from source.",
+      "p": "// BAD: getComputedStyle(el).animationName → returns name only, not keyframes // BAD: getComputedStyle(el).clipPath → returns computed polygon(), but not the @keyframes that drives it",
+      "src": "research — pt.squarespace.com analysis",
+      "date": "2026-04-01",
+      "not": null,
+      "warn": "Use document.styleSheets iteration (js-001) to get real @keyframes definitions",
+      "see": ["js-001", "js-002"]
+    },
+    {
+      "id": "js-004",
+      "title": "JS library detection before choosing animation strategy",
+      "tags": ["js", "cloning", "gsap", "framer-motion", "animation", "detection"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "Always check window.gsap, window.ScrollTrigger, data-framer-component-type before choosing animation implementation. Wrong library choice creates double-animation or no-animation bugs.",
+      "p": "const libs={gsap:!!window.gsap,scrollTrigger:!!window.ScrollTrigger,framer:!!document.querySelector('[data-framer-component-type]'),lottie:!!window.lottie,aos:!!window.AOS}",
+      "src": "research — pt.squarespace.com analysis",
+      "date": "2026-04-01",
+      "not": "Defaulting to IntersectionObserver when GSAP is detected on the source site",
+      "warn": "Site not using GSAP does NOT mean IntersectionObserver is the right choice — read the actual @keyframes first",
+      "see": ["js-001", "js-002", "css-005"]
+    },
+    {
+      "id": "font-001",
+      "title": "Proprietary fonts: extract woff2 from saved site, serve locally",
+      "tags": ["font", "typography", "woff2", "cloning", "font-face"],
+      "q": 4,
+      "v": "GOOD",
+      "s": "When site uses proprietary font (CDN-blocked), extract woff2 files from the saved site's fonts/ directory. Serve via @font-face pointing to public/fonts/. Reference assets only — rewrite content.",
+      "p": "@font-face{font-family:'Clarkson';font-weight:300;font-display:swap;src:url('/fonts/clarkson-300.woff2') format('woff2')}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "Trying to load proprietary fonts from CDN — 403 in production",
+      "warn": "Reference assets only — do not redistribute proprietary font files in public projects",
+      "see": []
+    }
+  ]
+}