@topy-ai/maggie 0.7.44 → 0.7.45

package/README-zh-TW.md

@@ -8,11 +8,29 @@ 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.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 +75,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 +100,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.45`。本版完成 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,9 @@ 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.45`. It adds 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 +344,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 +367,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
@@ -599,8 +631,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.45 update --scope project --project . --force
+npx @topy-ai/maggie@0.7.45 cleanup --scope project --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -1028,7 +1060,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"
 ```

package/bin/maggie.js

@@ -3,6 +3,7 @@
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -16,6 +17,8 @@ const MARKETPLACE_ROOT = join(PACKAGE_ROOT, "bundled-marketplace");
 const CONTRACTS_ROOT = join(PACKAGE_ROOT, "bundled-contracts");
 const TEMPLATES_ROOT = join(PACKAGE_ROOT, "bundled-templates");
 const STATE_DIR = ".maggie";
+const USER_SCOPE = "user";
+const PROJECT_SCOPE = "project";
 function loadSkillNames() {
   try {
     return JSON.parse(readFileSync(join(SKILLS_ROOT, "catalog.json"), "utf8")).skills.map((skill) => skill.name);
@@ -45,17 +48,23 @@ const RETIRED_PATHS = [
   "docs/ai-cmo-emdash",
 ];
 const RETIRED_REFERENCE_FILES = ["CLAUDE.md", ".claude/CLAUDE.md", ".agents/AGENTS.md", ".agents/README.md"];
+const USER_RETIRED_PATHS = [
+  "skills/maggie-emdash",
+  "skills/building-emdash-site",
+  "skills/creating-plugins",
+  "skills/emdash-cli",
+  "references/emdash-integration.md",
+];
 
 function usage() {
   console.log(`Maggie Skills installer
 
 Usage:
   maggie --version | version
-  maggie init [--project PATH] [--agent auto|codex|claude|all] [--skills LIST]
-  maggie install [SKILL ...] [--project PATH] [--agent auto|codex|claude|all]
-  maggie update [SKILL ...] [--project PATH] [--agent auto|codex|claude|all] [--force]
+  maggie init|install [--scope project|user|--global] [--project PATH] [--agent auto|codex|claude|all] [--skills LIST]
+  maggie update [SKILL ...] [--scope project|user|--global] [--project PATH] [--agent auto|codex|claude|all] [--force]
   maggie list
-  maggie doctor [--project PATH]
+  maggie doctor [--scope project|user|--global] [--project PATH]
   maggie bootstrap interview [project]
   maggie dash init|install|status|migrate|transition|variant|cms --project PATH [options]
   maggie booking install|worker-schedule|inspect|setup|contract|runtime-validate|ops-validate|release-gate|stripe-audit|tasks --project PATH [options]
@@ -77,8 +86,9 @@ Usage:
   maggie content FILE --source PROVIDER --project PATH --confirm
   maggie agent-content write --url URL --allowed-origin ORIGIN --token-env ENV --payload FILE
   maggie bootstrap phase <start|pass|fail|status> <phase> [project]
-  maggie remove [SKILL ...] [--project PATH] [--agent codex|claude|all]
-  maggie cleanup --project PATH [--confirm]
+  maggie remove [SKILL ...] [--scope project|user|--global] [--project PATH] [--agent codex|claude|all]
+  maggie cleanup [--scope project|user|--global] [--project PATH] [--confirm]
+  maggie tool <bundled-cli.py> [arguments]
   maggie marketplace add <template-url> clone <preview-url> --rename <id>
   maggie marketplace plan --workspace-id ID --merchant-id ID --site-slug SLUG --cal-url URL [--output FILE]
   maggie marketplace list
@@ -180,6 +190,29 @@ function projectRoot(args) {
   return resolve(option(args, "--project", process.cwd()));
 }
 
+function installScope(args) {
+  const explicit = option(args, "--scope");
+  const globalFlag = args.includes("--global");
+  if (globalFlag && explicit && explicit !== USER_SCOPE) throw new Error("--global cannot be combined with --scope project");
+  const scope = globalFlag ? USER_SCOPE : (explicit || PROJECT_SCOPE);
+  if (![PROJECT_SCOPE, USER_SCOPE].includes(scope)) throw new Error(`unknown install scope: ${scope}`);
+  return scope;
+}
+
+function userAgentRoot(agent) {
+  if (agent === "codex") return resolve(process.env.CODEX_HOME || join(homedir(), ".codex"));
+  if (agent === "claude") return resolve(process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"));
+  throw new Error(`unknown agent: ${agent}`);
+}
+
+function userStateRoot() {
+  return resolve(process.env.MAGGIE_HOME || join(homedir(), ".config", "maggie"));
+}
+
+function installManifestPath(root, scope) {
+  return scope === USER_SCOPE ? join(userStateRoot(), "install.json") : join(root, STATE_DIR, "install.json");
+}
+
 function selectedSkills(args) {
   const requested = values(args, "--skills").concat(args.filter((item) => SKILL_NAMES.includes(item)));
   const unique = [...new Set(requested)];
@@ -190,8 +223,12 @@ function selectedSkills(args) {
 }
 
 function diskSkillNames(root) {
+  return diskSkillNamesFromRoots([join(root, ".agents"), join(root, ".claude")]);
+}
+
+function diskSkillNamesFromRoots(agentRoots) {
   const installed = new Set();
-  for (const agentRoot of [join(root, ".agents"), join(root, ".claude")]) {
+  for (const agentRoot of agentRoots) {
     const skillsRoot = join(agentRoot, "skills");
     if (!existsSync(skillsRoot)) continue;
     for (const entry of readdirSync(skillsRoot, { withFileTypes: true })) {
@@ -216,9 +253,29 @@ function mergedSkillNames(root, selected) {
     .filter((skill) => SKILL_NAMES.includes(skill)).sort();
 }
 
-function agentRoots(args, root) {
+function mergedUserSkillNames(roots) {
+  return [...new Set(Object.values(userSkillInventory(roots)).flat())].sort();
+}
+
+function userSkillInventory(roots) {
+  return Object.fromEntries(roots.map((agentRoot) => [
+    agentRoot,
+    [...diskSkillNamesFromRoots([agentRoot])].filter((skill) => SKILL_NAMES.includes(skill)).sort(),
+  ]));
+}
+
+function allUserAgentRoots() {
+  return [userAgentRoot("codex"), userAgentRoot("claude")];
+}
+
+function agentRoots(args, root, scope = PROJECT_SCOPE) {
   const requested = option(args, "--agent", "auto");
   if (!["auto", "codex", "claude", "all"].includes(requested)) throw new Error(`unknown agent: ${requested}`);
+  if (scope === USER_SCOPE) {
+    if (requested === "codex") return [userAgentRoot("codex")];
+    if (requested === "claude") return [userAgentRoot("claude")];
+    return [userAgentRoot("codex"), userAgentRoot("claude")];
+  }
   if (requested === "codex") return [join(root, ".agents")];
   if (requested === "claude") return [join(root, ".claude")];
   if (requested === "all") return [join(root, ".agents"), join(root, ".claude")];
@@ -367,26 +424,45 @@ function managedFileDigests(root, roots, skills, previousManagedFiles = {}) {
   return Object.fromEntries(Object.entries(managedFiles).sort(([a], [b]) => a.localeCompare(b)));
 }
 
-function readInstallManifest(root) {
+function userManagedPairs(roots, skills) {
+  const pairs = [];
+  const add = (source, target) => { if (existsSync(source) && existsSync(target)) pairs.push([source, target]); };
+  for (const agentRoot of roots) {
+    for (const skill of skills) add(join(SKILLS_ROOT, skill), join(agentRoot, "skills", skill));
+    add(REFERENCES_ROOT, join(agentRoot, "references"));
+  }
+  return pairs;
+}
+
+function userManagedFileDigests(roots, skills, previousManagedFiles = {}) {
+  const managedFiles = {};
+  for (const [source, target] of userManagedPairs(roots, skills)) collectManagedFiles(source, target, "/", managedFiles, previousManagedFiles);
+  return Object.fromEntries(Object.entries(managedFiles).sort(([a], [b]) => a.localeCompare(b)));
+}
+
+function readInstallManifest(root, scope = PROJECT_SCOPE) {
   try {
-    const path = join(root, STATE_DIR, "install.json");
+    const path = installManifestPath(root, scope);
     return existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : {};
   } catch {
     return {};
   }
 }
 
-function writeInstallManifest(root, data) {
-  const stateDir = join(root, STATE_DIR);
+function writeInstallManifest(root, data, scope = PROJECT_SCOPE) {
+  const stateDir = scope === USER_SCOPE ? userStateRoot() : join(root, STATE_DIR);
   mkdirSync(stateDir, { recursive: true });
   writeFileSync(join(stateDir, "install.json"), JSON.stringify(data, null, 2) + "\n");
 }
 
 function install(args) {
+  const scope = installScope(args);
   const root = projectRoot(args);
   const skills = selectedSkills(args);
   const force = args.includes("--force");
-  const roots = agentRoots(args, root);
+  const roots = agentRoots(args, root, scope);
+  const previousManifest = scope === USER_SCOPE ? readInstallManifest(root, scope) : {};
+  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");
   for (const agentRoot of roots) {
     for (const skill of skills) {
@@ -395,25 +471,32 @@ function install(args) {
     }
     if (existsSync(REFERENCES_ROOT)) copyIfMissing(REFERENCES_ROOT, join(agentRoot, "references"), force);
   }
-  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)) syncTree(join(TOOLS_ROOT, group), target, force);
-        else copyIfMissing(join(TOOLS_ROOT, group), target, force);
+  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)) syncTree(join(TOOLS_ROOT, group), target, force);
+          else copyIfMissing(join(TOOLS_ROOT, group), target, force);
+        }
       }
     }
+    if (existsSync(join(DESIGN_ROOT, "SPA-DESIGN.md"))) {
+      copyIfMissing(join(DESIGN_ROOT, "SPA-DESIGN.md"), join(root, ".maggie", "design-reference", "SPA-DESIGN.md"));
+    }
+    if (existsSync(MARKETPLACE_ROOT)) copyIfMissing(MARKETPLACE_ROOT, join(root, "marketplace"));
+    if (existsSync(CONTRACTS_ROOT)) copyIfMissing(CONTRACTS_ROOT, join(root, "contracts"));
+    if (existsSync(join(TEMPLATES_ROOT, "maggiedash"))) copyIfMissing(join(TEMPLATES_ROOT, "maggiedash"), join(root, "templates", "maggiedash"));
   }
-  if (existsSync(join(DESIGN_ROOT, "SPA-DESIGN.md"))) {
-    copyIfMissing(join(DESIGN_ROOT, "SPA-DESIGN.md"), join(root, ".maggie", "design-reference", "SPA-DESIGN.md"));
-  }
-  if (existsSync(MARKETPLACE_ROOT)) copyIfMissing(MARKETPLACE_ROOT, join(root, "marketplace"));
-  if (existsSync(CONTRACTS_ROOT)) copyIfMissing(CONTRACTS_ROOT, join(root, "contracts"));
-  if (existsSync(join(TEMPLATES_ROOT, "maggiedash"))) copyIfMissing(join(TEMPLATES_ROOT, "maggiedash"), join(root, "templates", "maggiedash"));
-  writeInstallManifest(root, { version: PACKAGE_VERSION, agents: roots.map((item) => item.slice(root.length + 1)), skills: mergedSkillNames(root, skills), managedFiles: managedFileDigests(root, roots, skills), installed_at: new Date().toISOString() });
-  console.log(`Maggie installed in ${root}`);
-  console.log("Run `maggie doctor --project .` before using mutating workflows.");
+  const manifestRoots = scope === USER_SCOPE ? allUserAgentRoots() : roots;
+  const installedUserSkills = scope === USER_SCOPE ? mergedUserSkillNames(manifestRoots) : [];
+  const manifest = scope === USER_SCOPE
+    ? { scope, version: PACKAGE_VERSION, agents: manifestRoots, skills: installedUserSkills, skillsByAgent: userSkillInventory(manifestRoots), managedFiles: userManagedFileDigests(manifestRoots, installedUserSkills, previousManagedFiles), installed_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), installed_at: new Date().toISOString() };
+  writeInstallManifest(root, manifest, scope);
+  console.log(scope === USER_SCOPE ? `Maggie installed for this user in ${userStateRoot()}` : `Maggie installed in ${root}`);
+  console.log(scope === USER_SCOPE ? "Project state remains local; run `maggie doctor --scope user` to verify the user install." : "Run `maggie doctor --project .` before using mutating workflows.");
 }
 
 function update(args) {
@@ -421,14 +504,16 @@ function update(args) {
     usage();
     return;
   }
+  const scope = installScope(args);
   const root = projectRoot(args);
   const skills = selectedSkills(args);
   const force = args.includes("--force");
-  const roots = agentRoots(args, root);
-  const previousManifest = readInstallManifest(root);
+  const roots = agentRoots(args, root, scope);
+  const previousManifest = readInstallManifest(root, scope);
   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 managedRoot = scope === USER_SCOPE ? "/" : root;
   for (const agentRoot of roots) {
     for (const skill of skills) {
       const source = join(SKILLS_ROOT, skill);
@@ -437,23 +522,30 @@ function update(args) {
         console.log(`absent ${target} (run install to add it)`);
         continue;
       }
-      updated += syncTree(source, target, force, root, previousManagedFiles);
+      updated += syncTree(source, target, force, managedRoot, previousManagedFiles);
     }
-    if (existsSync(REFERENCES_ROOT) && existsSync(join(agentRoot, "references"))) updated += syncTree(REFERENCES_ROOT, join(agentRoot, "references"), force, root, previousManagedFiles);
+    if (existsSync(REFERENCES_ROOT) && existsSync(join(agentRoot, "references"))) updated += syncTree(REFERENCES_ROOT, join(agentRoot, "references"), force, managedRoot, previousManagedFiles);
   }
-  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(join(DESIGN_ROOT, "SPA-DESIGN.md")) && existsSync(join(root, ".maggie", "design-reference"))) {
-    updated += syncTree(DESIGN_ROOT, join(root, ".maggie", "design-reference"), force, root, previousManagedFiles);
+  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(join(DESIGN_ROOT, "SPA-DESIGN.md")) && existsSync(join(root, ".maggie", "design-reference"))) {
+      updated += syncTree(DESIGN_ROOT, join(root, ".maggie", "design-reference"), force, root, previousManagedFiles);
+    }
+    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);
-  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);
-  writeInstallManifest(root, { 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() });
-  console.log(`Maggie update complete: ${updated} files changed`);
+  const manifestRoots = scope === USER_SCOPE ? allUserAgentRoots() : roots;
+  const updatedUserSkills = scope === USER_SCOPE ? mergedUserSkillNames(manifestRoots) : [];
+  const manifest = scope === USER_SCOPE
+    ? { 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.");
 }
 
@@ -505,6 +597,23 @@ function workflowCli(name, args) {
   process.exitCode = result.status ?? 1;
 }
 
+function tool(args) {
+  const [name, ...forwarded] = args;
+  if (!name || name.includes("/") || name.includes("\\") || name.includes("..") || !name.endsWith(".py")) {
+    throw new Error("tool requires one bundled CLI filename such as maggie_design.py");
+  }
+  const root = projectRoot(forwarded);
+  const script = toolScript(name, root);
+  if (!existsSync(script)) throw new Error(`bundled CLI is missing: ${name}`);
+  const result = spawnSync("python3", [script, ...forwarded], {
+    stdio: "inherit",
+    cwd: root,
+    env: { ...process.env, MAGGIE_VERSION: PACKAGE_VERSION },
+  });
+  if (result.error) throw result.error;
+  process.exitCode = result.status ?? 1;
+}
+
 function toolScript(name, root) {
   const bundled = join(TOOLS_ROOT, "clis", name);
   return existsSync(bundled) ? bundled : join(root, "tools", "clis", name);
@@ -515,7 +624,25 @@ function version() {
 }
 
 function doctor(args) {
+  const scope = installScope(args);
   const root = projectRoot(args);
+  if (scope === USER_SCOPE) {
+    const roots = agentRoots(args, root, scope);
+    const checks = roots.map((agentRoot) => [agentRoot, existsSync(join(agentRoot, "skills"))]);
+    for (const [agentRoot, passed] of checks) console.log(`${passed ? "PASS" : "INFO"} ${agentRoot}/skills`);
+    const manifest = readInstallManifest(root, scope);
+    const expected = manifest?.skillsByAgent && typeof manifest.skillsByAgent === "object"
+      ? [...new Set(roots.flatMap((agentRoot) => Array.isArray(manifest.skillsByAgent[agentRoot]) ? manifest.skillsByAgent[agentRoot] : []))].filter((skill) => SKILL_NAMES.includes(skill)).sort()
+      : Array.isArray(manifest?.skills) ? [...new Set(manifest.skills)].filter((skill) => SKILL_NAMES.includes(skill)) : null;
+    const installedNames = new Set([...diskSkillNamesFromRoots(roots)].filter((skill) => SKILL_NAMES.includes(skill)));
+    const missing = expected ? expected.filter((skill) => !installedNames.has(skill)) : [];
+    const inventoryState = expected && missing.length ? "INCOMPLETE" : "PASS";
+    console.log(`${inventoryState} user-skill-inventory manifest=${expected?.length ?? "unknown"} on-disk=${installedNames.size}${missing.length ? ` missing=${missing.join(",")}` : ""}`);
+    console.log(`INFO user-install-manifest=${installManifestPath(root, scope)}`);
+    console.log(`INFO installed-skills=${installedNames.size}`);
+    if (inventoryState === "INCOMPLETE") process.exitCode = 1;
+    return;
+  }
   const checks = [
     ["project", existsSync(root)],
     ["bootstrap-state", existsSync(join(root, ".maggie", "bootstrap-state.json"))],
@@ -538,9 +665,11 @@ function doctor(args) {
 }
 
 function remove(args) {
+  const scope = installScope(args);
   const root = projectRoot(args);
   const skills = selectedSkills(args);
-  for (const agentRoot of agentRoots(args, root)) {
+  const roots = agentRoots(args, root, scope);
+  for (const agentRoot of roots) {
     for (const skill of skills) {
       const target = join(agentRoot, "skills", skill);
       if (existsSync(target)) {
@@ -549,31 +678,50 @@ function remove(args) {
       } else console.log(`absent ${target}`);
     }
   }
+  if (scope === USER_SCOPE) {
+    const manifestRoots = allUserAgentRoots();
+    const remainingSkills = mergedUserSkillNames(manifestRoots);
+    writeInstallManifest(root, {
+      scope,
+      version: PACKAGE_VERSION,
+      agents: manifestRoots,
+      skills: remainingSkills,
+      skillsByAgent: userSkillInventory(manifestRoots),
+      managedFiles: userManagedFileDigests(manifestRoots, remainingSkills),
+      updated_at: new Date().toISOString(),
+    }, scope);
+  }
 }
 
 function cleanup(args) {
+  const scope = installScope(args);
   const root = projectRoot(args);
-  const existing = RETIRED_PATHS
-    .map((relativePath) => ({ relativePath, target: join(root, relativePath) }))
-    .filter(({ target }) => existsSync(target));
+  const roots = scope === USER_SCOPE ? agentRoots(args, root, scope) : [root];
+  const retiredPaths = scope === USER_SCOPE ? USER_RETIRED_PATHS : RETIRED_PATHS;
+  const existing = roots.flatMap((base) => retiredPaths
+    .map((relativePath) => ({ relativePath, target: join(base, relativePath) }))
+    .filter(({ target }) => existsSync(target)));
+
   if (!existing.length) {
-    console.log("Maggie cleanup: no retired artifacts found");
+    console.log(`Maggie cleanup (${scope}): no retired artifacts found`);
   } else {
     for (const { relativePath, target } of existing) console.log(`${args.includes("--confirm") ? "removing" : "would remove"} ${relativePath}`);
     if (args.includes("--confirm")) {
       for (const { target } of existing) rmSync(target, { recursive: true, force: false });
-      console.log(`Maggie cleanup complete: removed ${existing.length} retired artifact(s)`);
+      console.log(`Maggie cleanup (${scope}) complete: removed ${existing.length} retired artifact(s)`);
     } else {
       console.log("Nothing was deleted. Rerun with --confirm to remove these retired artifacts.");
     }
   }
-  for (const relativePath of RETIRED_REFERENCE_FILES) {
-    const target = join(root, relativePath);
-    if (existsSync(target) && /emdash|em-dash|building-emdash-site|creating-plugins/i.test(readFileSync(target, "utf8"))) {
-      console.log(`review required ${relativePath}: contains a retired EmDash reference`);
+  if (scope === PROJECT_SCOPE) {
+    for (const relativePath of RETIRED_REFERENCE_FILES) {
+      const target = join(root, relativePath);
+      if (existsSync(target) && /emdash|em-dash|building-emdash-site|creating-plugins/i.test(readFileSync(target, "utf8"))) {
+        console.log(`review required ${relativePath}: contains a retired EmDash reference`);
+      }
     }
+    console.log("Migration history under docs/de-emdash-* and marketplace/.maggie were preserved.");
   }
-  console.log("Migration history under docs/de-emdash-* and marketplace/.maggie were preserved.");
 }
 
 const [command = "help", ...args] = process.argv.slice(2);
@@ -623,6 +771,7 @@ try {
   else if (command === "booking") workflowCli("maggie_booking.py", args);
   else if (command === "agent-content") workflowCli("maggie_agent_content.py", args);
   else if (command === "content") workflowCli("maggie_content.py", args);
+  else if (command === "tool") tool(args);
   else if (command === "init" || command === "install") install(args);
   else if (command === "update") update(args);
   else if (command === "doctor") doctor(args);

package/bundled-skills/maggie-blog-bootstrap/SKILL.md

@@ -14,14 +14,14 @@ project-specific design, service, SEO, operations, and deployment adapters.
 
 ## Workflow
 
-1. Run `python3 tools/clis/maggie.py analyze PROJECT --json --save` and record
+1. Run `maggie tool maggie.py analyze PROJECT --json --save` and record
    evidence for framework, language, UI, icons, data, content, routes, and
    deployment.
-2. Run `python3 tools/clis/maggie.py bootstrap interview PROJECT`; review the
+2. Run `maggie tool maggie.py bootstrap interview PROJECT`; review the
    checkpoint and confirm foundation, experience, data, and publishing choices.
 3. For a new MaggieDash project, run:
-   `python3 tools/clis/maggie_dash.py init --project PROJECT --confirm` and
-   `python3 tools/clis/maggie_dash.py migrate --project PROJECT --confirm`.
+   `maggie tool maggie_dash.py init --project PROJECT --confirm` and
+   `maggie tool maggie_dash.py migrate --project PROJECT --confirm`.
    If the first-party dashboard is installed, also run
    `maggie dash install --project PROJECT --confirm`; this copies the
    provider-neutral backend type boundary and idempotent starter schema beside
@@ -30,8 +30,8 @@ project-specific design, service, SEO, operations, and deployment adapters.
 4. Advance the ordered foundation gate:
 
    ```bash
-   python3 tools/clis/maggie.py bootstrap phase start maggiedash-foundation PROJECT
-   python3 tools/clis/maggie.py bootstrap phase pass maggiedash-foundation PROJECT \
+   maggie tool maggie.py bootstrap phase start maggiedash-foundation PROJECT
+   maggie tool maggie.py bootstrap phase pass maggiedash-foundation PROJECT \
      --validation "maggie analyze PROJECT; npm run build"
    ```
 
@@ -41,7 +41,7 @@ project-specific design, service, SEO, operations, and deployment adapters.
 7. Import external content through the provider-neutral draft workflow:
 
    ```bash
-   python3 tools/clis/maggie_content.py records.json --project PROJECT \
+   maggie tool maggie_content.py records.json --project PROJECT \
      --source PROVIDER --confirm
    ```