akili-specs 2.7.1 → 2.8.0

package/.claude/skills/gsap-animation/references/scrolltrigger.md

@@ -0,0 +1,255 @@
+# GSAP ScrollTrigger
+
+Read when implementing scroll-driven animation: triggering tweens/timelines on scroll, pinning, scrubbing, parallax, batching, horizontal scroll, or integrating a smooth-scroll library.
+
+## Registering the Plugin
+
+ScrollTrigger is a plugin — register once (see SKILL.md registration pattern):
+
+```javascript
+gsap.registerPlugin(ScrollTrigger);
+```
+
+## Basic Trigger
+
+```javascript
+gsap.to(".box", {
+  x: 500,
+  duration: 1,
+  scrollTrigger: {
+    trigger: ".box",
+    start: "top center",   // when top of trigger hits center of viewport
+    end: "bottom center",  // when the bottom of the trigger hits the center of the viewport
+    toggleActions: "play reverse play reverse" // onEnter, onLeave, onEnterBack, onLeaveBack
+  }
+});
+```
+
+**start** / **end**: `"triggerPosition viewportPosition"`. Examples: `"top top"`, `"center center"`, `"bottom 80%"`, or a numeric pixel value like `500` (scroller scrolls 500px from top). Relative values: `"+=300"`, `"+=100%"` (scroller height past start), or `"max"`. Wrap in **clamp()** (3.12+) to keep within page bounds: `start: "clamp(top bottom)"`. Can also be a **function** returning a string/number (receives the ScrollTrigger instance); call **ScrollTrigger.refresh()** when layout changes.
+
+## Key config options
+
+Shorthand `scrollTrigger: ".selector"` sets only `trigger`. Full list: [ScrollTrigger docs](https://gsap.com/docs/v3/Plugins/ScrollTrigger/).
+
+| Property | Type | Description |
+|----------|------|-------------|
+| **trigger** | String \| Element | Element whose position defines where the ScrollTrigger starts. Required (or use shorthand). |
+| **start** | String \| Number \| Function | When the trigger becomes active. Default `"top bottom"` (or `"top top"` if `pin: true`). |
+| **end** | String \| Number \| Function | When the trigger ends. Default `"bottom top"`. Use `endTrigger` if end is based on a different element. |
+| **endTrigger** | String \| Element | Element used for **end** when different from trigger. |
+| **scrub** | Boolean \| Number | Link animation progress to scroll. `true` = direct; number = seconds for playhead to "catch up". |
+| **toggleActions** | String | Four actions in order: **onEnter**, **onLeave**, **onEnterBack**, **onLeaveBack**. Each: `"play"`, `"pause"`, `"resume"`, `"reset"`, `"restart"`, `"complete"`, `"reverse"`, `"none"`. Default `"play none none none"`. |
+| **pin** | Boolean \| String \| Element | Pin an element while active. `true` = pin the trigger. Don't animate the pinned element itself; animate children. |
+| **pinSpacing** | Boolean \| String | Default `true` (adds spacer so layout doesn't collapse). `false` or `"margin"`. |
+| **horizontal** | Boolean | `true` for horizontal scrolling. |
+| **scroller** | String \| Element | Scroll container (default: viewport). |
+| **markers** | Boolean \| Object | `true` for dev markers; or `{ startColor, endColor, fontSize, ... }`. Remove in production. |
+| **once** | Boolean | If `true`, kills the ScrollTrigger after end is reached once (animation keeps running). |
+| **id** | String | Unique id for **ScrollTrigger.getById(id)**. |
+| **refreshPriority** | Number | Lower = refreshed first. Set when creating ScrollTriggers out of page order so they refresh in page order (first on page = lower number). |
+| **toggleClass** | String \| Object | Add/remove class when active. String = on trigger; or `{ targets: ".x", className: "active" }`. |
+| **snap** | Number \| Array \| Function \| "labels" \| Object | Snap to progress values. Number = increments (e.g. `0.25`); array = specific values; `"labels"` = timeline labels; object: `{ snapTo: 0.25, duration: 0.3, delay: 0.1, ease: "power1.inOut" }`. |
+| **containerAnimation** | Tween \| Timeline | For "fake" horizontal scroll (see below). Pinning and snapping are not available on containerAnimation-based ScrollTriggers. |
+| **onEnter**, **onLeave**, **onEnterBack**, **onLeaveBack** | Function | Callbacks when crossing start/end; receive the ScrollTrigger instance (`progress`, `direction`, `isActive`, `getVelocity()`). |
+| **onUpdate**, **onToggle**, **onRefresh**, **onScrubComplete** | Function | **onUpdate** fires when progress changes; **onToggle** when active flips; **onRefresh** after recalc; **onScrubComplete** when numeric scrub finishes. |
+
+**Standalone ScrollTrigger** (no linked tween): use **ScrollTrigger.create()** with the same config and callbacks for custom behavior.
+
+```javascript
+ScrollTrigger.create({
+  trigger: "#id",
+  start: "top top",
+  end: "bottom 50%+=100px",
+  onUpdate: (self) => console.log(self.progress.toFixed(3), self.direction)
+});
+```
+
+## ScrollTrigger.batch()
+
+**ScrollTrigger.batch(triggers, vars)** creates one ScrollTrigger per target and **batches** their callbacks (onEnter, onLeave, etc.) within a short interval — e.g. animate every element that just entered the viewport in one staggered go. Good alternative to IntersectionObserver. Returns an Array of ScrollTrigger instances.
+
+- **triggers**: selector text (e.g. `".box"`) or Array of elements.
+- **vars**: standard ScrollTrigger config (start, end, once, callbacks). Do **not** pass `trigger` or animation-related options: `animation`, `invalidateOnRefresh`, `onSnapComplete`, `onScrubComplete`, `scrub`, `snap`, `toggleActions`.
+
+**Callback signature:** Batched callbacks receive **two** parameters (unlike normal callbacks):
+1. **targets** — Array of trigger elements that fired this callback within the interval.
+2. **scrollTriggers** — Array of the ScrollTrigger instances that fired.
+
+**Batch options in vars:**
+- **interval** (Number) — Max seconds to collect each batch. Default ≈ one requestAnimationFrame.
+- **batchMax** (Number | Function) — Max elements per batch. Use a **function** returning a number for responsive layouts; it runs on refresh.
+
+```javascript
+ScrollTrigger.batch(".box", {
+  onEnter: (elements, triggers) => {
+    gsap.to(elements, { opacity: 1, y: 0, stagger: 0.15 });
+  },
+  onLeave: (elements, triggers) => {
+    gsap.to(elements, { opacity: 0, y: 100 });
+  },
+  start: "top 80%",
+  end: "bottom 20%"
+});
+```
+
+```javascript
+ScrollTrigger.batch(".card", {
+  interval: 0.1,
+  batchMax: 4,
+  onEnter: (batch) => gsap.to(batch, { opacity: 1, y: 0, stagger: 0.1, overwrite: true }),
+  onLeaveBack: (batch) => gsap.set(batch, { opacity: 0, y: 50, overwrite: true })
+});
+```
+
+See [ScrollTrigger.batch()](https://gsap.com/docs/v3/Plugins/ScrollTrigger/static.batch/).
+
+## ScrollTrigger.scrollerProxy()
+
+**ScrollTrigger.scrollerProxy(scroller, vars)** overrides how ScrollTrigger reads/writes scroll position for a scroller. Use when integrating a third-party smooth-scroll (or custom scroll) library. GSAP's **ScrollSmoother** is the built-in option and needs no proxy.
+
+- **scroller**: selector or element (e.g. `"body"`, `".container"`).
+- **vars**: object with **scrollTop** and/or **scrollLeft** functions. Each is both getter and setter: called **with** an argument = setter; **with no** argument = getter. At least one is required.
+
+**Optional in vars:**
+- **getBoundingClientRect** — Function returning `{ top, left, width, height }` for the scroller.
+- **scrollWidth** / **scrollHeight** — Getter/setter functions when the library exposes different dimensions.
+- **fixedMarkers** (Boolean) — When `true`, markers are treated as `position: fixed` (useful when the scroller is translated).
+- **pinType** — `"fixed"` or `"transform"`. Use `"fixed"` if pins jitter; `"transform"` if pins don't stick.
+
+**Critical:** When the third-party scroller updates, notify ScrollTrigger — register **ScrollTrigger.update** as a listener (e.g. `smoothScroller.addListener(ScrollTrigger.update)`), else calculations go stale.
+
+```javascript
+ScrollTrigger.scrollerProxy(document.body, {
+  scrollTop(value) {
+    if (arguments.length) scrollbar.scrollTop = value;
+    return scrollbar.scrollTop;
+  },
+  getBoundingClientRect() {
+    return { top: 0, left: 0, width: window.innerWidth, height: window.innerHeight };
+  }
+});
+scrollbar.addListener(ScrollTrigger.update);
+```
+
+See [ScrollTrigger.scrollerProxy()](https://gsap.com/docs/v3/Plugins/ScrollTrigger/static.scrollerProxy/).
+
+## Scrub
+
+Scrub ties animation progress to scroll. Use for the "scroll-driven" feel:
+
+```javascript
+gsap.to(".box", {
+  x: 500,
+  scrollTrigger: {
+    trigger: ".box",
+    start: "top center",
+    end: "bottom center",
+    scrub: true   // or a number (smoothness lag in seconds): 0.5 takes 0.5s to catch up
+  }
+});
+```
+
+## Pinning
+
+```javascript
+scrollTrigger: {
+  trigger: ".section",
+  start: "top top",
+  end: "+=1000",   // pin for 1000px scroll
+  pin: true,
+  scrub: 1
+}
+```
+
+**pinSpacing** — default `true`; adds a spacer so layout doesn't collapse when the pinned element becomes `position: fixed`. Set `pinSpacing: false` only when layout is handled separately.
+
+## Markers (Development)
+
+```javascript
+scrollTrigger: { trigger: ".box", start: "top center", end: "bottom center", markers: true }
+```
+
+Remove or set **markers: false** for production.
+
+## Timeline + ScrollTrigger
+
+Drive a timeline with scroll and optional scrub — put ScrollTrigger on the **timeline**, not a child tween:
+
+```javascript
+const tl = gsap.timeline({
+  scrollTrigger: { trigger: ".container", start: "top top", end: "+=2000", scrub: 1, pin: true }
+});
+tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });
+```
+
+## Horizontal scroll (containerAnimation)
+
+Pin a section, then as the user scrolls **vertically**, content inside moves **horizontally** ("fake" horizontal scroll). Animate **x**/**xPercent** of an element *inside* the pinned trigger, tie it to vertical scroll, and use **containerAnimation** so ScrollTrigger monitors the horizontal animation's progress.
+
+**Critical:** The horizontal tween/timeline **must** use **ease: "none"**, or scroll position and horizontal position won't line up — a very common mistake.
+
+1. Pin the section (trigger = the full-viewport panel).
+2. Build a tween animating inner content's **x**/**xPercent** with **ease: "none"**.
+3. Attach ScrollTrigger to that tween with **pin: true**, **scrub: true**.
+4. For things triggered by the horizontal movement, set **containerAnimation** to that tween.
+
+```javascript
+const scrollingEl = document.querySelector(".horizontal-el");
+const scrollTween = gsap.to(scrollingEl, {
+  xPercent: () => Math.max(0, window.innerWidth - scrollingEl.offsetWidth),
+  ease: "none", // required
+  scrollTrigger: {
+    trigger: scrollingEl,
+    pin: scrollingEl.parentNode, // wrapper so we're not animating the pinned element
+    start: "top top",
+    end: "+=1000"
+  }
+});
+
+gsap.to(".nested-el-1", {
+  y: 100,
+  scrollTrigger: {
+    containerAnimation: scrollTween, // IMPORTANT
+    trigger: ".nested-wrapper-1",
+    start: "left center", // based on horizontal movement
+    toggleActions: "play none none reset"
+  }
+});
+```
+
+**Caveats:** Pinning and snapping are not available on containerAnimation ScrollTriggers. The container animation must use **ease: "none"**. Animate a child, not the trigger element itself. If the trigger is moved, offset **start**/**end** accordingly.
+
+## Refresh and Cleanup
+
+- **ScrollTrigger.refresh()** — recalculate positions after DOM/layout changes (new content, images, fonts). Auto-called on viewport resize (debounced 200ms). Refresh runs in creation order (or by **refreshPriority**); create ScrollTriggers top-to-bottom or set **refreshPriority** so they refresh in page order.
+- When removing elements or changing pages (SPAs), **kill** stale ScrollTriggers:
+
+```javascript
+ScrollTrigger.getAll().forEach(t => t.kill());
+ScrollTrigger.getById("my-id")?.kill();
+```
+
+In React, use `useGSAP()` (@gsap/react) for automatic cleanup, or kill manually in a cleanup — see `references/react.md`.
+
+## Best practices
+
+- ✅ **gsap.registerPlugin(ScrollTrigger)** once before any use.
+- ✅ Call **ScrollTrigger.refresh()** after DOM/layout changes that affect trigger positions (viewport resize is auto-handled, debounced 200ms; dynamic content is not).
+- ✅ In React, use `useGSAP()`; elsewhere use `gsap.context()` + revert in cleanup.
+- ✅ Use **scrub** for scroll-linked progress OR **toggleActions** for discrete play/reverse — not both on the same trigger (scrub wins).
+- ✅ For fake horizontal scroll with **containerAnimation**, use **ease: "none"**.
+- ✅ Create ScrollTriggers top-to-bottom (scroll 0 → max), or set **refreshPriority** when created out of order.
+
+## Do Not
+
+- ❌ Put ScrollTrigger on a **child tween** of a timeline; put it on the **timeline** or a **top-level tween**. Wrong: `gsap.timeline().to(".a", { scrollTrigger: {...} })`. Correct: `gsap.timeline({ scrollTrigger: {...} }).to(".a", { x: 100 })`.
+- ❌ Forget **ScrollTrigger.refresh()** after DOM/layout changes.
+- ❌ Nest ScrollTriggered animations inside a parent timeline.
+- ❌ Forget **gsap.registerPlugin(ScrollTrigger)**.
+- ❌ Use **scrub** and **toggleActions** together on the same ScrollTrigger.
+- ❌ Use an ease other than **"none"** on the horizontal animation with **containerAnimation**.
+- ❌ Create ScrollTriggers in random/async order without setting **refreshPriority**.
+- ❌ Leave **markers: true** in production.
+
+### Learn More
+https://gsap.com/docs/v3/Plugins/ScrollTrigger/

package/.claude/skills/{gsap-timeline/SKILL.md → gsap-animation/references/timeline.md}

@@ -1,16 +1,6 @@
----
-name: gsap-timeline
-description: Official GSAP skill for timelines — gsap.timeline(), position parameter, nesting, playback. Use when sequencing animations, choreographing keyframes, or when the user asks about animation sequencing, timelines, or animation order (in GSAP or when recommending a library that supports timelines).
-license: MIT
----
-
 # GSAP Timeline
 
-## When to Use This Skill
-
-Apply when building multi-step animations, coordinating several tweens in sequence or parallel, or when the user asks about timelines, sequencing, or keyframe-style animation in GSAP.
-
-**Related skills:** For single tweens and eases use **gsap-core**; for scroll-driven timelines use **gsap-scrolltrigger**; for React use **gsap-react**.
+Read when sequencing multiple tweens, choreographing keyframes, or the task mentions timelines, sequencing, or animation order.
 
 ## Creating a Timeline
 
@@ -25,15 +15,13 @@ By default, tweens are **appended** one after another. Use the **position parame
 
 ## Position Parameter
 
-Third argument (or position property in vars) controls placement:
+Third argument (or `position` property in vars) controls placement:
 
 - **Absolute**: `1` — start at 1 second.
 - **Relative (default)**: `"+=0.5"` — 0.5s after end; `"-=0.2"` — 0.2s before end.
 - **Label**: `"labelName"` — at that label; `"labelName+=0.3"` — 0.3s after label.
 - **Placement**: `"<"` — start when recently-added animation starts; `">"` — start when recently-added animation ends (default); `"<0.2"` — 0.2s after recently-added animation start.
 
-Examples:
-
 ```javascript
 tl.to(".a", { x: 100 }, 0);           // at 0
 tl.to(".b", { y: 50 }, "+=0.5");      // 0.5s after last end
@@ -53,7 +41,7 @@ tl.to(".a", { x: 100 }).to(".b", { y: 50 }); // both use 0.5s and power2.out
 ## Timeline Options (constructor)
 
 - **paused: true** — create paused; call `.play()` to start.
-- **repeat**, **yoyo** — same as tweens; apply to whole timeline.
+- **repeat**, **yoyo** — same as tweens; apply to the whole timeline.
 - **onComplete**, **onStart**, **onUpdate** — timeline-level callbacks.
 - **defaults** — vars merged into every child tween.
 
@@ -67,7 +55,7 @@ tl.to(".a", { x: 100 }, "intro");
 tl.addLabel("outro", "+=0.5");
 tl.to(".b", { opacity: 0 }, "outro");
 tl.play("outro");  // start from "outro"
-tl.tweenFromTo("intro", "outro"); // pauses the timeline and returns a new Tween that animates the timeline's playhead from intro to outro with no ease.
+tl.tweenFromTo("intro", "outro"); // pauses the timeline; returns a new Tween that animates the playhead from intro to outro with no ease.
 ```
 
 ## Nesting Timelines
@@ -91,9 +79,9 @@ master.to(".c", { opacity: 0 }, "+=0.2");
 - **tl.progress(0.5)** — seek to 50%.
 - **tl.kill()** — kill timeline and (by default) its children.
 
-## Official GSAP Best practices
+## Best practices
 
-- ✅ Prefer timelines for sequencing
+- ✅ Prefer timelines for sequencing.
 - ✅ Use the **position parameter** (third argument) to place tweens at specific times or relative to labels.
 - ✅ Add **labels** with `addLabel()` for readable, maintainable sequencing.
 - ✅ Pass **defaults** into the timeline constructor so child tweens inherit duration, ease, etc.
@@ -103,5 +91,5 @@ master.to(".c", { opacity: 0 }, "+=0.2");
 
 - ❌ Chain animations with **delay** when a **timeline** can sequence them; prefer `gsap.timeline()` and the position parameter for multi-step animation.
 - ❌ Forget to pass **defaults** (e.g. `defaults: { duration: 0.5, ease: "power2.out" }`) when many child tweens share the same duration or ease.
-- ❌ Forget that **duration** on the timeline constructor is not the same as tween duration; timeline “duration” is determined by its children.
+- ❌ Confuse **duration** on the timeline constructor with tween duration; a timeline's "duration" is determined by its children.
 - ❌ Nest animations that contain a ScrollTrigger; ScrollTriggers should only be on top-level Tweens/Timelines.

package/.claude/skills/gsap-animation/references/utils.md

@@ -0,0 +1,254 @@
+# gsap.utils
+
+Read when using **gsap.utils** for math, array/collection handling, unit parsing, or value mapping in animations (e.g. mapping scroll to a value, randomizing, snapping to a grid, normalizing inputs).
+
+## Overview
+
+**gsap.utils** provides pure helpers; no registration needed. Use in tween vars (function-based values), in ScrollTrigger or Observer callbacks, or any JS that drives GSAP. All are on **gsap.utils** (e.g. `gsap.utils.clamp()`).
+
+**Omitting the value: function form.** Many utils accept the value to transform as the **last** argument. Omit it and the util returns a **function** that accepts the value later — use this when clamping/mapping/normalizing/snapping many values with the same config (e.g. a mousemove handler). **Exception: random()** — pass **true** as the last argument for a reusable function (do not omit the value).
+
+```javascript
+// With value: returns the result
+gsap.utils.clamp(0, 100, 150); // 100
+
+// Without value: returns a function you call later
+let c = gsap.utils.clamp(0, 100);
+c(150);  // 100
+c(-10);  // 0
+```
+
+## Clamping and Ranges
+
+### clamp(min, max, value?)
+
+Constrains a value between min and max.
+
+```javascript
+gsap.utils.clamp(0, 100, 150); // 100
+gsap.utils.clamp(0, 100, -10); // 0
+
+let clampFn = gsap.utils.clamp(0, 100);
+clampFn(150); // 100
+```
+
+### mapRange(inMin, inMax, outMin, outMax, value?)
+
+Maps a value from one range to another. Use when converting scroll position, progress (0–1), or input range to an animation range.
+
+```javascript
+gsap.utils.mapRange(0, 100, 0, 500, 50);  // 250
+gsap.utils.mapRange(0, 1, 0, 360, 0.5);   // 180 (progress to degrees)
+
+let mapFn = gsap.utils.mapRange(0, 100, 0, 500);
+mapFn(50);  // 250
+```
+
+### normalize(min, max, value?)
+
+Returns a value normalized to 0–1 for the given range.
+
+```javascript
+gsap.utils.normalize(0, 100, 50);    // 0.5
+gsap.utils.normalize(100, 300, 200); // 0.5
+```
+
+### interpolate(start, end, progress?)
+
+Interpolates between two values at a given progress (0–1). Handles numbers, colors, and objects with matching keys.
+
+```javascript
+gsap.utils.interpolate(0, 100, 0.5);               // 50
+gsap.utils.interpolate("#ff0000", "#0000ff", 0.5); // mid color
+gsap.utils.interpolate({ x: 0, y: 0 }, { x: 100, y: 50 }, 0.5); // { x: 50, y: 25 }
+
+let lerp = gsap.utils.interpolate(0, 100);
+lerp(0.5); // 50
+```
+
+## Random and Snap
+
+### random(minimum, maximum[, snapIncrement, returnFunction]) / random(array[, returnFunction])
+
+Returns a random number in the range, or a random element from an **array**. Optional **snapIncrement** snaps to the nearest multiple. **For a reusable function, pass true as the last argument** (returnFunction) — the only util that uses `true` instead of omitting the value.
+
+```javascript
+gsap.utils.random(-100, 100);  // e.g. 42.7
+gsap.utils.random(0, 500, 5);  // 0–500, snapped to nearest 5
+
+let randomFn = gsap.utils.random(-200, 500, 10, true);
+randomFn();  // random value in range, snapped to 10
+
+gsap.utils.random(["red", "blue", "green"]); // one at random
+let randomFromArray = gsap.utils.random([0, 100, 200], true);
+randomFromArray(); // 0, 100, or 200
+```
+
+**String form in tween vars:** `"random(-100, 100)"`, `"random(-100, 100, 5)"`, or `"random([0, 100, 200])"`; GSAP evaluates per target.
+
+```javascript
+gsap.to(".box", { x: "random(-100, 100, 5)", duration: 1 });
+gsap.to(".item", { backgroundColor: "random([red, blue, green])" });
+```
+
+### snap(snapTo, value?)
+
+Snaps to the nearest multiple of **snapTo**, or to the nearest value in an array.
+
+```javascript
+gsap.utils.snap(10, 23);             // 20
+gsap.utils.snap(0.25, 0.7);          // 0.75
+gsap.utils.snap([0, 100, 200], 150); // 100 or 200
+
+let snapFn = gsap.utils.snap(10);
+snapFn(23); // 20
+```
+
+In tweens for grid/step-based animation:
+
+```javascript
+gsap.to(".x", { x: 200, snap: { x: 20 } });
+```
+
+### shuffle(array)
+
+Returns a new array with the same elements in random order.
+
+```javascript
+gsap.utils.shuffle([1, 2, 3, 4]); // e.g. [3, 1, 4, 2]
+```
+
+### distribute(config)
+
+**Returns a function** that assigns a value to each target based on its position in the array (or grid). Used internally for advanced staggers; use whenever values must spread across many elements (scale, opacity, x, delay). The returned function receives `(index, target, targets)` — call it manually or pass it directly into a tween.
+
+**Config (all optional):**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `base` | Number | Starting value. Default `0`. |
+| `amount` | Number | Total distributed across all targets (added to base). E.g. `amount: 1` with 100 targets → 0.01 between each. |
+| `each` | Number | Amount added between each target. E.g. `each: 1` with 4 targets → 0, 1, 2, 3. |
+| `from` | Number \| String \| Array | Where distribution starts: index, `"start"`, `"center"`, `"edges"`, `"random"`, `"end"`, or ratios like `[0.25, 0.75]`. Default `0`. |
+| `grid` | String \| Array | Grid position instead of flat index: `[rows, columns]` or `"auto"`. |
+| `axis` | String | For grid: limit to one axis (`"x"` or `"y"`). |
+| `ease` | Ease | Distribute along an ease curve. Default `"none"`. |
+
+```javascript
+// Scale: middle elements 0.5, outer edges 3 (amount 2.5 from center)
+gsap.to(".class", {
+  scale: gsap.utils.distribute({ base: 0.5, amount: 2.5, from: "center" })
+});
+```
+
+**Manual use:** call the returned function with `(index, target, targets)`.
+
+```javascript
+const distributor = gsap.utils.distribute({ base: 50, amount: 100, from: "center", ease: "power1.inOut" });
+const targets = gsap.utils.toArray(".box");
+const valueForIndex2 = distributor(2, targets[2], targets);
+```
+
+See [distribute()](https://gsap.com/docs/v3/GSAP/UtilityMethods/distribute/).
+
+## Units and Parsing
+
+### getUnit(value)
+
+Returns the unit string of a value (`"px"`, `"%"`, `"deg"`).
+
+```javascript
+gsap.utils.getUnit("100px"); // "px"
+gsap.utils.getUnit("50%");   // "%"
+gsap.utils.getUnit(42);      // "" (unitless)
+```
+
+### unitize(value, unit)
+
+Appends a unit to a number, or returns the value unchanged if it already has one.
+
+```javascript
+gsap.utils.unitize(100, "px");    // "100px"
+gsap.utils.unitize("2rem", "px"); // "2rem" (unchanged)
+```
+
+### splitColor(color, returnHSL?)
+
+Converts a color string into an array: **[r, g, b]** (0–255) or **[r, g, b, a]** for RGBA. Pass **true** as the second argument (returnHSL) to get **[h, s, l]** / **[h, s, l, a]**. Works with `rgb()`, `rgba()`, `hsl()`, `hsla()`, hex, and named colors.
+
+```javascript
+gsap.utils.splitColor("red");                     // [255, 0, 0]
+gsap.utils.splitColor("#6fb936");                 // [111, 185, 54]
+gsap.utils.splitColor("rgba(204, 153, 51, 0.5)"); // [204, 153, 51, 0.5]
+gsap.utils.splitColor("#6fb936", true);           // [94, 55, 47] (HSL)
+```
+
+See [splitColor()](https://gsap.com/docs/v3/GSAP/UtilityMethods/splitColor/).
+
+## Arrays and Collections
+
+### selector(scope)
+
+Returns a scoped selector function that finds elements only within the given element (or ref). Use in components so `".box"` matches only descendants. Accepts a DOM element or a ref (handles `.current`).
+
+```javascript
+const q = gsap.utils.selector(containerRef);
+q(".box");        // array of .box elements inside container
+gsap.to(q(".circle"), { x: 100 });
+```
+
+### toArray(value, scope?)
+
+Converts a value to an array: selector string (scoped to element), NodeList, HTMLCollection, single element, or array.
+
+```javascript
+gsap.utils.toArray(".item");            // array of elements
+gsap.utils.toArray(".item", container); // scoped to container
+gsap.utils.toArray(nodeList);           // [ ... ] from NodeList
+```
+
+### pipe(...functions)
+
+Composes functions: **pipe(f1, f2, f3)(value)** returns f3(f2(f1(value))). Use for a chain of transforms (e.g. normalize → mapRange → snap).
+
+```javascript
+const fn = gsap.utils.pipe(
+  (v) => gsap.utils.normalize(0, 100, v),
+  (v) => gsap.utils.snap(0.1, v)
+);
+fn(50); // normalized then snapped
+```
+
+### wrap(min, max, value?)
+
+Wraps a value into the range min–max (inclusive min, exclusive max). Use for infinite scroll or cyclic values.
+
+```javascript
+gsap.utils.wrap(0, 360, 370); // 10
+gsap.utils.wrap(0, 360, -10); // 350
+
+let wrapFn = gsap.utils.wrap(0, 360);
+wrapFn(370); // 10
+```
+
+### wrapYoyo(min, max, value?)
+
+Wraps a value in range with a yoyo (bounces at ends).
+
+```javascript
+gsap.utils.wrapYoyo(0, 100, 150); // 50 (bounces back)
+```
+
+## Best practices
+
+- ✅ Omit the value argument to get a reusable function when the same range/config is used many times (e.g. `let mapFn = gsap.utils.mapRange(0, 1, 0, 360); mapFn(progress)`).
+- ✅ Use **snap** for grid-aligned or step-based values; use **toArray** when a real array is needed from a selector or NodeList.
+- ✅ Use **gsap.utils.selector(scope)** in components so selectors are scoped to a container or ref.
+
+## Do Not
+
+- ❌ Assume **mapRange** / **normalize** handle units; they work on numbers. Use **getUnit** / **unitize** when units matter.
+- ❌ Override or rely on undocumented behavior; stick to the documented API.
+
+### Learn More
+https://gsap.com/docs/v3/HelperFunctions

package/.claude/skills/judgment-day/SKILL.md

@@ -4,6 +4,9 @@ description: "Trigger: judgment day, dual review, adversarial review, juzgar. Ru
 license: Apache-2.0
 metadata:
   author: gentleman-programming
+  adapted-by: "Juan Carlos Cadavid — jcadavid.com"
+  adapted-for: "AKILI-SPECS"
+  binding: core
   version: "1.6"
 ---
 
@@ -49,4 +52,19 @@ Return target identity, round, confirmed/suspect/contradiction/INFO counts, corr
 ## References
 
 - [../_shared/review-ledger-contract.md](../_shared/review-ledger-contract.md) — canonical transaction, ledger, persistence, and lifecycle contract.
-- [references/prompts-and-formats.md](references/prompts-and-formats.md) — compact judge/fix prompts and verdict shape.
+- [references/prompts-and-formats.md](references/prompts-and-formats.md) — compact judge/fix prompts and verdict shape.
+
+These reference files are not packaged with AKILI-SPECS. When they are unavailable, proceed with the contract described in this document alone: persist the findings ledger inside the spec folder (see below) and derive judge prompts from the Hard Rules and Output Contract.
+
+## AKILI-SPECS Integration
+
+| AKILI moment | How to use this skill |
+|---|---|
+| `/akili-specify` Step 2.3 — **Review Design** option | The user-selected blind dual review of `design.md` before tasks are written; the target is the approved requirements + draft design |
+| `/akili-archive` Kaizen Measure | Severe confirmed findings from Judgment Day runs are a signal row in the `kaizen` retrospective |
+
+Adaptation rules:
+
+- Persist the findings ledger as `docs/specs/<spec-path>/judgment.md` so `/akili-archive` can read it as evidence.
+- The two-judge blind protocol, the two-round fix ceiling, and the `APPROVED`/`ESCALATED` terminal states apply unchanged.
+- Prefer running the two judges on a model different from the one that authored the design (author ≠ auditor, per AKILI model routing).

package/.claude/skills/kaizen/SKILL.md

@@ -4,6 +4,7 @@ description: "Trigger: kaizen, retrospective, continuous improvement, mejora con
 license: MIT
 metadata:
   author: Juan Carlos Cadavid — jcadavid.com
+  binding: core
   version: "1.0"
   inspired-by: "Kaizen Institute glossary (kaizen.com), 'El Método Kaizen' (small-steps approach, Robert Maurer), 'Emprendiendo Kaizen' (INTI, 2019, ISBN 978-950-532-415-6)"
 ---

package/.claude/skills/nestjs-expert/SKILL.md

@@ -4,6 +4,14 @@ description: Nest.js framework expert specializing in module architecture, depen
 category: framework
 displayName: Nest.js Framework Expert
 color: red
+license: MIT
+metadata:
+  author: Daniel Avila (davila7)
+  source: https://github.com/davila7/claude-code-templates
+  adapted-by: "Juan Carlos Cadavid — jcadavid.com"
+  adapted-for: "AKILI-SPECS"
+  binding: stack
+  version: "1.0"
 ---
 
 # Nest.js Expert

package/.claude/skills/product-manager-toolkit/SKILL.md

@@ -1,8 +1,14 @@
 ---
 name: product-manager-toolkit
 description: Comprehensive toolkit for product managers including RICE prioritization, customer interview analysis, PRD templates, discovery frameworks, and go-to-market strategies. Use for feature prioritization, user research synthesis, requirement documentation, and product strategy development. In AKILI-SPECS projects, follow the AKILI-SPECS Integration section first.
+license: MIT
 metadata:
-  adapted-for: "AKILI-SPECS methodology by Juan Carlos Cadavid — jcadavid.com"
+  author: Alireza Rezvani (alirezarezvani)
+  source: https://github.com/alirezarezvani/claude-skills
+  adapted-by: "Juan Carlos Cadavid — jcadavid.com"
+  adapted-for: "AKILI-SPECS"
+  binding: core
+  version: "1.0"
 ---
 
 # Product Manager Toolkit

package/.claude/skills/react-doctor/SKILL.md

@@ -2,6 +2,12 @@
 name: react-doctor
 description: Run after making React changes to catch issues early. Use when reviewing code, finishing a feature, or fixing bugs in a React project.
 version: 1.0.0
+metadata:
+  author: Million.dev (millionco)
+  source: https://github.com/millionco/react-doctor
+  adapted-by: "Juan Carlos Cadavid — jcadavid.com"
+  adapted-for: "AKILI-SPECS"
+  binding: stack
 ---
 
 # React Doctor