@topy-ai/maggie 0.7.34 → 0.7.36

package/README-zh-TW.md

@@ -8,7 +8,7 @@ Codex、Claude Code 與相容的 coding agents。
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.7.34 init --agent all
+npx @topy-ai/maggie@0.7.36 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 
@@ -25,7 +25,7 @@ maggie doctor --project . --require-bootstrap --strict
 deployment、memory、feedback 和 MaggieDash。內容先 draft/review，外部寫入、
 publish 與 production deployment 需要明確確認。
 
-目前 release 是 `0.7.34`，完成下一批已驗證 feedback：production fixture isolation、MaggieDash project-id inference、responsive/background asset extraction、穩定 SEO structure hash、decorative alt、明確 site URL/build validation、真正 404、Tailwind v4 starter、portable CLI scripts，以及不含 local dependencies/cache 的 Astro starter bundle。延後功能記錄在 issue #38，不會直接成為 active memory。0.7.33 記錄並審查一筆更正回饋；確認 0.7.32 已正確處理 batch index，沒有修改已驗證的 shared behavior。0.7.32 加入 feedback 一基索引支援、MaggieDash panel 的 source/freshness/error evidence、Consent Mode 與實際 write/no-op reconciliation、SEO baseline recapture、sitemap origin rebasing、content-diff scope、migration ledger reconciliation、deployment credential preflight、release provenance/runtime preflight、icon release gate、opt-in blog auto-publish gate，以及 least-privilege VPS deployer。也修復 top-level `maggie feedback` dispatcher parity。0.7.31 加入 update 差異摘要、atomic installer copy、subset install manifest merge，以及 inventory drift 時 doctor non-zero。0.7.30 補上 feedback tracking issue closeout gate 與 batch 14/15 audit ledger。0.7.29 修正 npm package landing page 使用英文 README；0.7.28 加入 versioned Gemini model policy、明確 fallback 與 provenance、bundled-first CLI
+目前 release 是 `0.7.36`，完成下一批已驗證 feedback：修正 doctor placeholder scope、Tailwind renderable source scope、internal link/fragment audit、unstable baseline classification、site-wide baseline reason、base64url asset hash、installed-file hash update safety，並加入 provider-routed Gemini v2、venue timezone/DST booking parsing、social-card release path、notification lifecycle contract 和 mobile hero video playback contract。provider-bound video generation 與 transactional delivery 已記錄在 issue #39；前一批延後功能仍在 issue #38，不會直接成為 active memory。0.7.33 記錄並審查一筆更正回饋；確認 0.7.32 已正確處理 batch index，沒有修改已驗證的 shared behavior。0.7.32 加入 feedback 一基索引支援、MaggieDash panel 的 source/freshness/error evidence、Consent Mode 與實際 write/no-op reconciliation、SEO baseline recapture、sitemap origin rebasing、content-diff scope、migration ledger reconciliation、deployment credential preflight、release provenance/runtime preflight、icon release gate、opt-in blog auto-publish gate，以及 least-privilege VPS deployer。也修復 top-level `maggie feedback` dispatcher parity。0.7.31 加入 update 差異摘要、atomic installer copy、subset install manifest merge，以及 inventory drift 時 doctor non-zero。0.7.30 補上 feedback tracking issue closeout gate 與 batch 14/15 audit ledger。0.7.29 修正 npm package landing page 使用英文 README；0.7.28 加入 versioned Gemini model policy、明確 fallback 與 provenance、bundled-first CLI
 dispatch、`maggie --version`、feedback batch review 聚合與重複偵測、marketplace enrichment evidence、booking
 worker/resolver evidence，以及 read-only migration preflight。它也包含 host-owned mobile app surface contract、signed-in
 camera-state QA、直接 Astro route resolution、correlated feedback batch，以及

package/README.md

@@ -60,14 +60,22 @@ Maggie keeps the existing project foundation and asks for decisions before
 shared routes, analytics, or publishing boundaries change. The current
 package ships 19 installable skills and a local-first MaggieDash foundation.
 
-The current release is `0.7.34`. It closes the next validated feedback batch:
+The current release is `0.7.36`. It closes the next validated feedback batch:
 production demo fixtures are development-only, Dash infers the persisted
 project id, clone asset extraction includes responsive/background assets, SEO
 structure hashes ignore content-hashed asset names, decorative empty alt text
 is accepted, and missing starter routes return a real 404. It also adds a
 Tailwind v4 starter entry point, explicit `PUBLIC_SITE_URL` validation, a
 portable installed-CLI script path, and a bundled Astro starter without local
-dependencies or build caches. Deferred feature requests are tracked in
+dependencies or build caches. Batch 20 also adds rendered-output placeholder
+scoping, Tailwind renderable source boundaries, same-origin link/fragment
+checks, unstable baseline classification, site-wide baseline reasons,
+base64url asset-hash normalization, installed-file update hashes, provider-
+routed Gemini v2, venue-timezone/DST booking parsing, social-card release-path
+discovery, a booking notification lifecycle contract, and mobile hero-video
+playback guidance. Provider-bound video generation and transactional delivery
+are tracked in [issue #39](https://github.com/TOPY-AI-LTD/ai-cmo-skills/issues/39).
+Deferred feature requests from the prior batch remain in
 [issue #38](https://github.com/TOPY-AI-LTD/ai-cmo-skills/issues/38), not active
 memory. The 0.7.33 release records the reviewed correction for the
 batch-index feedback workflow while keeping the verified 0.7.32 behavior
@@ -509,8 +517,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.34 update --project . --force
-npx @topy-ai/maggie@0.7.34 cleanup --project .
+npx @topy-ai/maggie@0.7.36 update --project . --force
+npx @topy-ai/maggie@0.7.36 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never

package/bin/maggie.js

@@ -3,7 +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 { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -132,9 +132,9 @@ Usage:
   maggie seo performance|images|sitemap|indexnow|social-cards|head-tags [options] (sitemap supports strict validate and agent-files)
   maggie feedback <collect|preview|batch|batch-review|submit|list> [options]
   maggie qa <start|record|summary|export|assertion-audit> [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] [--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
+  maggie site-audit URL --crawl --baseline FILE [--reason-all REASON]
   maggie browser-audit URL --browse PATH --output DIR --required SELECTOR [--sticky SELECTOR]
   maggie verification coverage --contract FILE --evidence FILE
   maggie ops audit|preflight|verify|lockfiles|seed-manifest|google-capabilities|favicon-check --project PATH
@@ -282,21 +282,25 @@ function diffSummary(source, target) {
   return `${added} local additions, ${removed} package lines removed across ${blocks} changed blocks (${localLines.length} local lines vs ${packageLines.length} package lines)`;
 }
 
-function syncTree(source, target, force) {
+function syncTree(source, target, force, root = null, managedFiles = {}) {
   let changed = 0;
   for (const entry of readdirSync(source, { withFileTypes: true })) {
     const sourcePath = join(source, entry.name);
     const targetPath = join(target, entry.name);
     if (entry.isDirectory()) {
-      changed += syncTree(sourcePath, targetPath, force);
+      changed += syncTree(sourcePath, targetPath, force, root, managedFiles);
       continue;
     }
+    const managedPath = root ? relative(root, targetPath) : targetPath;
+    const localDigest = existsSync(targetPath) ? digest(targetPath) : null;
+    const packageDigest = digest(sourcePath);
+    const wasManaged = managedFiles && managedFiles[managedPath] === localDigest;
     if (!existsSync(targetPath)) {
       mkdirSync(dirname(targetPath), { recursive: true });
       writeFileSync(targetPath, readFileSync(sourcePath));
       console.log(`installed ${targetPath}`);
       changed++;
-    } else if (force || digest(sourcePath) === digest(targetPath)) {
+    } else if (force || packageDigest === localDigest || wasManaged) {
       writeFileSync(targetPath, readFileSync(sourcePath));
       console.log(`updated ${targetPath}`);
       changed++;
@@ -307,6 +311,59 @@ function syncTree(source, target, force) {
   return changed;
 }
 
+function collectManagedFiles(source, target, root, managedFiles, previousManagedFiles = {}) {
+  if (!existsSync(source) || !existsSync(target)) return;
+  const sourceStat = readdirSync;
+  let entries;
+  try {
+    entries = sourceStat(source, { withFileTypes: true });
+  } catch {
+    const targetDigest = digest(target);
+    const relativePath = relative(root, target);
+    if (targetDigest === digest(source) || previousManagedFiles[relativePath] === targetDigest) managedFiles[relativePath] = targetDigest;
+    return;
+  }
+  for (const entry of entries) {
+    collectManagedFiles(join(source, entry.name), join(target, entry.name), root, managedFiles, previousManagedFiles);
+  }
+}
+
+function managedPairs(root, 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"));
+  }
+  for (const group of ["clis", "runtime", "integrations"]) add(join(TOOLS_ROOT, group), join(root, "tools", group));
+  add(DESIGN_ROOT, join(root, ".maggie", "design-reference"));
+  add(MARKETPLACE_ROOT, join(root, "marketplace"));
+  add(CONTRACTS_ROOT, join(root, "contracts"));
+  add(join(TEMPLATES_ROOT, "maggiedash"), join(root, "templates", "maggiedash"));
+  return pairs;
+}
+
+function managedFileDigests(root, roots, skills, previousManagedFiles = {}) {
+  const managedFiles = {};
+  for (const [source, target] of managedPairs(root, roots, skills)) collectManagedFiles(source, target, root, managedFiles, previousManagedFiles);
+  return Object.fromEntries(Object.entries(managedFiles).sort(([a], [b]) => a.localeCompare(b)));
+}
+
+function readInstallManifest(root) {
+  try {
+    const path = join(root, STATE_DIR, "install.json");
+    return existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeInstallManifest(root, data) {
+  const stateDir = join(root, STATE_DIR);
+  mkdirSync(stateDir, { recursive: true });
+  writeFileSync(join(stateDir, "install.json"), JSON.stringify(data, null, 2) + "\n");
+}
+
 function install(args) {
   const root = projectRoot(args);
   const skills = selectedSkills(args);
@@ -336,9 +393,7 @@ function install(args) {
   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"));
-  const stateDir = join(root, ".maggie");
-  mkdirSync(stateDir, { recursive: true });
-  writeFileSync(join(stateDir, "install.json"), JSON.stringify({ version: PACKAGE_VERSION, agents: roots.map((item) => item.slice(root.length + 1)), skills: mergedSkillNames(root, skills), installed_at: new Date().toISOString() }, null, 2) + "\n");
+  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.");
 }
@@ -348,6 +403,8 @@ function update(args) {
   const skills = selectedSkills(args);
   const force = args.includes("--force");
   const roots = agentRoots(args, root);
+  const previousManifest = readInstallManifest(root);
+  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;
   for (const agentRoot of roots) {
@@ -358,24 +415,22 @@ function update(args) {
         console.log(`absent ${target} (run install to add it)`);
         continue;
       }
-      updated += syncTree(source, target, force);
+      updated += syncTree(source, target, force, root, previousManagedFiles);
     }
-    if (existsSync(REFERENCES_ROOT) && existsSync(join(agentRoot, "references"))) updated += syncTree(REFERENCES_ROOT, join(agentRoot, "references"), force);
+    if (existsSync(REFERENCES_ROOT) && existsSync(join(agentRoot, "references"))) updated += syncTree(REFERENCES_ROOT, join(agentRoot, "references"), force, root, 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);
+    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);
+    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);
-  if (existsSync(CONTRACTS_ROOT) && existsSync(join(root, "contracts"))) updated += syncTree(CONTRACTS_ROOT, join(root, "contracts"), force);
-  if (existsSync(join(TEMPLATES_ROOT, "maggiedash")) && existsSync(join(root, "templates", "maggiedash"))) updated += syncTree(join(TEMPLATES_ROOT, "maggiedash"), join(root, "templates", "maggiedash"), force);
-  const stateDir = join(root, STATE_DIR);
-  mkdirSync(stateDir, { recursive: true });
-  writeFileSync(join(stateDir, "install.json"), JSON.stringify({ version: PACKAGE_VERSION, agents: roots.map((item) => item.slice(root.length + 1)), skills: mergedSkillNames(root, skills), updated_at: new Date().toISOString() }, null, 2) + "\n");
+  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`);
   if (!force) console.log("Local files with changes were preserved. Review the output and rerun with --force only when replacement is intended.");
 }

package/bundled-contracts/maggie-seo/model-policy-v2.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggie.noblox.app/contracts/maggie-seo/model-policy-v2.schema.json",
+  "title": "Maggie provider-routed Gemini model policy v2",
+  "type": "object",
+  "required": ["policyVersion", "model", "fallbackModel", "promptVersion", "schemaVersion", "locale", "sourceRevision", "providerRoute"],
+  "properties": {
+    "policyVersion": {"const": "maggie-gemini-model-policy.v2"},
+    "model": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{1,99}$"},
+    "fallbackModel": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{1,99}$"},
+    "promptVersion": {"type": "string", "minLength": 1},
+    "schemaVersion": {"type": "string", "minLength": 1},
+    "locale": {"type": ["string", "null"]},
+    "sourceRevision": {"type": ["string", "null"]},
+    "providerRoute": {
+      "type": "object",
+      "required": ["provider", "endpointEnv", "apiKeyEnv", "billingMode", "maxTokens"],
+      "properties": {
+        "provider": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{1,63}$"},
+        "endpointEnv": {"type": "string", "pattern": "^[A-Z][A-Z0-9_]{2,63}$"},
+        "apiKeyEnv": {"type": "string", "pattern": "^[A-Z][A-Z0-9_]{2,63}$"},
+        "billingMode": {"enum": ["byok", "managed"]},
+        "maxTokens": {"type": "integer", "minimum": 1, "maximum": 32768}
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/bundled-contracts/maggie-service-booking/notification-lifecycle-v1.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggie.noblox.app/contracts/maggie-service-booking/notification-lifecycle-v1.schema.json",
+  "title": "Maggie booking notification lifecycle v1",
+  "type": "object",
+  "required": ["schemaVersion", "bookingId", "state", "events"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-booking-notification-lifecycle.v1"},
+    "bookingId": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"},
+    "state": {"enum": ["received", "pending-confirmation", "confirmed", "alternative-proposed", "cancelled", "failed"]},
+    "events": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["eventId", "type", "occurredAt", "idempotencyKey", "status", "recipientRole"],
+        "properties": {
+          "eventId": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$"},
+          "type": {"enum": ["acknowledgement", "studio-notification", "confirmation", "alternative", "cancellation"]},
+          "occurredAt": {"type": "string", "format": "date-time"},
+          "idempotencyKey": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$"},
+          "status": {"enum": ["pending", "sent", "failed", "suppressed"]},
+          "recipientRole": {"enum": ["customer", "studio"]}
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

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

@@ -51,6 +51,12 @@ project-specific design, service, SEO, operations, and deployment adapters.
 9. Run build, route, SEO, accessibility, content, and deployment checks; hand
    private content operations to `maggie-ops`.
 
+After a build, run `maggie doctor PROJECT --rendered-dir dist` (or point it at
+the host's equivalent output directory). The placeholder gate prefers shipped
+HTML/assets and excludes server fixtures, API handlers, and CLI examples; this
+prevents a sample URL used in private preview code from failing public-site
+metadata validation.
+
 For an installed dashboard, create sanitized runtime observations for every
 endpoint in `maggiedash/contracts/host-adapter-v2.json` and run:
 

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

@@ -84,6 +84,21 @@ a successful `assetStatus` (2xx), and a non-empty accessible name. This
 gate is independent from typecheck/build and is read-only apart from its
 explicit output.
 
+## Hero video playback contract
+
+Hero video is an enhancement, not the only way to see the first-band message.
+For every video hero, capture desktop, tablet, and mobile evidence with the
+actual browser adapter. The contract must show a visible poster/fallback before
+`canplaythrough`, a usable play control when autoplay is unavailable, a
+reduced-motion path that does not autoplay, and a `Save-Data`/low-bandwidth
+fallback. Mobile evidence must not assume that `preload="none"` will emit
+`canplaythrough` without user interaction. Record poster visibility, playback
+state, console errors, network errors, and a screenshot per viewport.
+
+This contract is provider-neutral. It does not claim that Maggie can generate
+video assets; generated-video planning, continuation, safety review, retries,
+and cost approval remain separate product/provider work.
+
 ## Automatic memory hook
 
 Follow [Maggie Memory Hook](../../references/memory-hook.md) at invocation and completion.

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

@@ -10,7 +10,9 @@ metadata:
 ## Versioned Gemini policy
 
 AI-assisted SEO, localization, and content generation must resolve models
-through one explicit policy: `maggie-gemini-model-policy.v1`. Pin the primary
+through one explicit policy: `maggie-gemini-model-policy.v1` for legacy local
+routes or `contracts/maggie-seo/model-policy-v2.schema.json` for provider-routed
+work. Pin the primary
 model, declare a separate fallback, and record the policy version, exact
 prompt/schema versions, locale, and source revision with generated evidence.
 Only model availability failures (retired model, quota, timeout, or provider
@@ -18,6 +20,13 @@ Only model availability failures (retired model, quota, timeout, or provider
 invalid output remain errors. Do not scatter retired model defaults across
 routes.
 
+Provider-routed work must use policy v2 and declare the provider, endpoint
+environment variable, API-key environment variable, billing mode (`byok` or
+`managed`), and a finite `maxTokens` limit. A route is not considered BYOK
+merely because a key exists in the process; the selected endpoint and billing
+path must be recorded in the policy evidence. Never print key values or send a
+provider secret in a report.
+
 ## Static audit and sitemap evidence
 
 Run `maggie site-audit https://example.com --crawl --json` for sitemap-listed
@@ -129,6 +138,13 @@ maggie site-audit https://example.com --crawl --json \
   --reason 'https://example.com/pricing=approved pricing refresh'
 ```
 
+When the same approved reason applies to every drift, use `--reason-all` or
+`--reason '*=approved site-wide stylesheet rebuild'`. A URL-specific reason can
+still override the site-wide reason. If a page changes between its first and
+second fetch, the comparison reports it as `unstable` rather than silently
+calling it a content or markup change; review that page and supply a reason
+before recapture.
+
 The command fails closed when the current crawl is incomplete, a drift has no
 reason, a reason names a URL without a reported drift, or the destination file
 already exists. The new contract records its `baselineId`, `supersedes` value,
@@ -249,7 +265,9 @@ accepts JPEG, PNG, GIF, and ICO responses. It reports missing, unreachable,
 undersized, unreadable, or unsupported images and warns when one source is
 used for at least 75% of a sample of three or more pages. Page-specific
 first-band images remain an editorial choice and should be declared by the
-host manifest.
+host manifest. When `docs/social-cards-pages.json` or
+`docs/public-urls.json` exists, `maggie release` includes the social-card audit
+in its read-only release path.
 
 Head-tag auditing consumes a host-produced JSON manifest with `url`, `shell`,
 and normalized `tags`. It compares structural declarations for icons,
@@ -281,6 +299,10 @@ is intended; the report then says `"declared-origin"`.
 Use `--output <project>/docs/site-audit.json` to persist the evidence used by
 the release review.
 
+For a full crawl, add `--check-internal-links` to follow same-origin HTML links
+and check HTTP 200 targets plus `#fragment` IDs. External, mailto, and other
+non-site links are intentionally out of scope.
+
 - **Plan:** combine Project Context, GSC/search signals, competitor gaps, and
   AI visibility prompts into topic clusters and briefs.
 - **Audit:** inspect robots, sitemap, canonical URLs, metadata, JSON-LD,

package/bundled-skills/maggie-service-booking/SKILL.md

@@ -186,6 +186,25 @@ evidence artifact and validates the selected ending (`pending`, `redirect`,
 signals, and sitemap exclusion. It never stores response bodies or decides a
 redirect destination for the host.
 
+## Appointment time contract
+
+Any booking or seasonal variant that receives a timezone-naive wall-clock
+timestamp must carry an IANA `venueTimezone` such as `Europe/London`. The
+shared parser in `tools/clis/maggie_service_booking.py` applies venue DST rules
+instead of the server timezone. An ambiguous DST time must also declare
+`venueTimeFold: 0` or `1`; nonexistent local times are rejected. Prefer an
+offset-bearing timestamp when the provider already supplies one. This is a
+validation contract only: it does not claim that a provider supports booking
+creation or confirmation.
+
+When a host implements its own notification adapter, use
+[`notification-lifecycle-v1.schema.json`](../../bundled-contracts/maggie-service-booking/notification-lifecycle-v1.schema.json)
+to represent acknowledgement, studio notification, confirmation, alternative,
+and cancellation events. Every event needs an idempotency key and explicit
+status. A request must remain `pending-confirmation` until the host/provider
+actually confirms it; an email or UI receipt must never imply an appointment
+was booked. The contract is provider-neutral and does not send mail by itself.
+
 ## Asynchronous onboarding contract
 
 Provider onboarding is three independent state machines: `import` owns the

package/bundled-templates/astro-blog/starter/README.md

@@ -88,6 +88,10 @@ with `WORDPRESS_API_TOKEN` or a server-only application-password pair.
 The starter includes a Tailwind v4 Vite entry point for projects that choose
 Tailwind during bootstrap. It remains compatible with the existing contract
 surface and does not require replacing the host's design system.
+The entry point explicitly scopes Tailwind v4 scanning to renderable Astro
+pages, layouts, and components. API/lib fixtures and prose in server-only files
+are not treated as utility-class sources; keep that scope when adding a host
+component.
 
 `npm run maggie:*` uses the installed `maggie` binary. It is portable after the
 starter is copied out of this monorepo; it no longer depends on repository-

package/bundled-templates/astro-blog/starter/src/styles/global.css

@@ -1,4 +1,10 @@
 @import "tailwindcss";
 
+/* Scan renderable Astro surfaces only. Server fixtures and prose in API/lib
+   files must not become accidental utility classes in the shipped bundle. */
+@source "../pages/**/*.astro";
+@source "../layouts/**/*.astro";
+@source "../components/**/*.{astro,jsx,tsx}";
+
 /* The starter keeps its contract UI framework-neutral while providing a
    working Tailwind v4 entry point for projects that select Tailwind. */

package/bundled-tools/clis/maggie.py

@@ -23,6 +23,7 @@ STATE_FILE = "bootstrap-state.json"
 IGNORED_DIRS = {".git", ".next", "node_modules", "dist", "build", "coverage", "generated"}
 TEXT_SUFFIXES = {".css", ".html", ".js", ".jsx", ".md", ".mdx", ".svelte", ".ts", ".tsx", ".vue", ".astro", ".njk", ".liquid", ".json", ".yaml", ".yml"}
 DOCTOR_NON_SITE_DIRS = {".agents", ".claude", "__tests__", "contracts", "docs", "examples", "fixtures", "marketplace", "references", "scripts", "test", "tests", "tools"}
+DOCTOR_SERVER_DIRS = {"api", "data", "lib", "server", "services"}
 WORKFLOW_PHASES = (
     "maggiedash-foundation",
     "project-research",
@@ -81,6 +82,26 @@ def doctor_source_files(root: Path, files: list[Path]) -> list[Path]:
     return result
 
 
+def doctor_placeholder_files(root: Path, source_files: list[Path], rendered_dir: str | None = None) -> tuple[list[Path], str]:
+    """Choose rendered output first, with a narrow public-source fallback.
+
+    Server fixtures and CLI examples are not shipped page metadata and must not
+    fail a public-site placeholder check. A build output directory is the
+    strongest evidence; ``--rendered-dir`` makes that choice explicit for CI.
+    """
+    candidates = [Path(rendered_dir).expanduser().resolve()] if rendered_dir else [root / name for name in ("dist", "build", "out", "public")]
+    for candidate in candidates:
+        if not candidate.is_dir():
+            continue
+        files = sorted(path for path in candidate.rglob("*") if path.is_file() and path.suffix.lower() in TEXT_SUFFIXES)
+        return files, "rendered-output"
+    fallback = [
+        path for path in source_files
+        if not any(part.lower() in DOCTOR_SERVER_DIRS for part in path.relative_to(root).parts[:-1])
+    ]
+    return fallback, "public-site-source"
+
+
 def package_info(root: Path) -> tuple[dict, Path | None]:
     candidates = [root / "package.json"] + sorted(path for path in root.glob("*/package.json") if path.parent.name not in IGNORED_DIRS)
     parsed: list[tuple[int, dict, Path]] = []
@@ -819,6 +840,8 @@ def command_doctor(args: argparse.Namespace) -> int:
     files = list(files_for(root))
     source_files = doctor_source_files(root, files)
     text = "\n".join(read_text(path) for path in source_files)
+    placeholder_files, placeholder_scope = doctor_placeholder_files(root, source_files, getattr(args, "rendered_dir", None))
+    placeholder_text = "\n".join(read_text(path) for path in placeholder_files)
     paths = [evidence(path, root).lower() for path in source_files]
 
     checks = {
@@ -838,7 +861,7 @@ def command_doctor(args: argparse.Namespace) -> int:
         "jsonld_dates": "datePublished" in text and ("dateModified" in text or "updatedAt" in text),
         "published_only_guard": "published" in text.lower() and any(token in text.lower() for token in {"sitemap", "post"}),
         "no_public_api_key": not bool(re.search(r"(?:PUBLIC|NEXT_PUBLIC)[A-Z0-9_]*(?:API|KEY|TOKEN)", text, re.IGNORECASE)),
-        "no_placeholder_metadata": not any(token in text.lower() for token in {"your-domain.com", "example.com", "lorem ipsum", "replace-me"}),
+        "no_placeholder_metadata": not any(token in placeholder_text.lower() for token in {"your-domain.com", "example.com", "lorem ipsum", "replace-me"}),
     }
     if args.strict:
         checks.update({
@@ -886,7 +909,7 @@ def command_doctor(args: argparse.Namespace) -> int:
             safe_skips.append("robots route requires framework confirmation")
         for check, reason in (("canonical_metadata", "canonical metadata needs a site-specific URL"), ("meta_description", "metadata content needs editorial input"), ("article_jsonld", "JSON-LD shape needs content-specific fields")):
             if not checks[check]: safe_skips.append(reason)
-    result = {"project_root": str(root), "placeholder_scan": {"scope": "public-site-source", "files": len(source_files)}, "checks": {key: {"ok": value} for key, value in checks.items()}, "passed": all(checks.values())}
+    result = {"project_root": str(root), "placeholder_scan": {"scope": placeholder_scope, "files": len(placeholder_files)}, "checks": {key: {"ok": value} for key, value in checks.items()}, "passed": all(checks.values())}
     if getattr(args, "fix_safe", False): result["safe_fixes"] = {"applied": safe_fixes, "skipped_requires_confirmation": safe_skips}
     print(json.dumps(result, indent=2))
     return 0 if result["passed"] else 1
@@ -1000,6 +1023,7 @@ def parser() -> argparse.ArgumentParser:
     doctor.add_argument("--strict", action="store_true", help="also require the complete AI-native blog and Ops surface")
     doctor.add_argument("--ci", action="store_true", help="CI alias for strict checks")
     doctor.add_argument("--fix-safe", action="store_true", help="apply only low-risk route fixes; never changes schema, slugs, canonical URLs or publishing state")
+    doctor.add_argument("--rendered-dir", help="scan this build output for placeholder metadata instead of source fixtures")
     doctor.set_defaults(func=command_doctor)
     for name in ("routes", "schema", "seo", "migration", "env"):
         check = sub.add_parser(name, help=f"run Maggie {name} contract checks")

package/bundled-tools/clis/maggie_release.py

@@ -320,6 +320,29 @@ def editorial_gate(project: Path) -> dict:
     }
 
 
+def social_card_gate(project: Path) -> dict:
+    """Include the per-page social-card audit whenever a manifest is present."""
+    candidates = (
+        (project / "docs" / "social-cards-pages.json", "--pages-file"),
+        (project / ".maggie" / "social-cards-pages.json", "--pages-file"),
+        (project / "docs" / "public-urls.json", "--urls-file"),
+        (project / ".maggie" / "public-urls.json", "--urls-file"),
+    )
+    candidate = next(((path, flag) for path, flag in candidates if path.is_file()), None)
+    if candidate is None:
+        return {
+            "name": "social-card-audit",
+            "passed": True,
+            "exitCode": 0,
+            "result": {"passed": True, "state": "not-configured", "reason": "add docs/social-cards-pages.json or docs/public-urls.json to enable the release-path audit"},
+            "stderr": "",
+        }
+    path, flag = candidate
+    result = run_gate("social-card-audit", [sys.executable, str(ROOT / "maggie_social_cards.py"), "audit", flag, str(path)], project)
+    result["result"]["manifest"] = str(path.relative_to(project))
+    return result
+
+
 def runtime_smoke(base_url: str) -> dict:
     """Check basic public, admin redirect, and unknown-route behaviour."""
     base = base_url.rstrip("/") + "/"
@@ -366,6 +389,7 @@ def main() -> int:
     gates.append(changed_surface_gate(project))
     gates.append(qa_gate(project, args.environment, args.base_url))
     gates.append(build_gate(project))
+    gates.append(social_card_gate(project))
     for name, command in build_gates(project, args.environment, args.target, not args.skip_compatibility):
         gates.append(run_gate(name, command, project))
     if args.analytics_release_gate:

package/bundled-tools/clis/maggie_service_booking.py

@@ -7,6 +7,7 @@ import xml.etree.ElementTree as ET
 from datetime import datetime, timezone
 from html.parser import HTMLParser
 from pathlib import Path
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
 from urllib.parse import quote, urljoin, urlsplit, urlparse
 from urllib.request import Request, urlopen
 
@@ -20,6 +21,39 @@ DURATION = re.compile(r"(\d{2,3})\s*(?:min|mins|minutes?)", re.I)
 SUPPLY_STATES = {"live", "withdrawn"}
 DISPLAY_STATES = {"published", "hidden", "retired"}
 
+
+def parse_booking_time(value, venue_timezone=None, venue_time_fold=None):
+    """Parse an appointment time using venue wall-clock rules, not server TZ."""
+    raw = str(value or "").strip()
+    parsed = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+    if parsed.tzinfo is None:
+        if not venue_timezone:
+            raise ValueError("venueTimezone is required for a timezone-naive booking time")
+        try:
+            zone = ZoneInfo(str(venue_timezone))
+        except ZoneInfoNotFoundError as exc:
+            raise ValueError("venueTimezone is not an installed IANA timezone") from exc
+        candidates = []
+        for fold in (0, 1):
+            candidate = parsed.replace(tzinfo=zone, fold=fold)
+            round_trip = candidate.astimezone(timezone.utc).astimezone(zone).replace(tzinfo=None)
+            if round_trip == parsed:
+                candidates.append(candidate)
+        if not candidates:
+            raise ValueError("venue wall-clock time does not exist because of a DST transition")
+        if len({candidate.utcoffset() for candidate in candidates}) > 1:
+            if venue_time_fold not in (0, 1):
+                raise ValueError("venueTimeFold 0 or 1 is required for an ambiguous DST time")
+            parsed = parsed.replace(tzinfo=zone, fold=venue_time_fold)
+        else:
+            parsed = candidates[0]
+    elif venue_timezone:
+        try:
+            parsed = parsed.astimezone(ZoneInfo(str(venue_timezone)))
+        except ZoneInfoNotFoundError as exc:
+            raise ValueError("venueTimezone is not an installed IANA timezone") from exc
+    return parsed
+
 def slug(value):
     value = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
     return value or "service"
@@ -1081,8 +1115,10 @@ def cmd_variant_audit(args):
         if typ=="event" and not v.get("eventId"): errors.append(f"{prefix}: eventId is required")
         if typ=="promotion" and not v.get("promotionId"): errors.append(f"{prefix}: promotionId is required")
         if typ in {"holiday","seasonal","event","promotion"}:
-            try: start=datetime.fromisoformat(str(v.get("startsAt","")).replace("Z","+00:00")); end=datetime.fromisoformat(str(v.get("endsAt","")).replace("Z","+00:00"))
-            except ValueError: errors.append(f"{prefix}: startsAt and endsAt are required ISO timestamps"); start=end=None
+            venue_timezone = v.get("venueTimezone") or (payload.get("venueTimezone") if isinstance(payload, dict) else None)
+            fold = v.get("venueTimeFold") if "venueTimeFold" in v else (payload.get("venueTimeFold") if isinstance(payload, dict) else None)
+            try: start=parse_booking_time(v.get("startsAt"), venue_timezone, fold); end=parse_booking_time(v.get("endsAt"), venue_timezone, fold)
+            except ValueError as exc: errors.append(f"{prefix}: startsAt and endsAt require venue wall-clock timezone ({exc})"); start=end=None
             if start and end and end<=start: errors.append(f"{prefix}: endsAt must be after startsAt")
             if end and end<=as_of and v.get("indexable") is True: errors.append(f"{prefix}: expired variant cannot be indexable")
         indexable=v.get("indexable") is True; noindex=v.get("noIndex") is True

package/bundled-tools/clis/site_audit.py

@@ -26,7 +26,10 @@ def stable_structure_reference(key: str, value: str) -> str:
     path = parsed.path
     if not re.search(r"\.(?:css|js|mjs|png|jpe?g|gif|webp|avif|svg|ico|woff2?|ttf|otf)$", path, re.I):
         return value
-    path = re.sub(r"(?:[-_.])[0-9a-f]{8,64}(?=\.[^.]+$)", "-asset", path, flags=re.I)
+    # Vite/Astro and similar bundlers also emit base64url-safe digests such as
+    # ``SiteLayout.Bdp0itNn.css``. Restrict this to a digest-looking token
+    # immediately before a known asset extension.
+    path = re.sub(r"(?:[-_.])[A-Za-z0-9_-]{8,64}(?=\.[^.]+$)", "-asset", path)
     return urlunparse((parsed.scheme, parsed.netloc, path, parsed.params, "", ""))
 
 
@@ -65,9 +68,14 @@ class PageParser(HTMLParser):
         self.headings = []
         self.paragraphs = []
         self.links = []
+        self.fragment_ids = set()
 
     def handle_starttag(self, tag, attrs):
         data = dict(attrs)
+        if data.get("id"):
+            self.fragment_ids.add(data["id"])
+        if tag == "a" and data.get("name"):
+            self.fragment_ids.add(data["name"])
         if data.get("data-template"):
             self.templates.add(data["data-template"])
         if tag in {"script", "style", "noscript"}:
@@ -184,6 +192,7 @@ def audit_page(url: str, html: str, status: int, content_type: str, expected_lan
             "title": page.title, "meta": page.meta, "canonical": canonical,
             "lang": page.lang, "hreflang": page.hreflang, "robots": robots,
             "jsonld": page.jsonld_values, "images": page.images,
+            "fragmentIds": sorted(page.fragment_ids),
             "structureHash": hashlib.sha256(json.dumps(stable_structure(page.structure), sort_keys=True).encode()).hexdigest(),
             "textHash": hashlib.sha256(" ".join(page.visible_text).encode()).hexdigest(),
         },
@@ -298,6 +307,99 @@ def access_log_sitemap_check(path: Path, sitemap_path: str = "/sitemap.xml") ->
     return {"provided": True, "path": str(path), "requestCount": len(requests), "googlebotRequestCount": len(googlebot), "status": "requested" if requests else "not-requested", "diagnosis": "googlebot-request-observed" if googlebot else ("other-client-request-only" if requests else "no-matching-request")}
 
 
+def internal_link_check(base: str, pages: list[dict], fetcher=fetch) -> dict[str, object]:
+    """Validate same-origin links and fragment targets discovered during a crawl."""
+    origin = urlparse(base)
+    page_by_url = {page.get("url"): page for page in pages if page.get("url")}
+    errors: list[dict[str, str]] = []
+    checked = 0
+    seen: set[tuple[str, str]] = set()
+    for page in pages:
+        page_url = str(page.get("url") or "")
+        for link in (page.get("contentContract") or {}).get("links", []):
+            target = urljoin(page_url, str(link.get("href") or ""))
+            parsed = urlparse(target)
+            if parsed.scheme not in {"http", "https"} or (parsed.scheme, parsed.netloc.lower()) != (origin.scheme, origin.netloc.lower()):
+                continue
+            fragment = parsed.fragment
+            target_url = urlunparse((parsed.scheme, parsed.netloc, parsed.path or "/", parsed.params, parsed.query, ""))
+            key = (target_url, fragment)
+            if key in seen:
+                continue
+            seen.add(key)
+            checked += 1
+            target_page = page_by_url.get(target_url)
+            if target_page and isinstance(target_page.get("contract"), dict):
+                status = target_page.get("status")
+                content_type = target_page.get("content_type")
+                fragment_ids = set(target_page["contract"].get("fragmentIds", []))
+            else:
+                try:
+                    status, content_type, body = fetcher(target_url)
+                    parsed_target = PageParser()
+                    parsed_target.feed(body)
+                    fragment_ids = parsed_target.fragment_ids
+                except Exception as exc:
+                    errors.append({"source": page_url, "url": target_url, "reason": type(exc).__name__})
+                    continue
+            if status != 200 or content_type != "text/html":
+                errors.append({"source": page_url, "url": target_url, "reason": "target did not return HTTP 200 HTML"})
+            elif fragment and fragment not in fragment_ids:
+                errors.append({"source": page_url, "url": target, "reason": "fragment target not found"})
+    return {"ok": not errors, "linksChecked": checked, "errors": errors}
+
+
+def mark_unstable_pages(pages: list[dict]) -> None:
+    """Refetch baseline candidates once and label per-response markup drift."""
+    for page in pages:
+        if not isinstance(page.get("contract"), dict):
+            continue
+        try:
+            status, content_type, body = fetch(page["url"])
+            second = audit_page(page["url"], body, status, content_type)
+            first_contract = page["contract"]
+            second_contract = second["contract"]
+            first_content = page.get("contentContract", {})
+            second_content = second.get("contentContract", {})
+            changed = any(first_contract.get(key) != second_contract.get(key) for key in ("structureHash", "textHash")) or first_content.get("contentHash") != second_content.get("contentHash")
+            page["stability"] = {
+                "status": "unstable" if changed else "stable",
+                "changedBetweenFetches": changed,
+                "secondStructureHash": second_contract.get("structureHash"),
+                "secondTextHash": second_contract.get("textHash"),
+            }
+        except Exception as exc:
+            page["stability"] = {"status": "recapture-failed", "changedBetweenFetches": False, "error": type(exc).__name__}
+
+
+def parse_baseline_reasons(values: list[str], drift_urls: set[str], reason_all: str | None = None) -> dict[str, str]:
+    """Parse per-URL and site-wide reviewer reasons with actionable errors."""
+    reasons: dict[str, str] = {}
+    default = reason_all.strip() if reason_all and reason_all.strip() else ""
+    for value in values:
+        url, separator, reason = value.partition("=")
+        if not separator or not url.strip() or not reason.strip():
+            raise ValueError("each --reason must use URL=REASON")
+        url, reason = url.strip(), reason.strip()
+        if url == "*":
+            if default:
+                raise ValueError("duplicate site-wide baseline change reason")
+            default = reason
+            continue
+        if url in reasons:
+            raise ValueError("duplicate baseline change reason: " + url)
+        if url not in drift_urls:
+            raise ValueError("baseline change reason references a URL without a detected drift: " + url)
+        reasons[url] = reason
+    if default:
+        for url in drift_urls:
+            reasons.setdefault(url, default)
+    missing_reasons = sorted(drift_urls - reasons.keys())
+    if missing_reasons:
+        raise ValueError("every drifting URL requires a reviewer reason: " + ", ".join(missing_reasons))
+    return reasons
+
+
 def main() -> int:
     parser = argparse.ArgumentParser()
     parser.add_argument("url")
@@ -309,6 +411,7 @@ def main() -> int:
     parser.add_argument("--languages", help="comma-separated expected languages/locales, e.g. en-GB,es-MX,ja-JP")
     parser.add_argument("--markets", help="comma-separated markets: global,uk,us")
     parser.add_argument("--check-hreflang", action="store_true")
+    parser.add_argument("--check-internal-links", action="store_true", help="validate same-origin links and fragment targets during a crawl")
     parser.add_argument("--check-translation-completeness", action="store_true")
     parser.add_argument("--access-log", type=Path, help="optional local access log for crawler-request diagnosis")
     parser.add_argument("--require-sitemap-request", action="store_true", help="fail unless the supplied access log contains a sitemap request")
@@ -319,12 +422,15 @@ def main() -> int:
     parser.add_argument("--recapture-baseline", type=Path, help="write a reviewed versioned baseline after reviewing every drift")
     parser.add_argument("--baseline-id", help="required stable ID for --recapture-baseline")
     parser.add_argument("--reason", action="append", default=[], metavar="URL=REASON", help="reviewer-approved reason for one drifting URL; repeat for every drift")
+    parser.add_argument("--reason-all", help="reviewer-approved reason applied to every drifting URL during baseline recapture")
     parser.add_argument("--reviewer", help="required for --save-baseline")
     args = parser.parse_args()
     if args.max_pages < 1:
         parser.error("max-pages must be positive")
     if (args.save_baseline or args.baseline) and not args.crawl:
         parser.error("baseline operations require --crawl")
+    if args.check_internal_links and not args.crawl:
+        parser.error("internal link checks require --crawl")
     if args.save_baseline and not (args.reviewer or "").strip():
         parser.error("save-baseline requires --reviewer")
     if args.recapture_baseline:
@@ -422,6 +528,9 @@ def main() -> int:
             crawl["sitemapOriginPolicy"] = "declared-origin" if args.preserve_sitemap_origin else "requested-origin"
             crawl["passed"] = crawl["complete"] and bool(urls) and len(crawl["pages"]) == len(urls) and all(item["passed"] for item in crawl["pages"])
             crawl["url_count"] = len(urls)
+            if args.check_internal_links:
+                crawl["internal_links"] = internal_link_check(base, crawl["pages"])
+                crawl["passed"] = crawl["passed"] and crawl["internal_links"]["ok"]
         except Exception as exc:
             crawl = {"enabled": True, "passed": False, "error": type(exc).__name__, "pages": []}
 
@@ -431,6 +540,8 @@ def main() -> int:
     try:
         current_passed = result["passed"]
         if args.baseline:
+            if args.crawl:
+                mark_unstable_pages(crawl["pages"])
             previous_baseline = json.loads(args.baseline.read_text())
             result["baseline"] = site_baseline.compare(previous_baseline, result)
             result["passed"] = result["passed"] and result["baseline"]["passed"]
@@ -439,20 +550,8 @@ def main() -> int:
                 drift_urls = set(comparison.get("added", [])) | set(comparison.get("removed", []))
                 drift_urls |= {item["url"] for item in comparison.get("changed", []) if isinstance(item, dict) and item.get("url")}
                 drift_urls |= {item["url"] for item in comparison.get("contentChanged", []) if isinstance(item, dict) and item.get("url")}
-                reasons: dict[str, str] = {}
-                for value in args.reason:
-                    url, separator, reason = value.partition("=")
-                    if not separator or not url.strip() or not reason.strip():
-                        raise ValueError("each --reason must use URL=REASON")
-                    url = url.strip()
-                    if url in reasons:
-                        raise ValueError("duplicate baseline change reason")
-                    if url not in drift_urls:
-                        raise ValueError("baseline change reason references a URL without a detected drift")
-                    reasons[url] = reason.strip()
-                missing_reasons = sorted(drift_urls - reasons.keys())
-                if missing_reasons:
-                    raise ValueError("every drifting URL requires a reviewer reason")
+                drift_urls |= set(comparison.get("unstable", []))
+                reasons = parse_baseline_reasons(args.reason, drift_urls, args.reason_all)
                 if not current_passed:
                     raise ValueError("baseline recapture requires a passing current crawl")
                 recapture_report = dict(result)

package/bundled-tools/runtime/site_baseline.py

@@ -36,6 +36,8 @@ def snapshot(
     for page in pages:
         if not page.get("passed") or not isinstance(page.get("contract"), dict):
             raise ValueError("baseline requires successful page contracts")
+        if (page.get("stability") or {}).get("status") == "unstable":
+            raise ValueError("baseline requires stable page contracts")
         if page["url"] in contracts:
             raise ValueError("duplicate page URL")
         if urlparse(page["url"]).query:
@@ -75,11 +77,16 @@ def compare(baseline: dict, report: dict) -> dict:
     expected = baseline["pages"]
     added, removed = sorted(current.keys() - expected.keys()), sorted(expected.keys() - current.keys())
     changes = []
+    unstable = []
     for url in sorted(expected.keys() & current.keys()):
         actual = current[url]
         if not isinstance(actual, dict):
             errors.append("missing page contract: " + url)
             continue
+        page = next((item for item in crawl_pages if item.get("url") == url), {})
+        if (page.get("stability") or {}).get("status") == "unstable":
+            unstable.append(url)
+            continue
         fields = sorted(key for key in expected[url].keys() | actual.keys() if expected[url].get(key) != actual.get(key))
         if fields:
             changes.append({"url": url, "fields": fields})
@@ -88,6 +95,8 @@ def compare(baseline: dict, report: dict) -> dict:
     content_not_compared = []
     if expected_content:
         for url in sorted(expected_content.keys() & current_content.keys()):
+            if url in unstable:
+                continue
             expected_contract = expected_content[url]
             current_contract = current_content[url]
             ignored_legacy_fields = {"images", "imageAlts"} if "images" not in expected_contract else set()
@@ -99,9 +108,10 @@ def compare(baseline: dict, report: dict) -> dict:
         missing_content = sorted(expected_content.keys() - current_content.keys())
         if missing_content:
             errors.append("missing content contract: " + ", ".join(missing_content))
-    return {"passed": not errors and not added and not removed and not changes and not content_changes,
+    return {"passed": not errors and not added and not removed and not changes and not content_changes and not unstable,
             "errors": errors, "added": added, "removed": removed, "changed": changes,
             "contentChanged": content_changes,
+            "unstable": unstable,
             "contentNotCompared": content_not_compared,
             "excludedQueryUrls": query_urls}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.7.34",
+  "version": "0.7.36",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",