@topy-ai/maggie 0.7.13 → 0.7.15

package/README.md

@@ -58,7 +58,31 @@ Then invoke the installed skills from your coding agent, for example:
 
 Maggie keeps the existing project foundation and asks for decisions before
 shared routes, analytics, or publishing boundaries change. The current
-package ships 18 installable skills and a local-first MaggieDash foundation.
+package ships 19 installable skills and a local-first MaggieDash foundation.
+
+For repeatable browser QA, create a project-owned scenario manifest and record
+the test, fix, and retest lifecycle:
+
+```bash
+maggie qa start --project . \
+  --scenario-file .maggie/scenario-manifest.json \
+  --environment local --base-url http://localhost:4321
+maggie qa record --project . --run <run-id> \
+  --scenario HOME-001 --phase test --status pass \
+  --summary "Homepage smoke passed" --evidence .maggie/qa/home.png
+maggie qa summary --project . --run <run-id>
+```
+
+The QA workflow stores secret-free run state under `.maggie/qa-runs/` and
+keeps project-specific scenarios and evidence outside the npm package.
+
+The current package also includes reusable safeguards from the latest feedback
+review: `maggie dash api-contract` checks declared request and 2xx response
+shapes; `maggie blog check-gate`/`approve` enforces review before publish;
+sitemap validation flags suspiciously uniform `lastmod` dates; `maggie seo
+indexnow` plans only changed same-origin URLs and holds back URLs accepted in
+the last 24 hours; and dash inventory separates renderer kind from public page
+kind while reporting source coverage for code-rendered routes.
 
 For Google integrations, validate a redacted provider matrix before reporting
 access. The command fails closed on unknown scopes, missing Ads prerequisites,
@@ -105,7 +129,8 @@ maggie dash install | init | status | migrate | cms ...
 maggie dash transition ...      # explicit content approval transition
 maggie dash variant ...         # service variant create/review/preview/publish
 maggie dash sections ...        # field fan-out, locale, binding, media, copy, identity keys
-maggie dash inventory ...        # disjoint published-page inventory
+maggie dash inventory ...        # disjoint renderer/page-kind inventory + coverage
+maggie dash api-contract ...     # declared API body and 2xx response contract
 maggie agent-content write ...  # host-authorized, origin-bound content bridge
 maggie verification coverage ... # changed surface/locale evidence gate
 maggie clone ...                 # authorized homepage capture
@@ -114,11 +139,13 @@ maggie clone-to-template ...     # URL → validated marketplace template
 maggie marketplace ...           # catalog and on-demand template workflow
 maggie memory ...                # confirmed preferences and lessons
 maggie feedback ...              # redact, preview, submit, list
+maggie qa ...                    # scenario browser QA, fix/retest, release gate
 maggie localization ...          # plan, validate, review, publish, stale
 maggie service ...               # import, sync, generate, validate
 maggie seo performance ...       # sampled PageSpeed/CWV report and baseline
 maggie seo images ...             # inventory, variants, confirmation, validate
 maggie seo sitemap ...            # typed/semantic plan, agent-files, apply, rollback
+maggie seo indexnow ...           # changed URLs, key check, retry-safe 24h guard
 maggie deployment | migration | release | analytics | schedule
 maggie migration identity --identity-file FILE [--expected-file FILE]
 maggie deployment canary --asset URL=SHA256 --render-report report.json
@@ -220,8 +247,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.13 update --project . --force
-npx @topy-ai/maggie@0.7.13 cleanup --project .
+npx @topy-ai/maggie@0.7.15 update --project . --force
+npx @topy-ai/maggie@0.7.15 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -231,7 +258,12 @@ as a command-line argument:
 node scripts/publish-npm.mjs --maggie-env-file ../.env
 ```
 
-The 0.7.13 workflow adds field-aware section fan-out and locale coverage,
+The 0.7.15 workflow adds API contracts, blog review gates, sitemap freshness,
+change-driven IndexNow, and page-kind/source-coverage inventory. It also keeps
+the general `maggie-qa-workflow` skill and `maggie qa`
+CLI for scenario manifests, secret-free browser evidence metadata, test/fix/
+retest lifecycle, adjacent regression checks, and explicit release gates. The
+0.7.13 workflow adds field-aware section fan-out and locale coverage,
 sibling-copy/media checks, disjoint page inventory, binding validation,
 idempotency and database-target identity gates, full W3C sitemap lastmod
 validation, and the accepted `X-Robots-Tag: noindex` response contract. The
@@ -484,6 +516,7 @@ python3 tools/clis/maggie_design.py rebrand \
 | `maggie-memory` | Persist confirmed preferences, conventions, lessons, and errors |
 | `maggie-content-localization` | Manage locale-aware translation, review, provenance, stale state, and publication gates |
 | `maggie-feedback` | Collect redacted feedback drafts and explicitly submit them to the NoBlox feedback endpoint |
+| `maggie-qa-workflow` | Run scenario-based browser QA with evidence, fix/retest lifecycle, and release gates |
 | `maggie-auth-reference` | Generate and validate traditional email/password auth with secure server-side sessions |
 | `maggie-blog` | Run a provider-neutral blog lifecycle with stable identity, topics, feeds, settings, and rollback |
 
@@ -528,12 +561,13 @@ repairs with `maggie dash sections validate`, `fanout-validate`,
 `maggie dash inventory` to classify published pages once into disjoint kinds.
 See the [quality contract examples](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/contracts/maggiedash/quality-contracts.md).
 
-The package includes all 18 installable skills: `maggie-blog-bootstrap`,
+The package includes all 19 installable skills: `maggie-blog-bootstrap`,
 `maggie-dash`, `maggie-clone`, `maggie-clone-to-template`, `maggie-marketplace`,
 `maggie-template`, `maggie-design`, `maggie-ops`, `maggie-deployment`,
 `maggie-project-context`, `maggie-seo-geo`, `maggie-social-share`,
 `maggie-service-booking`, `maggie-memory`, `maggie-content-localization`,
-`maggie-feedback`, `maggie-auth-reference`, and `maggie-blog`. Use the stable
+`maggie-feedback`, `maggie-qa-workflow`, `maggie-auth-reference`, and
+`maggie-blog`. Use the stable
 commands below after installation:
 
 ```bash
@@ -543,6 +577,8 @@ maggie design author --project . --route /about --purpose "Explain our approach"
 maggie blog init --project . --confirm
 maggie blog ingest --project . --source local --input content/posts.json --confirm
 maggie blog validate --project .
+maggie blog check-gate --project .
+maggie blog approve --project . --slug example-post --actor reviewer --reason "reviewed" --confirm
 maggie blog sitemap --project .
 ```
 

package/README.zh-TW.md

@@ -2,13 +2,13 @@
 
 [English README](README.md) · [完整繁體中文 README](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/README.zh-TW.md)
 
-`@topy-ai/maggie` 提供 18 個可安裝的 AI website workflow skills，支援
+`@topy-ai/maggie` 提供 19 個可安裝的 AI website workflow skills，支援
 Codex、Claude Code 與相容的 coding agents。
 
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.7.13 init --agent all
+npx @topy-ai/maggie@0.7.15 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 
@@ -25,6 +25,9 @@ maggie doctor --project . --require-bootstrap --strict
 deployment、memory、feedback 和 MaggieDash。內容先 draft/review，外部寫入、
 publish 與 production deployment 需要明確確認。
 
+0.7.15 也加入 API schema contract、blog review gate、sitemap freshness
+warning、change-driven IndexNow 與 page-kind/source-coverage inventory。
+
 MaggieDash 也提供穩定 section identity、可重用 section arrangement、機器可讀
 section registry、短期 agent content bridge，以及 translation out-of-band write
 後的 restart gate。`maggie doctor` 會比較 install manifest 與磁碟上的實際 skills。
@@ -50,8 +53,13 @@ maggie dash inventory --pages-file .maggie/published-pages.json
 # Migration target identity (never prints or stores a database URL)
 maggie migration identity --identity-file .maggie/db-identity.json \
   --expected-file .maggie/service-db-identity.json
+
+# Scenario browser QA
+maggie qa start --project . --scenario-file .maggie/scenario-manifest.json \
+  --environment local --base-url http://localhost:4321
+maggie qa summary --project . --run <run-id>
 ```
 
-完整中文說明、18 個 skills 清單和 roadmap：
+完整中文說明、19 個 skills 清單和 roadmap：
 [繁體中文 README](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/README.zh-TW.md)
 · [Roadmap](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/ROADMAP.md)

package/bin/maggie.js

@@ -59,7 +59,8 @@ Usage:
   maggie bootstrap interview [project]
   maggie dash init|install|status|migrate|transition|variant|cms --project PATH [options]
   maggie dash sections <validate|prompt|keys|remap-translations|fanout-validate|locale-validate|variant-copy-validate|media-validate|bindings-validate|idempotency-validate|reconcile> [options]
-  maggie dash inventory --pages-file FILE
+  maggie dash inventory --pages-file FILE [--require-page-kinds] [--require-source-coverage]
+  maggie dash api-contract --spec FILE
   maggie dash components-audit --bindings-file FILE --sections-file FILE --pages-file FILE
   maggie dash status --project PATH
   maggie dash migrate --project PATH --confirm
@@ -92,7 +93,7 @@ Usage:
   maggie design step <job-id> --step NAME --evidence FILE
   maggie auth reference --project PATH --confirm
   maggie auth check --project PATH [--production]
-  maggie blog init|inspect|ingest|validate|publish|sitemap|settings|rollback|integration-state
+  maggie blog init|inspect|ingest|validate|check-gate|approve|publish|sitemap|settings|rollback|integration-state
   maggie design status <job-id>
   maggie service import <provider-url> --project PATH
   maggie service sync <provider-url> --project PATH
@@ -112,8 +113,9 @@ Usage:
   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]
-  maggie seo performance|images|sitemap [options] (sitemap supports strict validate and agent-files)
+  maggie seo performance|images|sitemap|indexnow [options] (sitemap supports strict validate and agent-files)
   maggie feedback <collect|preview|submit|list> [options]
+  maggie qa <start|record|summary|export> [options]
   maggie site-audit URL [--crawl] [--access-log FILE] [--require-sitemap-request] [--languages en-GB,es-MX,ja-JP] [--check-hreflang]
   maggie site-audit URL --crawl --save-baseline FILE --reviewer NAME
   maggie site-audit URL --crawl --baseline FILE
@@ -300,8 +302,8 @@ function service(args) {
 
 function seo(args) {
   const command = args[0];
-  const scripts = { performance: "maggie_performance.py", images: "maggie_images.py", sitemap: "maggie_sitemap.py" };
-  if (!scripts[command]) throw new Error("seo command must be performance, images, or sitemap");
+  const scripts = { performance: "maggie_performance.py", images: "maggie_images.py", sitemap: "maggie_sitemap.py", indexnow: "maggie_indexnow.py" };
+  if (!scripts[command]) throw new Error("seo command must be performance, images, sitemap, or indexnow");
   workflowCli(scripts[command], args.slice(1));
 }
 
@@ -406,6 +408,7 @@ try {
   else if (command === "memory") workflowCli("maggie_memory.py", args);
   else if (command === "localization") workflowCli("maggie_localization.py", args);
   else if (command === "feedback") workflowCli("maggie_feedback.py", args);
+  else if (command === "qa") workflowCli("maggie_qa_workflow.py", args);
   else if (command === "site-audit") workflowCli("site_audit.py", args);
   else if (command === "browser-audit") workflowCli("maggie_browser_audit.py", args);
   else if (command === "verification") workflowCli("maggie_verification.py", args);

package/bundled-skills/README.md

@@ -20,6 +20,7 @@ Skills are the agent-facing workflows. They compose with the tools in
 | `maggie-memory` | Persist confirmed preferences, project conventions, lessons, and error history across skill runs | local `.maggie/memory/` state |
 | `maggie-content-localization` | Plan, validate, review, publish, and age localized content with market, locale, provenance, and translation safeguards | localization contract, locale CLI |
 | `maggie-feedback` | Collect, redact, review, and explicitly submit feedback from skill runs | feedback CLI, hosted endpoint, GitHub Issue Forms |
+| `maggie-qa-workflow` | Run scenario-based browser QA with evidence, fix/retest lifecycle, and release gates | browser adapter, QA workflow CLI, scenario manifest |
 
 Read only the selected skill and its linked references for a task. Do not load
 all skills as one undifferentiated prompt.

package/bundled-skills/catalog.json

@@ -58,6 +58,10 @@
       "name": "maggie-project-context",
       "description": "Sync a site's safe AI CMO Project, selected brand voice, site settings, and CTA context into a local generated context file. Use when connecting a vibe-coded blog or existing website to AI CMO, refreshing brand context, or diagnosing missing CTA/project data."
     },
+    {
+      "name": "maggie-qa-workflow",
+      "description": "Run scenario-based browser QA with explicit evidence, fix/retest lifecycle, and release-gate decisions for web projects."
+    },
     {
       "name": "maggie-seo-geo",
       "description": "Plan, audit, create, rewrite, and measure content for AI CMO's paid SEO and GEO workflow. Use for topic opportunities, AI visibility, technical SEO, extractable article structure, sitemap-based rewrites, GSC readback, or SEO/GEO client reports."

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

@@ -27,7 +27,7 @@ locale/revision tasks are skipped; failed tasks retry from checkpoints. Run one
 worker per project. Outputs stay draft and non-indexable. Existing host HTTP
 and scheduler integrations still need separate implementation and tests.
 
-Use the stable CLI to initialize a local blog contract, ingest versioned local
+	Use the stable CLI to initialize a local blog contract, ingest versioned local
 content, validate lifecycle invariants, publish with an actor and reason, and
 generate route/feed artifacts. Read the host framework and database contract
 before adding public routes. The host project owns rendering, persistence
@@ -35,19 +35,23 @@ credentials, and deployment; this skill owns normalized blog semantics.
 
 ```bash
 maggie blog init --project . --base-path /our-blogs --confirm
-maggie blog ingest --project . --source local --input content/posts.json --confirm
-maggie blog validate --project .
-maggie blog publish --project . --slug example-post --actor owner --reason "approved" --confirm
+	maggie blog ingest --project . --source local --input content/posts.json --confirm
+	maggie blog validate --project .
+	maggie blog check-gate --project .
+	maggie blog approve --project . --slug example-post --actor reviewer --reason "reviewed" --confirm
+	maggie blog publish --project . --slug example-post --actor owner --reason "approved" --confirm
 maggie blog sitemap --project .
 maggie blog settings --project .
 maggie blog rollback --project . --confirm
 ```
 
-Posts are draft-first. Stable `contentId` is the ingest identity and a
-published slug must not change during a rewrite. Search/sort views are not
-indexable; drafts never appear in public routes, RSS, or sitemap output.
-Provider keys remain server-side. Public publication and migrations always
-require explicit confirmation.
+Posts are draft-first. `maggie blog check-gate` reports the publication policy;
+the default requires `requireReview=true`, disables auto-publish, and forces an
+explicit `approve` transition before `publish`. Stable `contentId` is the
+ingest identity and a published slug must not change during a rewrite.
+Search/sort views are not indexable; drafts never appear in public routes, RSS,
+or sitemap output. Provider keys remain server-side. Public publication and
+migrations always require explicit confirmation.
 
 To initialize native front-end pages from the approved local UI guideline,
 run `maggie-design`:

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

@@ -200,10 +200,25 @@ maggie dash sections bindings-validate --sections-file .maggie/sections.json \
   --references-file .maggie/reference-inventory.json
 maggie dash sections idempotency-validate --contract-file .maggie/reconcile-contract.json
 
-# Classify every published page exactly once:
-maggie dash inventory --pages-file .maggie/published-pages.json
+# Validate API body/response shapes before a client writes against an endpoint:
+maggie dash api-contract --spec .maggie/openapi.json
+
+# Classify every published page exactly once. `pageKind` describes the public
+# page family; `kind`/`rendererKind` describes how it is rendered. Keep these
+# axes separate and require explicit source coverage when database rows do not
+# contain code-rendered routes:
+maggie dash inventory --pages-file .maggie/published-pages.json \
+  --require-page-kinds --require-source-coverage
 ```
 
+The API contract checker fails closed when a body or 2xx response schema is
+missing. Intentional empty bodies must be explicit (`x-maggie-empty-request-body`
+or `x-maggie-empty-response`) so a consumer does not guess field names.
+Inventory reports `pageKindCounts` for service, variant, category hub,
+ordinary, and blog routes, plus `sourceCoverage`. A host adapter must include
+code-rendered routes in the input or declare coverage incomplete; a zero
+database-row count is not evidence that no public routes exist.
+
 The catalogue declares purpose, usage, placement, repeatability and layout
 limits, renderer-owned examples, and the shape of repeated entries. A repeat
 may contain an object (`title`, `body`, `href`, and so on), not just a count;

package/bundled-skills/maggie-qa-workflow/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: maggie-qa-workflow
+description: Run scenario-based browser QA with explicit evidence, fix/retest lifecycle, and release-gate decisions for web projects.
+metadata:
+  version: 1.0.0
+---
+
+# Maggie QA Workflow
+
+Use this skill when a web project needs repeatable user-scenario testing that
+connects browser evidence to a fix, a same-scenario retest, adjacent regression
+checks, and an explicit Pass/Blocked/Fail release decision. It is framework
+neutral and does not replace the project's browser-control or test tools.
+Follow the shared [memory hook](../../references/memory-hook.md) before and
+after the run; memory and feedback remain bounded by the privacy rules below.
+
+## Prepare a scenario manifest
+
+Create `.maggie/scenario-manifest.json` or pass another JSON file with a
+non-empty `scenarios` array. Each scenario needs a unique `id`; useful fields
+include `title`, `group`, `priority`, `routes`, `persona`, `auth`, `browser`,
+and `viewport`. Keep project-specific scenarios in the project; do not ship
+them in the Maggie package.
+
+## Start and record a run
+
+The CLI stores only secret-free run state under `.maggie/qa-runs/`. Screenshots
+and logs stay in the project and are represented by relative paths and hashes.
+Use a real browser adapter for visible interaction, computed layout,
+console/network evidence, final URLs, and response status:
+
+```bash
+maggie qa start --project . \
+  --scenario-file .maggie/scenario-manifest.json \
+  --run-id local-qa-001 --environment local \
+  --base-url http://localhost:4321 --browser chrome \
+  --commit "$(git rev-parse --short HEAD)"
+
+maggie qa record --project . --run local-qa-001 \
+  --scenario HOME-001 --phase test --status pass \
+  --summary "Homepage navigation and consent passed" \
+  --evidence .maggie/qa-runs/local-qa-001/home.png
+```
+
+For a failure, record expected behavior, actual behavior, and a stable error
+fingerprint. A failed scenario cannot be silently changed to Pass:
+
+```bash
+maggie qa record --project . --run local-qa-001 \
+  --scenario SEARCH-001 --phase test --status fail \
+  --summary "Search dialog did not open" \
+  --expected "Selecting a result opens its detail page" \
+  --actual "The click leaves the dialog open" \
+  --error-fingerprint search-dialog-click-stale \
+  --evidence .maggie/qa-runs/local-qa-001/search-console.txt
+
+maggie qa record --project . --run local-qa-001 \
+  --scenario SEARCH-001 --phase fix \
+  --resolution "Guarded the dialog transition after the selected result is resolved" \
+  --validation "focused browser check and project build passed"
+
+maggie qa record --project . --run local-qa-001 \
+  --scenario SEARCH-001 --phase retest --status pass \
+  --summary "Search result opens the detail page" \
+  --evidence .maggie/qa-runs/local-qa-001/search-retest.png
+```
+
+`fix` must follow a recorded failure. `retest` must follow a test and, when
+the test failed, a fix. After a fix, retest the original scenario and at least
+one adjacent scenario affected by the same surface.
+
+## Gate and release evidence
+
+The run gate is `fail` when any scenario fails, `blocked` when there is no
+failure but pending/blocked/inconclusive scenarios remain, and `pass` only
+when every scenario passes. Missing credentials, unsafe fixtures, a real
+mobile viewport, a payment sandbox, or a fault-injection environment are
+explicit blockers; never guess around them.
+
+```bash
+maggie qa summary --project . --run local-qa-001
+maggie qa summary --project . --run local-qa-001 --format markdown
+maggie qa export --project . --run local-qa-001 \
+  --output docs/qa-runs/local-qa-001.md
+```
+
+Before calling a release Pass, also run the relevant build, accessibility,
+SEO, media, API, and deployment-canary checks. A green build, HTTP 200, source
+class, or one guest smoke is not browser QA evidence.
+
+## Privacy and feedback
+
+Do not put passwords, tokens, cookies, full private URLs, personal data,
+provider response bodies, or secrets in run state, screenshots, or exported
+reports. When the same workflow defect is reusable across projects, create a
+privacy-safe draft through `maggie-feedback`; submitting it remains an explicit
+user-confirmed action. Do not promote a project-specific preference directly
+to active memory.
+
+The implementation is `tools/clis/maggie_qa_workflow.py`; it is intentionally
+small enough to run without a browser dependency and delegates browser
+interaction to the host agent/browser capability.

package/bundled-skills/maggie-seo-geo/SKILL.md

@@ -59,6 +59,11 @@ If the change date is unknown, omit `lastmod`. An empty content-type does not
 need a sitemap chunk in the sitemap index; serving an empty endpoint and
 advertising it are separate decisions.
 
+Validation also reports a freshness-distribution warning when a large sample
+collapses onto one date (especially today). Treat that as a provenance review,
+not as a reason to rewrite dates: verify the content-change event and omit
+unknown dates. Strict semantic validation promotes the warning to a failure.
+
 Generated sitemap XML uses the conventional readable shape by default: one
 `<url>`/`<sitemap>` entry per block, UTF-8 XML, and date-only `lastmod` evidence
 rendered as a full UTC W3C datetime. The plan also exposes the response
@@ -174,6 +179,15 @@ maggie seo sitemap validate --plan docs/sitemap-plan.json
 # After an approved host adapter apply, rollback uses its exact backup manifest.
 maggie seo sitemap rollback --backup-manifest .maggie-sitemap-backups/<plan>/backup-manifest.json \
   --public-dir public --confirm
+
+# Change-driven IndexNow: only pass URLs whose rendered content changed.
+maggie seo indexnow key-check --public-dir public --key-file <key>.txt --key <key>
+maggie seo indexnow plan --origin https://example.com \
+  --changed-urls-file .maggie/changed-urls.json \
+  --state-file .maggie/indexnow-state.json --key <key> \
+  --output .maggie/indexnow-plan.json
+maggie seo indexnow submit --plan .maggie/indexnow-plan.json \
+  --state-file .maggie/indexnow-state.json --confirm
 ```
 
 Only confirmed image variants may enter `srcset`; `apply` requires an explicit
@@ -182,6 +196,13 @@ omit empty chunks from the sitemap index, enforce absolute same-origin URLs, and
 record redirects for removed sitemap files. Read the [image and sitemap PRD](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/docs/image-sitemap-structure-prd.md)
 for adapter and rollback rules.
 
+IndexNow is opt-in and complements, rather than replaces, the sitemap. The
+host supplies a changed-URL set and a public verification-key file. The plan
+holds back URLs accepted within 24 hours, deduplicates same-origin URLs, and
+records accepted state only after HTTP 200/202. A 403/429/5xx or network error
+is retryable and must never make the editor save fail; do not retry unchanged
+URLs in a loop.
+
 For a deterministic technical smoke check, run:
 
 ```bash

package/bundled-tools/clis/maggie_blog.py

@@ -27,6 +27,8 @@ def main() -> int:
     inspect = sub.add_parser("inspect"); inspect.add_argument("--project", type=Path, default=Path.cwd())
     ingest = sub.add_parser("ingest"); ingest.add_argument("--project", type=Path, default=Path.cwd()); ingest.add_argument("--input", type=Path, required=True); ingest.add_argument("--source", default="local"); ingest.add_argument("--confirm", action="store_true")
     validate = sub.add_parser("validate"); validate.add_argument("--project", type=Path, default=Path.cwd())
+    gate = sub.add_parser("check-gate", help="report whether generated content requires review before publication"); gate.add_argument("--project", type=Path, default=Path.cwd())
+    approve = sub.add_parser("approve"); approve.add_argument("--project", type=Path, default=Path.cwd()); approve.add_argument("--slug", required=True); approve.add_argument("--actor", required=True); approve.add_argument("--reason", required=True); approve.add_argument("--confirm", action="store_true")
     publish = sub.add_parser("publish"); publish.add_argument("--project", type=Path, default=Path.cwd()); publish.add_argument("--slug", required=True); publish.add_argument("--actor", required=True); publish.add_argument("--reason", required=True); publish.add_argument("--confirm", action="store_true")
     sitemap = sub.add_parser("sitemap"); sitemap.add_argument("--project", type=Path, default=Path.cwd())
     settings = sub.add_parser("settings"); settings.add_argument("--project", type=Path, default=Path.cwd())
@@ -38,7 +40,7 @@ def main() -> int:
         print(json.dumps(result, indent=2, ensure_ascii=False))
         return 0 if result["status"] != "error" else 1
     store = BlogStore(args.project.resolve())
-    if args.command in {"init", "ingest", "publish", "rollback", "translate-pending"} and not args.confirm:
+    if args.command in {"init", "ingest", "publish", "approve", "rollback", "translate-pending"} and not args.confirm:
         print("CONFIRMATION_REQUIRED: rerun with --confirm", file=sys.stderr); return 2
     try:
         if args.command == "init": result = store.init(args.base_path, args.posts_per_page)
@@ -51,6 +53,8 @@ def main() -> int:
             if not isinstance(payload, list): raise ValueError("local input must be a JSON array")
             result = store.ingest(payload, args.source)
         elif args.command == "validate": result = store.validate()
+        elif args.command == "check-gate": result = store.review_gate(store.settings())
+        elif args.command == "approve": result = store.approve(args.slug, args.actor, args.reason)
         elif args.command == "publish": result = store.publish(args.slug, args.actor, args.reason)
         elif args.command == "settings": result = store.settings()
         elif args.command == "rollback": result = store.rollback(args.backup)

package/bundled-tools/clis/maggie_dash.py

@@ -25,6 +25,7 @@ from service_variants import ServiceVariantStore  # noqa: E402
 from maggie_dash_ui import load_and_validate  # noqa: E402
 from maggie_sections import catalogue, remap_translations, section_id_migration, validate_registry, copy_notes, validate_values, validate_fanout, reconcile_fields, validate_locale_coverage  # noqa: E402
 from maggie_quality import validate_variant_copy, validate_media_uniqueness, classify_inventory, validate_bindings, validate_reconcile_contract  # noqa: E402
+from maggie_api_contract import validate_api_contract  # noqa: E402
 from route_imports import classify_bindings  # noqa: E402
 
 
@@ -422,7 +423,14 @@ def command_components_audit(args: argparse.Namespace) -> int:
 def command_inventory(args: argparse.Namespace) -> int:
     """Classify each published page once, with no broad predicate overlap."""
     value = json.loads(Path(args.pages_file).resolve().read_text(encoding="utf-8"))
-    result = classify_inventory(value)
+    result = classify_inventory(value, require_page_kinds=args.require_page_kinds, require_source_coverage=args.require_source_coverage)
+    emit(result)
+    return 0 if result["passed"] else 1
+
+
+def command_api_contract(args: argparse.Namespace) -> int:
+    value = json.loads(Path(args.spec).resolve().read_text(encoding="utf-8"))
+    result = validate_api_contract(value)
     emit(result)
     return 0 if result["passed"] else 1
 
@@ -572,7 +580,12 @@ def parser() -> argparse.ArgumentParser:
     components.set_defaults(func=command_components_audit)
     inventory = sub.add_parser("inventory", help="classify published pages into disjoint band/code-rendered kinds")
     inventory.add_argument("--pages-file", required=True, help="JSON page inventory")
+    inventory.add_argument("--require-page-kinds", action="store_true", help="fail when a published page has no pageKind")
+    inventory.add_argument("--require-source-coverage", action="store_true", help="fail unless sourceCoverage.complete is true")
     inventory.set_defaults(func=command_inventory)
+    api_contract = sub.add_parser("api-contract", help="validate declared request and success-response schemas")
+    api_contract.add_argument("--spec", required=True, help="OpenAPI-like JSON document")
+    api_contract.set_defaults(func=command_api_contract)
     variant = sub.add_parser("variant", help="manage service variant lifecycle")
     variant_sub = variant.add_subparsers(dest="variant_command", required=True)
     create = variant_sub.add_parser("create"); create.add_argument("--project", default="."); create.add_argument("--service-id", required=True); create.add_argument("--variant-id", required=True); create.add_argument("--variant-type", required=True); create.add_argument("--locale", required=True); create.add_argument("--market", required=True); create.add_argument("--slug", required=True); create.add_argument("--title", required=True); create.add_argument("--facts", required=True); create.add_argument("--source-revision", required=True); create.add_argument("--canonical-variant-id"); create.add_argument("--cluster-link", action="append", default=[]); create.add_argument("--layout-family", default="service-default"); create.add_argument("--confirm", action="store_true")

package/bundled-tools/clis/maggie_indexnow.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Plan and submit change-driven IndexNow notifications."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
+from maggie_indexnow import check_key_file, plan_indexnow, submit_plan  # noqa: E402
+
+
+def read_json(path: Path, default: object) -> object:
+    if not path.exists():
+        return default
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def write_json(path: Path, value: object) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(value, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="maggie seo indexnow")
+    sub = parser.add_subparsers(dest="command", required=True)
+    key_check = sub.add_parser("key-check", help="verify the public ownership key file")
+    key_check.add_argument("--public-dir", required=True); key_check.add_argument("--key-file", required=True); key_check.add_argument("--key", required=True)
+    plan = sub.add_parser("plan", help="hold back recently accepted URLs and create a submission plan")
+    plan.add_argument("--origin", required=True); plan.add_argument("--changed-urls-file", required=True); plan.add_argument("--state-file", required=True); plan.add_argument("--key", required=True); plan.add_argument("--key-location"); plan.add_argument("--guard-hours", type=int, default=24); plan.add_argument("--now"); plan.add_argument("--output", required=True)
+    submit = sub.add_parser("submit", help="submit an approved plan; provider failure never updates accepted state")
+    submit.add_argument("--plan", required=True); submit.add_argument("--state-file", required=True); submit.add_argument("--endpoint", default="https://api.indexnow.org/indexnow"); submit.add_argument("--confirm", action="store_true")
+    args = parser.parse_args()
+    try:
+        if args.command == "key-check":
+            result = check_key_file(Path(args.public_dir).resolve(), args.key_file, args.key)
+            print(json.dumps(result, indent=2)); return 0 if result["status"] == "pass" else 1
+        if args.command == "plan":
+            changed = read_json(Path(args.changed_urls_file), [])
+            urls = changed.get("urls", []) if isinstance(changed, dict) else changed
+            if not isinstance(urls, list): raise ValueError("changed-urls-file must be a JSON array or {\"urls\": []}")
+            result = plan_indexnow(args.origin, urls, read_json(Path(args.state_file), {}), key=args.key, key_location=args.key_location, guard_hours=args.guard_hours, now=args.now)
+            write_json(Path(args.output), result)
+            print(json.dumps({"status": "planned", "eligible": len(result["eligible"]), "heldBack": len(result["heldBack"]), "rejected": len(result["rejected"]), "output": str(Path(args.output).resolve())}, indent=2)); return 0
+        if not args.confirm: raise ValueError("submit requires --confirm")
+        plan_value = read_json(Path(args.plan), {})
+        if not isinstance(plan_value, dict) or plan_value.get("schemaVersion") != "maggie-indexnow.v1": raise ValueError("invalid IndexNow plan")
+        state_path = Path(args.state_file); state = read_json(state_path, {})
+        if not isinstance(state, dict): state = {}
+        result = submit_plan(plan_value, state, args.endpoint)
+        if result["status"] == "accepted": write_json(state_path, state)
+        print(json.dumps(result, indent=2)); return 0 if result["status"] in {"accepted", "no-op"} else 1
+    except (OSError, ValueError, TypeError, json.JSONDecodeError) as error:
+        print(f"maggie-indexnow: {error}", file=sys.stderr); return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())