@topy-ai/maggie 0.8.19 → 0.8.20

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.19`,研究非 Q 設計 repo 所提供的**產品級 agent 介面**(MCP/skills/CLI)——即目標中「tools, MCP, skills, CLIs」這一維度,單靠檔案數無法涵蓋——寫入新的 `references/agent-native-design-surfaces.md`(tldraw 的 `search`+`exec` 畫布 MCP、Babylon.js WebMCP 雙 adapter、penpot/darktable/tsparticles 的 MCP 工具面、pixijs 的 router-skill 範式),並把具體 CLI 發現併入(svgo `--datauri`/`--precision`、whisperX 說話者分離/行寬旗標、editly 宣告式 spec),同時把 `docs/design-coverage-audit.md` 重寫為把**存在性**(檔案數)與**研究深度**(code/surface/API)當成兩條獨立軸——更正先前把「工作樹存在」與「代碼級研究過」混為一談的問題。`0.8.18` 把「每個非 Q repo 都在代碼級研究過」從斷言變成可查證的證據:`docs/design-coverage-audit.md` 重寫為逐 repo 的檔案數(工作樹大小),涵蓋全部 81 個非 Q 設計 repo(K-R),每個都抽查源碼深度,證明都是完整 checkout 而非 sparse stub(唯一的 stub,inkscape GitHub,由 GitLab clone 解決;blender 缺的是 git-LFS 二進位筆刷美術素材,屬內容非程式碼)。並驗證先前僅概念級借鑑的 O 類引擎源碼(synfig/friction/Natron/wick/rlottie),更正資料模型(synfig 緩動曲線為 `HALT` 非 `EASE`;wick 欄位為 `animationType` 非 `playbackMode`;rlottie 結構為 `Trim`/`Repeater`/`Mask` 非 `LOT*Data`)並把 net-new 併入 `video-timeline-model.md`。`0.8.17` 收尾最後兩個完整源碼覆蓋缺口:`inkscape/inkscape`(GitHub 鏡像僅 2 檔 stub,改從 GitLab clone 7053 檔逐一代碼級研究)與 L 類 web 動效庫(先前僅 README/API 層,現讀完整源碼)。net-new(借鑑邏輯非程式碼):`maggie_image.py` 新增 `svg-export --actions`(一次 Inkscape 呼叫完成清理+展平+匯出)與 `svg-query`(元素 id + 邊界框);`web-animation-patterns` 補上源碼級更正(AOS 其實是 scroll+throttle 而非 IntersectionObserver;lenis `autoRaf` 預設 false 且有 `respectReducedMotion`;typed.js 為 GPL-3.0 且無減動支援)與新點子(設計師友善的彈簧詞彙、mojs `Burst` 微互動條目、anime v4 網格 stagger、pixijs 超出範圍邊界註記)。`0.8.16` 把先前僅 README 的 repo 解稀疏為完整源碼並逐一代碼級研究(驗證所有 reference 並補 net-new:Remotion delayRender gate、opentoonz BSD 可移植的 xsheet 時間線、綠幕/LUT/卡拉OK 濾鏡、whisper turbo + 字幕旗標、Babylon NullEngine 無頭),並新增 maggie_image.py trim/auto-orient 與更豐富的 captions 旗標。先前 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
+目前 npm 版本為 `0.8.20`,以逐 repo × 六介面矩陣(`docs/design-surface-matrix.md`,涵蓋全部 81 個非 Q repo)收尾最後的逐介面缺口,讀取先前因路徑分類而漏掉的**產品級使用者 skills**(auto-editor 4 個、remotion 的 `@remotion/skills` 12 個、tldraw 的 4 個 MCP-app 建置 skill),以**實際閱讀**(而非路徑)確認維護類 skills,並讀取 CI workflows 介面(3 個可借鑑:pixijs 發版觸發的 skills 鏡像、three.js 安全的截圖 diff→PR 留言、pixijs 獨立視覺測試 job)。`0.8.19` 研究非 Q 設計 repo 所提供的**產品級 agent 介面**(MCP/skills/CLI)——即目標中「tools, MCP, skills, CLIs」這一維度,單靠檔案數無法涵蓋——寫入新的 `references/agent-native-design-surfaces.md`(tldraw 的 `search`+`exec` 畫布 MCP、Babylon.js WebMCP 雙 adapter、penpot/darktable/tsparticles 的 MCP 工具面、pixijs 的 router-skill 範式),並把具體 CLI 發現併入(svgo `--datauri`/`--precision`、whisperX 說話者分離/行寬旗標、editly 宣告式 spec),同時把 `docs/design-coverage-audit.md` 重寫為把**存在性**(檔案數)與**研究深度**(code/surface/API)當成兩條獨立軸——更正先前把「工作樹存在」與「代碼級研究過」混為一談的問題。`0.8.18` 把「每個非 Q repo 都在代碼級研究過」從斷言變成可查證的證據:`docs/design-coverage-audit.md` 重寫為逐 repo 的檔案數(工作樹大小),涵蓋全部 81 個非 Q 設計 repo(K-R),每個都抽查源碼深度,證明都是完整 checkout 而非 sparse stub(唯一的 stub,inkscape GitHub,由 GitLab clone 解決;blender 缺的是 git-LFS 二進位筆刷美術素材,屬內容非程式碼)。並驗證先前僅概念級借鑑的 O 類引擎源碼(synfig/friction/Natron/wick/rlottie),更正資料模型(synfig 緩動曲線為 `HALT` 非 `EASE`;wick 欄位為 `animationType` 非 `playbackMode`;rlottie 結構為 `Trim`/`Repeater`/`Mask` 非 `LOT*Data`)並把 net-new 併入 `video-timeline-model.md`。`0.8.17` 收尾最後兩個完整源碼覆蓋缺口:`inkscape/inkscape`(GitHub 鏡像僅 2 檔 stub,改從 GitLab clone 7053 檔逐一代碼級研究)與 L 類 web 動效庫(先前僅 README/API 層,現讀完整源碼)。net-new(借鑑邏輯非程式碼):`maggie_image.py` 新增 `svg-export --actions`(一次 Inkscape 呼叫完成清理+展平+匯出)與 `svg-query`(元素 id + 邊界框);`web-animation-patterns` 補上源碼級更正(AOS 其實是 scroll+throttle 而非 IntersectionObserver;lenis `autoRaf` 預設 false 且有 `respectReducedMotion`;typed.js 為 GPL-3.0 且無減動支援)與新點子(設計師友善的彈簧詞彙、mojs `Burst` 微互動條目、anime v4 網格 stagger、pixijs 超出範圍邊界註記)。`0.8.16` 把先前僅 README 的 repo 解稀疏為完整源碼並逐一代碼級研究(驗證所有 reference 並補 net-new:Remotion delayRender gate、opentoonz BSD 可移植的 xsheet 時間線、綠幕/LUT/卡拉OK 濾鏡、whisper turbo + 字幕旗標、Babylon NullEngine 無頭),並新增 maggie_image.py trim/auto-orient 與更豐富的 captions 旗標。先前 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

@@ -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 39 installable skills and a local-first MaggieDash foundation.
 
-This package is `0.8.19` — studies the product agent-surfaces (MCP/skills/CLI) that non-Q design repos ship (the "tools, MCP, skills, CLIs" dimension file counts didn't cover) in a new `references/agent-native-design-surfaces.md` (tldraw `search`+`exec` canvas MCP, Babylon.js WebMCP dual-adapter, penpot/darktable/tsparticles MCP, pixijs router-skill template), folds CLI findings in (svgo `--datauri`/`--precision`, whisperX diarization flags, editly declarative spec), and rewrites `docs/design-coverage-audit.md` to track existence (file count) vs study depth (code/surface/API) as separate axes. `0.8.18` — turns the "every non-Q repo studied at the codebase level" claim into measured evidence: `docs/design-coverage-audit.md` is rewritten with a per-repo file count for all 81 non-Q design repos (K-R), proving full checkouts not sparse stubs (inkscape stub resolved by a GitLab clone; blender's absent files are git-LFS binary brush art, not code). Also verifies the O-category engine source (synfig/friction/Natron/wick/rlottie) earlier borrowed at concept level, correcting the data model (synfig ease is `HALT`; wick field `animationType`; rlottie structs `Trim`/`Repeater`/`Mask`) and adding net-new to `video-timeline-model.md`. `0.8.17` — closes the last two full-source coverage gaps: `inkscape/inkscape` (GitHub is a 2-file stub; studied from GitLab, 7053 files) and the L web-animation libraries (now read at source). `maggie_image.py` gains `svg-export --actions` (clean+flatten+export in one Inkscape call) + `svg-query` (element ids + bounding boxes); `web-animation-patterns` gets source corrections (AOS is scroll+throttle not IntersectionObserver; lenis `autoRaf` default false; typed.js GPL-3.0) and new ideas (designer-spring vocabulary, mojs `Burst` entry, anime v4 grid-stagger, pixijs out-of-scope note). `0.8.16` — de-sparses the earlier README-only repos to full source and studies them at code level (confirm + net-new: Remotion delayRender gate, opentoonz BSD port target, green-screen/LUT/karaoke filters, whisper turbo + caption flags, Babylon NullEngine), plus maggie_image.py trim/auto-orient and richer captions flags. `0.8.15` closed the non-Q design coverage gap: `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.
+This package is `0.8.20` — closes the last per-surface gaps with a per-repo × 6-surface matrix (`docs/design-surface-matrix.md`, all 81 non-Q repos), reads the product user-facing skills path-classification had missed (auto-editor 4, remotion `@remotion/skills` 12, tldraw MCP-app-building 4), confirms the maintenance skills by reading them, and reads the CI surface (3 borrowable: pixijs skills-mirror, three.js screenshot-diff→PR, pixijs visual-test job). `0.8.19` — studies the product agent-surfaces (MCP/skills/CLI) that non-Q design repos ship (the "tools, MCP, skills, CLIs" dimension file counts didn't cover) in a new `references/agent-native-design-surfaces.md` (tldraw `search`+`exec` canvas MCP, Babylon.js WebMCP dual-adapter, penpot/darktable/tsparticles MCP, pixijs router-skill template), folds CLI findings in (svgo `--datauri`/`--precision`, whisperX diarization flags, editly declarative spec), and rewrites `docs/design-coverage-audit.md` to track existence (file count) vs study depth (code/surface/API) as separate axes. `0.8.18` — turns the "every non-Q repo studied at the codebase level" claim into measured evidence: `docs/design-coverage-audit.md` is rewritten with a per-repo file count for all 81 non-Q design repos (K-R), proving full checkouts not sparse stubs (inkscape stub resolved by a GitLab clone; blender's absent files are git-LFS binary brush art, not code). Also verifies the O-category engine source (synfig/friction/Natron/wick/rlottie) earlier borrowed at concept level, correcting the data model (synfig ease is `HALT`; wick field `animationType`; rlottie structs `Trim`/`Repeater`/`Mask`) and adding net-new to `video-timeline-model.md`. `0.8.17` — closes the last two full-source coverage gaps: `inkscape/inkscape` (GitHub is a 2-file stub; studied from GitLab, 7053 files) and the L web-animation libraries (now read at source). `maggie_image.py` gains `svg-export --actions` (clean+flatten+export in one Inkscape call) + `svg-query` (element ids + bounding boxes); `web-animation-patterns` gets source corrections (AOS is scroll+throttle not IntersectionObserver; lenis `autoRaf` default false; typed.js GPL-3.0) and new ideas (designer-spring vocabulary, mojs `Burst` entry, anime v4 grid-stagger, pixijs out-of-scope note). `0.8.16` — de-sparses the earlier README-only repos to full source and studies them at code level (confirm + net-new: Remotion delayRender gate, opentoonz BSD port target, green-screen/LUT/karaoke filters, whisper turbo + caption flags, Babylon NullEngine), plus maggie_image.py trim/auto-orient and richer captions flags. `0.8.15` closed the non-Q design coverage gap: `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/agent-native-design-surfaces.md

@@ -87,6 +87,53 @@ Form = pencil, Pt/Group = ideas"), then a **no-bundler sandbox-safe quick start*
 open a library skill with a tiny mental model + a copy-paste quick start that runs in a
 restricted sandbox, before any API list.
 
+### Router-only hub + progressively-disclosed spokes, shipped as a package (remotion)
+Remotion ships **12 user-facing skills as an npm package** (`@remotion/skills`,
+`npx skills add remotion-dev/skills`; a per-client mirror lives in
+`packages/codex-plugin/skills/`): best-practices, captions, create, docs, interactivity,
+maps, markup, multimedia, render, saas, studio, upgrade. Three patterns to adopt:
+- **A router-only hub** (`remotion-best-practices`) with *zero* task content — only "if the
+  user wants X, load skill Y." Keeps the always-loaded entry point tiny.
+- **Progressive disclosure**: each spoke is a thin SKILL.md that pulls in supporting `.md`
+  files only when relevant (markup has 37, best-practices 14, captions 6). Every skill
+  carries a `version:` matching the package.
+- **Round-trip-editable-artifact doctrine** (`remotion-interactivity`): author output so a
+  human can edit it in a GUI and it writes back to code — inline values only, no
+  constants/spreads/math, named elements, inline `interpolate()`. Directly applicable to
+  generating marketing/design/video assets that stay editable rather than opaque.
+
+### Concept-table + runnable-one-liner-per-row (auto-editor)
+auto-editor's 4 skills (one **hub** `auto-editor` + spokes `-effects`/`-export`/
+`-transcribe`) are built almost entirely of **dense option tables where every row is
+followed by an exact copy-paste one-liner** — including negative/inverted cases
+(`--edit "(not word:um)"`). An agent acts from the table without prose. Its label model
+(0=silent, 1=active, 2–255 custom, "higher label wins") is a compact way to teach a
+composable rule system. **Borrow:** write our toolkit skills as act-from-the-table
+reference, one runnable command per capability row.
+
+## Building MCP apps (tldraw mcp-app skills) — the blueprint for our own
+
+tldraw ships four **situation-split** skills for building MCP-UI apps (a tool + an HTML
+resource rendered inline in the host) with `@modelcontextprotocol/ext-apps`:
+`create-mcp-app` (new), `add-app-to-server` (enrich an existing MCP server),
+`convert-web-app` (one codebase → standalone + MCP), `migrate-oai-app` (port from the
+OpenAI Apps SDK). Rules to bake into every Maggie/design MCP app:
+- **Tool + resource + `_meta.ui.resourceUri` link**, and **always return a text `content`
+  fallback** beside `structuredContent` (UI is enhancement, never replacement); register
+  the App-tool only when `getUiCapability()` says the client supports UI.
+- **Host-theme integration via CSS variables** (`var(--color-*, fallback)`,
+  `applyDocumentTheme`/`HostStyleVariables`/`Fonts`, safe-area insets) so our UI inherits
+  the host look.
+- **Single-file bundle** (`vite-plugin-singlefile`): sandboxed iframe, no same-origin
+  server, so every external origin must be in CSP or it fails silently; **register all
+  handlers before `app.connect()`**.
+- Authoring technique worth copying: instead of inlining a huge SDK API into the skill,
+  **clone the SDK at the pinned installed version** (`git clone --branch "v$(npm view …
+  version)"`) and give a **file → what-you'll-find-in-it map**; end with a Testing step
+  against a reference host and a **"Before Finishing" self-injected-todo checklist**
+  (re-read each checkbox and state what you did) — a reliability pattern for any
+  migration/QA skill.
+
 ## CLIs: command surfaces worth matching
 
 - **svgo** (we already wrap it) — plugin architecture (`preset-default` = an ordered,
@@ -107,6 +154,37 @@ restricted sandbox, before any API list.
   caption into styled, karaoke-timed, speaker-split social-video subtitles. See
   [captions-transcription](captions-transcription.md).
 
+## Workflows (CI) — what's worth copying, and what isn't
+
+Most design-repo `.github/workflows` are standard build/test/lint/release/docker pipelines
+with nothing design-specific (excalidraw, darktable, motion-canvas, remotion). Three
+genuinely borrowable patterns, for our own release + asset-QA automation:
+- **Release-triggered skills mirror** (pixijs `sync-skills.yml`). On each non-prerelease
+  release it reads `skills/` at the release tag and one-way-pushes it to a standalone
+  mirror repo in lockstep with the npm package, short-lived GitHub-App token, a
+  ref-validation guard against injection, `workflow_dispatch` for out-of-band fixes. Exactly
+  the shape to publish/mirror our own skills toolkit on release (pairs with remotion's
+  `npx skills add` distribution).
+- **Screenshot-diff → PR comment, security-safe** (three.js `report-e2e.yml`). A
+  `workflow_run`-triggered privileged job downloads screenshot artifacts from the completed
+  CI run, pushes failures to a dedicated branch, and embeds them in a PR comment — under the
+  "never execute PR artifacts" rule (separate workflow, no PR checkout). Directly borrowable
+  for QA of our generated design/video assets: render → diff → post the visual diff inline.
+- **Visual tests in their own job on a pinned runner** (pixijs `pull-visuals.yml`,
+  `runs-on: macos-26`). Pixel/visual tests belong in a separate job on a consistent OS
+  (rendering is platform-sensitive), not folded into the unit matrix.
+
+## A note on maintenance vs product surfaces (confirmed by reading)
+
+To avoid path-name guessing, the `skills/`/`mcp` paths classified as maintenance were
+read: react-spring `speckit-*` (spec-kit dev workflow), tsparticles `nx-*` (monorepo
+scaffolding), tldraw/penpot/remotion `.agents/.github` skills (issue/PR/release/commit dev
+tooling), videojs `create-skill`/`maintain-tests` — all confirmed maintenance. Two soft
+flags glanced for reusable doctrine (not shipped user skills): Babylon
+`porting-tools-to-fluent` (a legacy-UI→Fluent-UI migration pattern) and videojs
+`implement-accessible-ui`/`implement-ui-transition` (ARIA/focus/live-region + transition-
+lifecycle engineering worth a look for our UI output).
+
 ## Licensing
 Patterns/architecture only (adopt the idea, write our own code): Babylon.js (Apache-2.0),
 tldraw (custom), penpot (MPL), tsparticles (MIT), pixijs (MIT), pts (Apache-2.0),

package/package.json

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

package/references/agent-native-design-surfaces.md

@@ -87,6 +87,53 @@ Form = pencil, Pt/Group = ideas"), then a **no-bundler sandbox-safe quick start*
 open a library skill with a tiny mental model + a copy-paste quick start that runs in a
 restricted sandbox, before any API list.
 
+### Router-only hub + progressively-disclosed spokes, shipped as a package (remotion)
+Remotion ships **12 user-facing skills as an npm package** (`@remotion/skills`,
+`npx skills add remotion-dev/skills`; a per-client mirror lives in
+`packages/codex-plugin/skills/`): best-practices, captions, create, docs, interactivity,
+maps, markup, multimedia, render, saas, studio, upgrade. Three patterns to adopt:
+- **A router-only hub** (`remotion-best-practices`) with *zero* task content — only "if the
+  user wants X, load skill Y." Keeps the always-loaded entry point tiny.
+- **Progressive disclosure**: each spoke is a thin SKILL.md that pulls in supporting `.md`
+  files only when relevant (markup has 37, best-practices 14, captions 6). Every skill
+  carries a `version:` matching the package.
+- **Round-trip-editable-artifact doctrine** (`remotion-interactivity`): author output so a
+  human can edit it in a GUI and it writes back to code — inline values only, no
+  constants/spreads/math, named elements, inline `interpolate()`. Directly applicable to
+  generating marketing/design/video assets that stay editable rather than opaque.
+
+### Concept-table + runnable-one-liner-per-row (auto-editor)
+auto-editor's 4 skills (one **hub** `auto-editor` + spokes `-effects`/`-export`/
+`-transcribe`) are built almost entirely of **dense option tables where every row is
+followed by an exact copy-paste one-liner** — including negative/inverted cases
+(`--edit "(not word:um)"`). An agent acts from the table without prose. Its label model
+(0=silent, 1=active, 2–255 custom, "higher label wins") is a compact way to teach a
+composable rule system. **Borrow:** write our toolkit skills as act-from-the-table
+reference, one runnable command per capability row.
+
+## Building MCP apps (tldraw mcp-app skills) — the blueprint for our own
+
+tldraw ships four **situation-split** skills for building MCP-UI apps (a tool + an HTML
+resource rendered inline in the host) with `@modelcontextprotocol/ext-apps`:
+`create-mcp-app` (new), `add-app-to-server` (enrich an existing MCP server),
+`convert-web-app` (one codebase → standalone + MCP), `migrate-oai-app` (port from the
+OpenAI Apps SDK). Rules to bake into every Maggie/design MCP app:
+- **Tool + resource + `_meta.ui.resourceUri` link**, and **always return a text `content`
+  fallback** beside `structuredContent` (UI is enhancement, never replacement); register
+  the App-tool only when `getUiCapability()` says the client supports UI.
+- **Host-theme integration via CSS variables** (`var(--color-*, fallback)`,
+  `applyDocumentTheme`/`HostStyleVariables`/`Fonts`, safe-area insets) so our UI inherits
+  the host look.
+- **Single-file bundle** (`vite-plugin-singlefile`): sandboxed iframe, no same-origin
+  server, so every external origin must be in CSP or it fails silently; **register all
+  handlers before `app.connect()`**.
+- Authoring technique worth copying: instead of inlining a huge SDK API into the skill,
+  **clone the SDK at the pinned installed version** (`git clone --branch "v$(npm view …
+  version)"`) and give a **file → what-you'll-find-in-it map**; end with a Testing step
+  against a reference host and a **"Before Finishing" self-injected-todo checklist**
+  (re-read each checkbox and state what you did) — a reliability pattern for any
+  migration/QA skill.
+
 ## CLIs: command surfaces worth matching
 
 - **svgo** (we already wrap it) — plugin architecture (`preset-default` = an ordered,
@@ -107,6 +154,37 @@ restricted sandbox, before any API list.
   caption into styled, karaoke-timed, speaker-split social-video subtitles. See
   [captions-transcription](captions-transcription.md).
 
+## Workflows (CI) — what's worth copying, and what isn't
+
+Most design-repo `.github/workflows` are standard build/test/lint/release/docker pipelines
+with nothing design-specific (excalidraw, darktable, motion-canvas, remotion). Three
+genuinely borrowable patterns, for our own release + asset-QA automation:
+- **Release-triggered skills mirror** (pixijs `sync-skills.yml`). On each non-prerelease
+  release it reads `skills/` at the release tag and one-way-pushes it to a standalone
+  mirror repo in lockstep with the npm package, short-lived GitHub-App token, a
+  ref-validation guard against injection, `workflow_dispatch` for out-of-band fixes. Exactly
+  the shape to publish/mirror our own skills toolkit on release (pairs with remotion's
+  `npx skills add` distribution).
+- **Screenshot-diff → PR comment, security-safe** (three.js `report-e2e.yml`). A
+  `workflow_run`-triggered privileged job downloads screenshot artifacts from the completed
+  CI run, pushes failures to a dedicated branch, and embeds them in a PR comment — under the
+  "never execute PR artifacts" rule (separate workflow, no PR checkout). Directly borrowable
+  for QA of our generated design/video assets: render → diff → post the visual diff inline.
+- **Visual tests in their own job on a pinned runner** (pixijs `pull-visuals.yml`,
+  `runs-on: macos-26`). Pixel/visual tests belong in a separate job on a consistent OS
+  (rendering is platform-sensitive), not folded into the unit matrix.
+
+## A note on maintenance vs product surfaces (confirmed by reading)
+
+To avoid path-name guessing, the `skills/`/`mcp` paths classified as maintenance were
+read: react-spring `speckit-*` (spec-kit dev workflow), tsparticles `nx-*` (monorepo
+scaffolding), tldraw/penpot/remotion `.agents/.github` skills (issue/PR/release/commit dev
+tooling), videojs `create-skill`/`maintain-tests` — all confirmed maintenance. Two soft
+flags glanced for reusable doctrine (not shipped user skills): Babylon
+`porting-tools-to-fluent` (a legacy-UI→Fluent-UI migration pattern) and videojs
+`implement-accessible-ui`/`implement-ui-transition` (ARIA/focus/live-region + transition-
+lifecycle engineering worth a look for our UI output).
+
 ## Licensing
 Patterns/architecture only (adopt the idea, write our own code): Babylon.js (Apache-2.0),
 tldraw (custom), penpot (MPL), tsparticles (MIT), pixijs (MIT), pts (Apache-2.0),