@topy-ai/maggie 0.8.13 → 0.8.15

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.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
+目前 npm 版本為 `0.8.15`,補齊除 Q 外所有設計類的覆蓋(深入研究先前略讀的桌面編輯器/動畫工具,只借思路不抄碼):maggie_image.py 新增 svg-export(Inkscape)/composite/look,新增 design-editor-patterns reference,並擴充 web-animation/generative-visuals/video-timeline;docs/design-coverage-audit.md 逐 repo 確認。先前 0.8.14 新增 `maggie-ai-media`(去背/放大/arm's-length ComfyUI 的命令生成器,自身不下載模型、不用 GPU),讓 Q 類達到同級;重型執行仍受成本把關。先前 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 38 installable skills and a local-first MaggieDash foundation.
+package ships 39 installable skills and a local-first MaggieDash foundation.
 
-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.
+This package is `0.8.15` — closes the non-Q design coverage gap (deep codebase study of the desktop editors/animation tools): `maggie_image.py` gains svg-export/composite/look, a new design-editor-patterns reference, and growth in web-animation/generative-visuals/video-timeline references. `0.8.14` adds `maggie-ai-media` (bg removal / upscaling / arm's-length ComfyUI as a command generator; no model downloads or GPU itself). `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/design-editor-patterns.md

@@ -0,0 +1,77 @@
+# Design-editor patterns
+
+Borrowable logic and creativity from open-source design, whiteboard, vector and raster
+**editors** (reference library category P), for making and handling marketing visuals
+programmatically. We adopt **concepts and data shapes, not code** (most are GPL/AGPL/
+MPL or custom-licensed; the few MIT ones are reimplemented, not bulk-copied). Pairs
+with [image recipes](image-recipes.md), [generative visuals](generative-visuals.md),
+and [AI media generation](ai-media-generation.md).
+
+## Non-destructive edit recipe (darktable)
+
+darktable (GPL) edits by a **replayable history stack of named module invocations**,
+stored in an **XMP sidecar** beside the untouched original - never mutating the source;
+the image is reconstructed by replaying the stack. Borrow this as a maggie "image edit
+recipe": a small JSON `[ {op, params}, ... ]` stored next to the original and replayed
+by `maggie_image.py` (each op -> an ImageMagick/sharp command). It is **reproducible,
+auditable, re-editable, and batchable** - apply one "look" recipe to every photo in a
+campaign for consistent brand grading. `darktable-cli <in> <sidecar.xmp> <out>` renders
+from such a stack (GPL binary, arm's-length).
+
+## LLM-generatable scene / diagram formats
+
+- **Excalidraw** (`.excalidraw` JSON, MIT) - a flat list of elements (`{type:
+  rectangle|ellipse|diamond|text|line|arrow|freedraw|image|frame, x, y, width, height,
+  strokeColor, backgroundColor, fillStyle, roughness, seed, roundness, groupIds,
+  boundElements}`) with a separate `files` asset map and ratio-based arrow/label
+  bindings that survive resize. **Emit it from a prompt** for diagrams, flowcharts,
+  annotated screenshots -> open in-app or render to SVG/PNG, with an on-brand hand-drawn
+  (rough.js) look.
+- **drawio / mxGraph** (`mxGraphModel` XML, Apache-2.0 code; diagram output
+  unrestricted) - `<mxCell>` nodes with `value` (label), a compact `style` DSL
+  (`rounded=1;fillColor=#dae8fc;strokeColor=#6c8ebf;`), `vertex="1"` or `edge="1"` with
+  `source`/`target`, and `<mxGeometry>`. Trivially generatable for org charts, funnels,
+  architecture diagrams; render headless to SVG/PNG (don't redistribute their icon/
+  stencil sets).
+
+## SVG as the document (Method-Draw) + safe ingest
+
+Method-Draw (MIT, from SVG-Edit) treats the **live SVG DOM as the single source of
+truth** - `XMLSerializer` is the save format; no separate scene JSON. Two borrows:
+(a) the simplest possible model for programmatic marketing SVGs (build the DOM,
+serialize); (b) a **sanitize whitelist** (`svgWhiteList_`) of allowed SVG elements/
+attributes - essential for safely ingesting user- or AI-supplied SVG before rendering
+(strips scripts/unknowns); pair with svgo in [image recipes](image-recipes.md). Its
+command `apply/unapply` history is the generic edit-history pattern (and the backbone
+of the edit-recipe above).
+
+## Design-doc patterns (penpot, tldraw)
+
+- **penpot** (MPL, concept) - a design doc in **open standards (SVG/CSS/HTML/JSON)**
+  with first-class **Design Tokens as the single source of truth** between brand and
+  code, **Components + Variants** (one card, many variants = reusable marketing
+  templates), CSS Grid/Flex layout on the doc, and an **MCP server** making the doc
+  agent-readable. Strong alignment with Maggie's brand-kit + MCP posture.
+- **tldraw** (custom license, concept) - an infinite-canvas **reactive record store**
+  of typed shape records (geometry + props + `parentId` + fractional index) with
+  bindings/assets/pages, and the explicit framing that **an LLM agent operates on the
+  canvas document as data** - reinforcing the "generate the scene JSON" approach.
+
+## AI-edit vocabulary (krita-ai-diffusion)
+
+krita-ai-diffusion (GPL, concept) bolts generative AI onto a layer/selection editor
+over a ComfyUI backend. The borrowable vocabulary for precise AI image edits (beyond
+full-frame generation): **mask/selection-scoped generative fill** (inpaint, expand,
+add/remove inside a region), **layer-as-region prompting** (a text prompt per image
+area defined by a layer), and **conditioning** via ControlNet (scribble/lineart/canny/
+pose/depth/segmentation) and IP-Adapter (reference image, style/composition transfer).
+The plugin-over-backend boundary (editor model stays; AI is a swappable backend)
+mirrors the arm's-length posture in [AI media generation](ai-media-generation.md).
+
+## Licensing
+
+Invoke binaries at arm's length (never vendor): inkscape, darktable (GPL). Concepts
+only: penpot (MPL), tldraw (custom), krita/krita-ai-diffusion (GPL), drawio icon sets.
+MIT and freely borrowable as ideas (still reimplement, don't bulk-copy): excalidraw,
+Method-Draw, rough.js, Pinta. drawio code Apache-2.0; its diagram output is
+unrestricted.

package/bundled-references/generative-visuals.md

@@ -92,3 +92,30 @@ zdog, pts, hydra, regl, Babylon.js, react-three-fiber, fogleman/primitive, svg.j
 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).
+
+## More patterns (from the desktop/editor study)
+
+- **The shared sketch model** (processing / openFrameworks / nannou / p5): a `setup()`
+  once + per-frame `draw()` loop with seeded `random()/noise()`. openFrameworks (MIT)
+  splits it into `setup()/update()/draw()` (sim vs render); nannou (MIT/Apache)
+  formalizes Model-Update-View. The reusable discipline: **keep state separate from the
+  render fn, index by frame, seed all randomness** - that is what makes a loop
+  reproducible and headless-capturable. Default to p5/three/regl in the browser;
+  reach for a desktop framework only for heavy GPU throughput or offline high-res
+  render the browser can't sustain. (Processing non-core is GPL - reimplement.)
+- **Hand-drawn scene JSON (excalidraw, MIT).** `.excalidraw` is a flat list of
+  elements (`{type, x, y, w, h, strokeColor, backgroundColor, fillStyle:
+  hachure|cross-hatch|solid|zigzag, roughness, seed, roundness}`) rendered with
+  rough.js. It is **LLM-generatable**: emit the JSON for a diagram/flowchart/annotated
+  screenshot, then render to SVG/PNG. The rough.js mapping for an on-brand hand-made
+  look: `seed` (determinism), `fillStyle`, `fillWeight = strokeWidth/2`,
+  `hachureGap = strokeWidth*4`, `roughness`, `disableMultiStroke` for non-solid strokes.
+- **Vector shape morphing** (synfig concept): tween between two paths by interpolating
+  each control point's vertex + in/out tangents + width - smooth logo/blob/path morphs.
+- **Repeater / radial stamp** (Lottie concept): one shape -> N transformed copies with
+  an incremental transform + opacity ramp (bursts, confetti, radial brand patterns) -
+  cheap, on-brand, deterministic.
+- For AI-assisted editing vocabulary (mask/selection-scoped generation, layer-as-region
+  prompting, ControlNet/IP-Adapter conditioning), see
+  [AI media generation](ai-media-generation.md) and
+  [design editor patterns](design-editor-patterns.md).

package/bundled-references/image-recipes.md

@@ -87,3 +87,37 @@ 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.
+
+## SVG beyond resvg/ImageMagick (Inkscape, arm's-length)
+
+Inkscape's headless CLI (GPL app, invoked like ImageMagick) fills gaps resvg and IM
+can't: **font outlining, PDF/EPS, and per-id slicing**. `maggie_image.py svg-export`
+generates these.
+
+```bash
+inkscape in.svg --export-type=png --export-filename=out.png --export-width=1200 \
+  --export-area-drawing --export-background=#ffffff --export-background-opacity=1
+inkscape in.svg --export-type=pdf --export-filename=out.pdf                      # print collateral
+inkscape in.svg --export-text-to-path --export-type=svg --export-filename=flat.svg  # outline fonts for handoff
+inkscape in.svg --export-id=badge --export-id-only --export-type=png --export-filename=badge.png  # slice one element
+inkscape in.svg --export-type=png --export-dpi=300 --export-area-page --export-filename=print.png
+```
+
+## Layered composite + named looks (Pinta vocabulary)
+
+Blend modes map from a raster editor's layer stack onto ImageMagick `-compose`:
+
+```bash
+convert base.png overlay.png -gravity center -compose Multiply -composite out.png
+# modes: Over, Multiply, Screen, Overlay, Darken, Lighten, ColorDodge, ColorBurn,
+#        HardLight, SoftLight, Difference, Exclusion
+```
+
+Named "looks" (each a one-line style preset - a lightweight take on darktable's
+non-destructive edit recipe): `grayscale` (`-colorspace Gray`), `sepia`
+(`-sepia-tone 80%`), `posterize` (`-posterize 4`), `duotone` (`-colorspace Gray
+-level-colors '#1a1a2e','#e94560'`), `vignette` (`-background black -vignette 0x20`),
+`oilpaint` (`-paint 4`), `sketch` (`-colorspace Gray -charcoal 1`), `blur`/`sharpen`.
+`maggie_image.py composite` and `maggie_image.py look` generate these. For a
+reusable, batchable edit *recipe* (a JSON stack of named ops applied to many photos),
+see [design editor patterns](design-editor-patterns.md).

package/bundled-references/video-timeline-model.md

@@ -130,3 +130,41 @@ arm's length, never linked or vendored.
   keyframe/ease vocabulary, the licensing note - stable and engine-neutral.
 - **`maggie-video` skill:** channel presets, caption/CTA safe-areas, the operational
   ffmpeg command layer (via `maggie_video.py`), and tool wiring.
+
+## Extensions from the animation-tool study (O-category)
+
+Concepts to grow the model (adopt the data shape / vocabulary; code only from the
+MIT/BSD sources - rlottie MIT, opentoonz/tahoma2d BSD; synfig/friction/wick/Natron
+GPL = concept only):
+
+- **Richer keyframe easing** (synfig). Extend `{t, v, ease}` with: **per-side ease**
+  (`easeIn` != `easeOut`), **`clamped`** (auto-smooth that won't overshoot the keyed
+  value), **`hold`/`constant`**, and optional **TCB** `{tension, continuity, bias}`.
+  Add **`fullRotations`** on a rotation keyframe (wick) to control spin count/direction
+  rather than shortest-path. These precompute to per-frame values for ffmpeg and map to
+  CSS/Lottie beziers. (compile currently interpolates linearly; this is the target
+  vocabulary.)
+- **Lottie JSON as the companion vector-motion-graphics format** (rlottie, MIT). For
+  logo stings, animated icons and kinetic type, use Lottie (After-Effects/Figma
+  exportable, in-browser renderable via lottie-web) alongside the MLT/NLE shape. Borrow
+  its primitives: **Trim-path** (`start%/end%/offset` - the formal version of the
+  "draw a line on" trick in [design-motion production](design-motion-production.md)),
+  **Repeater** (N copies with a transform + opacity ramp), **track mattes**
+  (`Alpha/Luma`), **transform parenting**, and **time remap** (`tm`).
+- **Nested clips / precomps** (wick/lottie). A clip may hold its own timeline with a
+  playback mode (`loop | playOnce | single`) and be instanced - reusable lower-thirds,
+  intro/outro stingers; a composable alternative to the flat track list.
+- **Decomposed transform + animatable pivot** (friction). Split transform into
+  `pos / scale / rot / shear / pivot / opacity`, each its own keyframe curve, with a
+  **movable pivot** for correct scale/rotate around a moving anchor.
+- **Blend-mode / compositing vocabulary** (Natron `MergingFunctionEnum`). The allowed
+  `blendMode` values on overlay clips: Porter-Duff (`Over, Under, In, Out, ATop, Copy,
+  Matte`) + blends (`Multiply, Screen, Overlay, SoftLight, HardLight, ColorBurn,
+  ColorDodge, Difference, Exclusion, Hue, Saturation, Color, Luminosity`).
+- **Xsheet tabular timing** (opentoonz/tahoma2d, BSD). An optional rows=frames /
+  columns=assets exposure grid (cells = a drawing exposed for N frames, with holds) -
+  an LLM- and spreadsheet-friendly way to author precise timing, convertible to this
+  JSON timeline.
+- **Optional node-graph "effect graph"** (Natron, concept) for branched layered effects
+  (mask -> blur -> merge) that a linear track can't express - heavy; a documented
+  escape hatch, not the default.

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

@@ -362,3 +362,37 @@ Most are MIT and safe to reference/learn from freely. The four to flag: **GSAP**
 (proprietary no-charge), **typed.js** (GPL), **animate.css** (Hippocratic 2.1), and
 **synfig/friction** (GPL desktop tools). For the flagged ones we adopt the *pattern*
 and author our own code.
+
+## Authoring motion visually, playing it in code (Theatre.js)
+
+[`theatre-js/theatre`](https://github.com/theatre-js/theatre) (Apache-2.0) is a
+motion-design *editor* (`@theatre/studio`) that writes a plain serializable **project
+state**, replayed by a tiny headless runtime (`@theatre/core`) against three.js,
+HTML/SVG, or any JS variable. The borrowable pattern is the **declarative keyframe
+document**, not the editor: store motion as JSON - a `sequence` with `length` +
+`subUnitsPerUnit` (an fps snap-grid) -> **tracks keyed by property path** ->
+**keyframes** each carrying `{ position, value, handles:[lx,ly,rx,ry],
+type:'bezier'|'hold' }` (per-keyframe bezier handles = per-segment easing baked into
+data; `value` may be non-numeric). Playback mirrors CSS: `play({ iterationCount,
+range, rate, direction:'alternateReverse' })`. Author a brand motion once, commit the
+JSON as a reusable asset, replay it deterministically with no editor shipped - the
+authoring story for `maggie-design-motion` (keep the motion *spec* as data, not
+imperative GSAP calls). Reach for it when motion must be re-edited by non-coders or
+reused across pages; a one-shot reveal stays plain CSS/GSAP.
+
+## Interactive, input-driven motion (Rive state machines)
+
+[`rive-app/rive-runtime`](https://github.com/rive-app/rive-runtime) (MIT) drives
+vector animation with a **state machine** instead of fixed playback - the pattern for
+interactive hero elements, product configurators and mascots. Model: a small **input**
+surface (`bool`, `number`, `trigger`) -> **transitions** guarded by
+**conditions/comparators** (`number > 0.5`, trigger fired) -> **states** (play an
+animation, or a **BlendState1D** that blends along a number input). A **listener**
+layer maps pointer/scroll/keyboard events to input changes; states run in parallel
+**layers**; transitions carry exit-time, ease interpolators, and **random weights**
+for non-repetitive idles. Borrow it in the browser without Rive: model an interactive
+hero as `inputs -> conditions -> states` - declare inputs (`hovered:bool`,
+`scroll:0..1`, `clicked:trigger`), bind DOM events to them, and switch CSS/WAAPI/GSAP
+timelines by state rather than scripting each handler; a number input + interpolation
+gives scroll-linked response, random-picked idle transitions give a "living" element.
+(Rive's own MIT player is also a legitimate option.)

package/bundled-skills/catalog.json

@@ -2,6 +2,10 @@
   "schemaVersion": "maggie-skill-catalog.v1",
   "generatedFrom": "skills/*/SKILL.md",
   "skills": [
+    {
+      "name": "maggie-ai-media",
+      "description": "Self-hosted AI media operations for marketing - background removal, upscaling, and arm's-length ComfyUI orchestration - as a command generator (prints the command; runs it only when you have the tool installed). It downloads no model weights and uses no GPU itself. Use when the user wants to remove a background, upscale/restore an image, or drive a local ComfyUI for generation. Heavy model runs are gated on an explicit cost go-ahead."
+    },
     {
       "name": "maggie-assistant-tools",
       "description": "Build an AI assistant's tools once and expose them safely to an in-app agent, an MCP server and ChatGPT/Claude apps. Use for tool registries, risk levels and gates, result cards, approval cards with signed one-time tokens and standing workflow approvals, audit logs, report inboxes and server-enforced limits for scheduled agents (agent keys, sign-in grants, clipped lists), MCP annotations, public discovery MCP and audience binding, visitor-facing receptionists, user-facing capability pages, publishing product CLI/MCP packages and app reviews, and multi-tenant assistant bridge hosts."

package/bundled-skills/maggie-ai-media/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: maggie-ai-media
+description: Self-hosted AI media operations for marketing - background removal, upscaling, and arm's-length ComfyUI orchestration - as a command generator (prints the command; runs it only when you have the tool installed). It downloads no model weights and uses no GPU itself. Use when the user wants to remove a background, upscale/restore an image, or drive a local ComfyUI for generation. Heavy model runs are gated on an explicit cost go-ahead.
+metadata:
+  version: 0.1.0
+---
+
+# Maggie AI Media
+
+The self-hosted AI-media lane (category Q): background removal, upscaling, and
+heavier generation via a host-run ComfyUI. It is a **command generator** like
+`maggie-video` / `maggie-image` - it prints the exact command and runs it with
+`--run` only when the tool is already on PATH. It **downloads no model weights and
+uses no GPU itself**; actually running an op is the host's resource/cost, under the
+rules in [AI media generation](../../references/ai-media-generation.md).
+
+Read that reference before doing anything here. The load-bearing rule: **a repo's
+code license is not its model-weight license** - verify each weight's terms for
+commercial use. No AGPL/GPL code is vendored (sd-webui, ComfyUI, Fooocus, Upscayl are
+invoked at arm's length or not at all).
+
+Follow the [Maggie Memory Hook](../../references/memory-hook.md) at invocation and
+completion.
+
+## Scope (commercial-safe subset)
+
+- **Background removal** - `rembg` (MIT) or `backgroundremover` (MIT). CPU-fine; pairs
+  with `maggie-image` compositing for clean product cut-outs.
+- **Upscaling** - `Real-ESRGAN` (BSD) via the standalone `realesrgan-ncnn-vulkan`
+  binary (never Upscayl, which is AGPL).
+- **Generation (heavier)** - submit a saved workflow to a **host-run ComfyUI**
+  endpoint over HTTP (GPL, arm's-length): the host supplies the GPU and the
+  license-cleared weights; Maggie only POSTs the workflow and fetches the result,
+  which then flows into `maggie-image` / `maggie-video`.
+
+## CLI
+
+```bash
+maggie tool maggie_ai_media.py rmbg --input product.png --output product-cut.png        # bg removal
+maggie tool maggie_ai_media.py --run rmbg --input product.png --output cut.png           # runs if rembg installed
+maggie tool maggie_ai_media.py upscale --input logo.png --output logo-4x.png --scale 4   # Real-ESRGAN
+maggie tool maggie_ai_media.py comfy --endpoint http://127.0.0.1:8188 --workflow wf.json  # ComfyUI submit
+maggie tool maggie_ai_media.py presets
+```
+
+Subcommands: `rmbg`, `upscale`, `comfy`, `presets`. `--run` executes only when the
+tool is present; otherwise the command is printed for review.
+
+## Guardrails
+
+- **State cost first** for any model download or GPU run (weights are gigabytes, GPU
+  time is real) - the global spend-first rule. Small CPU ops (rembg) aside, get a yes
+  before a batch.
+- **Weights license per model** (code license is not weight license); record which
+  weights are cleared for commercial use.
+- **No vendoring** of AGPL/GPL code; invoke ComfyUI / realesrgan at arm's length.
+- **If a hosted API is used** instead of self-host, the global BYOK rule applies
+  (`provider.order` + `allow_fallbacks:false` + explicit limits, our key, verify
+  `is_byok`/`cost:0`).
+- **Provenance + rights + moderation** on any generated asset before publishing (as
+  `maggie-design`'s hero-video policy requires); never pass generated media off as a
+  real photo of a real person/place without disclosure.
+- Do not claim a file was produced unless `--run` executed and it exists.
+
+## Related
+
+- [AI media generation](../../references/ai-media-generation.md) - the full landscape,
+  license map, and staged plan.
+- `maggie-image` / `maggie-video` - post-process the output (size, caption, assemble).
+- `maggie media generate` - the existing generation entry point.
+- [generative visuals](../../references/generative-visuals.md) - code-drawn (non-AI)
+  visuals.
+
+## Boundaries
+
+- Command generation + arm's-length orchestration only; the models, GPU, and their
+  licensing/cost belong to the host, gated on an explicit go-ahead.

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.1
+  version: 0.1.2
 ---
 
 # Maggie Image
@@ -58,8 +58,14 @@ 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.
+`svgo`, `svg2png`, `svg-export` (Inkscape: PDF/EPS, text-to-path, per-id slicing),
+`composite` (blend-mode layering), `look` (named style presets: sepia/duotone/
+posterize/vignette/...), `montage`, `presets`. `--run` (before the subcommand)
+executes when the tool is present; otherwise the command is printed for review.
+
+For reusable, batchable edit *recipes* and generatable scene/diagram formats
+(excalidraw/drawio), the non-destructive edit-stack idea, and SVG-ingest safety, see
+[design editor patterns](../../references/design-editor-patterns.md).
 
 ## Defaults and quality
 

package/bundled-tools/clis/maggie_ai_media.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""maggie_ai_media - generate commands for the license-clean AI-media subset.
+
+A recipe generator for self-hosted AI media operations, matching the maggie_video /
+maggie_image pattern: it PRINTS the exact command (reviewable/loggable) and runs it
+with --run only when the tool is already on PATH. It downloads NO model weights and
+uses NO GPU itself - actually running an op requires you to have installed the tool
+(and its weights), which is where the cost/licensing responsibilities in
+references/ai-media-generation.md apply (code license != weights license; check each
+model's weight terms for commercial use).
+
+Scope = the commercial-safe subset only: background removal (rembg / backgroundremover,
+MIT) and upscaling (Real-ESRGAN via the standalone realesrgan-ncnn-vulkan binary,
+BSD). Heavier generation goes through a ComfyUI endpoint at arm's length (comfy), never
+by vendoring its GPL code. No AGPL/GPL code is bundled.
+
+Subcommands: rmbg, upscale, comfy, presets.
+"""
+import argparse
+import json
+import shlex
+import shutil
+import subprocess
+import sys
+
+
+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 "
+                         f"(install it + its weights first - see ai-media-generation.md).\n")
+        return 3
+    return subprocess.run(args).returncode
+
+
+def c_rmbg(a):
+    """Background removal. rembg (MIT); u2net default, u2netp (light), isnet-general-use."""
+    if a.engine == "backgroundremover":
+        cmd = ["backgroundremover", "-i", a.input, "-o", a.output]
+        return emit(cmd, a.run, "backgroundremover")
+    cmd = ["rembg", "i", "-m", a.model, a.input, a.output]
+    print("# rembg downloads its model once on first run (~170MB for u2net); MIT, CPU-fine.")
+    return emit(cmd, a.run, "rembg")
+
+
+def c_upscale(a):
+    """Upscale with Real-ESRGAN via the standalone realesrgan-ncnn-vulkan binary (BSD).
+    Do NOT use Upscayl (AGPL). Models: realesrgan-x4plus, realesrgan-x4plus-anime."""
+    cmd = ["realesrgan-ncnn-vulkan", "-i", a.input, "-o", a.output,
+           "-n", a.model, "-s", str(a.scale)]
+    print("# needs the realesrgan-ncnn-vulkan binary + its models; invoked at arm's length (BSD).")
+    return emit(cmd, a.run, "realesrgan-ncnn-vulkan")
+
+
+def c_comfy(a):
+    """Submit a saved ComfyUI workflow graph to a running ComfyUI endpoint over HTTP.
+    ComfyUI is GPL - it runs as the host's own service; we only POST to its API."""
+    url = a.endpoint.rstrip("/") + "/prompt"
+    curl = ["curl", "-s", "-X", "POST", url, "-H", "Content-Type: application/json",
+            "-d", f"@{a.workflow}"]
+    print(f"# arm's-length: the host runs ComfyUI (GPL) + supplies the GPU and license-cleared weights.")
+    print(f"# the workflow JSON must be wrapped as {{\"prompt\": <graph>}}; outputs are fetched from /history.")
+    print(" ".join(shlex.quote(x) for x in curl))
+    if not a.run:
+        return 0
+    try:
+        import urllib.request
+        with open(a.workflow, "rb") as fh:
+            body = fh.read()
+        req = urllib.request.Request(url, data=body, method="POST",
+                                     headers={"Content-Type": "application/json"})
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            print(resp.read().decode("utf-8", "replace")[:2000])
+        return 0
+    except Exception as e:  # noqa: BLE001
+        sys.stderr.write(f"ComfyUI submit failed (is the endpoint running?): {e}\n")
+        return 5
+
+
+def c_presets(a):
+    print("Commercial-safe AI-media subset (generate-only; you install the tools+weights):")
+    print("  rmbg      background removal - rembg (MIT) / backgroundremover (MIT)")
+    print("  upscale   Real-ESRGAN via realesrgan-ncnn-vulkan (BSD); never Upscayl (AGPL)")
+    print("  comfy     submit a workflow to a host-run ComfyUI endpoint (GPL, arm's-length)")
+    print("\nHard rule: code license != model-weight license - verify each weight's terms")
+    print("for commercial use. Heavy runs (downloads/GPU) cost time/resources: see")
+    print("references/ai-media-generation.md and state cost before a batch.")
+    return 0
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="maggie_ai_media", description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--run", action="store_true", help="execute (needs the tool on PATH); default prints only")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    r = sub.add_parser("rmbg", help="remove background (rembg / backgroundremover)")
+    r.add_argument("--input", required=True); r.add_argument("--output", required=True)
+    r.add_argument("--engine", choices=["rembg", "backgroundremover"], default="rembg")
+    r.add_argument("--model", default="u2net"); r.set_defaults(fn=c_rmbg)
+
+    u = sub.add_parser("upscale", help="upscale (Real-ESRGAN ncnn-vulkan)")
+    u.add_argument("--input", required=True); u.add_argument("--output", required=True)
+    u.add_argument("--model", default="realesrgan-x4plus"); u.add_argument("--scale", type=int, default=4)
+    u.set_defaults(fn=c_upscale)
+
+    c = sub.add_parser("comfy", help="submit a workflow to a ComfyUI endpoint (arm's-length)")
+    c.add_argument("--endpoint", required=True, help="e.g. http://127.0.0.1:8188")
+    c.add_argument("--workflow", required=True, help="workflow JSON file ({\"prompt\": <graph>})")
+    c.set_defaults(fn=c_comfy)
+
+    sub.add_parser("presets", help="list the safe subset + the license rule").set_defaults(fn=c_presets)
+
+    a = ap.parse_args(argv)
+    raise SystemExit(a.fn(a))
+
+
+if __name__ == "__main__":
+    main()

package/bundled-tools/clis/maggie_image.py

@@ -10,7 +10,7 @@ and are generate-only until it is installed. Web-delivery quality defaults follo
 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.
+svg-export, composite, look, montage, presets.
 """
 import argparse
 import shlex
@@ -152,6 +152,63 @@ def c_montage(a):
     return emit(cmd, a.run, _montage()[0])
 
 
+def c_svg_export(a):
+    """Inkscape headless export - fills the gaps resvg/ImageMagick can't: text-to-path
+    font outlining, PDF/EPS for print, and per-id slicing. GPL app, invoked at arm's
+    length (like ImageMagick)."""
+    args = ["inkscape", a.input, f"--export-type={a.type}", f"--export-filename={a.output}"]
+    if a.width:
+        args.append(f"--export-width={a.width}")
+    if a.dpi:
+        args.append(f"--export-dpi={a.dpi}")
+    if a.area == "drawing":
+        args.append("--export-area-drawing")
+    elif a.area == "page":
+        args.append("--export-area-page")
+    if a.id:
+        args += [f"--export-id={a.id}", "--export-id-only"]
+    if a.text_to_path:
+        args.append("--export-text-to-path")
+    if a.background:
+        args += [f"--export-background={a.background}", "--export-background-opacity=1"]
+    print("# Inkscape: text-to-path outlining (font-independent handoff), PDF/EPS, per-id slicing.")
+    return emit(args, a.run, "inkscape")
+
+
+def c_composite(a):
+    """Layer an overlay onto a base with a blend mode (Pinta/Natron vocabulary ->
+    ImageMagick -compose). Modes: Over, Multiply, Screen, Overlay, Darken, Lighten,
+    ColorDodge, ColorBurn, HardLight, SoftLight, Difference, Exclusion."""
+    cmd = _im() + [a.base, a.overlay]
+    if a.gravity:
+        cmd += ["-gravity", a.gravity]
+    cmd += ["-compose", a.mode, "-composite", a.output]
+    return emit(cmd, a.run, _im_tool())
+
+
+LOOKS = {
+    "grayscale": ["-colorspace", "Gray"],
+    "sepia": ["-sepia-tone", "80%"],
+    "posterize": ["-posterize", "4"],
+    "oilpaint": ["-paint", "4"],
+    "sketch": ["-colorspace", "Gray", "-charcoal", "1"],
+    "vignette": ["-background", "black", "-vignette", "0x20"],
+    "blur": ["-blur", "0x8"],
+    "sharpen": ["-unsharp", "0x1.5"],
+}
+
+
+def c_look(a):
+    """Apply a named 'look' (a reusable, non-destructive style preset; the darktable
+    edit-recipe idea in a single op). `duotone` maps shadows->--dark, highlights->--light."""
+    if a.look == "duotone":
+        ops = ["-colorspace", "Gray", "-level-colors", f"{a.dark},{a.light}"]
+    else:
+        ops = LOOKS[a.look]
+    cmd = _im() + [a.input, "-strip"] + ops + [a.output]
+    return emit(cmd, a.run, _im_tool())
+
+
 def c_presets(a):
     print("Social/OG size presets (use with `social --preset <name>`; cover-cropped):")
     for name, (w, h) in SOCIAL.items():
@@ -211,6 +268,26 @@ def main(argv=None):
     mo.add_argument("--pad", type=int, default=10); mo.add_argument("--background", default="#ffffff")
     mo.set_defaults(fn=c_montage)
 
+    se = sub.add_parser("svg-export", help="Inkscape headless export (pdf/eps/png/svg, text-to-path, by-id)")
+    se.add_argument("--input", required=True); se.add_argument("--output", required=True)
+    se.add_argument("--type", default="png", help="png,pdf,ps,eps,svg")
+    se.add_argument("--width", type=int); se.add_argument("--dpi", type=int)
+    se.add_argument("--area", choices=["drawing", "page"], default="drawing")
+    se.add_argument("--id", help="export only this element/layer id")
+    se.add_argument("--text-to-path", dest="text_to_path", action="store_true", help="outline fonts")
+    se.add_argument("--background"); se.set_defaults(fn=c_svg_export)
+
+    cp = sub.add_parser("composite", help="layer an overlay on a base with a blend mode")
+    cp.add_argument("--base", required=True); cp.add_argument("--overlay", required=True)
+    cp.add_argument("--output", required=True); cp.add_argument("--mode", default="Over")
+    cp.add_argument("--gravity"); cp.set_defaults(fn=c_composite)
+
+    lk = sub.add_parser("look", help="apply a named look (sepia/duotone/posterize/vignette/...)")
+    lk.add_argument("--input", required=True); lk.add_argument("--output", required=True)
+    lk.add_argument("--look", choices=list(LOOKS) + ["duotone"], required=True)
+    lk.add_argument("--dark", default="#1a1a2e"); lk.add_argument("--light", default="#e94560")
+    lk.set_defaults(fn=c_look)
+
     sub.add_parser("presets", help="list size presets").set_defaults(fn=c_presets)
 
     a = ap.parse_args(argv)

package/package.json

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

package/references/design-editor-patterns.md

@@ -0,0 +1,77 @@
+# Design-editor patterns
+
+Borrowable logic and creativity from open-source design, whiteboard, vector and raster
+**editors** (reference library category P), for making and handling marketing visuals
+programmatically. We adopt **concepts and data shapes, not code** (most are GPL/AGPL/
+MPL or custom-licensed; the few MIT ones are reimplemented, not bulk-copied). Pairs
+with [image recipes](image-recipes.md), [generative visuals](generative-visuals.md),
+and [AI media generation](ai-media-generation.md).
+
+## Non-destructive edit recipe (darktable)
+
+darktable (GPL) edits by a **replayable history stack of named module invocations**,
+stored in an **XMP sidecar** beside the untouched original - never mutating the source;
+the image is reconstructed by replaying the stack. Borrow this as a maggie "image edit
+recipe": a small JSON `[ {op, params}, ... ]` stored next to the original and replayed
+by `maggie_image.py` (each op -> an ImageMagick/sharp command). It is **reproducible,
+auditable, re-editable, and batchable** - apply one "look" recipe to every photo in a
+campaign for consistent brand grading. `darktable-cli <in> <sidecar.xmp> <out>` renders
+from such a stack (GPL binary, arm's-length).
+
+## LLM-generatable scene / diagram formats
+
+- **Excalidraw** (`.excalidraw` JSON, MIT) - a flat list of elements (`{type:
+  rectangle|ellipse|diamond|text|line|arrow|freedraw|image|frame, x, y, width, height,
+  strokeColor, backgroundColor, fillStyle, roughness, seed, roundness, groupIds,
+  boundElements}`) with a separate `files` asset map and ratio-based arrow/label
+  bindings that survive resize. **Emit it from a prompt** for diagrams, flowcharts,
+  annotated screenshots -> open in-app or render to SVG/PNG, with an on-brand hand-drawn
+  (rough.js) look.
+- **drawio / mxGraph** (`mxGraphModel` XML, Apache-2.0 code; diagram output
+  unrestricted) - `<mxCell>` nodes with `value` (label), a compact `style` DSL
+  (`rounded=1;fillColor=#dae8fc;strokeColor=#6c8ebf;`), `vertex="1"` or `edge="1"` with
+  `source`/`target`, and `<mxGeometry>`. Trivially generatable for org charts, funnels,
+  architecture diagrams; render headless to SVG/PNG (don't redistribute their icon/
+  stencil sets).
+
+## SVG as the document (Method-Draw) + safe ingest
+
+Method-Draw (MIT, from SVG-Edit) treats the **live SVG DOM as the single source of
+truth** - `XMLSerializer` is the save format; no separate scene JSON. Two borrows:
+(a) the simplest possible model for programmatic marketing SVGs (build the DOM,
+serialize); (b) a **sanitize whitelist** (`svgWhiteList_`) of allowed SVG elements/
+attributes - essential for safely ingesting user- or AI-supplied SVG before rendering
+(strips scripts/unknowns); pair with svgo in [image recipes](image-recipes.md). Its
+command `apply/unapply` history is the generic edit-history pattern (and the backbone
+of the edit-recipe above).
+
+## Design-doc patterns (penpot, tldraw)
+
+- **penpot** (MPL, concept) - a design doc in **open standards (SVG/CSS/HTML/JSON)**
+  with first-class **Design Tokens as the single source of truth** between brand and
+  code, **Components + Variants** (one card, many variants = reusable marketing
+  templates), CSS Grid/Flex layout on the doc, and an **MCP server** making the doc
+  agent-readable. Strong alignment with Maggie's brand-kit + MCP posture.
+- **tldraw** (custom license, concept) - an infinite-canvas **reactive record store**
+  of typed shape records (geometry + props + `parentId` + fractional index) with
+  bindings/assets/pages, and the explicit framing that **an LLM agent operates on the
+  canvas document as data** - reinforcing the "generate the scene JSON" approach.
+
+## AI-edit vocabulary (krita-ai-diffusion)
+
+krita-ai-diffusion (GPL, concept) bolts generative AI onto a layer/selection editor
+over a ComfyUI backend. The borrowable vocabulary for precise AI image edits (beyond
+full-frame generation): **mask/selection-scoped generative fill** (inpaint, expand,
+add/remove inside a region), **layer-as-region prompting** (a text prompt per image
+area defined by a layer), and **conditioning** via ControlNet (scribble/lineart/canny/
+pose/depth/segmentation) and IP-Adapter (reference image, style/composition transfer).
+The plugin-over-backend boundary (editor model stays; AI is a swappable backend)
+mirrors the arm's-length posture in [AI media generation](ai-media-generation.md).
+
+## Licensing
+
+Invoke binaries at arm's length (never vendor): inkscape, darktable (GPL). Concepts
+only: penpot (MPL), tldraw (custom), krita/krita-ai-diffusion (GPL), drawio icon sets.
+MIT and freely borrowable as ideas (still reimplement, don't bulk-copy): excalidraw,
+Method-Draw, rough.js, Pinta. drawio code Apache-2.0; its diagram output is
+unrestricted.

package/references/generative-visuals.md

@@ -92,3 +92,30 @@ zdog, pts, hydra, regl, Babylon.js, react-three-fiber, fogleman/primitive, svg.j
 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).
+
+## More patterns (from the desktop/editor study)
+
+- **The shared sketch model** (processing / openFrameworks / nannou / p5): a `setup()`
+  once + per-frame `draw()` loop with seeded `random()/noise()`. openFrameworks (MIT)
+  splits it into `setup()/update()/draw()` (sim vs render); nannou (MIT/Apache)
+  formalizes Model-Update-View. The reusable discipline: **keep state separate from the
+  render fn, index by frame, seed all randomness** - that is what makes a loop
+  reproducible and headless-capturable. Default to p5/three/regl in the browser;
+  reach for a desktop framework only for heavy GPU throughput or offline high-res
+  render the browser can't sustain. (Processing non-core is GPL - reimplement.)
+- **Hand-drawn scene JSON (excalidraw, MIT).** `.excalidraw` is a flat list of
+  elements (`{type, x, y, w, h, strokeColor, backgroundColor, fillStyle:
+  hachure|cross-hatch|solid|zigzag, roughness, seed, roundness}`) rendered with
+  rough.js. It is **LLM-generatable**: emit the JSON for a diagram/flowchart/annotated
+  screenshot, then render to SVG/PNG. The rough.js mapping for an on-brand hand-made
+  look: `seed` (determinism), `fillStyle`, `fillWeight = strokeWidth/2`,
+  `hachureGap = strokeWidth*4`, `roughness`, `disableMultiStroke` for non-solid strokes.
+- **Vector shape morphing** (synfig concept): tween between two paths by interpolating
+  each control point's vertex + in/out tangents + width - smooth logo/blob/path morphs.
+- **Repeater / radial stamp** (Lottie concept): one shape -> N transformed copies with
+  an incremental transform + opacity ramp (bursts, confetti, radial brand patterns) -
+  cheap, on-brand, deterministic.
+- For AI-assisted editing vocabulary (mask/selection-scoped generation, layer-as-region
+  prompting, ControlNet/IP-Adapter conditioning), see
+  [AI media generation](ai-media-generation.md) and
+  [design editor patterns](design-editor-patterns.md).

package/references/image-recipes.md

@@ -87,3 +87,37 @@ 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.
+
+## SVG beyond resvg/ImageMagick (Inkscape, arm's-length)
+
+Inkscape's headless CLI (GPL app, invoked like ImageMagick) fills gaps resvg and IM
+can't: **font outlining, PDF/EPS, and per-id slicing**. `maggie_image.py svg-export`
+generates these.
+
+```bash
+inkscape in.svg --export-type=png --export-filename=out.png --export-width=1200 \
+  --export-area-drawing --export-background=#ffffff --export-background-opacity=1
+inkscape in.svg --export-type=pdf --export-filename=out.pdf                      # print collateral
+inkscape in.svg --export-text-to-path --export-type=svg --export-filename=flat.svg  # outline fonts for handoff
+inkscape in.svg --export-id=badge --export-id-only --export-type=png --export-filename=badge.png  # slice one element
+inkscape in.svg --export-type=png --export-dpi=300 --export-area-page --export-filename=print.png
+```
+
+## Layered composite + named looks (Pinta vocabulary)
+
+Blend modes map from a raster editor's layer stack onto ImageMagick `-compose`:
+
+```bash
+convert base.png overlay.png -gravity center -compose Multiply -composite out.png
+# modes: Over, Multiply, Screen, Overlay, Darken, Lighten, ColorDodge, ColorBurn,
+#        HardLight, SoftLight, Difference, Exclusion
+```
+
+Named "looks" (each a one-line style preset - a lightweight take on darktable's
+non-destructive edit recipe): `grayscale` (`-colorspace Gray`), `sepia`
+(`-sepia-tone 80%`), `posterize` (`-posterize 4`), `duotone` (`-colorspace Gray
+-level-colors '#1a1a2e','#e94560'`), `vignette` (`-background black -vignette 0x20`),
+`oilpaint` (`-paint 4`), `sketch` (`-colorspace Gray -charcoal 1`), `blur`/`sharpen`.
+`maggie_image.py composite` and `maggie_image.py look` generate these. For a
+reusable, batchable edit *recipe* (a JSON stack of named ops applied to many photos),
+see [design editor patterns](design-editor-patterns.md).

package/references/video-timeline-model.md

@@ -130,3 +130,41 @@ arm's length, never linked or vendored.
   keyframe/ease vocabulary, the licensing note - stable and engine-neutral.
 - **`maggie-video` skill:** channel presets, caption/CTA safe-areas, the operational
   ffmpeg command layer (via `maggie_video.py`), and tool wiring.
+
+## Extensions from the animation-tool study (O-category)
+
+Concepts to grow the model (adopt the data shape / vocabulary; code only from the
+MIT/BSD sources - rlottie MIT, opentoonz/tahoma2d BSD; synfig/friction/wick/Natron
+GPL = concept only):
+
+- **Richer keyframe easing** (synfig). Extend `{t, v, ease}` with: **per-side ease**
+  (`easeIn` != `easeOut`), **`clamped`** (auto-smooth that won't overshoot the keyed
+  value), **`hold`/`constant`**, and optional **TCB** `{tension, continuity, bias}`.
+  Add **`fullRotations`** on a rotation keyframe (wick) to control spin count/direction
+  rather than shortest-path. These precompute to per-frame values for ffmpeg and map to
+  CSS/Lottie beziers. (compile currently interpolates linearly; this is the target
+  vocabulary.)
+- **Lottie JSON as the companion vector-motion-graphics format** (rlottie, MIT). For
+  logo stings, animated icons and kinetic type, use Lottie (After-Effects/Figma
+  exportable, in-browser renderable via lottie-web) alongside the MLT/NLE shape. Borrow
+  its primitives: **Trim-path** (`start%/end%/offset` - the formal version of the
+  "draw a line on" trick in [design-motion production](design-motion-production.md)),
+  **Repeater** (N copies with a transform + opacity ramp), **track mattes**
+  (`Alpha/Luma`), **transform parenting**, and **time remap** (`tm`).
+- **Nested clips / precomps** (wick/lottie). A clip may hold its own timeline with a
+  playback mode (`loop | playOnce | single`) and be instanced - reusable lower-thirds,
+  intro/outro stingers; a composable alternative to the flat track list.
+- **Decomposed transform + animatable pivot** (friction). Split transform into
+  `pos / scale / rot / shear / pivot / opacity`, each its own keyframe curve, with a
+  **movable pivot** for correct scale/rotate around a moving anchor.
+- **Blend-mode / compositing vocabulary** (Natron `MergingFunctionEnum`). The allowed
+  `blendMode` values on overlay clips: Porter-Duff (`Over, Under, In, Out, ATop, Copy,
+  Matte`) + blends (`Multiply, Screen, Overlay, SoftLight, HardLight, ColorBurn,
+  ColorDodge, Difference, Exclusion, Hue, Saturation, Color, Luminosity`).
+- **Xsheet tabular timing** (opentoonz/tahoma2d, BSD). An optional rows=frames /
+  columns=assets exposure grid (cells = a drawing exposed for N frames, with holds) -
+  an LLM- and spreadsheet-friendly way to author precise timing, convertible to this
+  JSON timeline.
+- **Optional node-graph "effect graph"** (Natron, concept) for branched layered effects
+  (mask -> blur -> merge) that a linear track can't express - heavy; a documented
+  escape hatch, not the default.

package/references/web-animation-patterns.md

@@ -362,3 +362,37 @@ Most are MIT and safe to reference/learn from freely. The four to flag: **GSAP**
 (proprietary no-charge), **typed.js** (GPL), **animate.css** (Hippocratic 2.1), and
 **synfig/friction** (GPL desktop tools). For the flagged ones we adopt the *pattern*
 and author our own code.
+
+## Authoring motion visually, playing it in code (Theatre.js)
+
+[`theatre-js/theatre`](https://github.com/theatre-js/theatre) (Apache-2.0) is a
+motion-design *editor* (`@theatre/studio`) that writes a plain serializable **project
+state**, replayed by a tiny headless runtime (`@theatre/core`) against three.js,
+HTML/SVG, or any JS variable. The borrowable pattern is the **declarative keyframe
+document**, not the editor: store motion as JSON - a `sequence` with `length` +
+`subUnitsPerUnit` (an fps snap-grid) -> **tracks keyed by property path** ->
+**keyframes** each carrying `{ position, value, handles:[lx,ly,rx,ry],
+type:'bezier'|'hold' }` (per-keyframe bezier handles = per-segment easing baked into
+data; `value` may be non-numeric). Playback mirrors CSS: `play({ iterationCount,
+range, rate, direction:'alternateReverse' })`. Author a brand motion once, commit the
+JSON as a reusable asset, replay it deterministically with no editor shipped - the
+authoring story for `maggie-design-motion` (keep the motion *spec* as data, not
+imperative GSAP calls). Reach for it when motion must be re-edited by non-coders or
+reused across pages; a one-shot reveal stays plain CSS/GSAP.
+
+## Interactive, input-driven motion (Rive state machines)
+
+[`rive-app/rive-runtime`](https://github.com/rive-app/rive-runtime) (MIT) drives
+vector animation with a **state machine** instead of fixed playback - the pattern for
+interactive hero elements, product configurators and mascots. Model: a small **input**
+surface (`bool`, `number`, `trigger`) -> **transitions** guarded by
+**conditions/comparators** (`number > 0.5`, trigger fired) -> **states** (play an
+animation, or a **BlendState1D** that blends along a number input). A **listener**
+layer maps pointer/scroll/keyboard events to input changes; states run in parallel
+**layers**; transitions carry exit-time, ease interpolators, and **random weights**
+for non-repetitive idles. Borrow it in the browser without Rive: model an interactive
+hero as `inputs -> conditions -> states` - declare inputs (`hovered:bool`,
+`scroll:0..1`, `clicked:trigger`), bind DOM events to them, and switch CSS/WAAPI/GSAP
+timelines by state rather than scripting each handler; a number input + interpolation
+gives scroll-linked response, random-picked idle transitions give a "living" element.
+(Rive's own MIT player is also a legitimate option.)