@jaimevalasek/aioson 1.8.0 → 1.9.0

package/template/.aioson/docs/sheldon/research-loop.md

@@ -1,56 +1,56 @@
----
-description: "Sheldon research loop — extract short keyword phrases from the PRD and sources, consult research cache, and use fresh findings to prioritize enrichment."
----
-
-# Sheldon Research Loop
-
-Load this module after source consolidation and before sizing.
-
-## Goal
-
-Give `@sheldon` a lightweight but mandatory fresh-research pass so enrichment decisions are not limited to the PRD text or the user-supplied sources.
-
-## Mandatory keyword extraction
-
-Derive `3-7` short keyword phrases from:
-
-- the PRD's riskiest assumptions
-- unresolved flows or business rules
-- integrations, vendors, or external systems
-- domain nouns that affect quality
-- differentiators or market claims
-- technical patterns that may have aged
-
-Keep phrases short, concrete, and searchable. Prefer `2-6` words.
-
-## Mandatory scouting pass
-
-1. Load `.aioson/skills/static/web-research-cache.md`
-2. Rank phrases by:
-   - staleness risk
-   - chance of changing the PRD or phase plan
-   - risk to downstream implementation
-3. Reuse fresh `researchs/` hits first
-4. Search only the top `1-4` stale or missing phrases
-5. Save every result before using it
-
-At least one phrase must be validated through cache or fresh research whenever the PRD touches an external market, evolving UI pattern, vendor dependency, compliance surface, or non-trivial technical choice.
-
-## How to use the findings
-
-Use research to:
-
-- reprioritize improvements
-- distinguish critical gaps from cosmetic refinements
-- justify whether phased planning is necessary
-- challenge stale technical or product assumptions
-- enrich edge cases and operational details
-
-If the research is purely technical and tied to named stack decisions, combine this module with `.aioson/docs/sheldon/web-intelligence.md`.
-
-## Output discipline
-
-- `researchs/` is a temporary shared evidence layer, not a substitute for the PRD
-- show only findings that change priority, sizing, or correctness
-- mark inference separately from sourced facts
-- do not force enrichment changes without user confirmation
+---
+description: "Sheldon research loop — extract short keyword phrases from the PRD and sources, consult research cache, and use fresh findings to prioritize enrichment."
+---
+
+# Sheldon Research Loop
+
+Load this module after source consolidation and before sizing.
+
+## Goal
+
+Give `@sheldon` a lightweight but mandatory fresh-research pass so enrichment decisions are not limited to the PRD text or the user-supplied sources.
+
+## Mandatory keyword extraction
+
+Derive `3-7` short keyword phrases from:
+
+- the PRD's riskiest assumptions
+- unresolved flows or business rules
+- integrations, vendors, or external systems
+- domain nouns that affect quality
+- differentiators or market claims
+- technical patterns that may have aged
+
+Keep phrases short, concrete, and searchable. Prefer `2-6` words.
+
+## Mandatory scouting pass
+
+1. Load `.aioson/skills/static/web-research-cache.md`
+2. Rank phrases by:
+   - staleness risk
+   - chance of changing the PRD or phase plan
+   - risk to downstream implementation
+3. Reuse fresh `researchs/` hits first
+4. Search only the top `1-4` stale or missing phrases
+5. Save every result before using it
+
+At least one phrase must be validated through cache or fresh research whenever the PRD touches an external market, evolving UI pattern, vendor dependency, compliance surface, or non-trivial technical choice.
+
+## How to use the findings
+
+Use research to:
+
+- reprioritize improvements
+- distinguish critical gaps from cosmetic refinements
+- justify whether phased planning is necessary
+- challenge stale technical or product assumptions
+- enrich edge cases and operational details
+
+If the research is purely technical and tied to named stack decisions, combine this module with `.aioson/docs/sheldon/web-intelligence.md`.
+
+## Output discipline
+
+- `researchs/` is a temporary shared evidence layer, not a substitute for the PRD
+- show only findings that change priority, sizing, or correctness
+- mark inference separately from sourced facts
+- do not force enrichment changes without user confirmation

package/template/.aioson/docs/sheldon/web-intelligence.md

@@ -1,75 +1,75 @@
----
-description: "Sheldon web intelligence protocol — stale-tech validation, research cache, verdicts, and output rules."
----
-
-# Sheldon Web Intelligence
-
-Load this module when the target PRD names technologies, frameworks, integrations, or technical patterns that may be stale.
-
-## Goal
-
-Validate whether the technical decisions mentioned in the PRD are still good choices as of today.
-
-## When to run
-
-Run after source consolidation and before sizing.
-If the PRD contains no specific technical decisions, skip silently.
-
-## Technical signals to extract
-
-Look for:
-
-- named technologies or frameworks
-- architectural patterns
-- external integrations
-- stack decisions
-
-## Search protocol
-
-For each high-risk technical signal:
-
-1. Check `researchs/{decision-slug}/summary.md`
-2. If a result exists and is less than 7 days old, reuse it
-3. Otherwise search using the current year
-4. Classify the result as:
-   - `confirmed`
-   - `has-alternatives`
-   - `outdated`
-   - `deprecated`
-
-Max 4 searches per session.
-
-## Save to `researchs/`
-
-For each search, create:
-
-- `researchs/{decision-slug}/summary.md`
-- raw consulted pages under `researchs/{decision-slug}/files/`
-
-`summary.md` frontmatter must include:
-
-- `searched_at`
-- `agent: sheldon`
-- `prd`
-- `query`
-- `verdict`
-
-## User-facing output rule
-
-Show only actionable findings:
-
-- `has-alternatives`
-- `outdated`
-- `deprecated`
-
-If every finding is `confirmed`, tell the user no update is needed.
-
-Never silently modify the PRD based on web validation.
-Ask whether to incorporate the update first.
-
-## Failure behavior
-
-If a search fails:
-
-- log the failure in `summary.md`
-- continue without blocking the session
+---
+description: "Sheldon web intelligence protocol — stale-tech validation, research cache, verdicts, and output rules."
+---
+
+# Sheldon Web Intelligence
+
+Load this module when the target PRD names technologies, frameworks, integrations, or technical patterns that may be stale.
+
+## Goal
+
+Validate whether the technical decisions mentioned in the PRD are still good choices as of today.
+
+## When to run
+
+Run after source consolidation and before sizing.
+If the PRD contains no specific technical decisions, skip silently.
+
+## Technical signals to extract
+
+Look for:
+
+- named technologies or frameworks
+- architectural patterns
+- external integrations
+- stack decisions
+
+## Search protocol
+
+For each high-risk technical signal:
+
+1. Check `researchs/{decision-slug}/summary.md`
+2. If a result exists and is less than 7 days old, reuse it
+3. Otherwise search using the current year
+4. Classify the result as:
+   - `confirmed`
+   - `has-alternatives`
+   - `outdated`
+   - `deprecated`
+
+Max 4 searches per session.
+
+## Save to `researchs/`
+
+For each search, create:
+
+- `researchs/{decision-slug}/summary.md`
+- raw consulted pages under `researchs/{decision-slug}/files/`
+
+`summary.md` frontmatter must include:
+
+- `searched_at`
+- `agent: sheldon`
+- `prd`
+- `query`
+- `verdict`
+
+## User-facing output rule
+
+Show only actionable findings:
+
+- `has-alternatives`
+- `outdated`
+- `deprecated`
+
+If every finding is `confirmed`, tell the user no update is needed.
+
+Never silently modify the PRD based on web validation.
+Ask whether to incorporate the update first.
+
+## Failure behavior
+
+If a search fails:
+
+- log the failure in `summary.md`
+- continue without blocking the session

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

@@ -1,195 +1,195 @@
----
-description: "site-forge Phase 4 — Build Layer: component implementation, interactions, video, asset wiring, assembly"
-agents: [site-forge]
----
-
-# site-forge: Phase 4 — Build Layer
-
-**Goal:** Implement all sections and components.
-
-Active token source by mode:
-- **Mode A:** skill `references/design-tokens.md`
-- **Mode B:** forged skill from Phase 3B
-- **Mode C:** skill tokens; slot extracted content/images from component map
-- **Mode E:** `blended-tokens.css` from Phase 3E
-
-## 4.1 Complexity budget
-
-- **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 inline. Use skill tokens. Reference section spec and component map. Run `npx tsc --noEmit` after each file.
-
-## 4.3 Worktree builders (moderate/complex sections)
-
-```bash
-git worktree add ../worktree-<section> -b builder/<section>
-```
-
-Each builder receives:
-1. Section spec file (inline)
-2. Component map rows for this section (inline)
-3. Relevant tokens from active token file (inline — only what's needed)
-4. Path to screenshots
-5. Target file: `src/components/<SectionName>.tsx`
-6. Requirement: `npx tsc --noEmit` must pass
-
-After builder completes:
-```bash
-npx tsc --noEmit
-git add -A && git commit -m "build(<section>): implement with <skill-name> tokens"
-git worktree remove ../worktree-<section>
-git merge builder/<section> --no-ff -m "merge: <section> builder"
-```
-
-Conflict resolution: structure wins — preserve DOM hierarchy from spec; replace style values with skill tokens.
-
-## 4.4 Interaction implementation (MANDATORY — do not skip)
-
-Read `docs/research/<hostname>/animations-raw.json` → `jsLibraries` and `dom-mutations.json` before choosing strategy.
-
-### 4.4.A Implementation strategy routing
-
-**Step 1 — Choose animation layer based on detected libraries:**
-
-| Detected | Install | Strategy |
-|---|---|---|
-| `gsap: true` | `npm install gsap` | GSAP + ScrollTrigger for all scroll-driven |
-| `framerMotion: true` | `npm install framer-motion` | `<motion.div>` with `whileInView` / `useScroll` |
-| `swiper: true` | `npm install swiper` | Swiper React for carousels/sliders |
-| `lottie: true` | `npm install lottie-react` | `<Lottie>` for SVG animations |
-| `aos: true` | *(no install)* | `IntersectionObserver` + CSS classes |
-| none detected | *(no install)* | `IntersectionObserver` + CSS `@keyframes` |
-
-Install all detected libraries simultaneously.
-
-**Step 2 — Scroll-driven animations from `dom-mutations.json`:**
-
-```typescript
-// GSAP ScrollTrigger (when gsap detected)
-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,
-  },
-});
-
-// 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 `scrollY` values from `dom-mutations.json` to calibrate `start` offsets or `threshold` values.
-
-**Step 3 — Recreate `@keyframes` from `animations-raw.json`:**
-
-Copy each entry's `cssText` verbatim into `src/app/globals.css`. Apply duration via class, not inside keyframe:
-
-```css
-@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 — Parallax from `animations-raw.json.parallax`:**
-
-- `backgroundAttachment: fixed` → `background-attachment: fixed` — no JS.
-- JS parallax (transform changes between scroll positions):
-```typescript
-useEffect(() => {
-  const el = ref.current;
-  const handleScroll = () => {
-    const rate = 0.4; // adjust to match observed translation ratio
-    el.style.transform = `translate3d(0, ${window.scrollY * rate}px, 0)`;
-  };
-  window.addEventListener('scroll', handleScroll, { passive: true });
-  return () => window.removeEventListener('scroll', handleScroll);
-}, []);
-```
-
-**Step 5 — Remaining interactions from `interaction-spec.md`:**
-
-- **SCROLL-DRIVEN without mutation data:** `IntersectionObserver` with `threshold: 0.1`
-- **CLICK-DRIVEN:** React `useState` toggle + conditional className
-- **HOVER:** Tailwind hover variants or CSS `:hover` + `transition: var(--transition-all)`
-- **STATE-TOGGLE:** React `useState` + conditional className
-
-Use motion tokens for all `transition` and `animation-duration`. Never hardcode `ms`.
-
-Every interaction in the spec must be implemented. If too complex, implement simplified and note in QA report as ⚠️ — never leave unimplemented.
-
-### 4.4.B Video background implementation (MANDATORY when videos.json is non-empty)
-
-```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" />
-      </video>
-      <div className="absolute inset-0" style={{ backgroundColor: 'var(--overlay-dark)' }} />
-    </div>
-  );
-}
-```
-
-If skipped (> 10MB or blocked): use poster as `background-image`, note in QA report as ⚠️ with original URL.
-
-- Render video behind content (`z-index: 0` on video, `z-index: 1` on content).
-- Always include overlay div for text readability.
-- Always add `prefers-reduced-motion` support:
-```css
-@media (prefers-reduced-motion: reduce) {
-  video[autoplay] { display: none; }
-}
-```
-
-## 4.5 Asset wiring (MANDATORY — do not skip)
-
-Before assembly, verify every downloaded image is referenced in its component.
-
-Check `docs/research/components/<section-slug>.spec.md` → "Content slots" → Image entries. Use `next/image`:
-
-```tsx
-// Correct
-import Image from 'next/image'
-<Image src="/images/<hostname>/hero.webp" alt="hero" fill className="object-cover" />
-
-// Wrong — placeholder when downloaded asset exists
-<div className="bg-gray-200 w-full h-64" />
-```
-
-If not downloaded (> 2MB or blocked): placeholder + note in QA report as ⚠️ with original URL.
-
-**Asset lifecycle notice (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."
-
-## 4.6 Assembly
-
-1. Create `src/app/page.tsx` importing all sections in page topology order.
-2. Apply token root in `src/app/globals.css`:
-   - Modes A, B, C: paste 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.
-
-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 implemented. All downloaded assets referenced. Skill tokens active globally.
+---
+description: "site-forge Phase 4 — Build Layer: component implementation, interactions, video, asset wiring, assembly"
+agents: [site-forge]
+---
+
+# site-forge: Phase 4 — Build Layer
+
+**Goal:** Implement all sections and components.
+
+Active token source by mode:
+- **Mode A:** skill `references/design-tokens.md`
+- **Mode B:** forged skill from Phase 3B
+- **Mode C:** skill tokens; slot extracted content/images from component map
+- **Mode E:** `blended-tokens.css` from Phase 3E
+
+## 4.1 Complexity budget
+
+- **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 inline. Use skill tokens. Reference section spec and component map. Run `npx tsc --noEmit` after each file.
+
+## 4.3 Worktree builders (moderate/complex sections)
+
+```bash
+git worktree add ../worktree-<section> -b builder/<section>
+```
+
+Each builder receives:
+1. Section spec file (inline)
+2. Component map rows for this section (inline)
+3. Relevant tokens from active token file (inline — only what's needed)
+4. Path to screenshots
+5. Target file: `src/components/<SectionName>.tsx`
+6. Requirement: `npx tsc --noEmit` must pass
+
+After builder completes:
+```bash
+npx tsc --noEmit
+git add -A && git commit -m "build(<section>): implement with <skill-name> tokens"
+git worktree remove ../worktree-<section>
+git merge builder/<section> --no-ff -m "merge: <section> builder"
+```
+
+Conflict resolution: structure wins — preserve DOM hierarchy from spec; replace style values with skill tokens.
+
+## 4.4 Interaction implementation (MANDATORY — do not skip)
+
+Read `docs/research/<hostname>/animations-raw.json` → `jsLibraries` and `dom-mutations.json` before choosing strategy.
+
+### 4.4.A Implementation strategy routing
+
+**Step 1 — Choose animation layer based on detected libraries:**
+
+| Detected | Install | Strategy |
+|---|---|---|
+| `gsap: true` | `npm install gsap` | GSAP + ScrollTrigger for all scroll-driven |
+| `framerMotion: true` | `npm install framer-motion` | `<motion.div>` with `whileInView` / `useScroll` |
+| `swiper: true` | `npm install swiper` | Swiper React for carousels/sliders |
+| `lottie: true` | `npm install lottie-react` | `<Lottie>` for SVG animations |
+| `aos: true` | *(no install)* | `IntersectionObserver` + CSS classes |
+| none detected | *(no install)* | `IntersectionObserver` + CSS `@keyframes` |
+
+Install all detected libraries simultaneously.
+
+**Step 2 — Scroll-driven animations from `dom-mutations.json`:**
+
+```typescript
+// GSAP ScrollTrigger (when gsap detected)
+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,
+  },
+});
+
+// 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 `scrollY` values from `dom-mutations.json` to calibrate `start` offsets or `threshold` values.
+
+**Step 3 — Recreate `@keyframes` from `animations-raw.json`:**
+
+Copy each entry's `cssText` verbatim into `src/app/globals.css`. Apply duration via class, not inside keyframe:
+
+```css
+@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 — Parallax from `animations-raw.json.parallax`:**
+
+- `backgroundAttachment: fixed` → `background-attachment: fixed` — no JS.
+- JS parallax (transform changes between scroll positions):
+```typescript
+useEffect(() => {
+  const el = ref.current;
+  const handleScroll = () => {
+    const rate = 0.4; // adjust to match observed translation ratio
+    el.style.transform = `translate3d(0, ${window.scrollY * rate}px, 0)`;
+  };
+  window.addEventListener('scroll', handleScroll, { passive: true });
+  return () => window.removeEventListener('scroll', handleScroll);
+}, []);
+```
+
+**Step 5 — Remaining interactions from `interaction-spec.md`:**
+
+- **SCROLL-DRIVEN without mutation data:** `IntersectionObserver` with `threshold: 0.1`
+- **CLICK-DRIVEN:** React `useState` toggle + conditional className
+- **HOVER:** Tailwind hover variants or CSS `:hover` + `transition: var(--transition-all)`
+- **STATE-TOGGLE:** React `useState` + conditional className
+
+Use motion tokens for all `transition` and `animation-duration`. Never hardcode `ms`.
+
+Every interaction in the spec must be implemented. If too complex, implement simplified and note in QA report as ⚠️ — never leave unimplemented.
+
+### 4.4.B Video background implementation (MANDATORY when videos.json is non-empty)
+
+```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" />
+      </video>
+      <div className="absolute inset-0" style={{ backgroundColor: 'var(--overlay-dark)' }} />
+    </div>
+  );
+}
+```
+
+If skipped (> 10MB or blocked): use poster as `background-image`, note in QA report as ⚠️ with original URL.
+
+- Render video behind content (`z-index: 0` on video, `z-index: 1` on content).
+- Always include overlay div for text readability.
+- Always add `prefers-reduced-motion` support:
+```css
+@media (prefers-reduced-motion: reduce) {
+  video[autoplay] { display: none; }
+}
+```
+
+## 4.5 Asset wiring (MANDATORY — do not skip)
+
+Before assembly, verify every downloaded image is referenced in its component.
+
+Check `docs/research/components/<section-slug>.spec.md` → "Content slots" → Image entries. Use `next/image`:
+
+```tsx
+// Correct
+import Image from 'next/image'
+<Image src="/images/<hostname>/hero.webp" alt="hero" fill className="object-cover" />
+
+// Wrong — placeholder when downloaded asset exists
+<div className="bg-gray-200 w-full h-64" />
+```
+
+If not downloaded (> 2MB or blocked): placeholder + note in QA report as ⚠️ with original URL.
+
+**Asset lifecycle notice (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."
+
+## 4.6 Assembly
+
+1. Create `src/app/page.tsx` importing all sections in page topology order.
+2. Apply token root in `src/app/globals.css`:
+   - Modes A, B, C: paste 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.
+
+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 implemented. All downloaded assets referenced. Skill tokens active globally.