@topy-ai/maggie 0.8.11 → 0.8.12

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,100 @@
+---
+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.0
+---
+
+# 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 Q-category AI tools); 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
 

package/bundled-tools/clis/maggie_image.py

@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+"""maggie_image - generate correct image-processing commands for marketing assets.
+
+A recipe generator distilled from ImageMagick, sharp, svgo, resvg, squoosh and
+imagemin (see references/image-recipes.md). Each subcommand prints the exact command
+(reviewable/loggable) and runs it with --run only when the tool is on PATH. Raster
+ops prefer ImageMagick (`magick` on IM7, else `convert`) since it is almost always
+present and covers nearly everything; vector ops use the dedicated tool (svgo, resvg)
+and are generate-only until it is installed. Web-delivery quality defaults follow
+sharp/squoosh (JPEG/WebP ~80, AVIF ~50); OG/social are cover-cropped, logos pad.
+
+Subcommands: resize, social, webp, avif, favicon, strip, compress, svgo, svg2png,
+montage, presets.
+"""
+import argparse
+import shlex
+import shutil
+import subprocess
+import sys
+
+# OG/social use cover-crop; name -> (W, H)
+SOCIAL = {"og": (1200, 630), "twitter": (1600, 900), "square": (1080, 1080),
+          "story": (1080, 1920), "reel": (1080, 1920), "landscape": (1920, 1080),
+          "linkedin": (1200, 627), "pinterest": (1000, 1500)}
+FAVICON_PNG = [16, 32, 48, 180, 192, 512]  # 180 = apple-touch
+
+
+def _im():
+    return ["magick"] if shutil.which("magick") else ["convert"]
+
+
+def _im_tool():
+    return _im()[0]
+
+
+def _montage():
+    return ["magick", "montage"] if shutil.which("magick") else ["montage"]
+
+
+def emit(args, run, tool):
+    print(" ".join(shlex.quote(a) for a in args))
+    if not run:
+        return 0
+    if not shutil.which(tool):
+        sys.stderr.write(f"{tool} not found on PATH; printed the command only.\n")
+        return 3
+    return subprocess.run(args).returncode
+
+
+def _resize_ops(w, h, mode, pad):
+    if mode == "cover":
+        return ["-resize", f"{w}x{h}^", "-gravity", "center", "-extent", f"{w}x{h}"]
+    if mode == "contain":
+        return ["-resize", f"{w}x{h}", "-background", pad, "-gravity", "center", "-extent", f"{w}x{h}"]
+    if mode == "shrink":
+        return ["-resize", f"{w}x{h}>"]
+    return ["-resize", f"{w}x{h}"]  # fit
+
+
+def c_resize(a):
+    w, h = a.size.lower().split("x")
+    cmd = _im() + [a.input, "-strip"] + _resize_ops(w, h, a.mode, a.pad) + \
+        ["-quality", str(a.quality), a.output]
+    return emit(cmd, a.run, _im_tool())
+
+
+def c_social(a):
+    w, h = SOCIAL[a.preset]
+    cmd = _im() + [a.input, "-strip"] + _resize_ops(w, h, a.mode, a.pad) + \
+        ["-quality", str(a.quality), a.output]
+    return emit(cmd, a.run, _im_tool())
+
+
+def c_webp(a):
+    if shutil.which("cwebp") and not a.force_im:
+        return emit(["cwebp", "-q", str(a.quality), "-m", "6", a.input, "-o", a.output], a.run, "cwebp")
+    cmd = _im() + [a.input, "-strip", "-quality", str(a.quality), "-define", "webp:method=6", a.output]
+    return emit(cmd, a.run, _im_tool())
+
+
+def c_avif(a):
+    if shutil.which("avifenc") and not a.force_im:
+        return emit(["avifenc", "-s", "6", "--min", "20", "--max", "40", a.input, a.output], a.run, "avifenc")
+    cmd = _im() + [a.input, "-strip", "-quality", str(a.quality), a.output]
+    return emit(cmd, a.run, _im_tool())
+
+
+def c_favicon(a):
+    import os
+    os.makedirs(a.out_dir, exist_ok=True)
+    rc = 0
+    ico = os.path.join(a.out_dir, "favicon.ico")
+    rc |= emit(_im() + [a.input, "-define", "icon:auto-resize=64,48,32,16", ico], a.run, _im_tool())
+    for s in FAVICON_PNG:
+        name = "apple-touch-icon.png" if s == 180 else f"favicon-{s}.png"
+        out = os.path.join(a.out_dir, name)
+        rc |= emit(_im() + [a.input, "-strip", "-resize", f"{s}x{s}", out], a.run, _im_tool())
+    return rc
+
+
+def c_strip(a):
+    return emit(_im() + [a.input, "-strip", a.output], a.run, _im_tool())
+
+
+def c_compress(a):
+    out = a.output.lower()
+    if out.endswith((".jpg", ".jpeg")):
+        cmd = _im() + [a.input, "-strip", "-interlace", "Plane", "-quality", str(a.quality), a.output]
+    else:  # png: palette-reduce + max zlib (pngquant is the better alt)
+        if shutil.which("pngquant") and not a.force_im:
+            return emit(["pngquant", "--quality", "60-82", "--strip", "--force",
+                         "--output", a.output, a.input], a.run, "pngquant")
+        cmd = _im() + [a.input, "-strip", "-colors", "256",
+                       "-define", "png:compression-level=9", a.output]
+    return emit(cmd, a.run, _im_tool())
+
+
+def c_svgo(a):
+    args = ["svgo", "--multipass"] if a.multipass else ["svgo"]
+    args += ["-i", a.input, "-o", a.output]
+    print("# svgo keeps viewBox and title by default (responsive + accessible).")
+    if not shutil.which("svgo"):
+        print("# svgo not installed (npm i -g svgo). Do NOT rasterize an SVG as a substitute.")
+    return emit(args, a.run, "svgo")
+
+
+def c_svg2png(a):
+    if shutil.which("resvg") and not a.force_im:
+        args = ["resvg"]
+        if a.width:
+            args += ["-w", str(a.width)]
+        if a.background:
+            args += ["--background", a.background]
+        args += [a.input, a.output]
+        return emit(args, a.run, "resvg")
+    if shutil.which("rsvg-convert") and not a.force_im:
+        args = ["rsvg-convert"]
+        if a.width:
+            args += ["-w", str(a.width)]
+        return emit(args + [a.input, "-o", a.output], a.run, "rsvg-convert")
+    # ImageMagick fallback: drive size via -density (it rasterizes at DPI); lower fidelity
+    dens = 384
+    bg = ["-background", a.background] if a.background else ["-background", "none"]
+    size = ["-resize", f"{a.width}x"] if a.width else []
+    print("# ImageMagick SVG fallback is lower fidelity; install resvg for correct rendering.")
+    return emit(_im() + bg + ["-density", str(dens), a.input] + size + [a.output], a.run, _im_tool())
+
+
+def c_montage(a):
+    cmd = _montage() + list(a.inputs) + ["-tile", a.tile, "-geometry",
+          f"{a.cell}+{a.pad}+{a.pad}", "-background", a.background, a.output]
+    return emit(cmd, a.run, _montage()[0])
+
+
+def c_presets(a):
+    print("Social/OG size presets (use with `social --preset <name>`; cover-cropped):")
+    for name, (w, h) in SOCIAL.items():
+        print(f"  {name:<10} {w}x{h}")
+    print("\nDefaults: strip metadata; JPEG/WebP quality 80, AVIF 50; favicon .ico "
+          "(64/48/32/16) + PNG set (16/32/48/180-apple/192/512).")
+    print(f"ImageMagick binary detected: {_im_tool()}")
+    return 0
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="maggie_image", description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--run", action="store_true", help="execute (needs the tool on PATH); default prints only")
+    ap.add_argument("--force-im", action="store_true", dest="force_im",
+                    help="force the ImageMagick path even if a dedicated tool exists")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    def io(p, out=True):
+        p.add_argument("--input", required=True)
+        if out:
+            p.add_argument("--output", required=True)
+
+    r = sub.add_parser("resize", help="resize+fit to WxH")
+    io(r); r.add_argument("--size", required=True, help="WxH, e.g. 1200x630")
+    r.add_argument("--mode", choices=["cover", "contain", "fit", "shrink"], default="cover")
+    r.add_argument("--pad", default="#ffffff"); r.add_argument("--quality", type=int, default=82)
+    r.set_defaults(fn=c_resize)
+
+    s = sub.add_parser("social", help="resize to a channel/OG preset")
+    io(s); s.add_argument("--preset", choices=list(SOCIAL), required=True)
+    s.add_argument("--mode", choices=["cover", "contain", "fit", "shrink"], default="cover")
+    s.add_argument("--pad", default="#ffffff"); s.add_argument("--quality", type=int, default=82)
+    s.set_defaults(fn=c_social)
+
+    w = sub.add_parser("webp", help="encode WebP"); io(w)
+    w.add_argument("--quality", type=int, default=80); w.set_defaults(fn=c_webp)
+    av = sub.add_parser("avif", help="encode AVIF"); io(av)
+    av.add_argument("--quality", type=int, default=50); av.set_defaults(fn=c_avif)
+
+    fv = sub.add_parser("favicon", help="favicon .ico + PNG set")
+    fv.add_argument("--input", required=True); fv.add_argument("--out-dir", dest="out_dir", required=True)
+    fv.set_defaults(fn=c_favicon)
+
+    st = sub.add_parser("strip", help="strip metadata (EXIF/GPS/ICC)"); io(st); st.set_defaults(fn=c_strip)
+    co = sub.add_parser("compress", help="compress JPEG/PNG"); io(co)
+    co.add_argument("--quality", type=int, default=82); co.set_defaults(fn=c_compress)
+
+    so = sub.add_parser("svgo", help="optimize an SVG (svgo)"); io(so)
+    so.add_argument("--multipass", action="store_true"); so.set_defaults(fn=c_svgo)
+    sp = sub.add_parser("svg2png", help="render SVG -> PNG (resvg)"); io(sp)
+    sp.add_argument("--width", type=int); sp.add_argument("--background"); sp.set_defaults(fn=c_svg2png)
+
+    mo = sub.add_parser("montage", help="contact sheet / grid")
+    mo.add_argument("--inputs", nargs="+", required=True); mo.add_argument("--output", required=True)
+    mo.add_argument("--tile", default="3x"); mo.add_argument("--cell", default="400x400")
+    mo.add_argument("--pad", type=int, default=10); mo.add_argument("--background", default="#ffffff")
+    mo.set_defaults(fn=c_montage)
+
+    sub.add_parser("presets", help="list size presets").set_defaults(fn=c_presets)
+
+    a = ap.parse_args(argv)
+    raise SystemExit(a.fn(a))
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",

package/references/captions-transcription.md

@@ -0,0 +1,41 @@
+# Captions and transcription
+
+Local, offline speech-to-text for video captions and transcripts, used by
+`maggie-video`'s `captions` subcommand. All engines run on the user's machine - **no
+paid API** - so transcription has no per-minute cost, only local CPU/GPU time.
+Distilled from the reference library's R-category projects.
+
+## Engines
+
+| Engine | What / how | License | Reach for it when |
+|---|---|---|---|
+| openai-whisper | The reference Python CLI: `whisper IN --model base --output_format srt --output_dir DIR` | MIT | the default; simplest install (`pip install openai-whisper`) |
+| whisper.cpp | C/C++ port, fast on CPU, GGML models: `whisper-cli -m model.bin -f IN -osrt -of OUTBASE` | MIT | no GPU / fastest CPU / embedding in a pipeline |
+| whisperX | whisper + forced alignment for **word-level timestamps** and diarization: `whisperx IN --model large-v3 --output_format srt --output_dir DIR` | BSD-4 | word-accurate caption timing or speaker labels |
+
+Model size trades speed for accuracy: `tiny` / `base` (fast, rough) -> `small` /
+`medium` -> `large-v3` (slow, best). Use `--lang` to skip auto-detect when known.
+
+## Workflow (voiceover -> captions -> on-screen)
+
+1. **Transcribe** the voiceover or the video's audio to SRT with a local engine
+   (`maggie_video.py captions --input vo.mp3 --output vo.srt --engine whisper
+   --model base`). A larger model is slower but more accurate.
+2. **Review** the SRT - never ship an unreviewed transcript; whisper mishears names,
+   numbers, and brand terms. A human edits it.
+3. **Put it on screen**, one of:
+   - burn in (`maggie_video.py subtitle --input video.mp4 --srt vo.srt --output out.mp4`),
+   - soft-mux a toggleable track (`subtitle --soft`), or
+   - a `captions` layer in a `maggie_video.py compile` timeline (see
+     [video timeline model](video-timeline-model.md)).
+
+## Rules
+
+- Captions lift watch time and serve sound-off viewing - caption every social video.
+- **Never fabricate a transcript**; generate it from the real audio and have a human
+  review before publishing (accuracy, names, and brand terms).
+- Local/offline: no audio leaves the machine, no paid API. If a hosted transcription
+  API is ever wired in instead, the global spend-first rule applies - state the cost.
+- Keep caption text inside the safe area (see `maggie-video` channel presets).
+
+See `maggie-video` for the subcommands and the burn-in / soft-mux / compile options.

package/references/generative-visuals.md

@@ -0,0 +1,90 @@
+# Generative visuals (creative coding)
+
+Patterns for generating marketing visuals in code - hero backgrounds, textures, 3D
+product shots, data-viz, and stylized images - distilled from the leading creative-
+coding libraries. We adopt **patterns, not code**. Output becomes a deliverable as a
+**still** (canvas/SVG export) or a **loop** (captured via
+[design-motion production](design-motion-production.md) Part C or
+[ffmpeg recipes](ffmpeg-recipes.md), then assembled in `maggie-video`). Determinism
+by seeding matches `maggie-spirit`'s philosophy: same seed -> same pixels.
+
+## Libraries
+
+| Library | What / model | Lang | License | Marketing fit |
+|---|---|---|---|---|
+| three.js | WebGL 3D: Scene + Camera + WebGLRenderer; `renderer.render(scene,camera)` in a loop | JS | MIT | 3D product spins, logo stings, depth-y hero backgrounds |
+| Babylon.js | Higher-level 3D engine (PBR, asset pipeline); heavier | JS/TS | Apache-2.0 | 3D product config; alt to three when its pipeline earns the weight |
+| react-three-fiber | three.js as React JSX (`<mesh><boxGeometry/>…`), `useFrame` | JS/TS | MIT | 3D on a React site |
+| p5.js | Canvas sketch: `setup()` once + `draw()` per frame; `random()/noise()` with `randomSeed()/noiseSeed()` | JS | **LGPL-2.1** | generative hero backgrounds, flow fields, noise art |
+| paper.js | Vector scene graph (Path/Group), boolean ops, hit-testing | JS | MIT | editable vector hero art, print-quality SVG |
+| two.js | One 2D API across SVG/Canvas/WebGL renderers | JS | MIT | vector art you want to export as SVG or capture from canvas |
+| rough.js | Hand-drawn/sketchy shapes; `{seed}` = reproducible | JS/TS | MIT | approachable hand-made brand style, doodle accents |
+| zdog | Pseudo-3D round/flat vector, designer-friendly | JS | MIT | cute 3D-ish icons, mascot/logo spins |
+| pts | Computational geometry (Space + Form + Pt) | TS/JS | Apache-2.0 | geometric/particle hero art |
+| hydra | Live-coded video synth (chained GLSL ops) | JS | **AGPL-3.0** | trippy animated backgrounds - **pattern only, do not ship its code** |
+| regl | Functional WebGL (stateless draw commands) | JS | MIT | custom shader backgrounds/gradients when three is overkill |
+| d3 | Data-driven SVG (scales + selections) | JS | ISC | bespoke infographics - but defer standard charts to the `dataviz` skill |
+| fogleman/primitive | Reproduce an image with N geometric primitives (CLI) | Go | MIT | stylize a product photo into abstract art (still or GIF) |
+| svg.js | Lightweight SVG DOM manipulation | JS | MIT | programmatic SVG icons/badges/dividers |
+| nannou | Rust creative framework (desktop) | Rust | MIT/Apache | note only - high-perf generative art in Rust |
+
+**License flags:** hydra is **AGPL-3.0**, p5 is **LGPL-2.1**, processing (non-core)
+is GPL - fine as *idea* sources, but do not vendor their code into shipped product;
+reimplement the pattern or use an MIT equivalent (two.js / pts / regl / svg.js).
+
+## Patterns and the deliverable path
+
+- **2D generative** (p5 / paper / two / rough / zdog / pts / svg.js): `setup()` once +
+  `draw()`/`update()` per frame. Use for brand-tinted hero/section backgrounds,
+  textures, doodle accents, geometric motifs. **Still:** SVG-capable libs serialize
+  their `<svg>` (crisp, editable, print-ready); canvas libs use `canvas.toDataURL()`
+  -> PNG. **Loop:** run the sketch headless and capture via design-motion Part C, or
+  in-browser with CCapture.js (MIT), then hand to `maggie-video`.
+- **3D** (three / babylon / r3f): Scene + Camera + Renderer; animate by frame index.
+  Product spins, 3D logo stings, depth-y backgrounds. **Still:**
+  `renderer.domElement.toDataURL()` (set `preserveDrawingBuffer:true`); **loop:** drive
+  by frame, capture as above. Prefer three/r3f (MIT); babylon only when needed.
+- **Data-viz** (d3): `d3-scale` + `d3-selection`; SVG is the native output. For
+  standard charts, **defer to the `dataviz` skill** (its palette/spec); pull in d3
+  only for bespoke marks (arc diagrams, force layouts, custom infographics).
+- **Live visuals** (hydra): chained feedback-graph ops -> animated GLSL. Renders to a
+  canvas -> capture -> `maggie-video`. **AGPL: idea only**; for an MIT shader
+  background use regl.
+- **Image -> primitives** (fogleman/primitive, MIT, Go CLI): stylize a photo into
+  abstract geometry.
+
+  ```bash
+  primitive -i input.png -o output.svg -n 100 -m 1
+  # -n shapes (50-200); -m mode (1 triangle,2 rect,3 ellipse,4 circle,6 beziers,8 polygon);
+  # output type by extension: PNG/JPG (raster), SVG (vector), GIF (animated, needs ImageMagick)
+  ```
+
+  **Still:** PNG/SVG directly; **loop:** `.gif` or `%d`-numbered PNG frames ->
+  `maggie-video`. It is randomized (no seed): generate once and **store the artifact**;
+  do not regenerate on every build.
+
+## Determinism
+
+p5 `randomSeed()/noiseSeed()`, rough.js `{seed}`, and a seeded PRNG in place of
+`Math.random` give byte-reproducible stills; the frame-index/virtual-clock rule from
+[programmatic video](programmatic-video.md) gives reproducible motion. `primitive`
+and `hydra` are non-deterministic - capture and store their output as a fixed asset.
+
+## Placement
+
+- **maggie-spirit** owns seeded brand marks/characters; borrow the 2D-canvas sketch
+  model and seed discipline for flat-vector mark construction (zdog/two.js/rough).
+  Generative *backgrounds/scenes* do not live here.
+- **maggie-design** owns generative hero backgrounds, section textures, 3D product
+  shots and image stylization as page/brand visuals; it points at this reference and
+  cross-links design-motion / `maggie-video` for capture-to-deliverable.
+- **Reference-only:** d3 (defer to `dataviz`), hydra (AGPL, idea only), regl, babylon,
+  nannou/processing/openFrameworks (desktop notes), svg.js.
+
+## Credits
+
+Patterns adapted (not code) from three.js, p5.js, d3, paper.js, two.js, rough.js,
+zdog, pts, hydra, regl, Babylon.js, react-three-fiber, fogleman/primitive, svg.js,
+nannou - licenses in the table above. Capture pipeline: see
+[programmatic video](programmatic-video.md), [design-motion production](design-motion-production.md),
+[ffmpeg recipes](ffmpeg-recipes.md).