@topy-ai/maggie 0.7.44 → 0.7.46

package/README-zh-TW.md

@@ -8,11 +8,34 @@ Codex、Claude Code 與相容的 coding agents。
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.7.44 init --agent all
-npx @topy-ai/maggie@0.7.44 doctor --project .
+npm install --global @topy-ai/maggie
+maggie init --scope user --agent all
+maggie doctor --scope user --agent all
 ```
 
-目前 release 是 `0.7.44`。完成 2026-09-24 booking feedback batch：MaggieDash
+這只會把可重用 skills 和 shared references 安裝到 user-level Claude Code/Codex
+目錄；`.maggie/`、evidence、contracts、templates、marketplace 和 host files
+仍然由各 project 自己管理。更新全域安裝：
+
+```bash
+npm install --global @topy-ai/maggie@latest
+maggie update --scope user --agent all
+```
+
+若要讓 repository 固定自己的 skill 版本，才使用 project-local 安裝：
+
+```bash
+npx @topy-ai/maggie init --scope project --agent all
+npx @topy-ai/maggie doctor --scope project --project .
+```
+
+目前 release 是 `0.7.46`。新增 browser adapter capability preflight、privacy-safe
+feedback evidence references/relationships、bounded batch-review evidence graph、
+remediation suggestions，以及 root-level unittest import 支援。`browser-audit
+--check-browser` 會在導覽前拒絕 missing/incompatible adapter，包括解析成
+`xdg-open` 的系統 `browse`；feedback graph 不保存 raw payload、logs、credentials
+或本機路徑。另包含 0.7.45 的 Codex/Claude Code 一次性 user-scope 安裝、bundled
+workflow runner 與 user-scope maintenance commands；並完成 2026-09-24 booking feedback batch：MaggieDash
 Calendar availability grid/free-slot entry，以及 ORA modal focus restoration
 的驗證證據。另新增 secret-free Starter marketplace provisioning
 plan、versioned GitHub/Cloudflare/Starter contracts，以及 deterministic
@@ -57,8 +80,8 @@ maggie booking-delivery --policy .maggie/booking-delivery-policy.json
 常用流程：
 
 ```bash
-python3 tools/clis/maggie.py analyze . --json --save
-python3 tools/clis/maggie.py bootstrap interview .
+maggie tool maggie.py analyze . --json --save
+maggie tool maggie.py bootstrap interview .
 maggie memory context --project . --skill <skill-name>
 maggie doctor --project . --require-bootstrap --strict
 ```
@@ -82,7 +105,7 @@ structure drift 或重複 treatment product 時 fail closed。
 deployment、memory、feedback 和 MaggieDash。內容先 draft/review，外部寫入、
 publish 與 production deployment 需要明確確認。
 
-目前 source tree 的正式 release 是 `0.7.44`。本版完成 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
+目前 source tree 的正式 release 是 `0.7.46`。本版完成 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

@@ -12,7 +12,36 @@ composable skills for project bootstrap, authorized website cloning, design
 systems, SEO/GEO, content operations, marketplace templates, deployment, and
 persistent project memory.
 
-## Install
+## Install once for every project
+
+Install the CLI globally and place the reusable skills in the user-level
+directories used by Codex and Claude Code:
+
+```bash
+npm install --global @topy-ai/maggie
+maggie init --scope user --agent all
+maggie doctor --scope user --agent all
+```
+
+This writes only agent skills, shared references, and a user install manifest.
+Project `.maggie/` state, evidence, contracts, templates, marketplace data,
+and host files remain local to each project. Use `maggie tool` when a workflow
+needs a bundled Python CLI; it runs the package copy with the current project
+as its working directory.
+
+Upgrade the CLI and user skills together:
+
+```bash
+npm install --global @topy-ai/maggie@latest
+maggie update --scope user --agent all
+```
+
+`--global` is an alias for `--scope user`. Use `--force` only to replace an
+intentionally customized user skill.
+
+## Project-local install
+
+Use project scope when a repository must pin or customize its skill files:
 
 `site-audit --crawl --save-baseline FILE --reviewer NAME` records a reviewed
 site contract; `site-audit --crawl --baseline FILE` fails on URL, metadata,
@@ -25,14 +54,14 @@ with explicit `--confirm`, resumable draft batches and no automatic publishing.
 See the installed localization skill for the adapter protocol and examples.
 
 ```bash
-npx @topy-ai/maggie init --agent codex
+npx @topy-ai/maggie init --scope project --agent codex
 ```
 
 Install for Claude Code or both supported agent directories:
 
 ```bash
-npx @topy-ai/maggie init --agent claude
-npx @topy-ai/maggie init --agent all
+npx @topy-ai/maggie init --scope project --agent claude
+npx @topy-ai/maggie init --scope project --agent all
 ```
 
 Update an existing project while preserving local customisations by default:
@@ -60,7 +89,14 @@ 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.
 
-The current release is `0.7.44`. It closes the 2026-09-24 booking feedback
+The current release is `0.7.46`. It adds browser-adapter capability preflight,
+privacy-safe feedback evidence references/relationships, bounded batch-review
+evidence graphs, remediation suggestions, and root-level unittest import
+support. `browser-audit --check-browser` rejects missing or incompatible
+adapters before navigation, including a system `browse`/`xdg-open` opener.
+It also includes the 0.7.45 one-time user-scope installation for
+Codex and Claude Code, a bundled workflow runner, and scoped maintenance
+commands. It also closes the 2026-09-24 booking feedback
 batch with the canonical MaggieDash Calendar availability grid/free-slot
 entry and documented ORA modal focus-restoration evidence. It also adds the
 secret-free Starter marketplace
@@ -313,8 +349,8 @@ For a genuinely empty project, create the host framework first, then bootstrap
 Maggie in this order:
 
 ```bash
-python3 tools/clis/maggie.py analyze . --json --save
-python3 tools/clis/maggie.py bootstrap interview .
+maggie tool maggie.py analyze . --json --save
+maggie tool maggie.py bootstrap interview .
 maggie dash install --project . --confirm
 maggie dash init --project . --confirm
 maggie dash migrate --project . --confirm
@@ -336,8 +372,9 @@ The CLI provides the installer plus durable workflow commands:
 
 ```text
 maggie --version | version
-maggie init | install | update | remove | list | doctor
-maggie cleanup --project . [--confirm]
+maggie init | install | update | remove | list | doctor [--scope project|user]
+maggie cleanup [--scope project|user] --project . [--confirm]
+maggie tool <bundled-cli.py> [arguments]
 maggie bootstrap interview | phase ...
 maggie dash install | init | status | migrate | cms ...
 maggie dash transition ...      # explicit content approval transition
@@ -458,6 +495,23 @@ maggie blog auto-publish-gate \
 
 ### Design and deployment release gates
 
+`maggie release` requires an explicit `.maggie/release-profile.json` capability
+manifest. This prevents a public Astro site from being evaluated against
+unrelated MaggieDash, Booking, migration, service-catalogue, or analytics
+artifacts. A minimal profile is:
+
+```json
+{
+  "schemaVersion": "maggie-release-profile.v1",
+  "profile": "public-astro",
+  "projectType": "astro",
+  "capabilities": ["deployment"]
+}
+```
+
+Declare optional capabilities only when the project owns their evidence. The
+release report records undeclared optional gates as `skipped`.
+
 Check source-to-runtime icon coverage before shipping a design:
 
 ```bash
@@ -556,6 +610,10 @@ maggie deployment readiness --project . \
   --output .maggie/deployment-readiness.json
 ```
 
+Individual suites can also be invoked from the repository root with
+`python3 -m unittest tools.tests.test_maggie_feedback_batch`. Use the
+regression runner for the complete discovered suite.
+
 The readiness report follows `maggie-deployment-readiness.v1`. It reports unit
 regression, package smoke, host browser evidence, rendered canary, and
 deployment preflight separately. Missing host adapter evidence is
@@ -599,8 +657,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.39 update --project . --force
-npx @topy-ai/maggie@0.7.39 cleanup --project .
+npx @topy-ai/maggie@0.7.46 update --scope project --project . --force
+npx @topy-ai/maggie@0.7.46 cleanup --scope project --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -898,6 +956,16 @@ The `maggie-feedback-batch-review.v1` report retains bounded observations,
 missing-index and duplicate checks, and privacy flags. It never contains raw
 responses, local paths, or secrets.
 
+Add safe relationships when a report must point to a test or related run:
+
+```bash
+maggie feedback collect --project . --summary "Adapter unavailable" \
+  --evidence-ref test:browser-capability:passed \
+  --relationship same-run=clone-001
+```
+
+Batch review also emits bounded `evidenceGraph` and remediation suggestions.
+
 The same evidence-first pattern is available for the other maintainer checks:
 
 ```bash
@@ -1028,7 +1096,7 @@ See the [NoBlox preview gallery](https://github.com/TOPY-AI-LTD/NoBlox-App-Templ
 For an explicit brand change, run Maggie Design rebrand before `review`:
 
 ```bash
-python3 tools/clis/maggie_design.py rebrand \
+maggie tool maggie_design.py rebrand \
   --template marketplace/templates/<id> \
   --source-brand "Source Brand" --brand "Target Brand"
 ```
@@ -1147,6 +1215,12 @@ maggie browser-audit https://example.com \
 It captures scroll/geometry samples and screenshots, then fails on hidden
 required elements, horizontal overflow or invalid sticky positioning.
 
+Before navigation, the command writes a redacted
+`maggie-browser-capability.v1` report and rejects missing or incompatible
+adapters, including a system `browse`/`xdg-open` desktop opener. Add
+`--check-browser` to run only this preflight and receive bounded
+installation/fallback guidance.
+
 List every installed skill and command:
 
 ```bash