@topy-ai/maggie 0.8.6 → 0.8.8

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.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.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 36 installable skills and a local-first MaggieDash foundation.
+package ships 37 installable skills and a local-first MaggieDash foundation.
 
-This package is `0.8.6` — it completes the two adopted design skills with full production references (every copy-ready snippet and default table) and makes 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.8` — it adds `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/ffmpeg-recipes.md

@@ -0,0 +1,125 @@
+# ffmpeg recipes
+
+The distilled, correct ffmpeg command layer for marketing video, used by
+`maggie-video` (and shared with `maggie-design-motion`'s export). These are the
+commands `maggie_video.py` generates; this reference explains each so they can be
+adapted. Distilled from moviepy, editly, auto-editor, FFmpeg and HandBrake (see
+the design reference library category N). We **invoke the `ffmpeg` binary** (not
+link libav), so this stays license-clean; most ffmpeg builds bundle x264/x265 and
+are GPL binaries - fine to invoke, do not vendor a GPL build into a package.
+
+Common prefix: `ffmpeg -y -hide_banner -loglevel error`. Always force
+`-pix_fmt yuv420p` and `setsar=1` on output for universal playback (moviepy has a
+latent `yuva420p` typo - do not copy it).
+
+## Encode (web-safe MP4)
+
+```bash
+ffmpeg -y -i IN -c:v libx264 -profile:v high -preset medium -crf 20 \
+  -pix_fmt yuv420p -c:a aac -b:a 128k -movflags +faststart OUT.mp4
+```
+
+`+faststart` moves the moov atom to the front for web streaming. CRF 18-23 (lower =
+larger/better). WebM (VP9): `-c:v libvpx-vp9 -crf 32 -b:v 0 -row-mt 1 -pix_fmt
+yuv420p -c:a libopus -b:a 128k`.
+
+## High-quality GIF (one-pass palette)
+
+```bash
+ffmpeg -y -i IN -vf "fps=15,scale=480:-1:flags=lanczos,split[s0][s1];\
+[s0]palettegen[p];[s1][p]paletteuse" -loop 0 OUT.gif
+```
+
+Scale/fps down first to keep size sane; the palette pass avoids banding. Keep bayer
+dithering (`paletteuse=dither=bayer:bayer_scale=4`) when a photo is in frame.
+
+## Trim
+
+```bash
+# fast, no re-encode (cuts at the nearest keyframe)
+ffmpeg -y -ss START -i IN -t DURATION -map 0 -c copy -avoid_negative_ts make_zero OUT.mp4
+# frame-accurate: drop -c copy and re-encode with the MP4 recipe
+```
+
+## Concat
+
+```bash
+# same codec (fast): concat.txt has lines  file '/abs/clip1.mp4'
+ffmpeg -y -f concat -safe 0 -i concat.txt -c copy OUT.mp4
+# mixed sources (re-encode via filter)
+ffmpeg -y -i a.mp4 -i b.mp4 -filter_complex \
+  "[0:v][0:a][1:v][1:a]concat=n=2:v=1:a=1[v][a]" -map "[v]" -map "[a]" \
+  -c:v libx264 -crf 20 -pix_fmt yuv420p -movflags +faststart OUT.mp4
+```
+
+## Scale + pad or crop to a channel aspect
+
+```bash
+# 9:16 reel (1080x1920); use 1080x1080 square or 1920x1080 landscape likewise
+# pad (letterbox, no distortion):
+ffmpeg -y -i IN -vf "scale=1080:1920:force_original_aspect_ratio=decrease,\
+pad=1080:1920:(ow-iw)/2:(oh-ih)/2:color=black,setsar=1" \
+  -c:v libx264 -crf 20 -pix_fmt yuv420p -movflags +faststart OUT.mp4
+# crop (fill): force_original_aspect_ratio=increase,crop=1080:1920,setsar=1
+```
+
+## Overlay / watermark (logo bottom-right, scaled to 12% height, 24px margin)
+
+```bash
+ffmpeg -y -i IN -i logo.png -filter_complex \
+  "[1][0]scale2ref=w=oh*mdar:h=ih*0.12[logo][base];[base][logo]overlay=W-w-24:H-h-24" \
+  -c:a copy -c:v libx264 -crf 20 -pix_fmt yuv420p OUT.mp4
+```
+
+## Subtitles
+
+```bash
+# burn in (hardsub) from SRT
+ffmpeg -y -i IN -vf "subtitles=subs.srt:force_style='FontName=Inter,FontSize=24,BorderStyle=3'" \
+  -c:v libx264 -crf 20 -pix_fmt yuv420p -c:a copy OUT.mp4
+# soft-mux (toggleable track, MP4)
+ffmpeg -y -i IN -i subs.srt -c copy -c:s mov_text -metadata:s:s:0 language=eng OUT.mp4
+```
+
+## Loudness normalize (EBU R128; -14 LUFS = social/YouTube target)
+
+```bash
+# quick single pass
+ffmpeg -y -i IN -af loudnorm=I=-14:TP=-1.5:LRA=11 -c:v copy -c:a aac -b:a 128k OUT.mp4
+# accurate two pass: measure first (reads JSON from stderr), then apply measured_* values
+ffmpeg -i IN -af loudnorm=I=-14:TP=-1.5:LRA=11:print_format=json -f null -
+```
+
+editly's cheaper alternative is `dynaudnorm=g=5:maxgain=30`.
+
+## Thumbnail / poster
+
+```bash
+ffmpeg -y -ss 00:00:03 -i IN -frames:v 1 -q:v 2 OUT.jpg       # at a timestamp
+ffmpeg -y -i IN -vf "thumbnail,scale=1280:-1" -frames:v 1 OUT.jpg  # most representative frame
+```
+
+## Silence auto-cut (auto-editor's idea, via the CLI)
+
+```bash
+ffmpeg -i IN -af silencedetect=noise=-30dB:d=0.3 -f null -   # detect ranges
+# then build a select/concat of the kept ranges (pad each ~0.2s)
+```
+
+## Transitions (between two clips)
+
+`xfade=transition=fade:duration=0.5:offset=5.0` for video and `acrossfade=d=0.5`
+for audio. editly/gl-transitions names (`fade`, `dissolve`, `directional-left`, ...)
+map onto xfade's transition list.
+
+## The CLI
+
+`maggie_video.py` generates every command above (and runs it with `--run` when
+`ffmpeg` is on PATH). It prints the command so it is reviewable and loggable:
+
+```bash
+maggie tool maggie_video.py social --input in.mp4 --output reel.mp4 --aspect reel
+maggie tool maggie_video.py gif --input in.mp4 --output out.gif --fps 15 --width 480
+maggie tool maggie_video.py --run encode --input in.mov --output out.mp4   # actually runs
+maggie tool maggie_video.py presets
+```

package/bundled-references/programmatic-video.md

@@ -0,0 +1,80 @@
+# Programmatic video: the render-then-encode pattern
+
+How to produce video from code deterministically, distilled from the leading
+engines (Motion Canvas, Remotion, Revideo, CCapture). Used by `maggie-video`;
+`maggie-design-motion`'s Part C is one concrete implementation of this pattern (the
+DOM/Playwright case). Author your own code from this; adopt engines per the license
+table below.
+
+## The pattern (every engine agrees)
+
+1. **The frame is the unit of truth; the wall clock is the enemy.** Deterministic
+   output comes from driving content by an **absolute frame index or a virtual
+   clock**, never real time. Two techniques:
+   - **Seek by frame:** re-evaluate the scene at frame N (`playback.seek(frame)` in
+     Motion Canvas / Revideo; the current-frame hook in Remotion).
+   - **Fake the clock:** monkeypatch `performance.now`, `requestAnimationFrame`,
+     `Date`, timers and `currentTime`, and advance one fixed step per captured frame
+     (CCapture's `TimeWarp`; Playwright's `page.clock` + `__tick` in Part C).
+2. **Render then encode, decoupled.** Produce frames as fast as the machine allows
+   (not realtime) into a canvas/DOM, then feed an encoder as a separate stage.
+3. **Two encode routes.** (a) **Shell out to ffmpeg** via a pipe - `image2pipe`
+   base64 PNG (Revideo) or `rawvideo`/rgba (Motion Canvas), output
+   `-pix_fmt yuv420p -movflags +faststart` (the exact profile in
+   [ffmpeg recipes](ffmpeg-recipes.md)). (b) **In-browser WebCodecs** (CCapture) -
+   no ffmpeg dependency, hardware-accelerated.
+4. **Headless browser as the frame factory** when the composition is web tech:
+   Revideo = Puppeteer, Remotion = headless Chromium, Part C = Playwright. The page
+   renders; the driver screenshots or reads back each frame.
+5. **One source → preview + render + parameterized batch.** The same scene file
+   drives a live preview and the headless render; **variables/props** turn one
+   template into many videos (N brand variants, localized cuts, per-product reels).
+
+## Composition models
+
+- **React components** (Remotion, Revideo also supports React) - animation driven by
+  the current frame via hooks.
+- **Generator functions** (Motion Canvas, Revideo) - a scene is
+  `makeScene2D(function* (view) { view.add(<Rect/>); yield* all(rect().position.x(100, 1)); yield* waitFor(0.5); })`;
+  timing is the generator's control flow; signals (`createSignal`) provide
+  reactivity. These read cleanly for an LLM to author from a prompt.
+- **Canvas draw calls + a recorder** (CCapture) - any existing rAF canvas loop plus
+  one `capturer.capture(canvas)` line.
+
+## Choosing an engine (decision)
+
+- **Animating an existing rendered page/design** → stay in
+  `maggie-design-motion` Part C (Playwright fake-clock). No new engine needed; this
+  is the common Maggie case (social/hero motion from a design).
+- **Programmatic, data-driven video from scratch** (N variants from brand data,
+  charts, captions) → **Revideo** - MIT, headless-first, parameterizable
+  (`renderVideo({projectFile, variables, settings:{outFile, workers}})`),
+  parallelizable across workers, and it ships a `revideo serve` render endpoint
+  (with `callbackUrl` + SSE progress) for render-as-a-service.
+- **A pure canvas sketch already using rAF** that just needs recording → **CCapture**
+  (WebCodecs, no ffmpeg).
+- **Simple clip assembly / transcode / captions** (not code-drawn animation) → the
+  ffmpeg layer directly ([ffmpeg recipes](ffmpeg-recipes.md)) or the declarative
+  [timeline model](video-timeline-model.md).
+
+## Licenses (critical)
+
+| Engine | License | Adopt? |
+|---|---|---|
+| Motion Canvas | MIT | Yes (generators; editor-driven render) |
+| **Revideo** | MIT | **Yes - recommended programmatic default** (headless, parameterized, parallel) |
+| CCapture.js | MIT | Yes - the WebCodecs recorder / clock-faking reference |
+| video.js | Apache-2.0 | Playback only, not production |
+| **Remotion** | **Remotion License (source-available; paid Company License for for-profit orgs > 3 employees)** | **No hard dependency** - reference/option the end user may license; keep Maggie's default on the MIT stack |
+
+Rendering is a **local CPU/GPU cost** (ffmpeg, a headless browser), not a paid API -
+flag long renders as a time/resource cost, consistent with "local tools only". If
+any hosted or LLM video generation is wired in, the global BYOK + spend-first rules
+apply.
+
+## Shared encode profile
+
+`maggie-video` and `maggie-design-motion` share one profile:
+`libx264 -crf 14-20 -preset slow/medium -pix_fmt yuv420p -movflags +faststart`,
+even dimensions, plus 960px / 800x500 GIF deliverables. For transparent output,
+Revideo uses per-format pixel formats (`yuva420p` WebM, `yuva444p10le` ProRes).

package/bundled-references/redesign-audit.md

@@ -0,0 +1,144 @@
+# Redesign audit (existing sites)
+
+A diagnostic checklist for upgrading an **existing** site or app to premium quality:
+find the generic AI-design patterns, weak states, and sloppy code, then fix them
+**in place** without breaking functionality or migrating frameworks. Used by the `maggie-design` skill - run the
+audit to decide *what* to change, then apply the changes through maggie-design's
+`in-place` / `section` / `verify` flow (small, reviewable, evidence-backed edits),
+never a rewrite.
+
+Concrete values (fonts, dark colours, spacing, type scale, radius, icons, motion)
+come from [landing-page visual defaults](landing-page-visual-defaults.md); they are
+**defaults** that the project's own DESIGN.md/tokens override. Never invent a value
+that is in neither place - ask. Adapted from `elayadesign/redesign-skill`
+`redesign-existing-projects` (MIT; from `Leonxlnx/taste-skill`); see Credits.
+
+## How to run it
+
+1. **Scan** - read the codebase; identify framework, styling method (Tailwind v3/v4,
+   vanilla CSS, styled-components, CSS modules), and the current patterns.
+2. **Diagnose** - go through the audit below; list every generic pattern, weak
+   point, and missing state. **Report before fixing; let the user veto items.**
+3. **Fix** - apply targeted upgrades inside the existing stack, in the Fix-priority
+   order, through maggie-design (test after each; keep diffs reviewable).
+
+## Audit
+
+### Typography
+Browser-default or Inter/Roboto/Arial/Open Sans/Helvetica fonts; two typefaces on
+one site; any italics; ultra-bold (800/900); only 400+700 in use (add 500/600);
+headlines lacking presence (more display size, tighter tracking); body wider than
+~65 characters; proportional numerals in data UI (use `tabular-nums`); missing
+letter-spacing (negative on big headers, positive on small caps); all-caps
+subheaders everywhere; orphaned words (`text-wrap: balance`/`pretty`); hyphens in
+copy; off-scale font sizes (snap to the type scale, closest step below); off-scale
+button type (main `text-base` semibold, header `text-sm` semibold).
+
+### Colour and surfaces
+Backgrounds outside the approved dark palette (snap to it; not `#0a0a0a`/`#121212`/
+tinted navy); **any background gradient** (flat only; the one exception is hero
+heading text); flat hero heading colour (apply the approved text gradient); **the
+purple/blue "AI gradient" - the single most common AI fingerprint** (flat neutral
+base + one accent); oversaturated accents (keep under ~80%); more than one accent;
+mixing warm and cool grays; generic pure-black `box-shadow` (tint toward the
+background hue); zero-texture flatness (subtle noise/grain, never a gradient);
+inconsistent lighting direction (one light source); a random dark section in a light
+page or vice versa; empty sections with no depth (masked low-opacity imagery or a
+pattern; `https://picsum.photos/seed/{name}/1920/1080` as a placeholder, never an
+ambient gradient).
+
+### Layout
+Everything centred/symmetrical (break it); three equal card columns as the feature
+row (keep 3-5 benefits as content, but zig-zag/asymmetric/scroll/masonry as layout);
+`height: 100vh` (use `min-height: 100dvh`); complex flexbox percentage math (CSS
+Grid); no max-width container (~1200-1440px; hero capped ~680px); flexbox-forced
+equal card heights (allow variable/masonry); radius by feel (token scale +
+nested-radius formula); ad-hoc spacing (the spacing scale); no overlap/depth
+(negative margins to layer); symmetrical vertical padding (optical, usually more at
+the bottom); dashboard always a left sidebar (try top nav / command menu /
+collapsible); missing whitespace; CTAs not bottom-aligned in card groups; pricing/
+comparison list items starting at different Y (fixed-height title/price blocks);
+misaligned baselines across side-by-side elements; mathematically-but-not-optically
+aligned icons/text.
+
+### Interactivity and states
+Default easing (`ease`/`linear`/`ease-in-out` -> the base curve, 500ms movement /
+300ms colour-opacity, never under 200ms); content just "there" on scroll (rise+fade
+once, 600-800ms); scroll listeners (use `IntersectionObserver`/`whileInView`); nav
+welded to the top edge (float it, translucent blur); instant menu-icon swap (animate
+it); cramped mobile dropdown (full-height panel, links staggered ~60ms, under 400ms);
+no reduced-motion handling (swap movement for a fade); no hover state; no active/
+pressed feedback (`scale(0.98)`/`translateY(1px)`); missing focus ring; no loading
+states (skeletons, not spinners); no empty states (a composed getting-started view);
+no error states (inline, specific, never `alert()`); dead `#` links; no current-page
+nav indicator; scroll jumping (`scroll-behavior: smooth`); animating `top`/`left`/
+`width`/`height` (use `transform`/`opacity`).
+
+### Content
+Placeholder/stock people and repeated faces; suspiciously round numbers; generic
+brand names; filler words ("revolutionize", "supercharge", "cutting edge",
+"effortless", "transform your workflow", "world class"); vague value props
+("streamline"/"optimize" -> a measurable outcome); features with no outcome; weak
+CTAs ("Learn more"/"Submit" -> verb + what they get); competing CTAs above the fold;
+proof buried at the bottom; no risk reversal; loud/cute system messages (calm and
+specific); passive voice; placeholder/Latin text (a blocker); Title Case (use
+sentence case).
+
+### Component patterns
+Generic card (border + shadow + white bg -> background or spacing alone; cards only
+where elevation means hierarchy); single-side card border (all around or none);
+always one filled + one ghost button (add text/tertiary); pill "New"/"Beta" badges
+(square/flag/plain); accordion FAQ (keep 6-12 Q&A, change the pattern); three-card
+carousel testimonials with dots; three-tower pricing (emphasise the recommended tier
+by colour/weight, not height); modals for everything (inline/slide-over/expand);
+avatar circles only (squircles); sun/moon theme toggle (dropdown/system/settings);
+four-column footer link farm (main paths + legal only).
+
+### Iconography and imagery
+Lucide/Feather/Material icons (-> the approved set); cliche metaphors (rocket for
+"launch", shield for "security" -> bolt, fingerprint, spark, vault); inconsistent
+stroke widths; missing favicon; stock "diverse team" photos.
+
+### Code quality
+Div soup (semantic HTML); inline styles mixed with classes; hardcoded pixel widths
+(`%`/`rem`/`em`/`max-width`); missing/`alt="image"` alt text; arbitrary z-index like
+`9999` (a scale); commented-out dead code; **import hallucinations** (verify every
+import exists in the dependency file); missing meta tags (`<title>`, description,
+`og:image`, social).
+
+### Strategic omissions (what AI builds forgets)
+Legal links; back navigation; a custom 404; form validation; a skip-to-content link;
+cookie consent where required (see `maggie-legal`); landing-page indexing not
+considered (`noindex` ad-only/time-bound, real title/meta/internal-links/AEO FAQ for
+evergreen - hand SEO specifics to `maggie-seo-geo`).
+
+## Fix priority (max impact, min risk)
+
+1. Font swap - biggest instant win, lowest risk.
+2. Colour and surface cleanup - snap to the palette, remove background gradients.
+3. Hover / active / focus states - makes it feel alive.
+4. Layout and spacing - grid, max-width, spacing scale, nested-radius formula.
+5. Motion pass - base curve, IntersectionObserver reveals, floating nav, mobile menu.
+6. Replace generic components - swap cliche patterns for the alternatives above.
+7. Loading / empty / error states - makes it feel finished.
+8. Copy pass - cut cliches, add specificity, fix CTAs.
+9. Type-scale polish - the premium final touch.
+
+## Rules
+
+- Work with the existing stack; do not migrate frameworks or styling libraries.
+- Do not break functionality; test after every change (maggie-design's verify/QA).
+- Report the diagnosis before fixing; let the user veto items.
+- Check the dependency file before importing any library; check Tailwind v3 vs v4
+  before touching config; no framework -> vanilla CSS.
+- Small, targeted, reviewable changes over big rewrites.
+- Never invent a design value; if it is in neither this audit nor the visual
+  defaults nor the project's system, ask.
+
+## Credits
+
+Adapted (not transcribed) from
+[`elayadesign/redesign-skill`](https://github.com/elayadesign/redesign-skill)
+`redesign-existing-projects` by Elaya (MIT), which adapts audit structure and
+content-realism checks from [`Leonxlnx/taste-skill`](https://github.com/Leonxlnx/taste-skill)
+by Leon Lin (MIT).

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

@@ -0,0 +1,110 @@
+# Marketing-video timeline model
+
+An engine-neutral, provider-neutral data shape for "assemble these clips, images,
+text, captions and audio into a video", distilled from the open NLEs (MLT /
+Shotcut / Kdenlive, OpenShot, Olive). Used by `maggie-video`. We adopt the **data
+shape** (an uncopyrightable idea), never their code - MLT/Shotcut/Kdenlive/OpenShot/
+Olive are LGPL/GPL. It renders through the **ffmpeg binary** (the common
+denominator, arm's-length), or optionally through `melt` as a GPL external tool.
+
+## Conventions (chosen for LLM-friendliness)
+
+- **Seconds** (floats) at the authoring layer, not frames (OpenShot-style).
+- **`position`** = where a clip starts on the timeline; **`start`/`end`** = the trim
+  within its source (OpenShot's split; MLT calls the trim `in`/`out`).
+- **`z`** = track stacking; higher is on top (mirrors MLT `b_track` over `a_track`,
+  OpenShot's higher layer number).
+- **Keyframes** as `{t, v, ease}` arrays, ease in `linear | hold | smooth | bezier`
+  (MLT's linear/discrete/smooth + OpenShot's Linear/Constant/Bezier).
+- **Relative positions/sizes** (`"80%"`, 0..1) + named anchors, so it is
+  resolution-independent.
+
+## The model
+
+```jsonc
+{
+  "output": { "width": 1080, "height": 1920, "fps": 30, "format": "mp4",
+              "vcodec": "h264", "acodec": "aac", "duration": "auto" },
+  "assets": {
+    "shot1": { "type": "video", "src": "footage/a.mp4" },
+    "product": { "type": "image", "src": "footage/product.jpg" },
+    "logo": { "type": "image", "src": "brand/logo.png" },
+    "vo": { "type": "audio", "src": "audio/vo.mp3" },
+    "music": { "type": "audio", "src": "audio/track.mp3" }
+  },
+  "tracks": [
+    { "id": "main", "kind": "video", "z": 0, "clips": [
+      { "asset": "shot1", "start": 2.0, "end": 7.0, "position": 0.0, "fit": "cover",
+        "effects": [ { "type": "zoom", "keyframes": [
+          {"t":0.0,"v":1.0,"ease":"linear"}, {"t":5.0,"v":1.12,"ease":"smooth"} ] } ] },
+      { "asset": "product", "position": 5.0, "duration": 4.0, "fit": "cover" }
+    ] },
+    { "id": "overlay", "kind": "video", "z": 10, "clips": [
+      { "type": "text", "text": "50% OFF TODAY", "position": 1.0, "duration": 3.0,
+        "style": { "font": "Inter-Bold", "size": 96, "color": "#FFFFFF", "box": "#E11D48", "align": "center" },
+        "rect": { "x": "10%", "y": "70%", "w": "80%", "h": "15%" },
+        "effects": [ { "type": "opacity", "keyframes": [
+          {"t":0,"v":0}, {"t":0.4,"v":1}, {"t":2.6,"v":1}, {"t":3.0,"v":0} ] } ] },
+      { "asset": "logo", "position": 0.0, "duration": 9.0,
+        "rect": { "x": "80%", "y": "5%", "w": "15%", "h": "auto" } },
+      { "type": "captions", "src": "audio/vo.srt" }
+    ] }
+  ],
+  "transitions": [ { "type": "crossfade", "between": ["shot1","product"], "position": 5.0, "duration": 0.5 } ],
+  "audio": [
+    { "asset": "vo", "position": 0.5, "gain": 0 },
+    { "asset": "music", "position": 0.0, "gain": -18, "ducking": { "under": "vo", "amount": -12 },
+      "fade_out": { "at": 8.5, "duration": 0.5 } }
+  ]
+}
+```
+
+Minimal required: `output{width,height,fps,format}`, `assets{}`, one video track of
+`clips[]` each with `asset`+`position`+(`duration` or `start`/`end`). Everything
+else is additive.
+
+## Field crosswalk (stay compatible with any backend)
+
+| this model | MLT | OpenShot | Olive |
+|---|---|---|---|
+| asset `src` | producer `resource` | `files[].path` | footage node |
+| `start`/`end` (trim) | `in`/`out` (frames) | `start`/`end` (sec) | `kMediaInInput` |
+| `position` (timeline) | playlist order + `blank` | `position` (sec) | `ClipBlock.in()` |
+| track / `z` | playlist in multitrack | `layer` number | block in sequence |
+| overlay | `composite` transition | higher layer | graph edge |
+| keyframe ease | `linear`/`discrete`(`|`)/`smooth`(`~`) | Linear/Constant/Bezier | kLinear/kHold/kBezier |
+| time base | frames | seconds | rational |
+
+## Rendering through ffmpeg (default, no GPL linking)
+
+Compile the model to one `filter_complex`:
+
+- **trim / in-out:** `-ss start -t dur -i a.mp4`, or `trim=start=..:end=..,setpts=PTS-STARTPTS`.
+- **fit to canvas:** `"cover"` = `scale=W:H:force_original_aspect_ratio=increase,crop=W:H`;
+  `"contain"` = `...decrease,pad=...` (see [ffmpeg recipes](ffmpeg-recipes.md)).
+- **sequence:** `concat` back-to-back; `overlay=enable='between(t,P,P+D)'` for timed overlays.
+- **crossfade:** `xfade=transition=fade:duration=0.5:offset=5.0`; audio `acrossfade`.
+- **text / lower-thirds:** `drawtext=...:enable='between(t,1,4)'`; animate via `x=`/`alpha=` expressions in `t`.
+- **logo:** `overlay=W*0.8:H*0.05`. **captions:** `subtitles=vo.srt`.
+- **audio mix + ducking:** `amix`, `volume`, `sidechaincompress` (music under VO), `afade`.
+- **keyframes:** ffmpeg `t`-expressions (`alpha='if(lt(t,0.4),t/0.4,1)'`) or `zoompan`; for rich curves precompute per-frame values from the `{t,v,ease}` arrays.
+- **output:** `-c:v libx264 -r fps -pix_fmt yuv420p -c:a aac out.mp4`.
+
+`mifi/editly` (MIT) and `Zulko/moviepy` (MIT) are working prior art that this JSON
+shape renders through ffmpeg without any GPL engine.
+
+## Optional higher-fidelity backend: melt (GPL, external)
+
+The same model can emit **MLT XML** and render with
+`melt project.mlt -consumer avformat:out.mp4` - keyframes map to MLT's
+`frame=value` animation strings and `composite`/`luma` transitions. Treat `melt` as
+an optional external tool behind a provider-adapter boundary (see
+[provider adapter contract](provider-adapter-contract.md)); it is GPL, invoked at
+arm's length, never linked or vendored.
+
+## What belongs where
+
+- **This reference:** the data model, the crosswalk, the ffmpeg compilation map, the
+  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.

package/bundled-skills/catalog.json

@@ -44,7 +44,7 @@
     },
     {
       "name": "maggie-design",
-      "description": "Design authorized interior pages, review rendered responsive layouts, or explicitly rebrand a packaged homepage/template. Use rebrand only with a named source brand and target brand."
+      "description": "Design authorized interior pages, review rendered responsive layouts, explicitly rebrand a packaged homepage/template, or audit and upgrade an existing site/app in place (fix generic AI-design patterns, weak states, and sloppy code). Use rebrand only with a named source brand and target brand. Use the redesign audit whenever the user wants to improve, polish, upgrade, refine, audit, or redesign an existing page, even when they just say it looks cheap, generic, or AI-made."
     },
     {
       "name": "maggie-design-motion",
@@ -145,6 +145,10 @@
     {
       "name": "maggie-template",
       "description": "Discover, recommend, inspect, and apply verified Astro homepage templates from the Maggie marketplace. Use when a user wants to start a site from a selected template, compare available designs, or choose a visual direction before maggie-clone or maggie-design."
+    },
+    {
+      "name": "maggie-video",
+      "description": "Produce and process marketing video - render a composition to MP4/GIF/WebM, assemble clips/images/text/captions/audio on a timeline, cut to channel aspects (reel/square/youtube), burn in captions, normalize loudness, watermark, transcode, and make social cuts. Engine-neutral over the renderer (ffmpeg for assembly/transcode, a programmatic engine for code-drawn animation). Use when the user wants to make, edit, cut, caption, resize, or export a video for marketing."
     }
   ]
 }

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

@@ -1,12 +1,28 @@
 ---
 name: maggie-design
-description: Design authorized interior pages, review rendered responsive layouts, or explicitly rebrand a packaged homepage/template. Use rebrand only with a named source brand and target brand.
+description: Design authorized interior pages, review rendered responsive layouts, explicitly rebrand a packaged homepage/template, or audit and upgrade an existing site/app in place (fix generic AI-design patterns, weak states, and sloppy code). Use rebrand only with a named source brand and target brand. Use the redesign audit whenever the user wants to improve, polish, upgrade, refine, audit, or redesign an existing page, even when they just say it looks cheap, generic, or AI-made.
 metadata:
-  version: 1.6.1
+  version: 1.7.0
 ---
 
 # Maggie Design
 
+## Redesign audit (upgrade an existing site in place)
+
+When the user wants to improve, polish, upgrade, or redesign an **existing** page or
+app - including "it looks generic / cheap / AI-made" - run the
+[redesign audit](../../references/redesign-audit.md): scan the codebase, diagnose the
+generic AI-design patterns, weak states, and sloppy code against its checklist,
+**report the diagnosis before fixing**, then apply targeted upgrades in its
+fix-priority order through the in-place / section / verify flow below (small,
+reviewable, evidence-backed edits, never a rewrite, never a framework migration).
+Concrete values come from
+[landing-page visual defaults](../../references/landing-page-visual-defaults.md),
+overridden by the project's own DESIGN.md/tokens. For building a new landing page
+from scratch use [`maggie-landing-page`](../maggie-landing-page/SKILL.md); for
+turning a design into an animated showcase use
+[`maggie-design-motion`](../maggie-design-motion/SKILL.md).
+
 ## In-place route evidence
 
 `maggie design in-place --project . --route /example` resolves local source