@topy-ai/maggie 0.7.44 → 0.7.46

package/bundled-contracts/maggie-design/browser-capability-v1.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggie.noblox.app/contracts/browser-capability-v1.schema.json",
+  "title": "Maggie browser adapter capability report v1",
+  "type": "object",
+  "required": ["schemaVersion", "adapter", "status", "checks", "requiredCommands", "fallback"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-browser-capability.v1"},
+    "adapter": {
+      "type": "object",
+      "required": ["requested"],
+      "properties": {
+        "requested": {"type": "string", "minLength": 1, "maxLength": 160},
+        "name": {"type": "string", "maxLength": 160},
+        "requestedPathFingerprint": {"type": ["string", "null"], "pattern": "^(sha256:[a-f0-9]{64})?$"},
+        "resolvedPathFingerprint": {"type": ["string", "null"], "pattern": "^(sha256:[a-f0-9]{64})?$"}
+      },
+      "additionalProperties": false
+    },
+    "status": {"enum": ["ready", "missing", "incompatible"]},
+    "errorCode": {"type": "string", "maxLength": 80},
+    "message": {"type": "string", "maxLength": 240},
+    "checks": {
+      "type": "object",
+      "required": ["resolved", "regularFile", "executable", "help", "requiredCommands", "interactionCommands"],
+      "additionalProperties": {"type": "boolean"}
+    },
+    "requiredCommands": {"type": "array", "items": {"type": "string"}, "minItems": 1, "maxItems": 20},
+    "missingCommands": {"type": "array", "items": {"type": "string"}, "maxItems": 20},
+    "fallback": {"type": "array", "items": {"type": "string", "maxLength": 240}, "maxItems": 8}
+  },
+  "additionalProperties": false
+}

package/bundled-contracts/maggie-feedback/evidence-bundle-v1.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggie.noblox.app/contracts/feedback-evidence-bundle-v1.schema.json",
+  "title": "Maggie privacy-safe feedback evidence bundle v1",
+  "type": "object",
+  "required": ["evidence", "relationships"],
+  "properties": {
+    "evidence": {
+      "type": "array",
+      "maxItems": 20,
+      "items": {
+        "type": "object",
+        "required": ["kind", "ref", "status"],
+        "properties": {
+          "kind": {"enum": ["test", "report", "screenshot", "command", "deployment", "issue", "commit", "artifact"]},
+          "ref": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/=-]{0,159}$"},
+          "status": {"enum": ["passed", "failed", "observed", "not-run", "unknown"]}
+        },
+        "additionalProperties": false
+      }
+    },
+    "relationships": {
+      "type": "array",
+      "maxItems": 20,
+      "items": {
+        "type": "object",
+        "required": ["kind", "target", "confidence"],
+        "properties": {
+          "kind": {"enum": ["related", "same-run", "same-fingerprint", "duplicates", "validates", "remediates", "caused-by"]},
+          "target": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/=-]{0,159}$"},
+          "confidence": {"enum": ["low", "medium", "high"]}
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/bundled-references/browser-inspection.md

@@ -14,6 +14,23 @@ The browser capability must support:
 - slow scrolling, click, hover, keyboard focus, and back/forward navigation;
 - reading computed CSS, media sources, links, and visible accessibility labels.
 
+Before navigation, Maggie runs a capability preflight against the configured
+adapter. The report is `maggie-browser-capability.v1` and classifies the
+adapter as `ready`, `missing`, or `incompatible`. This prevents a system
+`browse`/`xdg-open` desktop opener from being mistaken for a browser adapter:
+
+```bash
+maggie browser-audit https://example.com \
+  --browse "$HOME/.codex/skills/gstack/browse/dist/browse" \
+  --output .maggie/browser-audit --required body --check-browser
+```
+
+The report contains only the adapter name, path fingerprints, capability
+checks, and bounded installation/fallback guidance. If it is `missing` or
+`incompatible`, install or enable an authorized Chrome/Playwright/gstack
+adapter and pass its executable path. Maggie does not silently install a
+browser runtime or use a desktop opener as a fallback.
+
 The minimum extraction result for a target is:
 
 ```text

package/bundled-references/google-integrations-runbook.md

@@ -111,8 +111,13 @@ maggie ops google-capabilities \
 ```
 
 The report contract is
-[`capability-report-v1.json`](../bundled-contracts/google-integrations/capability-report-v1.json).
+[`capability-report-v2.schema.json`](../bundled-contracts/google-integrations/capability-report-v2.schema.json).
 The CLI writes a normalized result and never copies arbitrary input fields.
+Every provider row must also identify the redacted active account and selected
+target resource, both with `verified: true`; the target ID must equal the
+selected `resource`. A report that only proves account discovery, or comes from
+the wrong browser account/property, is rejected before a write workflow can use
+it.
 
 ## Capability matrix
 
@@ -121,6 +126,8 @@ Every provider/resource row must expose this shape:
 | Field | Meaning |
 |---|---|
 | `provider` / `resource` | The Google product and scoped resource being checked |
+| `activeAccount` | Redacted account/principal reference confirmed by the current auth session |
+| `target` | Resource ID and kind confirmed in the current account; must match `resource` |
 | `authMode` | `desktop-oauth`, `service-account-impersonation`, or `none` |
 | `scopes` | Exact allowlisted OAuth scopes, never token values |
 | `productRole` | Role granted in the product, distinct from Cloud IAM |

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
    ```
 

package/bundled-skills/maggie-clone/SKILL.md

@@ -29,10 +29,10 @@ Invoke it as:
 The executable workflow is resumable:
 
 ```bash
-python3 tools/clis/maggie_clone.py run <homepage-url> \
+maggie tool maggie_clone.py run <homepage-url> \
   --project <project-root> --run-id <stable-run-id>
-python3 tools/clis/maggie_clone.py status --project <project-root> --run-id <stable-run-id>
-python3 tools/clis/maggie_clone.py run --project <project-root> --run-id <stable-run-id>
+maggie tool maggie_clone.py status --project <project-root> --run-id <stable-run-id>
+maggie tool maggie_clone.py run --project <project-root> --run-id <stable-run-id>
 ```
 
 Each run persists `manifest.json`, `state.json`, and phase outputs under
@@ -104,6 +104,13 @@ for the inspection contract and [`references/operational-model.md`](references/o
 for run artifacts and phase gates. If no browser tool is available, stop before
 editing and report the missing capability.
 
+When using the CLI adapter, run its capability preflight first. A command such
+as `/usr/bin/browse` that resolves to `xdg-open` is a desktop opener, not a
+browser adapter, and must be reported as incompatible. Use the report and its
+bounded fallback guidance to install or select an authorized adapter; do not
+silently substitute a desktop opener or install a browser runtime without the
+user's approval.
+
 ## Phase 0: Preflight and plan
 
 1. Parse and normalize all target URLs. Reject invalid, inaccessible, or
@@ -111,9 +118,9 @@ editing and report the missing capability.
 2. Run:
 
    ```bash
-   python3 tools/clis/maggie.py status <project-root>
-   python3 tools/clis/maggie.py doctor <project-root> --require-bootstrap --strict
-   python3 tools/clis/maggie_clone.py init <homepage-url> --project <project-root> --run-id <stable-run-id>
+   maggie tool maggie.py status <project-root>
+   maggie tool maggie.py doctor <project-root> --require-bootstrap --strict
+   maggie tool maggie_clone.py init <homepage-url> --project <project-root> --run-id <stable-run-id>
    ```
 
    The clone run emits collision-resistant site/page keys and creates a
@@ -147,10 +154,10 @@ shared foundation files that may change
 Inspect the target before building it. Run the executable capture first:
 
 ```bash
-python3 tools/clis/maggie_clone.py capture --project <project-root> --run-id <run-id>
-python3 tools/clis/maggie_clone.py extract --project <project-root> --run-id <run-id>
-python3 tools/clis/maggie_clone.py assets --project <project-root> --run-id <run-id>
-python3 tools/clis/maggie_design_system.py generate \
+maggie tool maggie_clone.py capture --project <project-root> --run-id <run-id>
+maggie tool maggie_clone.py extract --project <project-root> --run-id <run-id>
+maggie tool maggie_clone.py assets --project <project-root> --run-id <run-id>
+maggie tool maggie_design_system.py generate \
   --project <project-root> --sample <industry-design-reference> \
   --run-id <run-id> --output DESIGN.md
 ```
@@ -267,7 +274,7 @@ For the homepage target:
    required viewports. Use the executable comparison gate:
 
    ```bash
-   python3 tools/clis/maggie_clone.py compare --project <project-root> --run-id <run-id> --local-url <local-or-staging-url>
+   maggie tool maggie_clone.py compare --project <project-root> --run-id <run-id> --local-url <local-or-staging-url>
    ```
 
    Review `visual-diff/report.json` and the generated diff images; fix measured
@@ -277,9 +284,9 @@ For the homepage target:
 5. Run the run artifact gate and then:
 
    ```bash
-   python3 tools/clis/site_audit.py <local-or-production-url> --json
-   python3 tools/clis/maggie.py doctor <project-root> --require-bootstrap --strict
-   python3 tools/clis/maggie_clone.py verify --project <project-root> --run-id <run-id>
+   maggie tool site_audit.py <local-or-production-url> --json
+   maggie tool maggie.py doctor <project-root> --require-bootstrap --strict
+   maggie tool maggie_clone.py verify --project <project-root> --run-id <run-id>
    ```
 
 Do not claim pixel fidelity when a target asset, authenticated state, blocked

package/bundled-skills/maggie-clone-to-template/SKILL.md

@@ -29,18 +29,18 @@ evidence.
 For deterministic execution, use the stable checkpoints:
 
 ```bash
-python3 tools/clis/maggie_clone_to_template.py plan <url> "<approved brief>" --rename <template-id>
-python3 tools/clis/maggie_clone_to_template.py clone <template-id>
-python3 tools/clis/maggie_clone_to_template.py package <template-id>
-python3 tools/clis/maggie_clone_to_template.py design-review <template-id>
-python3 tools/clis/maggie_clone_to_template.py validate <template-id>
+maggie tool maggie_clone_to_template.py plan <url> "<approved brief>" --rename <template-id>
+maggie tool maggie_clone_to_template.py clone <template-id>
+maggie tool maggie_clone_to_template.py package <template-id>
+maggie tool maggie_clone_to_template.py design-review <template-id>
+maggie tool maggie_clone_to_template.py validate <template-id>
 ```
 
 If the brief explicitly names a target brand, run the separate Maggie Design
 rebrand checkpoint after packaging and before review:
 
 ```bash
-python3 tools/clis/maggie_design.py rebrand \
+maggie tool maggie_design.py rebrand \
   --template marketplace/templates/<template-id> \
   --source-brand "Source Brand" --brand "Target Brand"
 ```
@@ -54,7 +54,7 @@ and the approved colour palette byte-for-byte.
 convenience orchestration command that executes the same checkpoints in order:
 
 ```bash
-python3 tools/clis/maggie_clone_to_template.py run <url> \
+maggie tool maggie_clone_to_template.py run <url> \
   "Use a compact editorial layout, keep the existing copy, and use warm gold accents." \
   --rename <template-id> --category <category> --tag <tag>
 ```
@@ -80,15 +80,15 @@ template ID, then run the stable CLIs above. If the turn ends at any gate,
 continue with:
 
 ```bash
-python3 tools/clis/maggie_clone_to_template.py resume <template-id>
+maggie tool maggie_clone_to_template.py resume <template-id>
 ```
 
 After applying the prompt, run the review and validation checkpoints:
 
 ```bash
-python3 tools/clis/maggie_clone_to_template.py review <template-id> \
+maggie tool maggie_clone_to_template.py review <template-id> \
   --source-dir <source-screenshot-dir>
-python3 tools/clis/maggie_clone_to_template.py validate <template-id>
+maggie tool maggie_clone_to_template.py validate <template-id>
 ```
 
 `review` writes `visual-review/report.json` and three current screenshots. It
@@ -123,7 +123,7 @@ fails closed unless all three source screenshots can be compared; use
 7. Run:
 
    ```bash
-   python3 tools/clis/maggie_marketplace.py validate marketplace/templates/<id>
+   maggie tool maggie_marketplace.py validate marketplace/templates/<id>
    ```
 
 7. Sync only the approved metadata and previews to the public registry. Keep

package/bundled-skills/maggie-clone-to-template/references/workflow.md

@@ -67,7 +67,7 @@ Rebranding and review are separate actions. If the approved brief names a
 target brand, run the explicit rebrand command 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"
 ```
@@ -79,7 +79,7 @@ validation.
 After marketplace import, call the homepage-review mode of `maggie-design`:
 
 ```bash
-python3 tools/clis/maggie_design.py review \
+maggie tool maggie_design.py review \
   --template marketplace/templates/<id> \
   --source-dir <verified-maggie-clone-screenshot-dir>
 ```

package/bundled-skills/maggie-content-localization/SKILL.md

@@ -80,24 +80,24 @@ advisory and never bypasses validation or owner/Admin approval.
 ## Stable CLI
 
 ```bash
-python3 tools/clis/maggie_localization.py plan \
+maggie tool maggie_localization.py plan \
   --project . --content content.json --source-lang en --target-lang zh-Hans \
   --market uk --operation translate --locale zh-Hans-GB
-python3 tools/clis/maggie_localization.py extract --project . --source-dir src \
+maggie tool maggie_localization.py extract --project . --source-dir src \
   --routes-file docs/routes.tsv --output .maggie/localization/source.json
-python3 tools/clis/maggie_localization.py plan --project . --content content.json \
+maggie tool maggie_localization.py plan --project . --content content.json \
   --source .maggie/localization/source.json --source-lang en --target-lang zh-Hans \
   --market uk --operation translate --locale zh-Hans-GB
-python3 tools/clis/maggie_localization.py preview .maggie/localization/<job>.json
-python3 tools/clis/maggie_localization.py validate .maggie/localization/<job>.json
-python3 tools/clis/maggie_localization.py validate .maggie/localization/<job>.json \
+maggie tool maggie_localization.py preview .maggie/localization/<job>.json
+maggie tool maggie_localization.py validate .maggie/localization/<job>.json
+maggie tool maggie_localization.py validate .maggie/localization/<job>.json \
   --source .maggie/localization/source.json \
   --render-report .maggie/localization/rendered.json
-python3 tools/clis/maggie_localization.py review .maggie/localization/<job>.json \
+maggie tool maggie_localization.py review .maggie/localization/<job>.json \
   --reviewer owner@example.com --decision approve
-python3 tools/clis/maggie_localization.py publish .maggie/localization/<job>.json --confirm
-python3 tools/clis/maggie_localization.py stale --project .
-python3 tools/clis/maggie_localization.py glossary --project .
+maggie tool maggie_localization.py publish .maggie/localization/<job>.json --confirm
+maggie tool maggie_localization.py stale --project .
+maggie tool maggie_localization.py glossary --project .
 ```
 
 Operations are distinct: `translate` preserves meaning, `polish` improves

package/bundled-skills/maggie-deployment/SKILL.md

@@ -136,7 +136,7 @@ configuration under `.maggie/deployment`; merely creating the directory is not
 enough:
 
 ```bash
-python3 tools/clis/maggie_deployment.py /path/to/project \
+maggie tool maggie_deployment.py /path/to/project \
   --target cloudflare --environment staging \
   --output .maggie/deployment-preflight.json
 ```
@@ -188,7 +188,7 @@ read-only check.
 Generate a reviewable VPS plan and configuration artifacts locally:
 
 ```bash
-python3 tools/clis/maggie_deployment.py /path/to/project \
+maggie tool maggie_deployment.py /path/to/project \
   --vps-plan --domain example.co.uk --service example \
   --release-root /var/www/example \
   --node-port 4321 \
@@ -224,7 +224,7 @@ preserve the `current` target and rollback target, and review prune candidates
 before any operator executes cleanup. Generate a read-only candidate report:
 
 ```bash
-python3 tools/clis/maggie_deployment.py --retention-plan \
+maggie tool maggie_deployment.py --retention-plan \
   --release-root /var/www/example \
   --current-link /var/www/example/current \
   --keep-releases 2 --output .maggie/deployment/retention-plan.json
@@ -236,7 +236,7 @@ retained releases.
 Validate the database release separately before a VPS migration:
 
 ```bash
-python3 tools/clis/maggie_migration.py .maggie/migration-release.json \
+maggie tool maggie_migration.py .maggie/migration-release.json \
   --environment staging --output .maggie/migration-preflight.json
 ```
 
@@ -288,7 +288,7 @@ Validate and materialise scheduled jobs only after their quota and lock policy
 has been reviewed:
 
 ```bash
-python3 tools/clis/maggie_schedule.py .maggie/schedule.json \
+maggie tool maggie_schedule.py .maggie/schedule.json \
   --units-dir .maggie/deployment/schedules
 ```
 
@@ -301,34 +301,47 @@ output/state artifact and must never be used as the provider source argument.
 When validating a project schedule, pass `--project` so the URL is compared
 exactly with `.maggie/booking/services.json` `sourceUrl`.
 
-For a single read-only staging release gate, run. This gate also requires
-explicit editorial approval for all launch category copy; rendered draft
-evidence is not publication approval:
+For a single read-only staging release gate, first declare the project's release
+surface in `.maggie/release-profile.json`. The manifest is the source of truth;
+Maggie does not infer Booking, MaggieDash, migration, analytics, service
+catalogue, or editorial gates from incidental files. A minimal public Astro
+site can use:
+
+```json
+{
+  "schemaVersion": "maggie-release-profile.v1",
+  "profile": "public-astro",
+  "projectType": "astro",
+  "capabilities": ["deployment"]
+}
+```
+
+Add `migration`, `maggiedash-health`, `schedule`, `analytics-contract`,
+`service-facts`, `editorial-review`, or `durable-site-evidence` only when that
+project actually owns the corresponding artifact. For a single read-only
+staging release gate, run:
 
 ```bash
-python3 tools/clis/maggie_release.py /path/to/project \
+maggie tool maggie_release.py /path/to/project \
+  --profile /path/to/project/.maggie/release-profile.json \
   --environment staging --target vps-with-cloudflare-dns \
   --base-url https://staging.example.com
 ```
 
-If `.maggie/scenario-manifest.json` or `.maggie/qa-runs/` exists, the same
-preflight consumes the latest matching `maggie qa` run for the requested
-environment (and `--base-url`, when supplied). It blocks when a scenario is
-not passed, has no browser-adapter evidence, or the matching run is missing.
-Projects without scenario QA report `not-configured`; Maggie does not run the
-browser itself.
-
-This aggregates deployment, migration, provider-health, schedule, analytics,
-service-fact, editorial approval, durable SEO/route/category evidence,
-MaggieDash schema compatibility, and live runtime security-header checks. It writes
-`.maggie/release-preflight.json`; a failed gate blocks release. It never
-deploys, migrates, publishes, or sends provider requests.
+If `scenario-qa` is declared, the preflight consumes the latest matching
+`maggie qa` run for the requested environment (and `--base-url`, when
+supplied). It blocks when a scenario is not passed, has no browser-adapter
+evidence, or the matching run is missing. The report records every undeclared
+optional gate as `skipped`, so a public site is not blocked by Booking- or
+MaggieDash-only evidence. It writes `.maggie/release-preflight.json`; a failed
+gate blocks release. It never deploys, migrates, publishes, or sends provider
+requests.
 
 Generate a repeatable VPS runner as part of the plan. A deploy step that exists
 only in an operator's shell history is not a release contract:
 
 ```bash
-python3 tools/clis/maggie_deployment.py /path/to/project \
+maggie tool maggie_deployment.py /path/to/project \
   --vps-plan --domain example.co.uk --service example \
   --release-root /var/www/example \
   --runner-output .maggie/deployment/release-runner.sh
@@ -338,6 +351,27 @@ Review the generated runner before execution. Its order is install → typecheck
 → migrate → build → carry agent state → switch → restart → verify → prune;
 retention keeps the current release and one rollback candidate.
 
+Before writing a VPS plan or running the release gate, validate the real
+least-privilege deploy account. This check is read-only: it verifies SSH access,
+write permission for both the release root and `releases/`, and the exact
+non-interactive systemd allowlist. A failed check does not create the plan or
+runner:
+
+```bash
+maggie deployment --verify-deployer \
+  --deployer-host "$DEPLOY_SERVER_IP" \
+  --deployer-user "$DEPLOY_SERVER_SSH_USER" \
+  --release-root /var/www/example \
+  --service example \
+  --output .maggie/deployment/deployer-delegation.json
+```
+
+For a VPS `maggie release`, this evidence is required at
+`.maggie/deployment/deployer-delegation.json` (or pass
+`--deployer-evidence`). The generated runner waits for bounded transient
+`000/502/503/504` startup responses after restart, while returning a clear
+failure immediately for permanent HTTP responses.
+
 Production additionally requires `docs/deployment-rollback-smoke.json` with
 `passed: true`, `environment: production`, and `testedAt`. For an upgrade it
 must include a non-empty `previousRelease`. For the first production release,
@@ -348,7 +382,7 @@ production-only evidence.
 
 ## Required workflow
 
-1. Run `python3 tools/clis/maggie.py analyze <project> --save` and inspect the
+1. Run `maggie tool maggie.py analyze <project> --save` and inspect the
    selected framework, runtime, build/deploy commands, route inventory, data
    layer, and deployment risks.
 2. Confirm the target, domain, environment (`staging` or `production`), data

package/bundled-skills/maggie-deployment/references/vps.md

@@ -26,7 +26,7 @@ routes remain authenticated and `noindex`.
 ## Required preflight
 
 ```bash
-python3 tools/clis/maggie_deployment.py . \
+maggie tool maggie_deployment.py . \
   --target vps-with-cloudflare-dns \
   --environment staging \
   --output .maggie/deployment-preflight.json
@@ -86,7 +86,7 @@ this pattern assumes.
 Create a local, secret-free plan before remote execution:
 
 ```bash
-python3 tools/clis/maggie_deployment.py . --vps-plan \
+maggie tool maggie_deployment.py . --vps-plan \
   --domain example.co.uk --service example \
   --release-root /var/www/example \
   --node-port 4321 \
@@ -102,7 +102,7 @@ canonical HTTPS `allowedDomains` plus trusted `X-Forwarded-Host`/
 Use a dedicated least-privilege deployer when generating the plan:
 
 ```bash
-python3 tools/clis/maggie_deployment.py . --vps-plan \
+maggie tool maggie_deployment.py . --vps-plan \
   --domain example.co.uk --service example --node-port 4321 \
   --deployer-user maggie-deploy
 ```
@@ -116,7 +116,7 @@ Review the generated systemd and Nginx files, then obtain explicit approval
 before installing them on a host.
 
 Database safety is a separate gate. Run
-`python3 tools/clis/maggie_migration.py <manifest> --environment staging`
+`maggie tool maggie_migration.py <manifest> --environment staging`
 before staging migration and require a successful restore test before a
 production release. Keep the backup artifact and migration version in the
 handover record; never put a database URL or password in the manifest.

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

@@ -131,17 +131,17 @@ Run the complete clone workflow first. After the full target page has been
 built, compared, and verified, create the reconciliation contract:
 
 ```bash
-python3 tools/clis/maggie_design.py <target-url1> [<target-url2> ...] \\
+maggie tool maggie_design.py <target-url1> [<target-url2> ...] \\
   --project <project-root> --clone-run <verified-clone-run-id> --save
 ```
 
 The design contract also has a resumable CLI workflow:
 
 ```bash
-python3 tools/clis/maggie_design.py run <target-url1> [<target-url2> ...] \
+maggie tool maggie_design.py run <target-url1> [<target-url2> ...] \
   --project <project-root> --clone-run <verified-clone-run-id>
-python3 tools/clis/maggie_design.py status <design-job-id> --project <project-root>
-python3 tools/clis/maggie_design.py resume <design-job-id> --project <project-root>
+maggie tool maggie_design.py status <design-job-id> --project <project-root>
+maggie tool maggie_design.py resume <design-job-id> --project <project-root>
 ```
 
 The job writes `.maggie/design-jobs/<job-id>.json` and stops at `failed` when
@@ -163,7 +163,7 @@ Use in-place mode when the route already belongs to the current first-party
 project and should be redesigned without cloning an external URL:
 
 ```bash
-python3 tools/clis/maggie_design.py in-place \
+maggie tool maggie_design.py in-place \
   --project <project-root> \
   --route /pricing \
   --route /about
@@ -291,7 +291,7 @@ The homepage `review` mode only compares screenshots. It does not rebrand a
 template. When the user explicitly requests a brand change, run:
 
 ```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"
@@ -310,7 +310,7 @@ with Maggie Studio.
 - Require a completed `.maggie/bootstrap-state.json` and a completed homepage
   foundation from `maggie-clone`. If either is missing, stop and request it.
 - Require a project-level `DESIGN.md` generated from the industry reference and
-  clone evidence. Validate it with `python3 tools/clis/maggie_design_system.py
+  clone evidence. Validate it with `maggie tool maggie_design_system.py
   validate DESIGN.md`; if it is missing or invalid, stop before editing.
 - Reject the origin homepage as a target. Use `maggie-clone` for that job.
 - The target is initially cloned as a complete page. After that first pass,
@@ -334,9 +334,9 @@ Follow the shared [Maggie decision loop](../../references/decision-loop.md).
 Inspect before editing:
 
 ```bash
-python3 tools/clis/maggie.py status <project-root>
-python3 tools/clis/maggie.py doctor <project-root> --require-bootstrap --strict
-python3 tools/clis/maggie_clone.py verify --project <project-root> --run-id <verified-clone-run-id>
+maggie tool maggie.py status <project-root>
+maggie tool maggie.py doctor <project-root> --require-bootstrap --strict
+maggie tool maggie_clone.py verify --project <project-root> --run-id <verified-clone-run-id>
 ```
 
 Read and follow the complete `maggie-clone` workflow before proceeding. The
@@ -493,8 +493,8 @@ For every target:
    the final content region to the target for page fidelity.
 4. Sweep keyboard focus, links, forms, hover, tabs/dialogs, scroll behavior,
    mobile menu, and reduced-motion behavior.
-5. Run `python3 tools/clis/site_audit.py <local-or-production-url> --json`.
-6. Run `python3 tools/clis/maggie_clone.py compare --project <project-root> --run-id <verified-clone-run-id> --local-url <local-or-staging-url> --force` and review the final content-region diff.
+5. Run `maggie tool site_audit.py <local-or-production-url> --json`.
+6. Run `maggie tool maggie_clone.py compare --project <project-root> --run-id <verified-clone-run-id> --local-url <local-or-staging-url> --force` and review the final content-region diff.
 7. Confirm the final DOM has exactly one header and one footer, the homepage
    shell is the imported source of truth, and no target-shell fallback remains.