@topy-ai/maggie 0.7.44 → 0.7.46

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
@@ -143,7 +153,7 @@ Usage:
   maggie brand-kit --manifest FILE | --project PATH --design DESIGN.md [--write --confirm]
   maggie npm11 --project PATH [--smoke --confirm]
   maggie booking-delivery [--policy FILE]
-  maggie release PATH --environment staging --target vps-with-cloudflare-dns
+  maggie release PATH --profile .maggie/release-profile.json --environment staging --target vps-with-cloudflare-dns
   maggie api lifecycle --project PATH [--execute --allow-quota]
   maggie memory <init|list|search|context|add|record-error|transition|export> --project PATH
   maggie localization <extract|plan|generate|preview|validate|review|publish|stale|glossary> [options]
@@ -153,7 +163,7 @@ Usage:
   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]
-  maggie browser-audit URL --browse PATH --output DIR --required SELECTOR [--sticky SELECTOR] [--interactions FILE]
+  maggie browser-audit URL --browse PATH --output DIR [--required SELECTOR] [--sticky SELECTOR] [--interactions FILE] [--check-browser]
   maggie verification coverage --contract FILE --evidence FILE
   maggie ops audit|preflight|verify|lockfiles|seed-manifest|google-capabilities|favicon-check --project PATH
   maggie ops google-capabilities --project PATH --report FILE [--output FILE]
@@ -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-contracts/google-integrations/capability-report-v2.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggie.noblox.app/contracts/google-integrations/capability-report-v2.json",
+  "title": "Maggie Google integrations capability report v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "generatedAt", "providerResults", "passed", "mutationsAllowed"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-google-capability-report.v2"},
+    "generatedAt": {"type": "string", "minLength": 1},
+    "providerResults": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/providerResult"}},
+    "passed": {"type": "boolean"},
+    "mutationsAllowed": {"const": false}
+  },
+  "$defs": {
+    "providerResult": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "resource", "activeAccount", "target", "authMode", "scopes", "productRole", "evidence", "capabilities", "nextAction"],
+      "properties": {
+        "provider": {"enum": ["gsc", "ga4", "gtm", "google-ads", "firebase"]},
+        "resource": {"type": "string", "minLength": 1, "maxLength": 200},
+        "activeAccount": {"$ref": "#/$defs/verifiedRef"},
+        "target": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "kind", "verified"],
+          "properties": {
+            "id": {"type": "string", "minLength": 1, "maxLength": 200},
+            "kind": {"enum": ["property", "container", "customer", "project", "site", "account"]},
+            "verified": {"const": true}
+          }
+        },
+        "authMode": {"enum": ["desktop-oauth", "service-account-impersonation", "none"]},
+        "scopes": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true},
+        "productRole": {"type": "string", "minLength": 1, "maxLength": 200},
+        "evidence": {"$ref": "#/$defs/evidence"},
+        "capabilities": {"$ref": "#/$defs/capabilities"},
+        "nextAction": {"type": "string", "minLength": 1, "maxLength": 500}
+      }
+    },
+    "verifiedRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "verified"],
+      "properties": {
+        "id": {"type": "string", "pattern": "^[^@\\s]{1,200}$"},
+        "verified": {"const": true}
+      }
+    },
+    "evidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["verified", "endpoint", "statusCode", "readOnly"],
+      "properties": {
+        "verified": {"type": "boolean"},
+        "endpoint": {"type": "string", "minLength": 1, "maxLength": 500},
+        "statusCode": {"type": "integer", "minimum": 100, "maximum": 599},
+        "readOnly": {"type": "boolean"},
+        "writeTest": {"type": "object"},
+        "adsPrerequisites": {"type": "object"}
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["read", "report", "edit", "publish"],
+      "properties": {
+        "read": {"enum": ["verified", "not_tested", "not_available", "blocked"]},
+        "report": {"enum": ["verified", "not_tested", "not_available", "blocked"]},
+        "edit": {"enum": ["verified", "not_tested", "not_available", "blocked"]},
+        "publish": {"enum": ["verified", "not_tested", "not_available", "blocked"]}
+      }
+    }
+  }
+}

package/bundled-contracts/google-integrations/external-write-readback-v1.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggie.noblox.app/contracts/google-integrations/external-write-readback-v1.json",
+  "title": "Maggie external provider write readback evidence v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "generatedAt", "provider", "resource", "operation", "idempotencyKey", "retry", "mutation", "readback", "duplicates", "orphaned", "cleanup", "mutationExecuted"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-external-write-readback.v1"},
+    "generatedAt": {"type": "string", "minLength": 1},
+    "provider": {"enum": ["ga4", "gtm", "gsc", "google-ads", "firebase"]},
+    "resource": {"type": "string", "minLength": 1, "maxLength": 200},
+    "operation": {"type": "string", "pattern": "^[a-z][a-z0-9_.-]{1,63}$"},
+    "idempotencyKey": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{2,127}$"},
+    "retry": {
+      "type": "object", "additionalProperties": false, "required": ["attempt", "maxAttempts", "sameKeyOnRetry"],
+      "properties": {"attempt": {"type": "integer", "minimum": 1, "maximum": 3}, "maxAttempts": {"type": "integer", "minimum": 1, "maximum": 3}, "sameKeyOnRetry": {"const": true}}
+    },
+    "mutation": {
+      "type": "object", "additionalProperties": false, "required": ["status", "statusCode", "explicitConfirmation"],
+      "properties": {"status": {"enum": ["created", "updated", "no-op"]}, "statusCode": {"type": "integer", "minimum": 200, "maximum": 299}, "explicitConfirmation": {"const": true}}
+    },
+    "readback": {
+      "type": "object", "additionalProperties": false, "required": ["passed", "endpoint", "checks"],
+      "properties": {
+        "passed": {"const": true},
+        "endpoint": {"type": "string", "pattern": "^https://[^\\s?#]+$"},
+        "checks": {"type": "array", "minItems": 1, "items": {"type": "object"}}
+      }
+    },
+    "duplicates": {"type": "array", "maxItems": 0},
+    "orphaned": {"type": "array", "maxItems": 0},
+    "cleanup": {"type": "object", "additionalProperties": false, "required": ["status", "checked"], "properties": {"status": {"enum": ["not-needed", "passed"]}, "checked": {"const": true}}},
+    "mutationExecuted": {"const": true}
+  }
+}

package/bundled-contracts/maggie-deployment/deployer-delegation-v1.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggiedash.noblox.app/contracts/deployer-delegation-v1.schema.json",
+  "title": "Maggie deployment deployer delegation evidence v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "host", "user", "releaseRoot", "service", "state", "passed", "checks", "mutation"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-deployment-delegation.v1"},
+    "host": {"type": "string", "minLength": 1},
+    "user": {"type": "string", "pattern": "^[a-z_][a-z0-9_-]{0,31}\\$?$"},
+    "releaseRoot": {"type": "string", "pattern": "^/[^\\r\\n]*$"},
+    "service": {"type": "string", "pattern": "^[A-Za-z0-9_.@-]+$"},
+    "state": {"enum": ["passed", "failed", "transient", "inconclusive"]},
+    "passed": {"type": "boolean"},
+    "checks": {"type": "object"},
+    "errors": {"type": "array", "items": {"type": "string"}},
+    "mutation": {"const": "not executed"}
+  }
+}

package/bundled-contracts/maggie-deployment/release-profile-v1.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggiedash.noblox.app/contracts/release-profile-v1.schema.json",
+  "title": "Maggie release profile v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "profile", "capabilities"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-release-profile.v1"},
+    "profile": {"type": "string", "pattern": "^[a-z][a-z0-9-]{1,63}$"},
+    "projectType": {"type": "string", "enum": ["astro", "nextjs", "sveltekit", "nuxt", "vite-react", "vite-vue", "other"]},
+    "capabilities": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "deployment",
+          "scenario-qa",
+          "social-card-audit",
+          "migration",
+          "maggiedash-health",
+          "schedule",
+          "analytics-contract",
+          "analytics-release-gate",
+          "service-facts",
+          "maggiedash-schema",
+          "editorial-review",
+          "durable-site-evidence"
+        ]
+      }
+    }
+  }
+}