@topy-ai/maggie 0.8.11 → 0.8.13

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.13",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",

package/references/ai-media-generation.md

@@ -0,0 +1,88 @@
+# AI media generation (planning + guardrails)
+
+The analysis-and-plan layer for category Q (self-hosted AI image/video/audio
+generation). This is **not** a build: generating media with these models means large
+model-weight downloads (gigabytes) and GPU time, so the actual run is gated on an
+explicit go-ahead and a cost statement (the global spend-first rule). This reference
+maps the landscape, the licensing traps, the commercial-safe subset to start from,
+and the guardrails - so the build, when approved, is scoped and safe. Distilled from
+the reference library's Q-category projects.
+
+## The one rule that matters: code license != weights license
+
+A repo's code license (often Apache-2.0/MIT) says nothing about whether you may use
+its **model weights commercially**. Many permissively-licensed code repos ship
+weights under research-only or non-commercial terms. **Always check the specific
+model's weight license before any commercial use**, per model, per version. Example:
+`black-forest-labs/flux` code is Apache-2.0, but **FLUX.1-[dev] weights are
+non-commercial** while FLUX.1-[schnell] is Apache-2.0 - same repo, different answer.
+
+## Code-license map (from the screened repos)
+
+| Repo | code license | adoption posture |
+|---|---|---|
+| AUTOMATIC1111/stable-diffusion-webui | **AGPL-3.0** | arm's-length only; never vendor code |
+| Comfy-Org/ComfyUI | **GPL-3.0** | arm's-length (its HTTP API / workflow JSON); never vendor |
+| lllyasviel/Fooocus, Acly/krita-ai-diffusion | **GPL-3.0** | arm's-length only |
+| danielgatis/rembg, nadermx/backgroundremover | MIT | safe to depend on (bg removal) |
+| xinntao/Real-ESRGAN | BSD-3 | safe to depend on (upscaling) - check weight terms |
+| huggingface/diffusers | Apache-2.0 | safe library; **models vary** - check each |
+| Stability-AI/generative-models, black-forest-labs/flux, guoyww/AnimateDiff, Wan-Video/Wan2.1, zai-org/CogVideo, Lightricks/LTX-Video, hpcaitech/Open-Sora, genmoai/mochi, kohya-ss/sd-scripts | Apache-2.0/MIT code | code safe; **weights almost always have their own (often non-commercial) license - verify per model** |
+| TencentARC/GFPGAN, facefusion/facefusion | NOASSERTION | unclear; treat as restricted until verified; facefusion also has misuse/ethics constraints |
+| suno-ai/bark, facebookresearch/audiocraft | MIT | audio/music code safe; check weight + training-data terms |
+
+## Commercial-safe subset to start with (when approved)
+
+Lowest risk, highest marketing value, smallest footprint - do these first:
+
+1. **Background removal** - `rembg` (MIT; u2net weights, widely used) or
+   `backgroundremover` (MIT). Runs CPU-fine for product cut-outs. Pairs with
+   `maggie-image` compositing.
+2. **Upscaling / restore** - `Real-ESRGAN` (BSD-3) via the standalone
+   `realesrgan-ncnn-vulkan` binary (arm's-length; do NOT vendor Upscayl which is
+   AGPL). Enlarge logos/product shots without re-shooting.
+
+These two cover the everyday CMO needs (clean product images, upscale assets) with
+no GPL/AGPL code vendored and no license-murky weights.
+
+## Orchestration: ComfyUI at arm's length
+
+For heavier generation (image/video models), the practical backend is **ComfyUI
+driven over its HTTP API** with a saved **workflow JSON** - invoked as an external
+service, never vendored (it is GPL). The adapter pattern mirrors
+[provider adapter contract](provider-adapter-contract.md): a host supplies the
+running ComfyUI endpoint, the GPU, and the chosen (license-cleared) model weights;
+Maggie submits a workflow + prompt and retrieves the output. Image/video results then
+flow into `maggie-image` / `maggie-video` for sizing, captioning, and assembly.
+
+## Guardrails (before any run)
+
+- **State cost first.** Model downloads are gigabytes and GPU time is real; announce
+  the footprint and get a yes before downloading weights or running a generation
+  (global spend-first rule). Small CPU ops (rembg) are the exception.
+- **If a hosted/API model is used instead of self-host**, the global BYOK rule
+  applies: route through the aggregator with `provider.order` + `allow_fallbacks:
+  false` + explicit `max_tokens`/limits, use our own key, and verify `is_byok`/
+  `cost:0`.
+- **Weights license per model** (see the rule above) - record which weights are
+  cleared for commercial use.
+- **No vendoring** of AGPL/GPL code (sd-webui, ComfyUI, Fooocus, Upscayl); invoke at
+  arm's length.
+- **Provenance + rights + moderation**: generated media needs a recorded,
+  redacted provenance note and a rights/moderation check before publishing (as the
+  hero-video policy in `maggie-design` already requires for generated assets).
+- **Never pass off generated media as a real photo of a real person/place** without
+  disclosure; honour facefusion-style misuse constraints.
+
+## Staged plan (each gated on go-ahead + cost)
+
+1. `rembg` / `backgroundremover` bg-removal + `Real-ESRGAN` upscaling helpers
+   (license-clean, mostly CPU) - likely one release.
+2. ComfyUI HTTP-API adapter + a couple of saved workflows (image gen, inpaint),
+   host-supplied GPU + cleared weights - one release.
+3. Video/audio generation models as separate, individually license-vetted adapters -
+   later, per model.
+
+Pairs with: [generative visuals](generative-visuals.md) (code-drawn visuals, no
+models), `maggie-image` / `maggie-video` (post-processing the output),
+`maggie media generate` (the existing generation entry point).

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,94 @@
+# 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.
+
+For *AI* media generation (diffusion/video models, bg-removal, upscaling) rather than
+code-drawn visuals, see [AI media generation](ai-media-generation.md) (self-hosted,
+licensing + cost gated).
+
+## 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).

package/references/image-recipes.md

@@ -0,0 +1,89 @@
+# Image recipes
+
+The distilled, correct image-processing command layer for marketing assets, used by
+`maggie-image`. These are the commands `maggie_image.py` generates. Distilled from
+ImageMagick, sharp, svgo, resvg, squoosh and imagemin (reference library category P).
+We **invoke binaries at arm's length** (adopt defaults, not code).
+
+**Tool posture.** ImageMagick (`magick` on IM7, else `convert`) is almost always
+present and covers nearly every raster op, so it is the **primary** path; dedicated
+tools (svgo, resvg, cwebp, avifenc, pngquant) are the **better-quality alternative
+used automatically when installed**. Web-delivery quality defaults follow sharp/
+squoosh: JPEG/WebP ~80, AVIF ~50. OG/social are **cover-cropped**; logos **pad**.
+Strip metadata on anything public (privacy + bytes).
+
+## Resize + fit (the most-used op)
+
+```bash
+# cover / crop to exactly WxH (fills the frame, center-crop)
+convert in.jpg -strip -resize 1200x630^ -gravity center -extent 1200x630 -quality 82 out.jpg
+# contain / letterbox with a pad color
+convert in.jpg -strip -resize 1200x630 -background '#ffffff' -gravity center -extent 1200x630 out.jpg
+# downscale-only (never enlarge): -resize 1200x630>
+```
+
+sharp's smart crop (`fit:'cover', position:attention`) avoids cutting off a face;
+ImageMagick has no equal, so for portraits prefer sharp when available.
+
+## WebP / AVIF (file-size wins)
+
+```bash
+convert in.png -strip -quality 80 -define webp:method=6 out.webp   # or: cwebp -q 80 -m 6 in.png -o out.webp
+convert in.png -strip -quality 50 out.avif                         # or: avifenc -s 6 --min 20 --max 40 in.png out.avif
+```
+
+## Channel / OG presets
+
+Cover-crop to the target: OG 1200x630, Twitter 1600x900, square 1080x1080, story/reel
+1080x1920, landscape 1920x1080, LinkedIn 1200x627, Pinterest 1000x1500. Same command
+as cover resize with the preset size, `-strip -quality 82`.
+
+## Favicon + OG set
+
+```bash
+convert in.png -define icon:auto-resize=64,48,32,16 favicon.ico      # multi-res .ico
+convert in.png -strip -resize 180x180 apple-touch-icon.png          # + 16/32/48/192/512 PNGs
+```
+
+## Strip metadata / compress
+
+```bash
+convert in.jpg -strip out.jpg                                        # drop EXIF/GPS/ICC
+convert in.jpg -strip -interlace Plane -quality 82 out.jpg           # progressive JPEG
+pngquant --quality 60-82 --strip --output out.png in.png            # lossy PNG (best); IM fallback: -colors 256 -define png:compression-level=9
+```
+
+## SVG optimize / render
+
+```bash
+svgo --multipass -i in.svg -o out.svg      # keeps viewBox + title (responsive + a11y). If svgo absent, leave the SVG alone - never rasterize as a substitute.
+resvg -w 512 in.svg out.png                # best-fidelity SVG -> PNG (or rsvg-convert -w 512); IM fallback (-background none -density 384) is lower fidelity
+```
+
+## Montage / contact sheet (carousels, screenshot grids)
+
+```bash
+montage a.png b.png c.png -tile 3x -geometry 400x400+10+10 -background '#ffffff' sheet.jpg
+```
+
+## The CLI
+
+`maggie_image.py` generates each command above (and runs it with `--run` when the
+tool is on PATH; `--force-im` forces the ImageMagick path). It detects IM6 `convert`
+vs IM7 `magick`:
+
+```bash
+maggie tool maggie_image.py social --input hero.png --output og.jpg --preset og
+maggie tool maggie_image.py --run webp --input hero.png --output hero.webp --quality 80
+maggie tool maggie_image.py --run favicon --input logo.png --out-dir public/
+maggie tool maggie_image.py svg2png --input logo.svg --output logo.png --width 512
+maggie tool maggie_image.py presets
+```
+
+## Licenses
+
+Invoked at arm's length: ImageMagick (permissive), SVGO (MIT), resvg (MIT/Apache),
+sharp (Apache-2.0), squoosh codecs (Apache-2.0), imagemin (MIT), cwebp/avifenc
+(BSD). **Avoid vendoring code from** Upscayl (AGPL-3.0) - for AI upscaling invoke the
+separate `realesrgan-ncnn-vulkan` binary instead. sharp/squoosh quality defaults are
+adopted as the preset numbers.