@topy-ai/maggie 0.7.26 → 0.7.28

package/README.md

@@ -60,8 +60,17 @@ 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.26`. It corrects the top-level feedback help and
-includes the host-owned mobile app surface
+The current release is `0.7.28`. It adds a versioned Gemini model policy with
+an explicit fallback and provenance, bundled-CLI version discovery, and a
+bundled-first dispatcher that avoids stale project wrappers. It also adds
+privacy-safe feedback batch review/duplicate detection, marketplace
+enrichment evidence, bounded booking worker/resolver reports, and read-only
+migration preflight contracts. The release retains the provider-neutral MaggieDash host
+adapter contract, idempotent PostgreSQL starter schema, type-only backend
+boundary, runtime endpoint conformance evidence, safe quota/error summaries,
+stale marketplace readiness revalidation, explicit VPS port/origin planning,
+first-release rollback evidence, and clean non-interactive bootstrap errors.
+It retains the host-owned mobile app surface
 contract (`maggie design app-init`/`app-validate`), direct Astro route
 resolution, correlated feedback batches, and runtime package-version capture.
 
@@ -104,6 +113,9 @@ maggie dash api-contract --spec .maggie/openapi.json
 maggie dash api-contract --spec https://example.test/openapi.json
 maggie dash schema-audit --inventory .maggie/schema-inventory.json --fail-on-unread
 maggie dash ui runtime-validate --evidence .maggie/dashboard-runtime.json
+maggie dash conformance --contract .maggie/host-adapter-v2.json \
+  --evidence .maggie/maggiedash-conformance.json \
+  --output docs/maggiedash-conformance.json
 maggie docs audit --project . --docs-dir docs --output docs/documentation-audit.json
 ```
 
@@ -199,6 +211,7 @@ redacted and explicit; it is never promoted to active memory automatically.
 The CLI provides the installer plus durable workflow commands:
 
 ```text
+maggie --version | version
 maggie init | install | update | remove | list | doctor
 maggie cleanup --project . [--confirm]
 maggie bootstrap interview | phase ...
@@ -219,6 +232,7 @@ 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, batch, submit, list
+maggie feedback batch-review ... # aggregate bounded drafts and detect duplicates
 maggie qa ...                    # scenario browser QA, fix/retest, release gate
 maggie localization ...          # plan, validate, review, publish, stale
 maggie service ...                # import, sync/report, catalogue, lifecycle, validate
@@ -233,9 +247,13 @@ maggie deployment | migration | release | analytics | schedule
 maggie deployment readiness --project PATH
 maggie deployment parity --project PATH --evidence FILE --output FILE
 maggie migration identity --identity-file FILE [--expected-file FILE]
+maggie migration preflight --evidence FILE [--output FILE]
 maggie deployment canary --asset URL=SHA256 --render-report report.json
 maggie design icon-inventory --source-dir src --runtime assets/icons.css
 maggie api lifecycle | site-audit | ops audit
+maggie marketplace enrichment-report --project PATH --input FILE [--output FILE]
+maggie service worker-health --project PATH --evidence FILE [--output FILE]
+maggie service resolver-audit --project PATH --evidence FILE [--output FILE]
 ```
 
 Agent content writes must declare the exact host origin that minted the
@@ -398,8 +416,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.26 update --project . --force
-npx @topy-ai/maggie@0.7.26 cleanup --project .
+npx @topy-ai/maggie@0.7.28 update --project . --force
+npx @topy-ai/maggie@0.7.28 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -570,6 +588,34 @@ maggie feedback batch --project . --batch-file ./feedback-batch.json
 
 The batch command never submits automatically or writes active memory.
 
+Aggregate a correlated batch before reviewing individual drafts:
+
+```bash
+maggie feedback batch-review --project . --batch-id run-review-001
+```
+
+The `maggie-feedback-batch-review.v1` report retains bounded observations,
+missing-index and duplicate checks, and privacy flags. It never contains raw
+responses, local paths, or secrets.
+
+The same evidence-first pattern is available for the other maintainer checks:
+
+```bash
+maggie marketplace enrichment-report --project . \
+  --input .maggie/marketplace/enrichment-input.json
+maggie service worker-health --project . \
+  --evidence .maggie/booking/worker-health-input.json
+maggie service resolver-audit --project . \
+  --evidence .maggie/booking/resolver-input.json
+maggie migration preflight \
+  --evidence .maggie/migration/preflight-input.json
+```
+
+Each command validates a versioned, bounded evidence contract and writes only
+sanitized status data. The deployment parity report also records the active
+release revision, runtime configuration hash, migration version, worker
+revision, asset fingerprints, and rollback target.
+
 Submission is never implicit. Project paths, source files, logs, and secrets
 are excluded by default. The hosted endpoint stores the normalized feedback in
 NoBlox for maintainer review; it does not automatically create a GitHub Issue.

package/README.zh-TW.md

@@ -8,7 +8,7 @@ Codex、Claude Code 與相容的 coding agents。
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.7.26 init --agent all
+npx @topy-ai/maggie@0.7.28 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 
@@ -25,7 +25,9 @@ maggie doctor --project . --require-bootstrap --strict
 deployment、memory、feedback 和 MaggieDash。內容先 draft/review，外部寫入、
 publish 與 production deployment 需要明確確認。
 
-目前 release 是 `0.7.26`，修正 top-level feedback help 並包含 host-owned mobile app surface contract、signed-in
+目前 release 是 `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，以及
 runtime package version capture。
 

package/bin/maggie.js

@@ -51,6 +51,7 @@ function usage() {
   console.log(`Maggie Skills installer
 
 Usage:
+  maggie --version | version
   maggie init [--project PATH] [--agent auto|codex|claude|all] [--skills LIST]
   maggie install [SKILL ...] [--project PATH] [--agent auto|codex|claude|all]
   maggie update [SKILL ...] [--project PATH] [--agent auto|codex|claude|all] [--force]
@@ -117,6 +118,7 @@ Usage:
   maggie deployment readiness --project PATH
   maggie deployment parity --project PATH --evidence FILE --output FILE
   maggie deployment canary --project PATH --asset URL=SHA256 --render-report report.json --output docs/deployment-canary.json
+  maggie migration preflight --evidence FILE --output FILE
   maggie migration --project PATH --environment staging
   maggie migration identity --identity-file FILE [--expected-file FILE]
   maggie schedule PATH/.maggie/schedule.json --project PATH
@@ -126,7 +128,7 @@ Usage:
   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|indexnow|social-cards|head-tags [options] (sitemap supports strict validate and agent-files)
-  maggie feedback <collect|preview|batch|submit|list> [options]
+  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 --save-baseline FILE --reviewer NAME
@@ -294,7 +296,7 @@ function list() {
 
 function marketplace(args) {
   const root = projectRoot(args);
-  const script = join(root, "tools", "clis", "maggie_marketplace.py");
+  const script = toolScript("maggie_marketplace.py", root);
   if (!existsSync(script)) throw new Error(`marketplace CLI is missing: ${script}`);
   const command = args[0] || "list";
   const forwarded = args.slice(1);
@@ -306,7 +308,7 @@ function marketplace(args) {
 function service(args) {
   const root = projectRoot(args);
   const scriptName = args[0] === "orchestration-validate" ? "maggie_service_onboarding.py" : "maggie_service_booking.py";
-  const script = join(root, "tools", "clis", scriptName);
+  const script = toolScript(scriptName, root);
   if (!existsSync(script)) throw new Error(`service booking CLI is missing: ${script}`);
   const result = spawnSync("python3", [script, ...args], { stdio: "inherit", cwd: root, env: { ...process.env, MAGGIE_VERSION: PACKAGE_VERSION } });
   if (result.error) throw result.error;
@@ -327,7 +329,7 @@ function seo(args) {
 
 function workflowCli(name, args) {
   const root = projectRoot(args);
-  const script = join(root, "tools", "clis", name);
+  const script = toolScript(name, root);
   if (!existsSync(script)) throw new Error(`${name} is missing: ${script}`);
   const env = name === "maggie_feedback.py" ? { ...process.env, MAGGIE_VERSION: PACKAGE_VERSION } : process.env;
   const result = spawnSync("python3", [script, ...args], { stdio: "inherit", cwd: root, env });
@@ -335,6 +337,15 @@ function workflowCli(name, args) {
   process.exitCode = result.status ?? 1;
 }
 
+function toolScript(name, root) {
+  const bundled = join(TOOLS_ROOT, "clis", name);
+  return existsSync(bundled) ? bundled : join(root, "tools", "clis", name);
+}
+
+function version() {
+  console.log(PACKAGE_VERSION);
+}
+
 function doctor(args) {
   const root = projectRoot(args);
   const checks = [
@@ -404,7 +415,8 @@ function cleanup(args) {
 
 const [command = "help", ...args] = process.argv.slice(2);
 try {
-  if (["help", "--help", "-h"].includes(command)) usage();
+  if (["--version", "-v", "version"].includes(command)) version();
+  else if (["help", "--help", "-h"].includes(command)) usage();
   else if (command === "list") list();
   else if (command === "marketplace") marketplace(args);
   else if (command === "clone") workflowCli("maggie_clone.py", args);

package/bundled-contracts/maggie-deployment/runtime-parity-v1.schema.json

@@ -3,17 +3,35 @@
   "$id": "https://maggie.noblox.app/contracts/deployment-runtime-parity-v1.json",
   "title": "Maggie deployment worker and browser runtime parity evidence",
   "type": "object",
-  "required": ["schemaVersion", "environment", "passed", "worker", "browser"],
+  "required": ["schemaVersion", "environment", "passed", "release", "worker", "browser"],
   "properties": {
     "schemaVersion": {"const": "maggie-deployment-runtime-parity.v1"},
     "environment": {"enum": ["development", "staging", "production"]},
     "passed": {"const": true},
+    "release": {
+      "type": "object",
+      "required": ["activeRevision", "expectedRevision", "rollbackRevision", "environment", "runtimeConfigHash", "expectedConfigHash", "migrationVersion", "expectedMigrationVersion", "workerRevision", "assetVersions"],
+      "properties": {
+        "activeRevision": {"type": "string", "minLength": 1},
+        "expectedRevision": {"type": "string", "minLength": 1},
+        "rollbackRevision": {"type": "string", "minLength": 1},
+        "environment": {"enum": ["development", "staging", "production"]},
+        "runtimeConfigHash": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
+        "expectedConfigHash": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
+        "migrationVersion": {"type": "string", "minLength": 1},
+        "expectedMigrationVersion": {"type": "string", "minLength": 1},
+        "workerRevision": {"type": "string", "minLength": 1},
+        "assetVersions": {"type": "array", "minItems": 1, "items": {"type": "object", "required": ["name", "sha256"], "properties": {"name": {"type": "string"}, "sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"}}, "additionalProperties": false}}
+      },
+      "additionalProperties": true
+    },
     "worker": {
       "type": "object",
       "required": ["config", "migration", "routeApis", "residentProcesses", "sourceJobs"],
       "properties": {
         "config": {"$ref": "#/$defs/config"},
         "migration": {"type": "object", "required": ["privilegeCheck"], "properties": {"privilegeCheck": {"$ref": "#/$defs/passed"}}},
+        "revision": {"type": "string", "minLength": 1},
         "routeApis": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/route"}},
         "residentProcesses": {"$ref": "#/$defs/processes"},
         "sourceJobs": {"type": "array", "items": {"$ref": "#/$defs/job"}}
@@ -30,7 +48,7 @@
   "$defs": {
     "passed": {"type": "object", "required": ["passed"], "properties": {"passed": {"const": true}}, "additionalProperties": true},
     "config": {"type": "object", "required": ["required", "missing", "passed"], "properties": {"required": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}, "missing": {"type": "array", "maxItems": 0}, "passed": {"const": true}}, "additionalProperties": true},
-    "route": {"type": "object", "required": ["method", "path", "status", "passed"], "properties": {"method": {"type": "string"}, "path": {"type": "string", "pattern": "^/"}, "status": {"type": "integer", "minimum": 200, "maximum": 399}, "passed": {"const": true}}, "additionalProperties": true},
+    "route": {"type": "object", "required": ["method", "path", "status", "passed", "releaseRevision"], "properties": {"method": {"type": "string"}, "path": {"type": "string", "pattern": "^/"}, "status": {"type": "integer", "minimum": 200, "maximum": 399}, "passed": {"const": true}, "releaseRevision": {"type": "string", "minLength": 1}}, "additionalProperties": true},
     "processes": {"type": "object", "required": ["checked", "unexpected", "stale", "passed"], "properties": {"checked": {"const": true}, "unexpected": {"type": "array", "maxItems": 0}, "stale": {"type": "array", "maxItems": 0}, "passed": {"const": true}}, "additionalProperties": true},
     "job": {"type": "object", "required": ["jobId", "passed"], "properties": {"jobId": {"type": "string", "minLength": 1}, "passed": {"const": true}}, "additionalProperties": true}
   },

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

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggie.noblox.app/contracts/maggie-seo/model-policy-v1.schema.json",
+  "title": "Maggie Gemini model policy v1",
+  "type": "object",
+  "required": ["policyVersion", "model", "fallbackModel", "promptVersion", "schemaVersion", "locale", "sourceRevision"],
+  "properties": {
+    "policyVersion": {"const": "maggie-gemini-model-policy.v1"},
+    "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"]}
+  },
+  "additionalProperties": false
+}

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

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggie.noblox.app/contracts/resolver-v1.schema.json",
+  "title": "Maggie booking URL resolver outcomes v1",
+  "type": "object",
+  "required": ["schemaVersion", "status", "passed", "errors", "counts", "observations", "privacy"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-booking-resolver.v1"},
+    "status": {"enum": ["passed", "failed"]},
+    "passed": {"type": "boolean"},
+    "errors": {"type": "array", "items": {"type": "string"}},
+    "counts": {"type": "object", "additionalProperties": {"type": "integer", "minimum": 0}},
+    "observations": {"type": "array", "maxItems": 200, "items": {"type": "object"}},
+    "privacy": {"type": "object", "required": ["rawResponsesIncluded", "credentialsIncluded"]}
+  },
+  "additionalProperties": false
+}

package/bundled-contracts/maggie-service-booking/worker-health-v1.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggie.noblox.app/contracts/worker-health-v1.schema.json",
+  "title": "Maggie service booking worker health v1",
+  "type": "object",
+  "required": ["schemaVersion", "environment", "workerId", "status", "passed", "errors", "checks"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-booking-worker-health.v1"},
+    "environment": {"enum": ["development", "staging", "production"]},
+    "workerId": {"type": "string", "minLength": 1},
+    "status": {"enum": ["passed", "failed"]},
+    "passed": {"type": "boolean"},
+    "errors": {"type": "array", "items": {"type": "string"}},
+    "checks": {"type": "object", "additionalProperties": {"type": "boolean"}}
+  },
+  "additionalProperties": false
+}

package/bundled-contracts/maggiedash/README.md

@@ -50,6 +50,11 @@ import.
   items with stable ordering, nesting, and safe destinations;
 - [`dashboard-runtime-v1.json`](dashboard-runtime-v1.json) defines evidence
   that an admin screen mounted, ran its checks, and completed its data calls.
+- MaggieDash 0.2.6 also ships a screen-level host adapter contract and
+  provider-neutral install starters in the first-party distribution. The
+  `host-adapter-v2` contract lists endpoint methods, public routes, response
+  content types, and required fields; `maggie dash conformance` validates
+  sanitized runtime observations against it.
 
 These are adapter-facing interfaces, not database schemas. A host may use
 PostgreSQL, SQLite, or another first-party store. Activity recording happens

package/bundled-contracts/maggiedash/migration-preflight-v1.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggiedash.noblox.app/contracts/migration-preflight-v1.schema.json",
+  "title": "MaggieDash Migration Preflight v1",
+  "type": "object",
+  "required": ["schemaVersion", "environment", "status", "passed", "errors", "checks", "mutation"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-migration-preflight.v1"},
+    "environment": {"enum": ["development", "staging", "production"]},
+    "status": {"enum": ["passed", "failed"]}, "passed": {"type": "boolean"},
+    "errors": {"type": "array", "items": {"type": "string"}},
+    "checks": {"type": "object", "additionalProperties": {"type": "boolean"}},
+    "mutation": {"const": "not executed"}
+  },
+  "additionalProperties": false
+}

package/bundled-references/blog-translation-ingestion.md

@@ -25,6 +25,13 @@ return partial/nonzero and store only an error category. Use one worker per
 project. Host database/API schedulers must explicitly integrate this boundary;
 installing the skill does not patch an existing host ingestion implementation.
 
+When a host imports JavaScript helpers from strict TypeScript, ship an adjacent
+`.d.mts` declaration for every `.mjs` module that is part of the public
+translation/ingest boundary. Keep the declaration's nullable/error outcome
+types aligned with the runtime and include it in the typecheck fixture. This
+prevents a successful runtime helper from becoming an implicit `any` or a
+nullability mismatch in the scheduled path.
+
 ## Durable work
 
 After source persistence, enqueue translation work using an idempotency key

package/bundled-references/maggiedash-integration.md

@@ -5,6 +5,14 @@ approvals, jobs, audit, API, and MCP boundaries. External systems are adapters;
 they never become the local source of truth without an explicit migration and
 rollback decision.
 
+The first-party distribution installs the React admin under `./_maggie/admin`
+and portable host starters under `maggiedash/`: an idempotent PostgreSQL
+schema, type-only adapter boundary, and the screen-level
+`maggiedash-host-adapter.v2` contract. The schema is a starting migration for
+the host's normal migration system; it must not drop legacy tables or receive
+unbound project IDs. The type file is intentionally not a fake database
+implementation.
+
 ## Foundation
 
 Initialize and migrate the local project contract before content or provider
@@ -35,6 +43,17 @@ in environment variables and are never copied into reports.
   explicitly declares that mirror required.
 - API Pull, booking, analytics, email, and deployment providers expose health,
   normalized errors, and explicit configuration schemas.
+- Dashboard hosts must expose the exact method, route, response content type,
+  and required fields declared by `host-adapter-v2`. Create sanitized runtime
+  observations and validate them with `maggie dash conformance`; a static
+  component scan is not evidence that a screen works. Astro hosts that exclude
+  underscore filesystem segments must rewrite `/_maggie/section-preview` once
+  to the internal preview route without disabling origin checks.
+
+For API Pull, retain only bounded provider messages and effective quota values
+in lifecycle state. A quota-exhausted response means daily delivery remaining
+is zero even if an older allowance field says otherwise; raw provider bodies
+never enter `.maggie` reports.
 
 ## Ordered workflow
 

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

@@ -22,6 +22,11 @@ project-specific design, service, SEO, operations, and deployment adapters.
 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`.
+   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
+   the admin UI. Apply the schema through the host migration system, never by
+   dropping legacy tables.
 4. Advance the ordered foundation gate:
 
    ```bash
@@ -46,6 +51,19 @@ 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`.
 
+For an installed dashboard, create sanitized runtime observations for every
+endpoint in `maggiedash/contracts/host-adapter-v2.json` and run:
+
+```bash
+maggie dash conformance --project PROJECT \
+  --contract maggiedash/contracts/host-adapter-v2.json \
+  --evidence .maggie/maggiedash-conformance.json \
+  --output docs/maggiedash-conformance.json
+```
+
+The report checks method, public route, 2xx status, content type, and required
+response fields. It does not accept a static source scan as runtime evidence.
+
 ## Decisions and safety
 
 - Preserve detected framework, language, router, UI system, icon set, fonts,
@@ -58,6 +76,9 @@ project-specific design, service, SEO, operations, and deployment adapters.
   stop for manual conflict review; malformed content is never published.
 - Do not build a second CMS or editor beside MaggieDash. Use the shared
   ContentDocument contract and project-scoped roles.
+- If stdin is not interactive, bootstrap must receive
+  `--non-interactive --answers-file FILE --confirm`; it exits with a concise
+  remediation message instead of emitting an EOF traceback.
 
 ## Completion gate
 

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

@@ -5,6 +5,18 @@ description: Manage the MaggieDash project foundation, local content store, and
 
 # MaggieDash
 
+Run the read-only migration preflight before any schema write:
+
+```bash
+maggie migration preflight \
+  --evidence .maggie/migration/preflight-input.json \
+  --output .maggie/migration/preflight.json
+```
+
+It checks database privileges, required columns, unique constraints used by
+`ON CONFLICT`, idempotency, and version advancement. Evidence is secret-free
+and the command never executes a migration; a failed report blocks the write.
+
 Use the provider-neutral MaggieDash contracts and CLI for project setup,
 installation of the first-party admin workspace, and content operations.
 
@@ -46,6 +58,28 @@ owns the framework route, email/password session middleware, database, media
 storage, provider credentials, and `/api/maggie/*` adapter endpoints. Read the
 MaggieDash host adapter contract before adding a new framework adapter.
 
+The install also places a provider-neutral backend type boundary, an
+idempotent PostgreSQL starter schema, and the screen-level host adapter
+contract under `maggiedash/`. These are reviewable starting points, not a
+portable database implementation. Apply the schema through the host's normal
+migration system, keep project IDs bound as query parameters, and implement
+the declared endpoint fields before enabling a dashboard screen. The
+underscore-prefixed public preview route must be rewritten once by the host
+framework when that framework excludes underscore filesystem segments.
+
+Validate the live adapter with sanitized browser/runtime observations:
+
+```bash
+maggie dash conformance --project . \
+  --contract maggiedash/contracts/host-adapter-v2.json \
+  --evidence .maggie/maggiedash-conformance.json \
+  --output docs/maggiedash-conformance.json
+```
+
+This is a runtime contract gate, not a source-only check; it fails when a
+declared endpoint is missing, uses the wrong route/method, returns a non-2xx
+status or omits required fields.
+
 MaggieDash 0.2.4 adds two reusable operator workspaces. Activity is a read-only
 view backed by `/api/maggie/activity.json`; it supports actor/action filters,
 refresh, and a safe unavailable state. Navigation is an ordered,

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

@@ -52,10 +52,14 @@ maggie deployment parity --project . \
 The `maggie-deployment-runtime-parity.v1` contract checks required worker
 configuration and missing bindings, migration privileges, route API status,
 stale/unexpected resident import processes, non-empty source-job IDs, and
-browser/driver compatibility. It is provider-neutral: the host adapter runs
-the environment checks and supplies only safe facts; Maggie validates the
-evidence and never receives credentials, cookies, or response bodies. A failed
-parity report blocks the readiness command and therefore the canary.
+browser/driver compatibility. It also requires the active release revision to
+match the expected revision, an equal runtime configuration hash, the expected
+migration and worker revisions, non-empty asset fingerprints, route release
+revisions, and a valid rollback target. It is provider-neutral: the host
+adapter runs the environment checks and supplies only safe facts; Maggie
+validates the evidence and never receives credentials, cookies, or response
+bodies. A failed parity report blocks the readiness command and therefore the
+canary.
 
 ## Release readiness evidence
 
@@ -123,10 +127,18 @@ Generate a reviewable VPS plan and configuration artifacts locally:
 python3 tools/clis/maggie_deployment.py /path/to/project \
   --vps-plan --domain example.co.uk --service example \
   --release-root /var/www/example \
+  --node-port 4321 \
   --plan-dir .maggie/deployment/vps-staging \
   --runner-output .maggie/deployment/vps-staging/release-runner.sh
 ```
 
+`--node-port` is intentionally explicit and must be an unused host port; the
+planner never guesses a default because a guessed port can collide with an
+existing service. The generated plan also records the TLS-proxy boundary:
+keep Astro `security.checkOrigin` enabled, configure the canonical HTTPS
+`allowedDomains`, and forward the public host/protocol only from a trusted
+reverse proxy.
+
 The output contains only the immutable release/current layout, systemd unit,
 Nginx reverse-proxy config, health commands, rollback command, and an ordered
 reviewable release runner. The runner keeps migrations before the symlink flip,
@@ -237,9 +249,12 @@ Review the generated runner before execution. Its order is install → typecheck
 retention keeps the current release and one rollback candidate.
 
 Production additionally requires `docs/deployment-rollback-smoke.json` with
-`passed: true`, `environment: production`, a non-empty `previousRelease`, and
-`testedAt`. A rollback command in a plan is not proof that the rollback was
-tested. Staging does not require this production-only evidence.
+`passed: true`, `environment: production`, and `testedAt`. For an upgrade it
+must include a non-empty `previousRelease`. For the first production release,
+set `releaseKind: "first"` and record a non-empty `notApplicableReason`; the
+runner also requires `RELEASE_KIND=first`. A rollback command in a plan is not
+proof that the rollback was tested. Staging does not require this
+production-only evidence.
 
 ## Required workflow
 

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

@@ -76,9 +76,16 @@ Create a local, secret-free plan before remote execution:
 python3 tools/clis/maggie_deployment.py . --vps-plan \
   --domain example.co.uk --service example \
   --release-root /var/www/example \
+  --node-port 4321 \
   --plan-dir .maggie/deployment/vps-staging
 ```
 
+Always choose and pass an unused `--node-port`; no default is assumed because
+the planner cannot safely know which ports are occupied on the target host.
+The generated Nginx/Astro boundary keeps `checkOrigin` enabled and requires
+canonical HTTPS `allowedDomains` plus trusted `X-Forwarded-Host`/
+`X-Forwarded-Proto` handling when TLS terminates at the proxy.
+
 Review the generated systemd and Nginx files, then obtain explicit approval
 before installing them on a host.
 
@@ -106,5 +113,8 @@ canonical URLs, booking links, and protected Ops/API routes. Check both apex
 and `www` when configured. Record HTTP status, commit, and release.
 
 Rollback switches `current` to the previous immutable release and restarts the
-service. If migrations are not backward-compatible, stop before deployment
-and provide a tested restore or database rollback plan.
+service. If migrations are not backward-compatible, stop before deployment and
+provide a tested restore or database rollback plan. The first production
+release may declare rollback as not applicable only with `releaseKind: "first"`,
+a non-empty `notApplicableReason`, and `RELEASE_KIND=first`; upgrades still
+need tested `previousRelease` evidence.

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

@@ -55,9 +55,19 @@ The batch file contains 1–50 items and may provide shared `skill`, `runId`,
 `phase`, `priority`, and `affectedCli` values. An item can override those
 fields and supplies the normal `type`, `summary`, `expected`, `actual`,
 `errorFingerprint`, reproduction, resolution, validation, and screenshot
-metadata fields. Each generated draft stores only the safe batch ID, zero-based
-index, and bounded size. The batch command still creates local drafts only;
-review each draft and submit explicitly.
+metadata fields. It may also provide bounded `routeIds` and
+`validationEvidence` identifiers. Each generated draft stores only the safe
+batch ID, zero-based index, and bounded size. The batch command still creates
+local drafts only.
+
+Aggregate a batch before manual review:
+
+    maggie feedback batch-review --project . --batch-id run-review-001
+
+This writes `.maggie/feedback/batches/<batch-id>-review.json` under the
+`maggie-feedback-batch-review.v1` contract. It reports missing indexes and
+duplicate fingerprints/summaries, while retaining only redacted observations;
+review the aggregate and each draft before submitting.
 
 Example:
 

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

@@ -7,6 +7,22 @@ metadata:
 
 # Maggie Marketplace
 
+## Enrichment evidence
+
+Candidate discovery must preserve enough structured evidence to debug a
+missing Google candidate, crawl, audit, snapshot, or SEO backfill without
+storing provider HTML or credentials:
+
+```bash
+maggie marketplace enrichment-report --project . \
+  --input .maggie/marketplace/enrichment-input.json
+```
+
+The output follows `maggie-marketplace-enrichment.v1`, records safe status and
+error codes for each stage, and makes retry eligibility explicit. Null/error
+reasons remain visible for a maintainer; raw response bodies, local paths, and
+secrets are excluded.
+
 ## Automatic memory hook
 
 Follow [Maggie Memory Hook](../../references/memory-hook.md) at invocation and completion.
@@ -74,7 +90,10 @@ python3 tools/clis/maggie_marketplace.py resume <template-id>
 
 If generated assets are missing, the job stops at `WAITING_FOR_ASSETS`; cloned
 images are never accepted as generated-asset fallbacks. Only a job at `READY`
-is complete.
+is complete. A previously `READY` job is revalidated against the current
+validator before it is reported complete. If the validator has changed or the
+artifact drifted, the job becomes `STALE` and must be resumed or rebuilt; do
+not treat an old readiness flag as proof of current validity.
 
 Each import also creates `tasks.json`. It is the workflow ledger: it stores
 source/output inventories for logos, icons, images, headings, links, buttons,

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

@@ -7,6 +7,17 @@ metadata:
 
 # Maggie SEO and GEO
 
+## 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
+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
+5xx) may roll forward to the declared fallback; authentication failures and
+invalid output remain errors. Do not scatter retired model defaults across
+routes.
+
 ## Static audit and sitemap evidence
 
 Run `maggie site-audit https://example.com --crawl --json` for sitemap-listed