@topy-ai/maggie 0.8.5 → 0.8.7

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.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.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 36 installable skills and a local-first MaggieDash foundation.
 
-This package is `0.8.5` — it adopts 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.7` — it folds 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-motion-production.md

@@ -0,0 +1,234 @@
+# Design-motion production detail
+
+The complete, copy-ready snippets and tables for the `maggie-design-motion` skill.
+The skill carries
+the method in prose; this reference holds the full executable detail so nothing is
+lost. Values are the defaults from the skill's "Make it yours" section. Adapted from
+`elayadesign/ai-design-skills` `design-to-motion` (MIT); see the skill's Credits.
+
+## Source alternatives (Figma is optional)
+
+The best fidelity comes from a source with real layers and values, but **Figma is
+not required**. In order of "least guessing":
+
+1. **Live URL (recommended when the design is already on the web).** The design is
+   already rendered - do not replicate pixels. Open it in headless Chrome (the
+   project's browser tooling, as `maggie-clone`/`browser-inspection` do), read the
+   computed styles, fonts, and bounds from the DOM, and screenshot it for the
+   `?still` reference. You get exact values without pixel-lifting.
+2. **Existing code / component.** If the design already exists as HTML/React/etc.,
+   skip replication entirely: mount it, add the motion layer (Part B) and the
+   capture (Part C) on top. This is the highest fidelity of all.
+3. **Figma REST API.** Exact layers, bounds, fills, effects, radii (A2/A3). Best for
+   a design that lives only in Figma.
+4. **Screenshot / flat image.** Always works; every element is rebuilt or lifted
+   from pixels (A2). Lowest fidelity, no external dependency at all.
+
+Pick the first one that fits what the user actually has. Only paths 3-4 need the
+pixel work below; paths 1-2 jump straight to the motion system.
+
+## A3. Layer export placement (Figma)
+
+Export each moving element as its own PNG at 3x (batched 20-25 ids):
+
+| Case | Placement |
+|---|---|
+| PNG size equals `absoluteRenderBounds` (text always) | Place at the render bounds |
+| PNG larger than render bounds (parent clipped it), even overhang | `x = bbox.x - (pngW - bbox.w)/2`; use `renderBounds.y` unless the top was clipped |
+| Uneven overhang (arrowhead, one square cap) | Use `strokeGeometry`/`fillGeometry` bounds from the `geometry=paths` response |
+| Rotated vectors with a large layer blur | `use_absolute_bounds=true`, place at the bbox; PSNR offset search only if that region < ~45 dB; blobs may store at 1x |
+| Zero-height/width stroked vectors | `use_absolute_bounds=true` returns null; export without it |
+| Mask group with blurred content | Anchor on the edge that was not clipped |
+| Arcs, donuts, partial ellipses | `use_absolute_bounds=true` |
+| Patterns/overlays larger than their surface | `use_absolute_bounds=true`, then crop to the surface rect |
+| Instance children (`I12:34;56:78`) | Often null; export the parent instance |
+| Lines that draw on | Write the centerline yourself and use it as a mask over the PNG (below) |
+| Photo baked in a larger layer | Export the photo node separately; cover the baked photo with a skeleton, put the separate photo on top |
+
+Keep Figma z-order; render frame strokes as an overlay above clipped content;
+rebuild a container in CSS when its children must move separately; map drop-shadow
+blur `R` to `box-shadow` blur `R` (or `filter: drop-shadow()` ~`R/2` on a group); a
+group shadow is the shadow of the union; skip hidden layers.
+
+### Drawing a line on
+
+Read corner points and arc radii from `strokeGeometry` (centerline = halfway across
+the stroke; a rounded corner's centerline radius = inner radius + half the stroke):
+
+```html
+<svg class="ly" viewBox="0 0 1440 990" style="left:0;top:0;width:1440px;height:990px">
+  <mask id="draw1">
+    <path d="M193 832 V700 A45 45 0 0 1 238 655 H380" fill="none" stroke="#fff" stroke-width="8"
+          pathLength="1" stroke-dasharray="1" stroke-dashoffset="1"/>
+  </mask>
+  <image href="data:image/png;base64,..." x="192" y="653" width="190" height="181" mask="url(#draw1)"/>
+</svg>
+```
+
+Animate `stroke-dashoffset` 1 -> 0 on the JS clock. `pathLength="1"` avoids length
+measuring; the wide mask stroke covers antialiasing. For travelling pulses, read
+positions with `getPointAtLength` on the same path.
+
+## A5. Clip pattern
+
+Keeps stage coordinates valid inside a clip; for separate cards the card's unit
+wraps its clip so the card and contents move together:
+
+```html
+<div class="clip" style="left:113px;top:138px;width:305px;height:907px;border-radius:16px 0 0 16px">
+  <div class="cin" style="left:-113px;top:-138px"><!-- units in stage coordinates --></div>
+</div>
+```
+
+```css
+.clip { position: absolute; overflow: hidden; isolation: isolate; }
+.cin  { position: absolute; width: var(--stage-w); height: var(--stage-h); }
+```
+
+## B2. Loading choreography kinds
+
+| Kind | Use for | From |
+|---|---|---|
+| `card` | Separate cards, with shadow | `translateY(24px)`, `scale(0.985)`, `blur(6px)`, opacity 0 |
+| `up` | Text, headers, values, rows | `translateY(10px)`, `blur(4px)`, opacity 0 |
+| `down` | Top toolbars/bars | `translateY(-8px)`, `blur(4px)` |
+| `left` | Sidebar items, list rows, labels | `translateX(-10px)`, `blur(4px)` |
+| `pop` | Icons, badges, avatars, buttons, dots | `scale(0.82-0.88)` from own centre, `blur(4px)` |
+| `photo` | Images | skeleton shimmer, then `blur(14px) saturate(0.6)` to sharp |
+| `wipe` | Bars, fills, highlights | left-to-right `clip-path` reveal in pixels on the full-stage unit |
+| `line`/`grow` | Rules, ticks, timelines | `scaleX(0)`/`scaleY(0)` from the start edge |
+| `donut` | Rings, gauges | conic mask sweeping clockwise from 12 o'clock |
+| `tray`/`rise` | Sheets, trays, folders | slide up 40px from the container's bottom edge, clipped |
+| `fade` | Layers under another layer | opacity only |
+
+Containers load in reading order 80-90ms apart; items 30-80ms; total intro ~2-2.5s.
+Never `scale(0)` an object (only lines/bars grow from zero). Covered layers arrive
+last and leave first. Skeletons match the real shape, 1px inside it.
+
+## B4. Story + accent tables
+
+| Visual | Story |
+|---|---|
+| Stack (leads, notifications, files) | A new item lands on top with blur, others step back a slot, the last leaves |
+| Line/area chart | A scrubber glides across, dots ride the curve, the tooltip counts; or the line redraws and numbers count up |
+| Bar chart, equalizer, grid | Bars breathe like a live feed and settle to design heights; a dot/tooltip rides the active bar |
+| Donut, gauge | Segments ease out one at a time and back; or the ring sweeps again clockwise |
+| Table, list | A cursor inspects rows, the row highlights, a preview loads; or a soft highlight steps down |
+| Calendar, scheduler | A highlight searches for an open slot, the event glides in, then back |
+| Flow, connectors | Pulses travel along connectors in flow direction, nodes light up as a pulse passes |
+| AI, prompt, form | The prompt deletes and retypes, chips evaluate one by one, the result appears with blur |
+| Counters, KPIs | Numbers count up with the chart that drives them |
+| Logo row | A continuous marquee moving exactly one full set per loop |
+| Media player | The handle and progress advance while the play button pulses |
+
+| Accent | Use for | Values |
+|---|---|---|
+| Pulse ring | Status dots, live indicators, play | 1.8-2.2s period, ring scale 1 -> 2.6, opacity 0.55 -> 0 |
+| Heartbeat | Hearts, likes, sparkles | +20% over 0.35s, every 3s |
+| Gentle bob | Floating objects | +/-2.6px, 2.8s sine |
+| Sheen sweep | Photos, bars, buttons | band 38% width, peak 34% white, 1.5s pass every 3.4s |
+| Skeleton glimmer | Placeholder lines | 2.4s shimmer |
+
+### Story track helper
+
+```js
+// [[time, value], ...] eased per segment; values may be numbers or arrays
+function track(keys, t, ease = easeInOut) {
+  if (t <= keys[0][0]) return keys[0][1];
+  for (let i = 1; i < keys.length; i++) {
+    const [t1, v1] = keys[i], [t0, v0] = keys[i - 1];
+    if (t <= t1) {
+      const k = ease(Math.min(1, (t - t0) / (t1 - t0 || 1)));
+      return Array.isArray(v0) ? v0.map((v, j) => v + (v1[j] - v) * k) : v0 + (v1 - v0) * k;
+    }
+  }
+  return keys[keys.length - 1][1];
+}
+// a slot that scrubs along a curve and returns to its design position
+slot.style.transform = `translate(${track([[0,[0,0]],[1.2,[46,-18]],[2.6,[46,-18]],[3.8,[0,0]]], t).join('px,')}px)`;
+```
+
+## B5-B6. Cycle and easing
+
+| Phase | Default timing |
+|---|---|
+| Build in | 0 -> 2.4s |
+| Stories | 2.4 -> 11.0s |
+| Dissolve | 11.0 -> 11.6s |
+| Empty beat | 11.6 -> 12.0s |
+
+| Token | Curve | Use |
+|---|---|---|
+| `--e` | `cubic-bezier(0.16, 1, 0.3, 1)` | entrance transforms (~1.05s) |
+| `--e2` | `cubic-bezier(0.33, 1, 0.68, 1)` | opacity and blur (0.7-0.8s) |
+| `--io` | `cubic-bezier(0.65, 0, 0.35, 1)` | wipes, fills, sweeps, camera |
+| linear | `linear` | constant motion only (shimmer, playback) |
+
+## C1. Deterministic capture (full)
+
+```js
+await page.clock.install({ time: 0 });
+await page.goto(url + '?capture', { waitUntil: 'load' });
+await page.evaluate(() => document.fonts.ready);
+await page.clock.pauseAt(10000);
+const loopTime = [];
+for (let i = 0; i < frames; i++) {
+  // 1. whole milliseconds that average exactly 1000/60 (17,17,16,...); runFor(1000/60) drifts
+  const dt = Math.round((i + 1) * 1000 / 60) - Math.round(i * 1000 / 60);
+  await page.clock.runFor(dt);
+  loopTime.push(await page.evaluate(([i, PRE, dt]) => {
+    if (i === PRE) window.__start();          // 2. start inside the same evaluate as the seek
+    if (i >= PRE) window.__tick(dt / 1000);   // 3. the page clock advances here, never through rAF
+    const now = performance.now();
+    for (const a of document.getAnimations()) {  // CSS transitions follow the fake clock
+      a.__m ??= window.__mark;
+      a.pause(); a.currentTime = Math.max(0, now - a.__m);
+    }
+    return i >= PRE ? window.__lt : 0;
+  }, [i, PRE, dt]));
+  await page.screenshot({ path: `${out}/${String(i).padStart(5, '0')}.png` });
+}
+```
+
+`PRE` is ~15 settle frames before the start. Viewport = frame size;
+`deviceScaleFactor = min(1920/W, 1200/H)`; the export window starts at frame `PRE-1`
+(loop time 0, empty state) and spans `cycle x 60` frames; record ~10 past it for the
+seam check. Page side in `?capture`: `__start()` adds the `in` class and every state
+change sets `window.__mark = performance.now()`; `__tick(dt)` advances loop time,
+runs the cycle phases, draws stories/accents, sets `window.__lt`; never-ending loops
+(shimmer, marquee) are driven by the JS clock, not infinite CSS keyframes.
+
+## C2. Export commands
+
+| File | Spec |
+|---|---|
+| `<name>-x.mp4` | H.264, `yuv420p`, 60fps, CRF 14-15, preset slow, `+faststart`, max 1920x1200, even dims |
+| `<name>-loop.gif` | 960px wide, 15-20fps, ~2-3MB |
+| `<name>-800x500.gif` | always delivered; crop to content at 1.6:1 or fit+pad; 20fps (12 if heavy) |
+
+```bash
+# MP4 for X
+ffmpeg -start_number $A -framerate 60 -i frames/%05d.png -frames:v $N \
+  -vf "crop=trunc(iw/2)*2:trunc(ih/2)*2" -c:v libx264 -preset slow -crf 15 \
+  -pix_fmt yuv420p -movflags +faststart name-x.mp4
+
+# website GIF (960px)
+ffmpeg -start_number $A -framerate 60 -i frames/%05d.png -filter_complex \
+  "trim=end_frame=$N,fps=20,scale=960:-2:flags=lanczos,split[a][b];\
+   [a]palettegen=max_colors=192:stats_mode=diff[p];\
+   [b][p]paletteuse=dither=bayer:bayer_scale=4:diff_mode=rectangle" -loop 0 name-loop.gif
+```
+
+For the 800x500 GIF, add before `split`:
+`scale=800:500:force_original_aspect_ratio=decrease,pad=800:500:(ow-iw)/2:(oh-ih)/2:color=<page bg>`.
+Keep bayer dithering whenever a photo is in frame (else photos band); if a GIF is
+too heavy, lower frame rate or colours before size.
+
+## Make it yours (defaults)
+
+Rise 10px (`up`), 8px (`down`/`left`); entrance blur 4px (photos 14px); pop scale
+0.82-0.88; transform 1.05s `--e`; opacity/blur 0.7-0.8s `--e2`; wipe 0.7s (slow bars
+1.1s) `--io`; card rise 24px + `scale(0.985)` + `blur(6px)`; website hero appear 6px
+rise + 2px blur, 50-70ms stagger, ~1.2s; container stagger 80-90ms; typing 45-70ms/
+glyph; story start 2.4s; story length 3-8s; cycle 12s; MP4 60fps CRF 15; GIFs 960px
+and 800x500 at 20fps.

package/bundled-references/landing-page-visual-defaults.md

@@ -0,0 +1,101 @@
+# Landing-page visual defaults
+
+The complete default value tables for the `maggie-landing-page` skill (Part B). These are
+**defaults**: the user's prompt and the project's own system (a `DESIGN.md`, token
+set, or brand) win over them. Use them to fill gaps or when there is no system yet,
+never to repaint an established brand. Adapted from `elayadesign/ai-design-skills`
+`landing-page-design` (MIT; itself from `Leonxlnx/taste-skill`); see the skill's
+Credits.
+
+## Fonts
+
+- **Default to:** Geist, Manrope, or Poppins (one typeface per site). A mono (Geist
+  Mono) only for code, data, or numeric UI where a monospace is functionally needed.
+- **Avoid defaulting to:** Inter, Roboto, Arial, Open Sans, Helvetica.
+- No italics in the interface; cap weight at bold (no 900/black).
+- The project's font choice always wins.
+
+## Type scale (snap every size to a step)
+
+Snap to the closest step **below**, taking its paired line height. Never leave
+arbitrary values (`text-[19px]`, `font-size: 22px`, `1.4rem`). Default scale is
+Tailwind's:
+
+| Class | Size | Line height |
+|---|---|---|
+| `text-xs` | 12px (0.75rem) | 16px |
+| `text-sm` | 14px (0.875rem) | 20px |
+| `text-base` | 16px (1rem) | 24px |
+| `text-lg` | 18px (1.125rem) | 28px |
+| `text-xl` | 20px (1.25rem) | 28px |
+| `text-2xl` | 24px (1.5rem) | 32px |
+| `text-3xl` | 30px (1.875rem) | 36px |
+| `text-4xl` | 36px (2.25rem) | 40px |
+| `text-5xl` | 48px (3rem) | 1 |
+| `text-6xl` | 60px (3.75rem) | 1 |
+| `text-7xl` | 72px (4.5rem) | 1 |
+| `text-8xl` | 96px (6rem) | 1 |
+| `text-9xl` | 128px (8rem) | 1 |
+
+Buttons: main `text-base` (16px) semibold; smaller header buttons `text-sm` (14px)
+semibold.
+
+## Spacing (only these values)
+
+| Token | Value | | Token | Value |
+|---|---|---|---|---|
+| Spacing-0 | 0 | | Spacing-300 | 24px |
+| Spacing-25 | 2px | | Spacing-400 | 32px |
+| Spacing-50 | 4px | | Spacing-500 | 40px |
+| Spacing-75 | 8px | | Spacing-600 | 48px |
+| Spacing-100 | 12px | | Spacing-700 | 64px |
+| Spacing-200 | 16px | | Spacing-800 | 80px |
+| | | | Spacing-900 | 96px |
+
+Main buttons: 8px vertical / 12px horizontal padding.
+
+## Corner radius
+
+Use the token radii. **Nested-radius formula** when a shape sits inside another and
+the gap is under 32px: `inner = outer - gap`, applied only when the result is > 2px
+(else leave square). Example: an outer card at 16px with 8px padding gives the inner
+element an 8px radius.
+
+## Backgrounds and hero
+
+- Backgrounds are flat - no gradients. The one exception is gradient **text** on the
+  hero heading. (A project whose brand uses gradient surfaces overrides this.)
+- Never border only one side of a card (all around or none).
+- Default dark-mode background colours: `#000000`, `#181818`, `#1F1F1F`, `#272727`,
+  `#313131`, `#131209`.
+- Hero heading text gradient: dark theme `#FFFFFF` -> `#9B9B9B`; light theme
+  `#000000` -> `#666666`, left to right. Cap heading and subheading width at ~680px;
+  break lines at meaningful points, never mid-phrase.
+
+## Icons
+
+Default to Phosphor, Solar, or Iconamoon; avoid Material Icons/Symbols. The
+project's icon set wins; validate it with `maggie-design`'s icon inventory +
+glyph-render gates before release.
+
+## Motion
+
+- Base curve `cubic-bezier(0.22,1,0.36,1)` with ~500ms for layout/position changes;
+  hover colour/opacity 300ms (never under 200ms). Never a browser-default curve
+  (`ease`, `linear`, `ease-in-out`).
+- Animate only `transform` and `opacity`; never `top`/`left`/`width`/`height`.
+- Respect `prefers-reduced-motion` (replace movement with a plain opacity change).
+- Scroll reveals rise ~32px and fade over 600-800ms, once, via `IntersectionObserver`
+  (never an unthrottled scroll listener).
+- Menu link entrance: items arrive in reading order, each rising ~24px while fading,
+  stepped 60ms apart, capped at 400ms total.
+- Tagline reveal: words go from ~25-35% opacity to full colour one at a time in
+  reading order as each crosses a trigger line (base curve; `IntersectionObserver`
+  per word or an rAF-throttled listener).
+
+## Banned filler words (content realism)
+
+Do not write "revolutionize", "supercharge", "cutting edge", "effortless",
+"transform your workflow", "take it to the next level", "harness the power", or
+"world class". Say what the product does in plain terms. Sentence case for headings
+and buttons; calm, specific system messages.

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-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",

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

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

@@ -2,7 +2,7 @@
 name: maggie-design-motion
 description: Turn a static design (a Figma frame, screenshot, dashboard, card set, app screen, or a UI on a photo) into a pixel-exact HTML replica that loads from an empty state, then has every visual act out what it does in a seamless loop, and export an MP4 plus GIFs. Use when asked to animate a design, a Figma link, a screenshot, UI cards, a dashboard or hero image, or to make a showcase loop, motion mockup, or a video/GIF of a design. Also for bento/feature cards on a landing page.
 metadata:
-  version: 0.1.0
+  version: 0.1.1
 ---
 
 # Maggie Design Motion
@@ -21,6 +21,16 @@ completion. Timing/distance/curve values live in **Make it yours** (defaults;
 override there, never ad hoc). Adapted from `elayadesign/ai-design-skills` (MIT);
 see Credits.
 
+**Figma is optional.** Choose the source with the least guessing for what the user
+actually has: a **live URL** (already rendered - read computed styles + screenshot
+via the project's browser tooling, as `maggie-clone`/`browser-inspection` do; no
+pixel-lifting), **existing code/component** (skip replication, add the motion layer
+on top - highest fidelity), **Figma REST** (exact layers), or a **screenshot** (works
+with zero dependencies, elements rebuilt/lifted from pixels). Only Figma and
+screenshot need the pixel work in Part A; a live URL or existing code jumps to the
+motion system. See [design-motion production detail](../../references/design-motion-production.md)
+for the full source-alternatives list and every copy-ready snippet and table.
+
 ## Two contexts (decide first)
 
 | | Showcase | Website |

package/bundled-skills/maggie-landing-page/SKILL.md

@@ -2,7 +2,7 @@
 name: maggie-landing-page
 description: Build a high-converting landing page - intake, page structure, layout selection, conversion copy, SEO/AEO, plus a visual-system discipline (typography, spacing, radius, backgrounds, hero, icons, motion) whose specific values are defaults the project's DESIGN.md overrides. Use when building, editing, styling, or writing copy for a landing page, marketing page, or a page section meant to convert. Designs the page; maggie-design produces and validates it.
 metadata:
-  version: 0.1.0
+  version: 0.1.1
 ---
 
 # Maggie Landing Page
@@ -106,7 +106,11 @@ proof buried; mobile that breaks readability; no clear next step.
 # Part B - Visual system (defaults; the project's DESIGN.md wins)
 
 Resolve every visual value through a rule, never ad hoc. When the project has a
-token system, use it; the values below are the starting defaults.
+token system, use it; the values below are the starting defaults. The **complete
+default tables** (the full type scale, spacing tokens, dark-mode colours, hero
+gradients, motion curves and durations, banned filler words) are in
+[landing-page visual defaults](../../references/landing-page-visual-defaults.md); the
+summary below is the working subset.
 
 ## B1. Typography
 

package/package.json

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

package/references/design-motion-production.md

@@ -0,0 +1,234 @@
+# Design-motion production detail
+
+The complete, copy-ready snippets and tables for the `maggie-design-motion` skill.
+The skill carries
+the method in prose; this reference holds the full executable detail so nothing is
+lost. Values are the defaults from the skill's "Make it yours" section. Adapted from
+`elayadesign/ai-design-skills` `design-to-motion` (MIT); see the skill's Credits.
+
+## Source alternatives (Figma is optional)
+
+The best fidelity comes from a source with real layers and values, but **Figma is
+not required**. In order of "least guessing":
+
+1. **Live URL (recommended when the design is already on the web).** The design is
+   already rendered - do not replicate pixels. Open it in headless Chrome (the
+   project's browser tooling, as `maggie-clone`/`browser-inspection` do), read the
+   computed styles, fonts, and bounds from the DOM, and screenshot it for the
+   `?still` reference. You get exact values without pixel-lifting.
+2. **Existing code / component.** If the design already exists as HTML/React/etc.,
+   skip replication entirely: mount it, add the motion layer (Part B) and the
+   capture (Part C) on top. This is the highest fidelity of all.
+3. **Figma REST API.** Exact layers, bounds, fills, effects, radii (A2/A3). Best for
+   a design that lives only in Figma.
+4. **Screenshot / flat image.** Always works; every element is rebuilt or lifted
+   from pixels (A2). Lowest fidelity, no external dependency at all.
+
+Pick the first one that fits what the user actually has. Only paths 3-4 need the
+pixel work below; paths 1-2 jump straight to the motion system.
+
+## A3. Layer export placement (Figma)
+
+Export each moving element as its own PNG at 3x (batched 20-25 ids):
+
+| Case | Placement |
+|---|---|
+| PNG size equals `absoluteRenderBounds` (text always) | Place at the render bounds |
+| PNG larger than render bounds (parent clipped it), even overhang | `x = bbox.x - (pngW - bbox.w)/2`; use `renderBounds.y` unless the top was clipped |
+| Uneven overhang (arrowhead, one square cap) | Use `strokeGeometry`/`fillGeometry` bounds from the `geometry=paths` response |
+| Rotated vectors with a large layer blur | `use_absolute_bounds=true`, place at the bbox; PSNR offset search only if that region < ~45 dB; blobs may store at 1x |
+| Zero-height/width stroked vectors | `use_absolute_bounds=true` returns null; export without it |
+| Mask group with blurred content | Anchor on the edge that was not clipped |
+| Arcs, donuts, partial ellipses | `use_absolute_bounds=true` |
+| Patterns/overlays larger than their surface | `use_absolute_bounds=true`, then crop to the surface rect |
+| Instance children (`I12:34;56:78`) | Often null; export the parent instance |
+| Lines that draw on | Write the centerline yourself and use it as a mask over the PNG (below) |
+| Photo baked in a larger layer | Export the photo node separately; cover the baked photo with a skeleton, put the separate photo on top |
+
+Keep Figma z-order; render frame strokes as an overlay above clipped content;
+rebuild a container in CSS when its children must move separately; map drop-shadow
+blur `R` to `box-shadow` blur `R` (or `filter: drop-shadow()` ~`R/2` on a group); a
+group shadow is the shadow of the union; skip hidden layers.
+
+### Drawing a line on
+
+Read corner points and arc radii from `strokeGeometry` (centerline = halfway across
+the stroke; a rounded corner's centerline radius = inner radius + half the stroke):
+
+```html
+<svg class="ly" viewBox="0 0 1440 990" style="left:0;top:0;width:1440px;height:990px">
+  <mask id="draw1">
+    <path d="M193 832 V700 A45 45 0 0 1 238 655 H380" fill="none" stroke="#fff" stroke-width="8"
+          pathLength="1" stroke-dasharray="1" stroke-dashoffset="1"/>
+  </mask>
+  <image href="data:image/png;base64,..." x="192" y="653" width="190" height="181" mask="url(#draw1)"/>
+</svg>
+```
+
+Animate `stroke-dashoffset` 1 -> 0 on the JS clock. `pathLength="1"` avoids length
+measuring; the wide mask stroke covers antialiasing. For travelling pulses, read
+positions with `getPointAtLength` on the same path.
+
+## A5. Clip pattern
+
+Keeps stage coordinates valid inside a clip; for separate cards the card's unit
+wraps its clip so the card and contents move together:
+
+```html
+<div class="clip" style="left:113px;top:138px;width:305px;height:907px;border-radius:16px 0 0 16px">
+  <div class="cin" style="left:-113px;top:-138px"><!-- units in stage coordinates --></div>
+</div>
+```
+
+```css
+.clip { position: absolute; overflow: hidden; isolation: isolate; }
+.cin  { position: absolute; width: var(--stage-w); height: var(--stage-h); }
+```
+
+## B2. Loading choreography kinds
+
+| Kind | Use for | From |
+|---|---|---|
+| `card` | Separate cards, with shadow | `translateY(24px)`, `scale(0.985)`, `blur(6px)`, opacity 0 |
+| `up` | Text, headers, values, rows | `translateY(10px)`, `blur(4px)`, opacity 0 |
+| `down` | Top toolbars/bars | `translateY(-8px)`, `blur(4px)` |
+| `left` | Sidebar items, list rows, labels | `translateX(-10px)`, `blur(4px)` |
+| `pop` | Icons, badges, avatars, buttons, dots | `scale(0.82-0.88)` from own centre, `blur(4px)` |
+| `photo` | Images | skeleton shimmer, then `blur(14px) saturate(0.6)` to sharp |
+| `wipe` | Bars, fills, highlights | left-to-right `clip-path` reveal in pixels on the full-stage unit |
+| `line`/`grow` | Rules, ticks, timelines | `scaleX(0)`/`scaleY(0)` from the start edge |
+| `donut` | Rings, gauges | conic mask sweeping clockwise from 12 o'clock |
+| `tray`/`rise` | Sheets, trays, folders | slide up 40px from the container's bottom edge, clipped |
+| `fade` | Layers under another layer | opacity only |
+
+Containers load in reading order 80-90ms apart; items 30-80ms; total intro ~2-2.5s.
+Never `scale(0)` an object (only lines/bars grow from zero). Covered layers arrive
+last and leave first. Skeletons match the real shape, 1px inside it.
+
+## B4. Story + accent tables
+
+| Visual | Story |
+|---|---|
+| Stack (leads, notifications, files) | A new item lands on top with blur, others step back a slot, the last leaves |
+| Line/area chart | A scrubber glides across, dots ride the curve, the tooltip counts; or the line redraws and numbers count up |
+| Bar chart, equalizer, grid | Bars breathe like a live feed and settle to design heights; a dot/tooltip rides the active bar |
+| Donut, gauge | Segments ease out one at a time and back; or the ring sweeps again clockwise |
+| Table, list | A cursor inspects rows, the row highlights, a preview loads; or a soft highlight steps down |
+| Calendar, scheduler | A highlight searches for an open slot, the event glides in, then back |
+| Flow, connectors | Pulses travel along connectors in flow direction, nodes light up as a pulse passes |
+| AI, prompt, form | The prompt deletes and retypes, chips evaluate one by one, the result appears with blur |
+| Counters, KPIs | Numbers count up with the chart that drives them |
+| Logo row | A continuous marquee moving exactly one full set per loop |
+| Media player | The handle and progress advance while the play button pulses |
+
+| Accent | Use for | Values |
+|---|---|---|
+| Pulse ring | Status dots, live indicators, play | 1.8-2.2s period, ring scale 1 -> 2.6, opacity 0.55 -> 0 |
+| Heartbeat | Hearts, likes, sparkles | +20% over 0.35s, every 3s |
+| Gentle bob | Floating objects | +/-2.6px, 2.8s sine |
+| Sheen sweep | Photos, bars, buttons | band 38% width, peak 34% white, 1.5s pass every 3.4s |
+| Skeleton glimmer | Placeholder lines | 2.4s shimmer |
+
+### Story track helper
+
+```js
+// [[time, value], ...] eased per segment; values may be numbers or arrays
+function track(keys, t, ease = easeInOut) {
+  if (t <= keys[0][0]) return keys[0][1];
+  for (let i = 1; i < keys.length; i++) {
+    const [t1, v1] = keys[i], [t0, v0] = keys[i - 1];
+    if (t <= t1) {
+      const k = ease(Math.min(1, (t - t0) / (t1 - t0 || 1)));
+      return Array.isArray(v0) ? v0.map((v, j) => v + (v1[j] - v) * k) : v0 + (v1 - v0) * k;
+    }
+  }
+  return keys[keys.length - 1][1];
+}
+// a slot that scrubs along a curve and returns to its design position
+slot.style.transform = `translate(${track([[0,[0,0]],[1.2,[46,-18]],[2.6,[46,-18]],[3.8,[0,0]]], t).join('px,')}px)`;
+```
+
+## B5-B6. Cycle and easing
+
+| Phase | Default timing |
+|---|---|
+| Build in | 0 -> 2.4s |
+| Stories | 2.4 -> 11.0s |
+| Dissolve | 11.0 -> 11.6s |
+| Empty beat | 11.6 -> 12.0s |
+
+| Token | Curve | Use |
+|---|---|---|
+| `--e` | `cubic-bezier(0.16, 1, 0.3, 1)` | entrance transforms (~1.05s) |
+| `--e2` | `cubic-bezier(0.33, 1, 0.68, 1)` | opacity and blur (0.7-0.8s) |
+| `--io` | `cubic-bezier(0.65, 0, 0.35, 1)` | wipes, fills, sweeps, camera |
+| linear | `linear` | constant motion only (shimmer, playback) |
+
+## C1. Deterministic capture (full)
+
+```js
+await page.clock.install({ time: 0 });
+await page.goto(url + '?capture', { waitUntil: 'load' });
+await page.evaluate(() => document.fonts.ready);
+await page.clock.pauseAt(10000);
+const loopTime = [];
+for (let i = 0; i < frames; i++) {
+  // 1. whole milliseconds that average exactly 1000/60 (17,17,16,...); runFor(1000/60) drifts
+  const dt = Math.round((i + 1) * 1000 / 60) - Math.round(i * 1000 / 60);
+  await page.clock.runFor(dt);
+  loopTime.push(await page.evaluate(([i, PRE, dt]) => {
+    if (i === PRE) window.__start();          // 2. start inside the same evaluate as the seek
+    if (i >= PRE) window.__tick(dt / 1000);   // 3. the page clock advances here, never through rAF
+    const now = performance.now();
+    for (const a of document.getAnimations()) {  // CSS transitions follow the fake clock
+      a.__m ??= window.__mark;
+      a.pause(); a.currentTime = Math.max(0, now - a.__m);
+    }
+    return i >= PRE ? window.__lt : 0;
+  }, [i, PRE, dt]));
+  await page.screenshot({ path: `${out}/${String(i).padStart(5, '0')}.png` });
+}
+```
+
+`PRE` is ~15 settle frames before the start. Viewport = frame size;
+`deviceScaleFactor = min(1920/W, 1200/H)`; the export window starts at frame `PRE-1`
+(loop time 0, empty state) and spans `cycle x 60` frames; record ~10 past it for the
+seam check. Page side in `?capture`: `__start()` adds the `in` class and every state
+change sets `window.__mark = performance.now()`; `__tick(dt)` advances loop time,
+runs the cycle phases, draws stories/accents, sets `window.__lt`; never-ending loops
+(shimmer, marquee) are driven by the JS clock, not infinite CSS keyframes.
+
+## C2. Export commands
+
+| File | Spec |
+|---|---|
+| `<name>-x.mp4` | H.264, `yuv420p`, 60fps, CRF 14-15, preset slow, `+faststart`, max 1920x1200, even dims |
+| `<name>-loop.gif` | 960px wide, 15-20fps, ~2-3MB |
+| `<name>-800x500.gif` | always delivered; crop to content at 1.6:1 or fit+pad; 20fps (12 if heavy) |
+
+```bash
+# MP4 for X
+ffmpeg -start_number $A -framerate 60 -i frames/%05d.png -frames:v $N \
+  -vf "crop=trunc(iw/2)*2:trunc(ih/2)*2" -c:v libx264 -preset slow -crf 15 \
+  -pix_fmt yuv420p -movflags +faststart name-x.mp4
+
+# website GIF (960px)
+ffmpeg -start_number $A -framerate 60 -i frames/%05d.png -filter_complex \
+  "trim=end_frame=$N,fps=20,scale=960:-2:flags=lanczos,split[a][b];\
+   [a]palettegen=max_colors=192:stats_mode=diff[p];\
+   [b][p]paletteuse=dither=bayer:bayer_scale=4:diff_mode=rectangle" -loop 0 name-loop.gif
+```
+
+For the 800x500 GIF, add before `split`:
+`scale=800:500:force_original_aspect_ratio=decrease,pad=800:500:(ow-iw)/2:(oh-ih)/2:color=<page bg>`.
+Keep bayer dithering whenever a photo is in frame (else photos band); if a GIF is
+too heavy, lower frame rate or colours before size.
+
+## Make it yours (defaults)
+
+Rise 10px (`up`), 8px (`down`/`left`); entrance blur 4px (photos 14px); pop scale
+0.82-0.88; transform 1.05s `--e`; opacity/blur 0.7-0.8s `--e2`; wipe 0.7s (slow bars
+1.1s) `--io`; card rise 24px + `scale(0.985)` + `blur(6px)`; website hero appear 6px
+rise + 2px blur, 50-70ms stagger, ~1.2s; container stagger 80-90ms; typing 45-70ms/
+glyph; story start 2.4s; story length 3-8s; cycle 12s; MP4 60fps CRF 15; GIFs 960px
+and 800x500 at 20fps.

package/references/landing-page-visual-defaults.md

@@ -0,0 +1,101 @@
+# Landing-page visual defaults
+
+The complete default value tables for the `maggie-landing-page` skill (Part B). These are
+**defaults**: the user's prompt and the project's own system (a `DESIGN.md`, token
+set, or brand) win over them. Use them to fill gaps or when there is no system yet,
+never to repaint an established brand. Adapted from `elayadesign/ai-design-skills`
+`landing-page-design` (MIT; itself from `Leonxlnx/taste-skill`); see the skill's
+Credits.
+
+## Fonts
+
+- **Default to:** Geist, Manrope, or Poppins (one typeface per site). A mono (Geist
+  Mono) only for code, data, or numeric UI where a monospace is functionally needed.
+- **Avoid defaulting to:** Inter, Roboto, Arial, Open Sans, Helvetica.
+- No italics in the interface; cap weight at bold (no 900/black).
+- The project's font choice always wins.
+
+## Type scale (snap every size to a step)
+
+Snap to the closest step **below**, taking its paired line height. Never leave
+arbitrary values (`text-[19px]`, `font-size: 22px`, `1.4rem`). Default scale is
+Tailwind's:
+
+| Class | Size | Line height |
+|---|---|---|
+| `text-xs` | 12px (0.75rem) | 16px |
+| `text-sm` | 14px (0.875rem) | 20px |
+| `text-base` | 16px (1rem) | 24px |
+| `text-lg` | 18px (1.125rem) | 28px |
+| `text-xl` | 20px (1.25rem) | 28px |
+| `text-2xl` | 24px (1.5rem) | 32px |
+| `text-3xl` | 30px (1.875rem) | 36px |
+| `text-4xl` | 36px (2.25rem) | 40px |
+| `text-5xl` | 48px (3rem) | 1 |
+| `text-6xl` | 60px (3.75rem) | 1 |
+| `text-7xl` | 72px (4.5rem) | 1 |
+| `text-8xl` | 96px (6rem) | 1 |
+| `text-9xl` | 128px (8rem) | 1 |
+
+Buttons: main `text-base` (16px) semibold; smaller header buttons `text-sm` (14px)
+semibold.
+
+## Spacing (only these values)
+
+| Token | Value | | Token | Value |
+|---|---|---|---|---|
+| Spacing-0 | 0 | | Spacing-300 | 24px |
+| Spacing-25 | 2px | | Spacing-400 | 32px |
+| Spacing-50 | 4px | | Spacing-500 | 40px |
+| Spacing-75 | 8px | | Spacing-600 | 48px |
+| Spacing-100 | 12px | | Spacing-700 | 64px |
+| Spacing-200 | 16px | | Spacing-800 | 80px |
+| | | | Spacing-900 | 96px |
+
+Main buttons: 8px vertical / 12px horizontal padding.
+
+## Corner radius
+
+Use the token radii. **Nested-radius formula** when a shape sits inside another and
+the gap is under 32px: `inner = outer - gap`, applied only when the result is > 2px
+(else leave square). Example: an outer card at 16px with 8px padding gives the inner
+element an 8px radius.
+
+## Backgrounds and hero
+
+- Backgrounds are flat - no gradients. The one exception is gradient **text** on the
+  hero heading. (A project whose brand uses gradient surfaces overrides this.)
+- Never border only one side of a card (all around or none).
+- Default dark-mode background colours: `#000000`, `#181818`, `#1F1F1F`, `#272727`,
+  `#313131`, `#131209`.
+- Hero heading text gradient: dark theme `#FFFFFF` -> `#9B9B9B`; light theme
+  `#000000` -> `#666666`, left to right. Cap heading and subheading width at ~680px;
+  break lines at meaningful points, never mid-phrase.
+
+## Icons
+
+Default to Phosphor, Solar, or Iconamoon; avoid Material Icons/Symbols. The
+project's icon set wins; validate it with `maggie-design`'s icon inventory +
+glyph-render gates before release.
+
+## Motion
+
+- Base curve `cubic-bezier(0.22,1,0.36,1)` with ~500ms for layout/position changes;
+  hover colour/opacity 300ms (never under 200ms). Never a browser-default curve
+  (`ease`, `linear`, `ease-in-out`).
+- Animate only `transform` and `opacity`; never `top`/`left`/`width`/`height`.
+- Respect `prefers-reduced-motion` (replace movement with a plain opacity change).
+- Scroll reveals rise ~32px and fade over 600-800ms, once, via `IntersectionObserver`
+  (never an unthrottled scroll listener).
+- Menu link entrance: items arrive in reading order, each rising ~24px while fading,
+  stepped 60ms apart, capped at 400ms total.
+- Tagline reveal: words go from ~25-35% opacity to full colour one at a time in
+  reading order as each crosses a trigger line (base curve; `IntersectionObserver`
+  per word or an rAF-throttled listener).
+
+## Banned filler words (content realism)
+
+Do not write "revolutionize", "supercharge", "cutting edge", "effortless",
+"transform your workflow", "take it to the next level", "harness the power", or
+"world class". Say what the product does in plain terms. Sentence case for headings
+and buttons; calm, specific system messages.

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