@topy-ai/maggie 0.8.11 → 0.8.13

package/bundled-references/web-animation-patterns.md

@@ -0,0 +1,364 @@
+# Web / UI animation patterns
+
+Engine-neutral motion vocabulary for marketing web pages, distilled from the leading
+open-source animation libraries. We adopt **patterns and per-library guidance, not
+code** — we rarely ship these libraries; we copy the technique (the eases, the
+IntersectionObserver reveal, the spring config, the Lottie workflow). Feeds
+`maggie-landing-page` (B7 motion + the mandatory tagline reveal) and
+`maggie-design-motion` (its *website* context).
+
+Rule of thumb: a marketing page needs **CSS transitions + IntersectionObserver +
+one tiny helper** far more often than a 30KB animation engine. Reach for a library
+only when the pattern below says so. Default is zero-dependency.
+
+---
+
+## 1. The libraries
+
+Each entry: what it is · core API shape (real snippet) · license · when to reach for it.
+
+### GSAP (greensock/GSAP) — v3.15
+Framework-agnostic JS animation engine: tweens, timelines, eases, plugins
+(ScrollTrigger, SplitText, MorphSVG, Flip, MotionPath). The gold standard for
+sequenced, scroll-driven work.
+```js
+gsap.registerPlugin(ScrollTrigger);
+const tl = gsap.timeline({ defaults: { ease: "power3.out", duration: 0.6 } });
+tl.from(".hero h1", { y: 40, opacity: 0 })
+  .from(".hero p",  { y: 24, opacity: 0 }, "-=0.3");   // overlap previous by 0.3s
+gsap.from(".card", {
+  scrollTrigger: { trigger: ".card", start: "top 80%", once: true },
+  y: 32, opacity: 0, stagger: 0.08,
+});
+```
+**License: custom "Standard no-charge license" (NOT MIT/OSI).** As of 2024 (Webflow)
+GSAP including all former Club plugins is 100% free for commercial use, but it is a
+proprietary license, not open source — flag it before bundling. CDN:
+`cdn.jsdelivr.net/npm/gsap@3.15/dist/gsap.min.js`.
+**Reach for it when:** a page needs a real timeline (chained, overlapping steps) or
+scroll-scrubbed sequencing beyond a one-shot reveal. Overkill for simple fades.
+
+### Motion / framer-motion (motiondivision/motion)
+Hybrid engine: a tiny imperative `animate()` for vanilla JS plus declarative
+`<motion.div>` for React/Vue. Uses the native WAAPI where possible (GPU, 120fps),
+springs, `scroll()`, `inView()`, layout transitions.
+```js
+import { animate, inView, scroll, stagger } from "motion";
+animate("#box", { x: 100, opacity: 1 }, { type: "spring", stiffness: 300, damping: 30 });
+inView(".card", (el) => { animate(el, { opacity: 1, y: 0 }); }, { amount: 0.3 });
+// React: <motion.div initial={{opacity:0,y:24}} whileInView={{opacity:1,y:0}} viewport={{once:true}}/>
+```
+**License: MIT** (core; a paid "Motion+" add-on exists but isn't required).
+**Reach for it when:** the project is already React/Vue, or you want springs +
+scroll + inView from one small MIT lib. `inView` is a clean IntersectionObserver
+wrapper — our preferred engine when a dependency is acceptable.
+
+### anime.js (juliangarnier/anime) — v4
+Small, elegant timeline/stagger/easing lib. V4 is ESM tree-shakable.
+```js
+import { animate, stagger } from "animejs";
+animate(".square", {
+  x: 320, rotate: { from: -180 }, duration: 1250,
+  delay: stagger(65, { from: "center" }), ease: "inOutQuint",
+});
+```
+**License: MIT.** **Reach for it when:** you want expressive staggers/keyframes
+lighter than GSAP and don't need ScrollTrigger-grade scroll control.
+
+### lottie-web (airbnb/lottie-web)
+Plays **Lottie JSON** (vector animations exported from After Effects via Bodymovin)
+in the browser as SVG/canvas/HTML.
+```js
+const anim = lottie.loadAnimation({
+  container: el, renderer: "svg", loop: true, autoplay: true,
+  path: "hero.json",                       // or animationData: <obj>
+});
+anim.playSegments([0, 60], true);          // play part of the timeline
+anim.setSpeed(1); anim.pause();
+```
+**License: MIT.** **Reach for it when:** a designer delivers an AE/Lottie file and
+you need a crisp, scalable, small looped illustration (see §2 Lottie workflow).
+Default to `renderer: "svg"`; switch to `canvas` for heavy/many-layer files.
+
+### rlottie (Samsung/rlottie)
+Native (C++) Lottie renderer — the runtime behind Lottie on native/embedded (not a
+web lib). Category O. **License: MIT** (mostly; some vendored parts differ, see
+COPYING). **Reach for it when:** the same Lottie JSON must also play in a native app
+(our Expo/RN surfaces) — same asset, native renderer. On web it's lottie-web.
+
+### theatre.js (theatre-js/theatre)
+In-browser motion-design **editor**: scrub a timeline, keyframe any JS object's
+props, then play the saved sequence at runtime via `@theatre/core`.
+```js
+import { getProject } from "@theatre/core";
+const sheet = getProject("Hero").sheet("Intro");
+const obj = sheet.object("Logo", { x: 0, opacity: 0 });
+obj.onValuesChange((v) => { el.style.transform = `translateX(${v.x}px)`; el.style.opacity = v.opacity; });
+sheet.sequence.play({ iterationCount: 1 });
+```
+**License: Apache-2.0.** **Reach for it when:** a complex bespoke sequence is easier
+to hand-author on a timeline than in code. Niche for marketing pages; mostly a
+design-time tool. Note for `maggie-design-motion`, not landing pages.
+
+### auto-animate (formkit/auto-animate)
+Zero-config: one call and children added/removed/moved animate automatically.
+```js
+import autoAnimate from "@formkit/auto-animate";
+autoAnimate(document.getElementById("list"));   // React: const [ref] = useAutoAnimate()
+```
+**License: MIT.** **Reach for it when:** lists, filters, accordions, or reordering UI
+need smooth transitions with no keyframes. Great low-effort polish for interactive
+sections (pricing toggles, FAQ, filtered galleries).
+
+### AOS (michalsnik/aos)
+Animate-on-scroll via HTML data-attributes + a prebuilt CSS set.
+```html
+<div data-aos="fade-up" data-aos-delay="50" data-aos-duration="800"
+     data-aos-once="true" data-aos-anchor-placement="top-center"></div>
+<script>AOS.init({ once: true, duration: 800, easing: "ease-out-cubic" });</script>
+```
+**License: MIT.** Uses IntersectionObserver internally. **Reach for it when:** a
+no-JS-authoring team wants declarative scroll reveals fast. For our output we
+usually hand-roll the same effect (§2) rather than ship AOS, but its attribute
+vocabulary (`fade-up`, `once`, per-element delay/offset) is the pattern to copy.
+
+### typed.js (mattboldt/typed.js)
+Typewriter effect.
+```js
+const typed = new Typed("#el", { strings: ["First.", "& second."], typeSpeed: 50, backSpeed: 30, loop: true });
+```
+**License: GPL — flag it.** GNU GPL, not MIT. Do **not** bundle into proprietary
+output; reimplement the ~20-line effect yourself (or use a permissive alt) if you
+need typing. **Reach for the pattern when:** a hero rotates through phrases. Keep it
+short, respect reduced-motion (render the final string statically).
+
+### tsparticles (tsparticles/tsparticles)
+Config-driven particle backgrounds/confetti.
+```js
+await tsParticles.load({ id: "tsparticles", options: {
+  background: { color: "#0d1117" },
+  particles: { number: { value: 60 }, move: { enable: true } },
+}});
+```
+**License: MIT.** **Reach for it when:** a hero wants a subtle particle/constellation
+backdrop or a celebratory confetti burst. Use sparingly — it's a performance and
+taste liability; cap particle count, pause offscreen, disable on reduced-motion.
+
+### rive (rive-app/rive-runtime)
+Interactive vector animations driven by **state machines** (inputs → states), not
+just linear playback. `rive-runtime` is the C++ core; on web you use `@rive-app/canvas`.
+```js
+import { Rive } from "@rive-app/canvas";
+const r = new Rive({ src: "button.riv", canvas, autoplay: true,
+  stateMachines: "State Machine 1", onLoad: () => r.resizeDrawingSurfaceToCanvas() });
+r.stateMachineInputs("State Machine 1").find(i => i.name === "hover").value = true;
+```
+**License: MIT.** **Reach for it when:** an element must *react* (hover/click/scroll
+drives animation state) — interactive mascots, animated toggles. Heavier workflow
+(needs the Rive editor); overkill for passive decoration — prefer Lottie for that.
+
+### vivus (maxwellito/vivus)
+Animates SVG stroke draw-on ("self-drawing" line art).
+```js
+new Vivus("my-svg", { type: "oneByOne", duration: 200, start: "inViewport" }, cb);
+// type: delayed | sync | oneByOne | scenario ; start: inViewport | manual | autostart
+```
+**License: MIT.** **Reach for it when:** a logo/icon/diagram should draw itself in.
+The same effect is achievable with CSS `stroke-dasharray`/`stroke-dashoffset` — use
+that for one element, Vivus when orchestrating many paths.
+
+### lenis (darkroomengineering/lenis)
+Smooth-scroll normalizer (momentum/eased scrolling). Already referenced by
+`maggie-clone`.
+```js
+const lenis = new Lenis({ autoRaf: true });     // or drive lenis.raf(t) in your own rAF
+lenis.on("scroll", (e) => {/* sync scroll-linked effects */});
+```
+**License: MIT.** **Reach for it when:** the design calls for premium eased scrolling
+and you pair it with scroll-triggered motion (commonly `lenis.raf` + GSAP
+ScrollTrigger). Accessibility caveat: disable/reduce under `prefers-reduced-motion`;
+never trap or override scroll in a way that breaks keyboard/anchor jumps.
+
+### barba.js (barbajs/barba)
+SPA-style page transitions over MPAs: intercepts navigation, animates the old
+container out and the new one in (no full reload).
+```js
+barba.init({ transitions: [{
+  name: "fade",
+  leave: ({ current }) => gsap.to(current.container, { opacity: 0 }),
+  enter: ({ next })    => gsap.from(next.container, { opacity: 0 }),
+}]});
+// markup: <main data-barba="wrapper"><section data-barba="container" data-barba-namespace="home">
+```
+**License: MIT.** **Reach for it when:** a multi-page marketing site wants seamless
+cross-page transitions. Needs care for SEO/analytics/scroll-restore; often more than
+a landing page needs.
+
+### react-spring (pmndrs/react-spring)
+Spring-physics animation for React (hooks).
+```js
+import { animated, useSpring } from "@react-spring/web";
+const styles = useSpring({ from: { opacity: 0, y: 24 }, to: { opacity: 1, y: 0 } });
+return <animated.div style={styles}>…</animated.div>;
+```
+**License: MIT.** **Reach for it when:** a React project wants physics-based
+(not duration-based) motion. For non-React, Motion's `spring` covers the same need.
+
+### animate.css (animate-css/animate.css)
+Prebuilt CSS keyframe classes (`animate__animated animate__fadeInUp`).
+```html
+<h1 class="animate__animated animate__fadeInUp">Hi</h1>
+```
+**License: Hippocratic License 2.1 — flag it (NOT MIT).** An ethical-source license
+with use restrictions; not OSI-approved. Treat as a caution for commercial bundling;
+the keyframe recipes (`fadeInUp`, durations, timing) are fine to **reimplement**
+yourself. **Reach for the patterns when:** you want a quick named-entrance
+vocabulary — but author your own keyframes to stay license-clean.
+
+### Category O (offline / desktop, NOT web)
+- **synfig** (synfig/synfig) — desktop 2D vector animation studio. **GPL-3.0.**
+- **friction** (friction2d/friction) — desktop motion-graphics/vector animator.
+  **GPL-3.0.** Sparse docs.
+Both are authoring tools, not runtimes. Note as offline/GPL; they can *produce*
+assets (e.g. exported video/sequences) but nothing here ships to the web.
+
+---
+
+## 2. Engine-neutral pattern set (what we actually adopt)
+
+For each pattern: the technique, which libs embody it, and where it belongs
+(**LP** = `maggie-landing-page`, **DM** = `maggie-design-motion` website context).
+
+### Eased entrances — the good cubic-beziers
+Default to expressive ease-out curves, never browser defaults (`ease`, `linear`,
+`ease-in-out`). House base curve: `cubic-bezier(0.22, 1, 0.36, 1)` ("ease-out-quint",
+~500ms for layout/position; GSAP's `power3/power4.out` equivalent). Hover
+color/opacity 300ms (never < 200ms). Other good ones: `cubic-bezier(0.16,1,0.3,1)`
+(ease-out-expo), `cubic-bezier(0.34,1.56,0.64,1)` (gentle back/overshoot).
+Libs: GSAP eases, anime `inOut*`, Motion. **LP + DM.**
+
+### Spring physics
+Duration-less, physics-based motion — natural for interactive/hover and anything
+that should feel tactile. Config shape is universal: `{ stiffness, damping, mass }`
+(Motion: `type:"spring", stiffness:300, damping:30`; react-spring: `config.gentle`).
+Libs: Motion `spring`, react-spring, GSAP (via plugins). **DM;** light touch on LP
+(mostly micro-interactions).
+
+### Scroll-reveal via IntersectionObserver — never scroll listeners
+Elements rise ~32px and fade over 600–800ms, **once**, when they cross into view.
+Always IntersectionObserver (or a lib that wraps it); never an unthrottled `scroll`
+listener. Engine-neutral baseline (no dependency):
+```js
+const io = new IntersectionObserver((entries) => {
+  for (const e of entries) if (e.isIntersecting) {
+    e.target.classList.add("in");           // CSS transitions transform+opacity
+    io.unobserve(e.target);                 // once
+  }
+}, { threshold: 0.2, rootMargin: "0px 0px -10% 0px" });
+document.querySelectorAll("[data-reveal]").forEach((el) => io.observe(el));
+```
+Libs that embody it: Motion `inView`, AOS (`data-aos` + `once`), GSAP ScrollTrigger
+(`once:true`). **LP (core) + DM.**
+
+### Stagger
+Sequence a group so items arrive one after another (reading order), stepped
+~60–80ms, capped (~400ms total for menus). Libs: GSAP `stagger`, anime
+`stagger(65,{from:"center"})`, Motion `stagger`. Hand-rolled: per-item
+`transition-delay: calc(var(--i) * 60ms)`. **LP (menu entrance, card grids) + DM.**
+
+### SVG draw-on
+Line art draws itself via `stroke-dasharray`/`stroke-dashoffset` animated to 0.
+Libs: Vivus (`type:"oneByOne"`), or pure CSS for a single path. **DM (logos,
+diagrams);** occasional LP hero accent.
+
+### Typing
+Rotate/type phrases in a hero. Pattern: type → pause → delete → next, respect
+reduced-motion by rendering the final string. Lib: typed.js (**GPL — reimplement**,
+don't bundle). **LP (hero headline variants) + DM.**
+
+### Page transitions + smooth scroll
+Cross-page: animate container out/in instead of a hard reload (barba.js, or a
+framework's view-transitions). Smooth scroll: eased momentum scrolling (lenis),
+commonly paired with scroll-triggered motion (`lenis.raf` → GSAP ScrollTrigger).
+**DM / full-site builds;** a single landing page rarely needs barba. Lenis already
+used by `maggie-clone`.
+
+### Particles
+Subtle generative backdrop or confetti. Lib: tsparticles (config: `particles.number`,
+`move`, `background`). Use sparingly; cap count, pause offscreen, kill on
+reduced-motion. **LP hero (optional accent) + DM.**
+
+### The Lottie workflow
+Pipeline: **design in After Effects → export with Bodymovin → `.json` →** play with
+**lottie-web** on web / **rlottie** on native (same JSON asset, two renderers).
+```js
+lottie.loadAnimation({ container: el, renderer: "svg", loop: true, autoplay: true, path: "hero.json" });
+```
+**When to use Lottie vs code vs looped video:**
+- **Lottie** — designer-authored vector illustration/icon motion; scalable, crisp,
+  small, loopable, recolorable, interactive (segments/speed). The default for
+  "animated illustration." Prefer `renderer:"svg"`; use `canvas` for heavy files.
+- **Code (CSS/GSAP/Motion)** — UI motion tied to the DOM: entrances, hovers,
+  scroll reveals, state changes. Anything that must respond to layout/interaction.
+- **Looped video (mp4/webm)** — photographic/complex/3D content that isn't vector
+  and doesn't need interaction or recolor. Heaviest payload; provide a poster and
+  `prefers-reduced-motion` fallback. (See `references/programmatic-video.md`.)
+Libs: lottie-web (web), rlottie (native). **DM (primary);** LP for a hero/spot
+illustration when a designer supplies the JSON.
+
+---
+
+## 3. Performance & accessibility rules (shared by all of them)
+
+- **Animate only `transform` and `opacity`.** Never `top`/`left`/`width`/`height`/
+  `margin` (they trigger layout/paint and jank). Use `transform: translate/scale`
+  for position and size. Prefer the compositor; add `will-change` only on the
+  element about to animate, and remove it after.
+- **No scroll/resize listeners for reveal.** Use IntersectionObserver for visibility
+  and `requestAnimationFrame` for any per-frame work; throttle/debounce the rest.
+  Never run animation logic directly in a `scroll` handler.
+- **Respect `prefers-reduced-motion`.** Replace movement with a plain opacity change
+  (or show the final state instantly). Gate every nontrivial effect:
+  ```css
+  @media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after { animation-duration:.01ms!important;
+      animation-iteration-count:1!important; transition-duration:.01ms!important; }
+  }
+  ```
+  In JS, branch on `matchMedia("(prefers-reduced-motion: reduce)").matches` before
+  typing, particles, smooth-scroll, or autoplay loops.
+- **Reveal once; don't re-fire** on scroll-back (`once:true` / `unobserve`).
+- **Pause offscreen / on hidden tab** (Lottie, particles, video): check
+  `document.hidden` / IntersectionObserver and stop rAF to save battery/CPU.
+- **Keep durations honest:** entrances 300–800ms; hovers 200–300ms; never block
+  interaction or delay content paint behind an animation. Don't animate above the
+  fold in a way that hides LCP text.
+
+---
+
+## License quick-reference
+
+| Library | License | Note |
+|---|---|---|
+| GSAP | Custom "no-charge" | **Not OSI/MIT.** Free (incl. all plugins) but proprietary — flag before bundling. |
+| Motion / framer-motion | MIT | Paid Motion+ add-on optional, not required. |
+| anime.js | MIT | |
+| lottie-web | MIT | |
+| rlottie | MIT | Some vendored parts differ (see COPYING). |
+| theatre.js | Apache-2.0 | |
+| auto-animate | MIT | |
+| AOS | MIT | |
+| typed.js | **GPL** | **Flag — don't bundle in proprietary output; reimplement.** |
+| tsparticles | MIT | |
+| rive-runtime | MIT | Web runtime is `@rive-app/canvas`. |
+| vivus | MIT | |
+| lenis | MIT | |
+| barba.js | MIT | |
+| react-spring | MIT | |
+| animate.css | **Hippocratic 2.1** | **Flag — ethical-source, not OSI. Reimplement keyframes.** |
+| synfig / friction | GPL-3.0 | Desktop authoring tools (category O), not web runtimes. |
+
+Most are MIT and safe to reference/learn from freely. The four to flag: **GSAP**
+(proprietary no-charge), **typed.js** (GPL), **animate.css** (Hippocratic 2.1), and
+**synfig/friction** (GPL desktop tools). For the flagged ones we adopt the *pattern*
+and author our own code.

package/bundled-skills/catalog.json

@@ -66,6 +66,10 @@
       "name": "maggie-fundraising",
       "description": "Fundraising and investor relations for a founder - draft a pitch deck and narrative, assemble a data room, write investor updates, keep cap-table and round hygiene, and prepare SEIS/EIS materials. Use when the user asks to prepare to raise, build a deck or data room, write an investor update, or organise round documents. Factual only; not securities, investment, legal, or tax advice. Pairs with maggie-finance and the TOPY/CEO tools."
     },
+    {
+      "name": "maggie-image",
+      "description": "Process marketing images - resize and fit to channel/OG sizes, convert to WebP/AVIF, make favicon and OG-image sets, strip metadata, compress, optimize and render SVG, and build contact-sheet montages. A recipe generator over ImageMagick (primary) with dedicated tools (svgo/resvg/cwebp/avifenc/pngquant) used when installed. Use when the user wants to resize, convert, optimize, favicon, watermark, or batch-process images for a site or social post."
+    },
     {
       "name": "maggie-landing-page",
       "description": "Build a high-converting landing page - intake, page structure, layout selection, conversion copy, SEO/AEO, plus a visual-system discipline (typography, spacing, radius, backgrounds, hero, icons, motion) whose specific values are defaults the project's DESIGN.md overrides. Use when building, editing, styling, or writing copy for a landing page, marketing page, or a page section meant to convert. Designs the page; maggie-design produces and validates it."

package/bundled-skills/maggie-design/SKILL.md

@@ -2,7 +2,7 @@
 name: maggie-design
 description: Design authorized interior pages, review rendered responsive layouts, explicitly rebrand a packaged homepage/template, or audit and upgrade an existing site/app in place (fix generic AI-design patterns, weak states, and sloppy code). Use rebrand only with a named source brand and target brand. Use the redesign audit whenever the user wants to improve, polish, upgrade, refine, audit, or redesign an existing page, even when they just say it looks cheap, generic, or AI-made.
 metadata:
-  version: 1.7.0
+  version: 1.7.1
 ---
 
 # Maggie Design
@@ -21,7 +21,12 @@ Concrete values come from
 overridden by the project's own DESIGN.md/tokens. For building a new landing page
 from scratch use [`maggie-landing-page`](../maggie-landing-page/SKILL.md); for
 turning a design into an animated showcase use
-[`maggie-design-motion`](../maggie-design-motion/SKILL.md).
+[`maggie-design-motion`](../maggie-design-motion/SKILL.md). For page visuals and
+assets: process images with [`maggie-image`](../maggie-image/SKILL.md)
+([recipes](../../references/image-recipes.md)), add motion from
+[web animation patterns](../../references/web-animation-patterns.md), and generate
+code-drawn backgrounds/3D/stylized art from
+[generative visuals](../../references/generative-visuals.md).
 
 ## In-place route evidence
 

package/bundled-skills/maggie-design-motion/SKILL.md

@@ -2,7 +2,7 @@
 name: maggie-design-motion
 description: Turn a static design (a Figma frame, screenshot, dashboard, card set, app screen, or a UI on a photo) into a pixel-exact HTML replica that loads from an empty state, then has every visual act out what it does in a seamless loop, and export an MP4 plus GIFs. Use when asked to animate a design, a Figma link, a screenshot, UI cards, a dashboard or hero image, or to make a showcase loop, motion mockup, or a video/GIF of a design. Also for bento/feature cards on a landing page.
 metadata:
-  version: 0.1.1
+  version: 0.1.2
 ---
 
 # Maggie Design Motion
@@ -287,6 +287,9 @@ size/dimensions/fps/duration; anything not reproduced exactly, named plainly.
 - `maggie-spirit` - deterministic brand sprites/avatars (a different motion job).
 - `maggie-landing-page` / `maggie-design` - where website motion lives and is
   produced.
+- [web animation patterns](../../references/web-animation-patterns.md) - the motion
+  vocabulary for the website context; [generative visuals](../../references/generative-visuals.md)
+  - code-drawn visuals you capture through this skill's Part C.
 
 # Credits
 

package/bundled-skills/maggie-image/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: maggie-image
+description: Process marketing images - resize and fit to channel/OG sizes, convert to WebP/AVIF, make favicon and OG-image sets, strip metadata, compress, optimize and render SVG, and build contact-sheet montages. A recipe generator over ImageMagick (primary) with dedicated tools (svgo/resvg/cwebp/avifenc/pngquant) used when installed. Use when the user wants to resize, convert, optimize, favicon, watermark, or batch-process images for a site or social post.
+metadata:
+  version: 0.1.1
+---
+
+# Maggie Image
+
+The image-asset lane: turn a source image into the correctly-sized, correctly-
+formatted, metadata-clean asset a site or social post needs. It is a **recipe
+generator** like `maggie-video` - it prints the exact command (reviewable/loggable)
+and runs it with `--run` when the tool is on PATH. It **invokes binaries at arm's
+length** (no GPL code vendored).
+
+This is image *processing*. For generating *new* visuals from a prompt see
+`maggie media generate` and the [AI media generation](../../references/ai-media-generation.md)
+plan (self-hosted models - licensing and cost gated); for brand marks/avatars see
+`maggie-spirit`; for generative/3D/stylized visuals see
+[generative visuals](../../references/generative-visuals.md). Responsive-variant
+manifests are `maggie_images.py` (a different concern).
+
+Follow the [Maggie Memory Hook](../../references/memory-hook.md) at invocation and
+completion.
+
+## When to use
+
+- Resize/crop an image to a channel or OG size (1200x630, 1080x1080, 9:16, ...).
+- Convert to WebP/AVIF for faster pages.
+- Make a favicon set and OG/social images.
+- Strip EXIF/GPS metadata, compress, or optimize before publishing.
+- Optimize an SVG (svgo) or render one to PNG (resvg).
+- Build a contact sheet / grid for a carousel.
+
+## Tool posture
+
+ImageMagick (`magick` on IM7, else `convert`) is the primary path - almost always
+present and covers nearly every raster op. Dedicated tools give better bytes-per-
+quality and are used **automatically when installed**: `cwebp`/`avifenc` (encode),
+`pngquant` (lossy PNG), `svgo` (SVG optimize), `resvg`/`rsvg-convert` (SVG render).
+`--force-im` forces the ImageMagick path. Full commands are in
+[image recipes](../../references/image-recipes.md).
+
+## CLI
+
+```bash
+maggie tool maggie_image.py social --input hero.png --output og.jpg --preset og     # 1200x630 cover-crop
+maggie tool maggie_image.py resize --input a.jpg --output a.jpg --size 1080x1080 --mode cover
+maggie tool maggie_image.py --run webp --input hero.png --output hero.webp --quality 80
+maggie tool maggie_image.py --run avif --input hero.png --output hero.avif
+maggie tool maggie_image.py --run favicon --input logo.png --out-dir public/
+maggie tool maggie_image.py --run strip --input photo.jpg --output photo.jpg
+maggie tool maggie_image.py --run compress --input big.jpg --output small.jpg --quality 82
+maggie tool maggie_image.py svgo --input logo.svg --output logo.min.svg --multipass
+maggie tool maggie_image.py svg2png --input logo.svg --output logo.png --width 512
+maggie tool maggie_image.py --run montage --inputs a.png b.png c.png --output sheet.jpg --tile 3x
+maggie tool maggie_image.py presets
+```
+
+Subcommands: `resize`, `social`, `webp`, `avif`, `favicon`, `strip`, `compress`,
+`svgo`, `svg2png`, `montage`, `presets`. `--run` (before the subcommand) executes
+when the tool is present; otherwise the command is printed for review.
+
+## Defaults and quality
+
+- Metadata **stripped** on public assets (privacy + bytes).
+- JPEG/WebP quality ~80, AVIF ~50 (sharp/squoosh web-delivery defaults).
+- OG/social are **cover-cropped** (fill, no distortion); logos **contain-pad**.
+- Favicon: `.ico` (64/48/32/16) + PNG set (16/32/48/180-apple-touch/192/512).
+- SVG: svgo keeps `viewBox` and `title` (responsive + accessible); never rasterize an
+  SVG as a substitute for optimizing it.
+
+## Quality bar
+
+- Output is the exact target size with no distortion; cover vs pad chosen for the
+  content (photos crop, logos pad).
+- Public images carry no EXIF/GPS; file sizes are web-appropriate (WebP/AVIF offered).
+- SVGs stay vector and keep `viewBox`; a rendered PNG is only made on request.
+- Every command is printed/logged before (or instead of) running.
+
+## Guardrails
+
+- Local tools only; invoke `convert`/`magick` and dedicated binaries at arm's length;
+  never vendor GPL/AGPL code (e.g. Upscayl is AGPL - for AI upscaling invoke the
+  separate `realesrgan-ncnn-vulkan` binary instead).
+- Do not claim a file was produced unless `--run` executed and it exists.
+- Do not upscale/alter a logo or product shot in a way that misrepresents it; keep
+  brand assets faithful.
+- Reproducing copyrighted or third-party imagery is the caller's responsibility.
+
+## Related skills
+
+- `maggie-video` - the moving-image counterpart (same recipe-generator pattern).
+- `maggie-spirit` - brand marks/avatars; `maggie-design` - where assets are placed
+  and the icon/responsive gates run.
+- `maggie media generate` - generating new images from a prompt.
+- [generative visuals](../../references/generative-visuals.md) - making visuals in code.
+
+## Boundaries
+
+- Processing and optimization only; generation and placement live in other lanes.

package/bundled-skills/maggie-landing-page/SKILL.md

@@ -2,7 +2,7 @@
 name: maggie-landing-page
 description: Build a high-converting landing page - intake, page structure, layout selection, conversion copy, SEO/AEO, plus a visual-system discipline (typography, spacing, radius, backgrounds, hero, icons, motion) whose specific values are defaults the project's DESIGN.md overrides. Use when building, editing, styling, or writing copy for a landing page, marketing page, or a page section meant to convert. Designs the page; maggie-design produces and validates it.
 metadata:
-  version: 0.1.1
+  version: 0.1.2
 ---
 
 # Maggie Landing Page
@@ -156,6 +156,10 @@ icon inventory + glyph-render gates before release.
 
 ## B7. Motion
 
+The motion vocabulary (eases, scroll-reveal, stagger, SVG draw-on, typing, page
+transitions, Lottie, particles) with per-library guidance is in
+[web animation patterns](../../references/web-animation-patterns.md).
+
 Weighted, decelerating motion; never a browser-default curve. Default base curve
 `cubic-bezier(0.22,1,0.36,1)` ~500ms for layout/position; 300ms (never under 200ms)
 for hover colour/opacity. Animate only `transform`/`opacity`. Respect

package/bundled-skills/maggie-spirit/SKILL.md

@@ -2,7 +2,7 @@
 name: maggie-spirit
 description: Generate an AI brand's flat-pixel spirit (sprite) system - a logo mark that animates through a fixed 32-state base set, and per-agent avatar faces animated through the same states. Use for agent/brand avatars, logo marks, sprite-sheet and sprite-animation assets, and a shared motion vocabulary across Core and Service agents.
 metadata:
-  version: 0.1.0
+  version: 0.1.1
 ---
 
 # Maggie Spirit
@@ -14,7 +14,9 @@ states** (power, work, comms, outcome, gov). Agents differ only by their
 and status badges stay identical so a state reads the same everywhere.
 
 Everything is deterministic (seeded by accent + persona) and self-contained
-(Pillow only - no model calls, no per-image cost). It pairs with
+(Pillow only - no model calls, no per-image cost). For code-drawn generative
+visuals (backgrounds, 3D, stylized photos) beyond the brand mark, see
+[generative visuals](../../references/generative-visuals.md). It pairs with
 [agent goal-led design](../../references/agent-goal-design.md): design the agent,
 then give it a spirit.
 

package/bundled-skills/maggie-video/SKILL.md

@@ -2,7 +2,7 @@
 name: maggie-video
 description: Produce and process marketing video - render a composition to MP4/GIF/WebM, assemble clips/images/text/captions/audio on a timeline, cut to channel aspects (reel/square/youtube), burn in captions, normalize loudness, watermark, transcode, and make social cuts. Engine-neutral over the renderer (ffmpeg for assembly/transcode, a programmatic engine for code-drawn animation). Use when the user wants to make, edit, cut, caption, resize, or export a video for marketing.
 metadata:
-  version: 0.1.3
+  version: 0.1.4
 ---
 
 # Maggie Video
@@ -92,7 +92,8 @@ paid API):
    toggleable track.
 
 Never fabricate a transcript; generate it from the real audio and have a human
-review before publishing.
+review before publishing. Engine choice and the full flow are in
+[captions and transcription](../../references/captions-transcription.md).
 
 ## Channel presets and safe areas