@topy-ai/maggie 0.8.12 → 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.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
+目前 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

@@ -89,7 +89,7 @@ Maggie keeps the existing project foundation and asks for decisions before
 shared routes, analytics, or publishing boundaries change. The current
 package ships 38 installable skills and a local-first MaggieDash foundation.
 
-This package is `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.
+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/generative-visuals.md

@@ -81,6 +81,10 @@ and `hydra` are non-deterministic - capture and store their output as a fixed as
 - **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,

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

@@ -2,7 +2,7 @@
 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
+  version: 0.1.1
 ---
 
 # Maggie Image
@@ -14,7 +14,8 @@ and runs it with `--run` when the tool is on PATH. It **invokes binaries at arm'
 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 media generate` and the [AI media generation](../../references/ai-media-generation.md)
+plan (self-hosted models - licensing and cost gated); for brand marks/avatars see
 `maggie-spirit`; for generative/3D/stylized visuals see
 [generative visuals](../../references/generative-visuals.md). Responsive-variant
 manifests are `maggie_images.py` (a different concern).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.8.12",
+  "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/generative-visuals.md

@@ -81,6 +81,10 @@ and `hydra` are non-deterministic - capture and store their output as a fixed as
 - **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,