@topy-ai/maggie 0.7.49 → 0.7.51

package/README-zh-TW.md

@@ -29,7 +29,7 @@ npx @topy-ai/maggie init --scope project --agent all
 npx @topy-ai/maggie doctor --scope project --project .
 ```
 
-目前 npm 版本為 `0.7.49`，完成 batch 27：33 條 2026-09-09 至 09-16 建立但從未提交的本機 feedback drafts，已逐條對照目前程式碼（其中兩條已被既有功能滿足）。新增離線 `maggie ops notifications`（通知 catalogue 合約、consent/retention/durable lead delivery 規則、provider template drift、只檢查變數名稱的 Resend preflight、queue health 門檻與 operator alerts、dry-run retention plan）；`maggie localization email-matrix` 與 `maggie localization lifecycle`（locale 優先順序、未翻譯/缺漏 locale、變數與 HTML/text 一致、market CTA route、consent-aware 行銷 email 預設不發送）；Deployment 的 `--keep-releases` 統一 retention policy、`auth-canary`、資料庫 owner 無法讀取 release 路徑時的 streamed migration、`collect` 單一 readiness report；Google failure remediation（`maggie ops google-diagnose`）與唯讀 `google-ads-preflight`/`google-ads-keyword-ideas`；Social Share `reconcile`（timeout 後不重複發文）、`maggie-marketing-run-v1` 合約、命名排程層與只管制對外發布的 regulated-content review；`maggie design icon-glyph-check`、`maggie design verify`、`maggie service import-stages-validate`/`import-readiness`/`fact-provenance`；以及 `--release-metadata` 版本一致性檢查、`maggie docs rollout-status` 與 stdin batch 輸入。前一版 `0.7.48` 處理 2026-10-10 的 27 條 hosted feedback（batch 26）：Social Share 新增 `adapters`（每個 provider 一組 canonical OAuth scope，LinkedIn 不同 scope 會撤銷舊 token；共用 OAuth client 警告）、`connections`（撤銷或無法解密的 token 標為 `needs_reconnect`，偵測會過期的簽名頭像 URL）、`queue`（slot-based 排程：not-before、最新優先、campaign 輪流與每日上限、DST-safe）與 `campaigns`（idea stage Start gate）；Deployment 新增 hash-only `secret-fingerprint`/`secret-parity`、`env-isolation`（本機 `.env` 指向 production database 時警告）、release retention 與 worker-before-enqueue 發布順序；QA 在未明確同意時阻擋對 production API 的寫入情境，並以 `maggie qa cors-preflight` 只用 OPTIONS 檢查每個 HTTP method；Design 新增 `pressable-check`、`layer-check`（Tailwind v4 unlayered CSS）、onboarding wizard/picker 模式與 `maggie-palette-roles-v1` palette generate/validate；Marketplace 加入 screenshot 完整性與像素預算、從 CSS 量測 palette、asset provenance、中性 `displayName`（全部模板已補齊）、template studio、`maggie-template-content-v1` 合約與圖片生成成本/無文字審查 gate；Booking 新增唯讀 Stripe live setup runbook 與 gift voucher lifecycle 合約（`maggie booking voucher-contract --ledger`）；Feedback 新增 `improvement` 類型與 `maggie feedback session-summary`。MaggieDash 0.2.11 會保留尚未部署 template 的 outbox email 而不是 dead-letter，並從 ORA host 上游通用修正。本版也包含 Booking 十個 email events 合約與 CLI validator 同步及安全輸出的 `arrivalNote`。前一版 `0.7.47` 處理 2026-09-26 五條新 feedback：project-scope
+目前 npm 版本為 `0.7.51`，完成 batch 28：17 條 hosted feedback，來自一個跨平台產品開發 session（同一套 Expo 程式碼支援 web、iOS、Android，加上具備 MCP 與 ChatGPT/Claude app 的 AI 助理、產品自己的 CLI/MCP 套件、第三方 skills catalog 以及多租戶 assistant bridge host）。`maggie design app-validate` 改讀每個 viewport 的 evidence（scroll owner、固定 header/footer），只有 `app-init --pane list-detail:1024:2` 宣告的多欄版面才允許多個 scroll owner，並以 PNG 實際尺寸對照 plan viewport；`app-init --capabilities none|camera,…`（或 `--camera none`）讓非相機頁面不必填相機狀態，`--pattern` 加入新的 app UI patterns 驗收規則。新增 `maggie design app-collect`：在同一個瀏覽器分頁逐一以真實尺寸渲染已登入的 app 路由、略過 React Native Web 的包裝層計算 scroll owner、證明固定 shell，並寫出 `runtime-evidence.json` 與截圖（可 `--cdp-url` 接上已登入的 Chrome，或用專用 QA profile，`--read-only` 阻擋寫入）。新增 `maggie qa app-preflight`：偵測以 `CI=1` 或從錯誤資料夾啟動的 Metro/Expo dev server，並對會輪替的 refresh token 與連到 production API 的本機 server 發出警告。新增 `maggie-mobile-app` skill 與 `maggie mobile preflight|plan`（EAS build profile、TestFlight / Play 內部測試、EAS Update channel 與 fingerprint runtime policy、上架審核規則、建置前成本提示；`--auto-submit` 缺 `ascAppId` 或 `appVersion` policy 配上 remote build number 時在花費額度前就失敗）。新增 `maggie-assistant-tools` skill 與 `maggie assistant`（單一 tool registry、風險等級與 gate、與 model description 分開的使用者文案、由風險推導 MCP annotations、自動產生「助理能做與不能做」頁面、audit 檢查與簽章一次性 approval token 參考實作）。新增 `maggie product release-check|smoke|mcp-check|review-status`（產品 npm CLI/MCP 套件 metadata、`server.json`/`mcpName`、打包檔案機密掃描、安裝後 binary smoke、OAuth protected-resource metadata、ChatGPT/Claude/商店審核追蹤）、`maggie skills scaffold|validate|package|smoke`（第三方 skills catalog 打包成分類 plugin、all-in-one plugin 與 Claude Code `marketplace.json`）、`maggie deployment bridge-plan|bridge-collect-script|bridge-check`（多租戶 bridge host）；`maggie feedback session-summary` 支援多個 repo 與一般句子形式的 commit。MaggieDash 0.2.12 從 ORA host 上游通用修正。前一版 `0.7.50`：`maggie update` 改為 idempotent，內容已與套件相同的檔案不再改寫（保留時間戳），摘要分別列出 changed/unchanged/preserved 數量，只有真的保留了本機修改時才顯示 preserved 提示。前一版 `0.7.49` 完成 batch 27：33 條 2026-09-09 至 09-16 建立但從未提交的本機 feedback drafts，已逐條對照目前程式碼（其中兩條已被既有功能滿足）。新增離線 `maggie ops notifications`（通知 catalogue 合約、consent/retention/durable lead delivery 規則、provider template drift、只檢查變數名稱的 Resend preflight、queue health 門檻與 operator alerts、dry-run retention plan）；`maggie localization email-matrix` 與 `maggie localization lifecycle`（locale 優先順序、未翻譯/缺漏 locale、變數與 HTML/text 一致、market CTA route、consent-aware 行銷 email 預設不發送）；Deployment 的 `--keep-releases` 統一 retention policy、`auth-canary`、資料庫 owner 無法讀取 release 路徑時的 streamed migration、`collect` 單一 readiness report；Google failure remediation（`maggie ops google-diagnose`）與唯讀 `google-ads-preflight`/`google-ads-keyword-ideas`；Social Share `reconcile`（timeout 後不重複發文）、`maggie-marketing-run-v1` 合約、命名排程層與只管制對外發布的 regulated-content review；`maggie design icon-glyph-check`、`maggie design verify`、`maggie service import-stages-validate`/`import-readiness`/`fact-provenance`；以及 `--release-metadata` 版本一致性檢查、`maggie docs rollout-status` 與 stdin batch 輸入。前一版 `0.7.48` 處理 2026-10-10 的 27 條 hosted feedback（batch 26）：Social Share 新增 `adapters`（每個 provider 一組 canonical OAuth scope，LinkedIn 不同 scope 會撤銷舊 token；共用 OAuth client 警告）、`connections`（撤銷或無法解密的 token 標為 `needs_reconnect`，偵測會過期的簽名頭像 URL）、`queue`（slot-based 排程：not-before、最新優先、campaign 輪流與每日上限、DST-safe）與 `campaigns`（idea stage Start gate）；Deployment 新增 hash-only `secret-fingerprint`/`secret-parity`、`env-isolation`（本機 `.env` 指向 production database 時警告）、release retention 與 worker-before-enqueue 發布順序；QA 在未明確同意時阻擋對 production API 的寫入情境，並以 `maggie qa cors-preflight` 只用 OPTIONS 檢查每個 HTTP method；Design 新增 `pressable-check`、`layer-check`（Tailwind v4 unlayered CSS）、onboarding wizard/picker 模式與 `maggie-palette-roles-v1` palette generate/validate；Marketplace 加入 screenshot 完整性與像素預算、從 CSS 量測 palette、asset provenance、中性 `displayName`（全部模板已補齊）、template studio、`maggie-template-content-v1` 合約與圖片生成成本/無文字審查 gate；Booking 新增唯讀 Stripe live setup runbook 與 gift voucher lifecycle 合約（`maggie booking voucher-contract --ledger`）；Feedback 新增 `improvement` 類型與 `maggie feedback session-summary`。MaggieDash 0.2.11 會保留尚未部署 template 的 outbox email 而不是 dead-letter，並從 ORA host 上游通用修正。本版也包含 Booking 十個 email events 合約與 CLI validator 同步及安全輸出的 `arrivalNote`。前一版 `0.7.47` 處理 2026-09-26 五條新 feedback：project-scope
 `maggie init` 會建立本地 memory store；context 預設只讀取本 project scope；memory hook
 在 local Python adapter 不存在時 fallback 到已安裝 CLI；重複 init 保留既有檔案與時間戳；
 `maggie feedback list` 的 `--project` 可放在子命令前或後。Generated VPS runner 現在記錄
@@ -113,7 +113,7 @@ structure drift 或重複 treatment product 時 fail closed。
 deployment、memory、feedback 和 MaggieDash。內容先 draft/review，外部寫入、
 publish 與 production deployment 需要明確確認。
 
-目前 npm 版本為 `0.7.49`，包含 batch 26、27 feedback 修正與 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.7.51`，包含 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，以及
@@ -265,6 +265,6 @@ maggie service retirement-audit --project . \
   --evidence .maggie/booking/retirement-evidence.json
 ```
 
-完整中文說明、20 個 skills 清單和 roadmap：
+完整中文說明、22 個 skills 清單和 roadmap：
 [繁體中文 README](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/README.zh-TW.md)
 · [Roadmap](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/ROADMAP.md)

package/README.md

@@ -87,9 +87,59 @@ 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 20 installable skills and a local-first MaggieDash foundation.
-
-This package is `0.7.49`. It closes batch 27: 33 local feedback
+package ships 22 installable skills and a local-first MaggieDash foundation.
+
+This package is `0.7.51`. It closes batch 28: 17 hosted feedback
+records from a cross-platform product session (one Expo codebase for web,
+iOS and Android, an assistant with MCP and ChatGPT/Claude app surfaces,
+product CLI/MCP packages, a third-party skills catalog, and a multi-tenant
+assistant bridge host):
+
+- App surfaces: `maggie design app-validate` reads per-viewport evidence
+  (scroll owners, fixed shell), accepts extra scroll owners only where
+  `app-init --pane list-detail:1024:2` declares them, and checks each PNG's
+  real size against the plan viewport. `app-init --capabilities none|camera,…`
+  (or `--camera none`) drops irrelevant device states, and `--pattern` adds
+  acceptance rules from the new [app UI patterns](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/skills/maggie-design/references/app-ui-patterns.md).
+- New `maggie design app-collect`: renders a signed-in app route one viewport
+  at a time in one browser tab at the real size, counts scroll owners while
+  skipping React Native Web wrappers, proves the fixed shell, and writes
+  `runtime-evidence.json` plus screenshots. It can attach to your signed-in
+  Chrome (`--cdp-url`) or use a QA profile, and can block writes (`--read-only`).
+- New `maggie qa app-preflight`: catches Metro/Expo dev servers started with
+  `CI=1` or from the wrong folder, and warns about rotating refresh tokens and
+  local servers that talk to production APIs.
+- New [`maggie-mobile-app`](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/skills/maggie-mobile-app/SKILL.md) skill and
+  `maggie mobile preflight|plan`: EAS build profiles, TestFlight / Play
+  internal testing, EAS Update channels and the fingerprint runtime policy,
+  store-review rules, and a cost notice. It fails before quota is spent when
+  `--auto-submit` lacks `ascAppId` or `appVersion` runtime policy is combined
+  with remote build numbers.
+- New [`maggie-assistant-tools`](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/skills/maggie-assistant-tools/SKILL.md)
+  skill and `maggie assistant`: one tool registry with risk levels, gates and
+  user-facing copy kept apart from model descriptions, MCP annotations derived
+  from risk, a generated "what the assistant can and can't do" page, audit
+  checks, and reference signed one-time approval tokens.
+- New `maggie product release-check|smoke|mcp-check|review-status` for a
+  product's own npm CLI and MCP packages (metadata, `server.json`/`mcpName`,
+  packed-file secret scan, installed-binary smoke, OAuth protected-resource
+  metadata, ChatGPT/Claude/store review tracking).
+- New `maggie skills scaffold|validate|package|smoke` for third-party skill
+  catalogs, packaging category plugins, an all-in-one plugin and a Claude Code
+  `marketplace.json` (checked with `claude plugin validate`).
+- New `maggie deployment bridge-plan|bridge-collect-script|bridge-check` for a
+  multi-tenant assistant bridge host on a VPS.
+- `maggie feedback session-summary` reads several repositories
+  (`--repo app=../app --since-date …`) and classifies plain commit subjects.
+- MaggieDash 0.2.12 upstreams generic fixes from the ORA host.
+
+The 0.7.50 release made `maggie update` idempotent: files whose content already
+matches the package are left untouched (timestamps included) and counted as
+unchanged, the summary reports changed/unchanged/preserved counts, and the
+"local files were preserved" notice appears only when a file was actually
+preserved.
+
+The 0.7.49 release closed batch 27: 33 local feedback
 drafts from 2026-09-09 to 09-16 that were never submitted, reconciled against
 the current code (two were already satisfied):
 
@@ -728,8 +778,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.49 update --scope project --project . --force
-npx @topy-ai/maggie@0.7.49 cleanup --scope project --project .
+npx @topy-ai/maggie@0.7.51 update --scope project --project . --force
+npx @topy-ai/maggie@0.7.51 cleanup --scope project --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -1235,13 +1285,13 @@ repairs with `maggie dash sections validate`, `fanout-validate`,
 `maggie dash inventory` to classify published pages once into disjoint kinds.
 See the [quality contract examples](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/contracts/maggiedash/quality-contracts.md).
 
-The package includes all 20 installable skills: `maggie-blog-bootstrap`,
+The package includes all 22 installable skills: `maggie-blog-bootstrap`,
 `maggie-dash`, `maggie-clone`, `maggie-clone-to-template`, `maggie-marketplace`,
 `maggie-template`, `maggie-design`, `maggie-ops`, `maggie-deployment`,
 `maggie-project-context`, `maggie-seo-geo`, `maggie-social-share`,
 `maggie-service-booking`, `maggie-memory`, `maggie-content-localization`,
-`maggie-feedback`, `maggie-qa-workflow`, `maggie-auth-reference`, and
-`maggie-blog`. Use the stable
+`maggie-feedback`, `maggie-qa-workflow`, `maggie-auth-reference`,
+`maggie-blog`, `maggie-mobile-app`, and `maggie-assistant-tools`. Use the stable
 commands below after installation:
 
 ```bash

package/bin/maggie.js

@@ -126,7 +126,8 @@ Usage:
   maggie design reference-ui --project PATH --reference PATH --surface blog,service --confirm
   maggie design init --project PATH --surface blog|service --reference-run PATH --confirm
   maggie design validate-ui --project PATH --plan PATH --rendered-dir PATH --confirm
-  maggie design app-init --project PATH --route /app/valuation --auth-mode email-password --confirm
+  maggie design app-init --project PATH --route /inbox --auth-mode existing-session [--capabilities none|camera,...] [--pane list-detail:1024:2] [--pattern usage-hero] --confirm
+  maggie design app-collect --plan PATH --base-url URL (--cdp-url http://127.0.0.1:9222 | --profile-dir DIR) [--read-only --allow-write /auth/refresh] --confirm
   maggie design app-validate --project PATH --plan PATH --runtime-evidence FILE --rendered-dir PATH --confirm
   maggie design icon-inventory --project PATH --source-dir src --runtime assets/icons.css --output docs/icon-inventory.json
   maggie design icon-release-gate --icon-report FILE --browser-report FILE --output FILE
@@ -161,6 +162,14 @@ Usage:
   maggie deployment --project PATH --target vps-with-cloudflare-dns
   maggie deployment worker-secrets --project PATH --environment staging --required RESEND_API_KEY
   maggie deployment secret-parity --manifest api-1.json --manifest api-2.json --required KEY
+  maggie deployment bridge-plan|bridge-collect-script --plan bridge-host.json
+  maggie deployment bridge-check --plan bridge-host.json --observed observed.json
+  maggie mobile preflight|plan --project PATH [--app-dir apps/app] [--profile production] [--platform ios|android|all] [--auto-submit]
+  maggie assistant registry-validate|annotations|capability-page|audit-check --registry FILE [--mcp-tools FILE] [--session FILE] [--output FILE]
+  maggie assistant approval-selftest
+  maggie product release-check --package DIR [--server-json FILE] [--changelog FILE] [--pack]
+  maggie product smoke --package DIR | mcp-check --mcp-url URL | review-status --reviews FILE [--chatgpt-plugin FILE]
+  maggie skills scaffold|validate|package|smoke --root DIR [--out DIR --prefix NAME --owner NAME] [--claude]
   maggie deployment env-isolation --project PATH --production-env .env.production
   maggie deployment readiness --project PATH
   maggie deployment collect --project PATH --config .maggie/deployment/collector.json
@@ -187,7 +196,7 @@ Usage:
   maggie localization <extract|plan|generate|preview|validate|review|publish|stale|glossary|email-matrix|lifecycle> [options]
   maggie seo performance|images|sitemap|indexnow|social-cards|head-tags [options] (sitemap supports strict validate and agent-files)
   maggie feedback <collect|preview|batch|batch-review|session-summary|submit|list> [options]
-  maggie qa <start|record|summary|export|assertion-audit|cors-preflight> [options]
+  maggie qa <start|record|summary|export|assertion-audit|cors-preflight|app-preflight> [options]
   maggie site-audit URL [--crawl] [--access-log FILE] [--require-sitemap-request] [--languages en-GB,es-MX,ja-JP] [--check-hreflang] [--check-internal-links]
   maggie site-audit URL --crawl --save-baseline FILE --reviewer NAME
   maggie site-audit URL --crawl --baseline FILE [--reason-all REASON]
@@ -388,13 +397,13 @@ function diffSummary(source, target) {
   return `${added} local additions, ${removed} package lines removed across ${blocks} changed blocks (${localLines.length} local lines vs ${packageLines.length} package lines)`;
 }
 
-function syncTree(source, target, force, root = null, managedFiles = {}) {
+function syncTree(source, target, force, root = null, managedFiles = {}, stats = { unchanged: 0, preserved: 0 }) {
   let changed = 0;
   for (const entry of readdirSync(source, { withFileTypes: true })) {
     const sourcePath = join(source, entry.name);
     const targetPath = join(target, entry.name);
     if (entry.isDirectory()) {
-      changed += syncTree(sourcePath, targetPath, force, root, managedFiles);
+      changed += syncTree(sourcePath, targetPath, force, root, managedFiles, stats);
       continue;
     }
     const managedPath = root ? relative(root, targetPath) : targetPath;
@@ -406,12 +415,16 @@ function syncTree(source, target, force, root = null, managedFiles = {}) {
       writeFileSync(targetPath, readFileSync(sourcePath));
       console.log(`installed ${targetPath}`);
       changed++;
-    } else if (force || packageDigest === localDigest || wasManaged) {
+    } else if (packageDigest === localDigest) {
+      // Identical content: leave the file and its timestamps untouched.
+      stats.unchanged++;
+    } else if (force || wasManaged) {
       writeFileSync(targetPath, readFileSync(sourcePath));
       console.log(`updated ${targetPath}`);
       changed++;
     } else {
       console.log(`preserved ${targetPath} (local changes; ${diffSummary(sourcePath, targetPath)}; use --force to replace)`);
+      stats.preserved++;
     }
   }
   return changed;
@@ -545,6 +558,7 @@ function update(args) {
   const previousManagedFiles = previousManifest.managedFiles && typeof previousManifest.managedFiles === "object" ? previousManifest.managedFiles : {};
   if (!existsSync(SKILLS_ROOT)) throw new Error("bundled skills are missing; run npm pack from the package source");
   let updated = 0;
+  const stats = { unchanged: 0, preserved: 0 };
   const managedRoot = scope === USER_SCOPE ? "/" : root;
   for (const agentRoot of roots) {
     for (const skill of skills) {
@@ -554,22 +568,22 @@ function update(args) {
         console.log(`absent ${target} (run install to add it)`);
         continue;
       }
-      updated += syncTree(source, target, force, managedRoot, previousManagedFiles);
+      updated += syncTree(source, target, force, managedRoot, previousManagedFiles, stats);
     }
-    if (existsSync(REFERENCES_ROOT) && existsSync(join(agentRoot, "references"))) updated += syncTree(REFERENCES_ROOT, join(agentRoot, "references"), force, managedRoot, previousManagedFiles);
+    if (existsSync(REFERENCES_ROOT) && existsSync(join(agentRoot, "references"))) updated += syncTree(REFERENCES_ROOT, join(agentRoot, "references"), force, managedRoot, previousManagedFiles, stats);
   }
   if (scope === PROJECT_SCOPE) {
     const tools = join(root, "tools");
     if (existsSync(TOOLS_ROOT)) for (const group of ["clis", "runtime", "integrations"]) if (existsSync(join(TOOLS_ROOT, group))) {
       const target = join(tools, group);
-      if (existsSync(target)) updated += syncTree(join(TOOLS_ROOT, group), target, force, root, previousManagedFiles);
+      if (existsSync(target)) updated += syncTree(join(TOOLS_ROOT, group), target, force, root, previousManagedFiles, stats);
     }
     if (existsSync(join(DESIGN_ROOT, "SPA-DESIGN.md")) && existsSync(join(root, ".maggie", "design-reference"))) {
-      updated += syncTree(DESIGN_ROOT, join(root, ".maggie", "design-reference"), force, root, previousManagedFiles);
+      updated += syncTree(DESIGN_ROOT, join(root, ".maggie", "design-reference"), force, root, previousManagedFiles, stats);
     }
-    if (existsSync(MARKETPLACE_ROOT) && existsSync(join(root, "marketplace"))) updated += syncTree(MARKETPLACE_ROOT, join(root, "marketplace"), force, root, previousManagedFiles);
-    if (existsSync(CONTRACTS_ROOT) && existsSync(join(root, "contracts"))) updated += syncTree(CONTRACTS_ROOT, join(root, "contracts"), force, root, previousManagedFiles);
-    if (existsSync(join(TEMPLATES_ROOT, "maggiedash")) && existsSync(join(root, "templates", "maggiedash"))) updated += syncTree(join(TEMPLATES_ROOT, "maggiedash"), join(root, "templates", "maggiedash"), force, root, previousManagedFiles);
+    if (existsSync(MARKETPLACE_ROOT) && existsSync(join(root, "marketplace"))) updated += syncTree(MARKETPLACE_ROOT, join(root, "marketplace"), force, root, previousManagedFiles, stats);
+    if (existsSync(CONTRACTS_ROOT) && existsSync(join(root, "contracts"))) updated += syncTree(CONTRACTS_ROOT, join(root, "contracts"), force, root, previousManagedFiles, stats);
+    if (existsSync(join(TEMPLATES_ROOT, "maggiedash")) && existsSync(join(root, "templates", "maggiedash"))) updated += syncTree(join(TEMPLATES_ROOT, "maggiedash"), join(root, "templates", "maggiedash"), force, root, previousManagedFiles, stats);
   }
   const manifestRoots = scope === USER_SCOPE ? allUserAgentRoots() : roots;
   const updatedUserSkills = scope === USER_SCOPE ? mergedUserSkillNames(manifestRoots) : [];
@@ -577,8 +591,8 @@ function update(args) {
     ? { scope, version: PACKAGE_VERSION, agents: manifestRoots, skills: updatedUserSkills, skillsByAgent: userSkillInventory(manifestRoots), managedFiles: userManagedFileDigests(manifestRoots, updatedUserSkills, previousManagedFiles), updated_at: new Date().toISOString() }
     : { scope, version: PACKAGE_VERSION, agents: roots.map((item) => item.slice(root.length + 1)), skills: mergedSkillNames(root, skills), managedFiles: managedFileDigests(root, roots, skills, previousManagedFiles), updated_at: new Date().toISOString() };
   writeInstallManifest(root, manifest, scope);
-  console.log(`Maggie ${scope} update complete: ${updated} files changed`);
-  if (!force) console.log("Local files with changes were preserved. Review the output and rerun with --force only when replacement is intended.");
+  console.log(`Maggie ${scope} update complete: ${updated} files changed, ${stats.unchanged} unchanged, ${stats.preserved} preserved`);
+  if (stats.preserved) console.log("Local files with changes were preserved. Review the output and rerun with --force only when replacement is intended.");
 }
 
 function list() {
@@ -776,6 +790,11 @@ try {
   else if (command === "docs") docs(args);
   else if (command === "seo") seo(args);
   else if (command === "ops") workflowCli("maggie_ops.py", args);
+  else if (command === "deployment" && ["bridge-plan", "bridge-collect-script", "bridge-check"].includes(args[0])) workflowCli("maggie_bridge_host.py", args);
+  else if (command === "mobile") workflowCli("maggie_mobile.py", args);
+  else if (command === "assistant") workflowCli("maggie_assistant_tools.py", args);
+  else if (command === "product") workflowCli("maggie_product_release.py", args);
+  else if (command === "skills") workflowCli("maggie_skill_catalog.py", args);
   else if (command === "deployment" && args[0] === "canary") workflowCli("maggie_deployment_canary.py", args.slice(1));
   else if (command === "deployment" && args[0] === "readiness") workflowCli("maggie_deployment_readiness.py", args.slice(1));
   else if (command === "deployment" && args[0] === "auth-canary") workflowCli("maggie_deployment_auth_canary.py", args.slice(1));

package/bundled-contracts/maggie-assistant-tools/tool-registry-example-v1.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": "maggie-assistant-tool-registry.v1",
+  "gates": {
+    "verified-site": {"label": "Needs a verified website", "modelNote": "Fails until the site is verified."},
+    "credits": {"label": "Uses a post credit", "modelNote": "Consumes one credit per call."},
+    "ai-generation": {"label": "Uses AI generation", "modelNote": "Counts against the AI generation allowance."}
+  },
+  "tools": [
+    {"name": "report_traffic", "description": "Return sessions and conversions for the current website over a date range.", "risk": "read", "scope": "workspace", "channels": ["in-app", "mcp", "chatgpt", "claude"], "user": {"label": "Show your traffic", "detail": "Visits and conversions for a date range."}},
+    {"name": "post_draft_create", "description": "Create a draft social post for the current website from a brief.", "risk": "write-reversible", "scope": "workspace", "channels": ["in-app", "mcp"], "gates": ["ai-generation"], "user": {"label": "Draft a social post", "detail": "Writes a draft you can edit; nothing is published.", "confirm": "Create a draft post from this brief?"}},
+    {"name": "post_schedule", "description": "Schedule an approved post on a connected channel at a time.", "risk": "write-spends", "scope": "workspace", "channels": ["in-app", "mcp"], "gates": ["credits", "verified-site"], "user": {"label": "Schedule a post", "detail": "Uses one post credit when it goes out.", "confirm": "Schedule this post for the time shown?"}},
+    {"name": "post_publish_now", "description": "Publish an approved post immediately on a connected channel.", "risk": "write-public", "scope": "workspace", "channels": ["in-app", "mcp"], "gates": ["credits", "verified-site"], "user": {"label": "Publish a post now", "detail": "Goes live straight away and cannot be unpublished from here.", "confirm": "Publish this post now? It will be public."}},
+    {"name": "website_add", "description": "Add a website to the account.", "risk": "write-reversible", "scope": "account", "channels": ["in-app", "mcp"], "audit": {"scope": "account"}, "user": {"label": "Add a website", "detail": "Adds it to your account; you can remove it later.", "confirm": "Add this website to your account?"}},
+    {"name": "billing_change_plan", "description": "Change the subscription plan.", "risk": "never", "scope": "account", "channels": ["in-app"], "user": {"label": "Change your plan", "detail": "Open Billing in the app to change plans."}}
+  ],
+  "cantDo": [
+    {"text": "Read your private messages on social networks.", "instead": "Paste the message you want help with."}
+  ]
+}

package/bundled-contracts/maggie-assistant-tools/tool-registry-v1.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/contracts/maggie-assistant-tools/tool-registry-v1.schema.json",
+  "title": "Maggie assistant tool registry",
+  "description": "One definition per tool, exported by the product and shared by the in-app agent, MCP server and ChatGPT/Claude apps. Model-facing description and user-facing copy are separate fields. Checked by `maggie assistant registry-validate`.",
+  "type": "object",
+  "required": ["schemaVersion", "tools"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-assistant-tool-registry.v1"},
+    "gates": {
+      "description": "Preconditions a tool may require, e.g. credits, AI generation, verified site.",
+      "type": "object",
+      "additionalProperties": {"type": "object", "required": ["label"], "properties": {"label": {"type": "string"}, "modelNote": {"type": "string"}}}
+    },
+    "tools": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["name", "description", "risk", "scope", "channels", "user"],
+        "properties": {
+          "name": {"type": "string", "pattern": "^[a-z][a-z0-9_]*$", "maxLength": 64},
+          "description": {"type": "string", "minLength": 1, "description": "Model-facing; never shown to people."},
+          "risk": {"enum": ["read", "write-reversible", "write-spends", "write-public", "never", "R0", "W1", "W2", "W3", "W4"]},
+          "scope": {"enum": ["account", "workspace"]},
+          "channels": {"type": "array", "minItems": 1, "items": {"enum": ["in-app", "mcp", "chatgpt", "claude", "cli"]}},
+          "gates": {"type": "array", "items": {"type": "string"}},
+          "idempotent": {"type": "boolean"},
+          "openWorld": {"type": "boolean"},
+          "hidden": {"type": "boolean", "description": "Omit from the capability page (e.g. host-only helpers)."},
+          "user": {
+            "type": "object",
+            "required": ["label"],
+            "properties": {
+              "label": {"type": "string", "maxLength": 60},
+              "detail": {"type": "string"},
+              "confirm": {"type": "string", "description": "Approval-card sentence; required for writes."},
+              "status": {"type": "string", "description": "Shown while the tool runs."}
+            }
+          },
+          "audit": {"type": "object", "properties": {"scope": {"enum": ["account", "workspace"]}}}
+        }
+      }
+    },
+    "cantDo": {
+      "type": "array",
+      "items": {"type": "object", "required": ["text"], "properties": {"text": {"type": "string"}, "instead": {"type": "string"}}}
+    }
+  }
+}

package/bundled-contracts/maggie-deployment/bridge-host-example-v1.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": "maggie-bridge-host.v1",
+  "tenantsRoot": "/srv/bridge/tenants",
+  "isolation": {
+    "uidPerTenant": true,
+    "uidRange": [20000, 29999],
+    "tenantDirMode": "0700",
+    "parentDirMode": "0711",
+    "cleanEnvironment": true,
+    "envAllowlist": ["HOME", "PATH", "LANG", "TZ"],
+    "ownerPinning": true,
+    "nonDumpable": true
+  },
+  "network": {"proxy": "nginx", "publicBind": "127.0.0.1:3210", "adminBind": "127.0.0.1:3211", "adminProxied": false},
+  "capacity": {"maxSessions": 20, "eviction": "lru-idle", "idleTimeoutMinutes": 15},
+  "recycle": {"on": ["mcp", "skills", "cli"], "busySessions": "after-current-turn"},
+  "image": {
+    "label": "com.example.app=bridge-host",
+    "retain": 2,
+    "healthcheck": {"path": "/health", "attempts": 30, "intervalSeconds": 2},
+    "rollback": true,
+    "readOnlyRootfs": true,
+    "capDropAll": true,
+    "noNewPrivileges": true
+  },
+  "providers": [
+    {"name": "assistant-cli", "accountType": "customer-own", "termsUrl": "https://example.com/terms", "termsReviewedAt": "2026-10-01"}
+  ]
+}

package/bundled-contracts/maggie-design/mobile-app-evidence-v1.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/contracts/maggie-design/mobile-app-evidence-v1.schema.json",
+  "title": "Maggie mobile app runtime evidence",
+  "description": "Written by `maggie design app-collect`, read by `maggie design app-validate`. Per-viewport entries are authoritative; no credentials, storage or page text.",
+  "type": "object",
+  "required": ["schemaVersion", "route", "auth", "viewports"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-mobile-app-evidence.v1"},
+    "collector": {"type": "string"},
+    "route": {"type": "string", "pattern": "^/"},
+    "auth": {
+      "type": "object",
+      "properties": {
+        "signedIn": {"type": "boolean"},
+        "sessionMode": {"enum": ["attached-host-session", "dedicated-profile", "manual"]},
+        "credentialsRecorded": {"const": false}
+      }
+    },
+    "shell": {
+      "type": "object",
+      "properties": {
+        "fixedHeader": {"type": "boolean"},
+        "fixedFooter": {"type": "boolean"},
+        "scrollOwnerCount": {"description": "Legacy; ignored by app-validate.", "type": "integer"},
+        "method": {"type": "string"}
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": {"type": "object", "properties": {"states": {"type": "array", "items": {"type": "string"}}}}
+    },
+    "viewports": {
+      "type": "object",
+      "required": ["desktop", "tablet", "mobile"],
+      "additionalProperties": {
+        "type": "object",
+        "required": ["width", "height", "scrollOwners"],
+        "properties": {
+          "width": {"type": "integer", "minimum": 1},
+          "height": {"type": "integer", "minimum": 1},
+          "deviceScaleFactor": {"type": "number", "exclusiveMinimum": 0},
+          "scrollOwners": {"type": "integer", "minimum": 0},
+          "fixedHeader": {"type": "boolean"},
+          "fixedFooter": {"type": "boolean"},
+          "tabBar": {"enum": ["bottom", "top", "side", "inline", "none"]},
+          "fullPage": {"type": "boolean"},
+          "screenshot": {"type": "string"}
+        }
+      }
+    },
+    "warnings": {"type": "array", "items": {"type": "string"}}
+  }
+}

package/bundled-contracts/maggie-design/mobile-app-surface-v1.schema.json

@@ -31,10 +31,18 @@
     },
     "auth": {
       "type": "object",
-      "required": ["mode", "required", "credentialPolicy"],
+      "required": [
+        "mode",
+        "required",
+        "credentialPolicy"
+      ],
       "properties": {
         "mode": {
-          "enum": ["email-password", "existing-session", "none"]
+          "enum": [
+            "email-password",
+            "existing-session",
+            "none"
+          ]
         },
         "required": {
           "type": "boolean"
@@ -47,41 +55,116 @@
     },
     "shell": {
       "type": "object",
-      "required": ["fixedHeader", "fixedFooter", "oneScrollOwner"],
+      "required": [
+        "fixedHeader",
+        "fixedFooter"
+      ],
       "properties": {
-        "fixedHeader": {"const": true},
-        "fixedFooter": {"const": true},
-        "oneScrollOwner": {"const": true}
+        "fixedHeader": {
+          "const": true
+        },
+        "fixedFooter": {
+          "const": true
+        },
+        "oneScrollOwner": {
+          "type": "boolean"
+        },
+        "scrollOwners": {
+          "type": "object",
+          "properties": {
+            "default": {
+              "const": 1
+            },
+            "intentionalPanes": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": [
+                  "name",
+                  "minWidth",
+                  "scrollOwners"
+                ],
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "pattern": "^[a-z0-9][a-z0-9-]*$"
+                  },
+                  "minWidth": {
+                    "type": "integer",
+                    "minimum": 100
+                  },
+                  "scrollOwners": {
+                    "type": "integer",
+                    "minimum": 2,
+                    "maximum": 4
+                  }
+                }
+              }
+            }
+          }
+        }
       },
+      "anyOf": [
+        {
+          "required": [
+            "oneScrollOwner"
+          ],
+          "properties": {
+            "oneScrollOwner": {
+              "const": true
+            }
+          }
+        },
+        {
+          "required": [
+            "scrollOwners"
+          ]
+        }
+      ],
       "additionalProperties": true
     },
     "camera": {
       "type": "object",
-      "required": ["requiredStates", "controls", "fallback"],
+      "required": [
+        "requiredStates"
+      ],
       "properties": {
         "requiredStates": {
           "type": "array",
-          "contains": {"const": "permission"}
+          "items": {
+            "type": "string"
+          }
         },
         "controls": {
-          "type": "array",
-          "minItems": 4
+          "type": "array"
         },
         "fallback": {
-          "type": "string",
-          "minLength": 1
+          "type": "string"
+        },
+        "notApplicable": {
+          "type": "string"
         }
       },
       "additionalProperties": true
     },
     "viewports": {
       "type": "object",
-      "required": ["desktop", "tablet", "mobile"],
+      "required": [
+        "desktop",
+        "tablet",
+        "mobile"
+      ],
       "additionalProperties": {
         "type": "array",
         "prefixItems": [
-          {"type": "integer", "minimum": 1},
-          {"type": "integer", "minimum": 1}
+          {
+            "type": "integer",
+            "minimum": 1
+          },
+          {
+            "type": "integer",
+            "minimum": 1
+          }
         ],
         "minItems": 2,
         "maxItems": 2
@@ -89,10 +172,48 @@
     },
     "requiredSteps": {
       "type": "array",
-      "contains": {"const": "signed-in-browser-qa"}
+      "contains": {
+        "const": "signed-in-browser-qa"
+      }
     },
     "publicWrite": {
       "const": false
+    },
+    "capabilities": {
+      "type": "object",
+      "propertyNames": {
+        "enum": [
+          "camera",
+          "location",
+          "notifications",
+          "media-library"
+        ]
+      },
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "requiredStates"
+        ],
+        "properties": {
+          "requiredStates": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "patterns": {
+      "type": "array",
+      "items": {
+        "enum": [
+          "tabbed-modal",
+          "editor-sheet-assistant",
+          "usage-hero",
+          "site-switcher"
+        ]
+      }
     }
   },
   "additionalProperties": true