@topy-ai/maggie 0.8.11 → 0.8.13

package/README-zh-TW.md

@@ -143,7 +143,7 @@ structure drift 或重複 treatment product 時 fail closed。
 deployment、memory、feedback 和 MaggieDash。內容先 draft/review，外部寫入、
 publish 與 production deployment 需要明確確認。
 
-目前 npm 版本為 `0.8.11`,收尾 N 類影片功能:`maggie_video.py compile` 再補上視頻 clip ken-burns、sidechain ducking、以及非透明度 overlay 效果(move/slide、圖片 zoom),並新增 `autocut` 子命令(silencedetect 去靜音)。先前 0.8.10 新增圖片 ken-burns + 文字透明度關鍵幀與 `captions`(whisper)子命令。先前 0.8.9 新增 `compile`(宣告式 timeline JSON→單一 ffmpeg 命令)。先前 0.8.8 新增 `maggie-video`(製作與處理行銷影片:剪輯、字幕、裁切成各渠道比例、浮水印、轉碼、響度正規化、clip 組裝、程式化動畫),附一個實測可用的 ffmpeg 配方 CLI(`maggie_video.py`),從參考庫的影片專案(moviepy/editly/ffmpeg 命令層、Revideo/Motion Canvas/CCapture 程式化渲染、MLT/OpenShot/Olive 的 timeline 資料形狀)提煉而來;另加 `ffmpeg-recipes`、`programmatic-video`、`video-timeline-model` 三個 reference。先前 0.8.7 把 redesign 稽核併入 `maggie-design`(改編自 MIT 的 `elayadesign/redesign-skill`):掃描 + 診斷 AI 通病/缺失狀態/雜亂程式碼,再經 in-place/verify 流程就地修正,因此「稽核/打磨/升級既有站點」會路由到 maggie-design。先前 0.8.6 補齊兩個設計技能:加入完整的生產 reference,並把設計來源明確為 Figma 非必需(實時 URL、既有程式碼、Figma、或純截圖)。先前 0.8.5 採納兩個設計技能(改編自 MIT 的 `elayadesign/ai-design-skills`):maggie-landing-page(轉化策略 + 視覺系統紀律,具體數值為可被專案 DESIGN.md 覆蓋的預設值;由 maggie-design 生產與驗證)與 maggie-design-motion(靜態設計→像素級動畫 HTML 複刻→匯出 MP4 + GIF)。先前 0.8.4 將技能庫擴展成完整的「一人用 AI 跑一家公司」C-suite,新增八條職能線:maggie-sales(CRM 中立的銷售管線)、maggie-finance(只解釋的 CFO 指標,含確定性 maggie_finance.py 計算器)、maggie-support(面向客戶的客戶成功)、maggie-product(路線圖 + 預註冊實驗)、maggie-fundraising(pitch deck、data room、投資人更新)、maggie-legal(ToS/隱私/DPA/SOC2 readiness)、maggie-monetization(定價/paywall/dunning,金錢操作需人工批准)、maggie-orchestrator(CEO 編排層:將目標拆成帶審批門的 mission 分派到各職能線,含 maggie_orchestrator.py 規劃器)。先前 0.8.3 將 cmo.so/www 開發經驗沉澱進技能庫:新增兩個技能 maggie-skill-authoring(依 catalog 與 MCP 工具白名單撰寫/校驗社區營銷 playbook 技能)與 maggie-feedback-triage(反饋的團隊接收端:決策/定級/分派、PRD + issue 流程、24/7 隊列守護);新增多個 reference(OAuth PKCE 登入、Expo 約定與 Router 骨架、MCP evals 測試框架、conversation cards、WordPress→Firebase 認證遷移手冊);並增補 maggie-assistant-tools(tool≤user 每輪工具過濾、agent loop 安全不變量、preview-only 橋接代理、MCP resources/prompts、注解加固、CLI 與 ChatGPT 插件打包)、maggie-auth-reference(自清理登入測試套件、自簽單次令牌)、maggie-mobile-app(OTA 開機拉取、live==built 部署守衛)、maggie-deployment(pm2 單包發布、live-hash 校驗)與 maggie-ops(template-as-code 郵件同步)。先前 0.8.2 新增 maggie-spirit(為 AI 品牌生成平面像素 spirit/sprite 系統)與 goal-led AI agent 設計參考;0.8.0 為安全優化 roadmap(scan、image-patch、標頭評分、SSVC、GDPR 日誌規則、新 MCP 工具)。先前 0.8.0 為安全優化 roadmap(scan、image-patch、標頭評分、SSVC、GDPR 日誌規則、新 MCP 工具),含 fix-plan 修補風險分級 T1–T4(判斷補丁是否安全套用)與 host-impact 補丁影響面量測(哪些服務需重啟、是否需重開機)、public-check、Maggie Security、batch 31 排程 agent routines、報告收件匣與無人值守 agent 限制、PHP runtime 盤點與主機鎖、pull 網站改寫、query 點子與社群佇列檢查，batch 30 MaggieDash 先裝核心、release privacy gate、feedback 備援、社群連結與圖片檢查、大量頁面產生與 app 檢查，batch 29 預約規則、部署、app QA、助理與社群功能，以及 batch 28 產品 app、assistant tools、mobile、product release、skills catalog 與 bridge host 功能、batch 26、27 feedback 修正與 idempotent `maggie update`與 Booking email-template 合約/CLI validator 同步。本版完成 2026-09-24 booking feedback batch：Calendar grid/free-slot entry 與 host modal focus-restoration evidence。本版新增 Starter marketplace provisioning plan；本版完成 feedback batches 22、23：加入 declarative browser interaction evidence、design markup/style/content-key gate、compiler source anchoring、entity double-escape protection、`update --help` read-only、noindex hypothetical indexability、可過期 baseline acknowledgement、DOM-only link extraction regression，以及 MaggieDash 0.2.10 的 content override、短期 browser session、CDN-safe public-session cache contracts。authentication 和 isolated dev server 仍由 host 負責。`maggie-booking` workflow、傳統 email/password、Stripe、Resend、public booking flow 及既有安全邊界維持不變；provider-bound video generation 與 transactional delivery 仍記錄在 issue #39，前一批延後功能仍在 issue #38，不會直接成為 active memory。0.7.33 記錄並審查一筆更正回饋；確認 0.7.32 已正確處理 batch index，沒有修改已驗證的 shared behavior。0.7.32 加入 feedback 一基索引支援、MaggieDash panel 的 source/freshness/error evidence、Consent Mode 與實際 write/no-op reconciliation、SEO baseline recapture、sitemap origin rebasing、content-diff scope、migration ledger reconciliation、deployment credential preflight、release provenance/runtime preflight、icon release gate、opt-in blog auto-publish gate，以及 least-privilege VPS deployer。也修復 top-level `maggie feedback` dispatcher parity。0.7.31 加入 update 差異摘要、atomic installer copy、subset install manifest merge，以及 inventory drift 時 doctor non-zero。0.7.30 補上 feedback tracking issue closeout gate 與 batch 14/15 audit ledger。0.7.29 修正 npm package landing page 使用英文 README；0.7.28 加入 versioned Gemini model policy、明確 fallback 與 provenance、bundled-first CLI
+目前 npm 版本為 `0.8.13`,新增 AI 媒體生成規劃 reference(Q 類:自託管模型概覽、程式碼授權≠權重授權規則、商用安全子集 rembg/Real-ESRGAN、成本/BYOK 守則;實際建置待明確許可)。先前 0.8.12 收尾其餘設計類:新增 `maggie-image`(影像處理 CLI:尺寸/OG/favicon/WebP-AVIF/svg/montage)與 web 動效、生成式視覺、圖像配方、字幕四個 reference。先前 0.8.11 收尾 N 類影片功能:`maggie_video.py compile` 再補上視頻 clip ken-burns、sidechain ducking、以及非透明度 overlay 效果(move/slide、圖片 zoom),並新增 `autocut` 子命令(silencedetect 去靜音)。先前 0.8.10 新增圖片 ken-burns + 文字透明度關鍵幀與 `captions`(whisper)子命令。先前 0.8.9 新增 `compile`(宣告式 timeline JSON→單一 ffmpeg 命令)。先前 0.8.8 新增 `maggie-video`(製作與處理行銷影片:剪輯、字幕、裁切成各渠道比例、浮水印、轉碼、響度正規化、clip 組裝、程式化動畫),附一個實測可用的 ffmpeg 配方 CLI(`maggie_video.py`),從參考庫的影片專案(moviepy/editly/ffmpeg 命令層、Revideo/Motion Canvas/CCapture 程式化渲染、MLT/OpenShot/Olive 的 timeline 資料形狀)提煉而來;另加 `ffmpeg-recipes`、`programmatic-video`、`video-timeline-model` 三個 reference。先前 0.8.7 把 redesign 稽核併入 `maggie-design`(改編自 MIT 的 `elayadesign/redesign-skill`):掃描 + 診斷 AI 通病/缺失狀態/雜亂程式碼,再經 in-place/verify 流程就地修正,因此「稽核/打磨/升級既有站點」會路由到 maggie-design。先前 0.8.6 補齊兩個設計技能:加入完整的生產 reference,並把設計來源明確為 Figma 非必需(實時 URL、既有程式碼、Figma、或純截圖)。先前 0.8.5 採納兩個設計技能(改編自 MIT 的 `elayadesign/ai-design-skills`):maggie-landing-page(轉化策略 + 視覺系統紀律,具體數值為可被專案 DESIGN.md 覆蓋的預設值;由 maggie-design 生產與驗證)與 maggie-design-motion(靜態設計→像素級動畫 HTML 複刻→匯出 MP4 + GIF)。先前 0.8.4 將技能庫擴展成完整的「一人用 AI 跑一家公司」C-suite,新增八條職能線:maggie-sales(CRM 中立的銷售管線)、maggie-finance(只解釋的 CFO 指標,含確定性 maggie_finance.py 計算器)、maggie-support(面向客戶的客戶成功)、maggie-product(路線圖 + 預註冊實驗)、maggie-fundraising(pitch deck、data room、投資人更新)、maggie-legal(ToS/隱私/DPA/SOC2 readiness)、maggie-monetization(定價/paywall/dunning,金錢操作需人工批准)、maggie-orchestrator(CEO 編排層:將目標拆成帶審批門的 mission 分派到各職能線,含 maggie_orchestrator.py 規劃器)。先前 0.8.3 將 cmo.so/www 開發經驗沉澱進技能庫:新增兩個技能 maggie-skill-authoring(依 catalog 與 MCP 工具白名單撰寫/校驗社區營銷 playbook 技能)與 maggie-feedback-triage(反饋的團隊接收端:決策/定級/分派、PRD + issue 流程、24/7 隊列守護);新增多個 reference(OAuth PKCE 登入、Expo 約定與 Router 骨架、MCP evals 測試框架、conversation cards、WordPress→Firebase 認證遷移手冊);並增補 maggie-assistant-tools(tool≤user 每輪工具過濾、agent loop 安全不變量、preview-only 橋接代理、MCP resources/prompts、注解加固、CLI 與 ChatGPT 插件打包)、maggie-auth-reference(自清理登入測試套件、自簽單次令牌)、maggie-mobile-app(OTA 開機拉取、live==built 部署守衛)、maggie-deployment(pm2 單包發布、live-hash 校驗)與 maggie-ops(template-as-code 郵件同步)。先前 0.8.2 新增 maggie-spirit(為 AI 品牌生成平面像素 spirit/sprite 系統)與 goal-led AI agent 設計參考;0.8.0 為安全優化 roadmap(scan、image-patch、標頭評分、SSVC、GDPR 日誌規則、新 MCP 工具)。先前 0.8.0 為安全優化 roadmap(scan、image-patch、標頭評分、SSVC、GDPR 日誌規則、新 MCP 工具),含 fix-plan 修補風險分級 T1–T4(判斷補丁是否安全套用)與 host-impact 補丁影響面量測(哪些服務需重啟、是否需重開機)、public-check、Maggie Security、batch 31 排程 agent routines、報告收件匣與無人值守 agent 限制、PHP runtime 盤點與主機鎖、pull 網站改寫、query 點子與社群佇列檢查，batch 30 MaggieDash 先裝核心、release privacy gate、feedback 備援、社群連結與圖片檢查、大量頁面產生與 app 檢查，batch 29 預約規則、部署、app QA、助理與社群功能，以及 batch 28 產品 app、assistant tools、mobile、product release、skills catalog 與 bridge host 功能、batch 26、27 feedback 修正與 idempotent `maggie update`與 Booking email-template 合約/CLI validator 同步。本版完成 2026-09-24 booking feedback batch：Calendar grid/free-slot entry 與 host modal focus-restoration evidence。本版新增 Starter marketplace provisioning plan；本版完成 feedback batches 22、23：加入 declarative browser interaction evidence、design markup/style/content-key gate、compiler source anchoring、entity double-escape protection、`update --help` read-only、noindex hypothetical indexability、可過期 baseline acknowledgement、DOM-only link extraction regression，以及 MaggieDash 0.2.10 的 content override、短期 browser session、CDN-safe public-session cache contracts。authentication 和 isolated dev server 仍由 host 負責。`maggie-booking` workflow、傳統 email/password、Stripe、Resend、public booking flow 及既有安全邊界維持不變；provider-bound video generation 與 transactional delivery 仍記錄在 issue #39，前一批延後功能仍在 issue #38，不會直接成為 active memory。0.7.33 記錄並審查一筆更正回饋；確認 0.7.32 已正確處理 batch index，沒有修改已驗證的 shared behavior。0.7.32 加入 feedback 一基索引支援、MaggieDash panel 的 source/freshness/error evidence、Consent Mode 與實際 write/no-op reconciliation、SEO baseline recapture、sitemap origin rebasing、content-diff scope、migration ledger reconciliation、deployment credential preflight、release provenance/runtime preflight、icon release gate、opt-in blog auto-publish gate，以及 least-privilege VPS deployer。也修復 top-level `maggie feedback` dispatcher parity。0.7.31 加入 update 差異摘要、atomic installer copy、subset install manifest merge，以及 inventory drift 時 doctor non-zero。0.7.30 補上 feedback tracking issue closeout gate 與 batch 14/15 audit ledger。0.7.29 修正 npm package landing page 使用英文 README；0.7.28 加入 versioned Gemini model policy、明確 fallback 與 provenance、bundled-first CLI
 dispatch、`maggie --version`、feedback batch review 聚合與重複偵測、marketplace enrichment evidence、booking
 worker/resolver evidence，以及 read-only migration preflight。它也包含 host-owned mobile app surface contract、signed-in
 camera-state QA、直接 Astro route resolution、correlated feedback batch，以及

package/README.md

@@ -87,9 +87,9 @@ Then invoke the installed skills from your coding agent, for example:
 
 Maggie keeps the existing project foundation and asks for decisions before
 shared routes, analytics, or publishing boundaries change. The current
-package ships 37 installable skills and a local-first MaggieDash foundation.
+package ships 38 installable skills and a local-first MaggieDash foundation.
 
-This package is `0.8.11` — `maggie_video.py compile` now also does video-clip ken-burns, sidechain ducking, and non-opacity overlay effects (move/slide, image zoom), and a new `autocut` subcommand removes silent gaps. `0.8.10` added image ken-burns + text opacity keyframes and the `captions` (whisper) subcommand. `0.8.9` added `compile` (declarative timeline JSON -> one ffmpeg command). `0.8.8` added `maggie-video` (produce and process marketing video: cut, caption, resize to channel aspects, watermark, transcode, normalize loudness, assemble clips, render code-drawn animation) with a tested ffmpeg-recipe CLI, distilled from the reference library's video projects; plus references `ffmpeg-recipes`, `programmatic-video`, `video-timeline-model`. `0.8.7` folded a redesign audit into `maggie-design` (from the MIT `elayadesign/redesign-skill`): scan + diagnose generic AI-design patterns/weak states/sloppy code, then fix in place via the in-place/verify flow, so "audit/polish/upgrade an existing site" routes to maggie-design. `0.8.6` completed the two adopted design skills with full production references and made the design source Figma-optional (live URL, existing code, Figma, or a screenshot). `0.8.5` adopted the two design skills (adapted, MIT, from `elayadesign/ai-design-skills`): `maggie-landing-page` (conversion strategy + a visual-system discipline whose values defer to the project's DESIGN.md) and `maggie-design-motion` (static design → pixel-exact animated HTML replica → MP4 + GIF export). `0.8.4` expanded the library into a full "one person runs a company with AI" C-suite with eight new function lanes: `maggie-sales` (CRM-neutral pipeline), `maggie-finance` (explain-only CFO metrics + a deterministic `maggie_finance.py` calculator), `maggie-support` (customer success), `maggie-product` (roadmap + pre-registered experiments), `maggie-fundraising` (deck, data room, investor updates), `maggie-legal` (ToS/privacy/DPA/SOC2 readiness), `maggie-monetization` (pricing/paywalls/dunning; money actions human-approved), and `maggie-orchestrator` (the CEO layer that decomposes a goal into gated missions across the lanes, with a `maggie_orchestrator.py` planner). `0.8.3` folded cmo.so/www development learnings in (maggie-skill-authoring, maggie-feedback-triage, and mobile/MCP/auth references); `0.8.2` added `maggie-spirit`; `0.8.0` was the security optimization roadmap.
+This package is `0.8.13` — adds the AI-media-generation planning reference (category Q: licensing + safe subset + cost guardrails; build gated on go-ahead). `0.8.12` adds `maggie-image` (process images via an ImageMagick recipe CLI) + references for web animation, generative visuals, image recipes, and captions. `0.8.11` - `maggie_video.py compile` now also does video-clip ken-burns, sidechain ducking, and non-opacity overlay effects (move/slide, image zoom), and a new `autocut` subcommand removes silent gaps. `0.8.10` added image ken-burns + text opacity keyframes and the `captions` (whisper) subcommand. `0.8.9` added `compile` (declarative timeline JSON -> one ffmpeg command). `0.8.8` added `maggie-video` (produce and process marketing video: cut, caption, resize to channel aspects, watermark, transcode, normalize loudness, assemble clips, render code-drawn animation) with a tested ffmpeg-recipe CLI, distilled from the reference library's video projects; plus references `ffmpeg-recipes`, `programmatic-video`, `video-timeline-model`. `0.8.7` folded a redesign audit into `maggie-design` (from the MIT `elayadesign/redesign-skill`): scan + diagnose generic AI-design patterns/weak states/sloppy code, then fix in place via the in-place/verify flow, so "audit/polish/upgrade an existing site" routes to maggie-design. `0.8.6` completed the two adopted design skills with full production references and made the design source Figma-optional (live URL, existing code, Figma, or a screenshot). `0.8.5` adopted the two design skills (adapted, MIT, from `elayadesign/ai-design-skills`): `maggie-landing-page` (conversion strategy + a visual-system discipline whose values defer to the project's DESIGN.md) and `maggie-design-motion` (static design → pixel-exact animated HTML replica → MP4 + GIF export). `0.8.4` expanded the library into a full "one person runs a company with AI" C-suite with eight new function lanes: `maggie-sales` (CRM-neutral pipeline), `maggie-finance` (explain-only CFO metrics + a deterministic `maggie_finance.py` calculator), `maggie-support` (customer success), `maggie-product` (roadmap + pre-registered experiments), `maggie-fundraising` (deck, data room, investor updates), `maggie-legal` (ToS/privacy/DPA/SOC2 readiness), `maggie-monetization` (pricing/paywalls/dunning; money actions human-approved), and `maggie-orchestrator` (the CEO layer that decomposes a goal into gated missions across the lanes, with a `maggie_orchestrator.py` planner). `0.8.3` folded cmo.so/www development learnings in (maggie-skill-authoring, maggie-feedback-triage, and mobile/MCP/auth references); `0.8.2` added `maggie-spirit`; `0.8.0` was the security optimization roadmap.
 
 The 0.7.59 release made `maggie security host-audit` (the deep
 lynis audit over SSH) robust on hosts where a storage test can stall: lynis runs

package/bundled-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/bundled-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/bundled-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/bundled-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.