@topy-ai/maggie 0.7.25 → 0.7.27

package/README.md

@@ -60,7 +60,12 @@ 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.25`. It adds a host-owned mobile app surface
+The current release is `0.7.27`. It adds a 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.
 
@@ -103,6 +108,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
 ```
 
@@ -397,8 +405,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.25 update --project . --force
-npx @topy-ai/maggie@0.7.25 cleanup --project .
+npx @topy-ai/maggie@0.7.27 update --project . --force
+npx @topy-ai/maggie@0.7.27 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never

package/README.zh-TW.md

@@ -8,7 +8,7 @@ Codex、Claude Code 與相容的 coding agents。
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.7.25 init --agent all
+npx @topy-ai/maggie@0.7.26 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.25`，加入 host-owned mobile app surface contract、signed-in
+目前 release 是 `0.7.26`，修正 top-level feedback help 並包含 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

@@ -126,7 +126,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|submit|list> [options]
+  maggie feedback <collect|preview|batch|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

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

@@ -46,6 +46,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

@@ -123,10 +123,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 +245,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-marketplace/SKILL.md

@@ -74,7 +74,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-tools/clis/maggie.py

@@ -426,8 +426,29 @@ def command_api_lifecycle(args: argparse.Namespace) -> int:
             "total_posts", "matchedPosts", "matched_posts", "eligible",
             "unmatched", "queued", "accepted", "created", "updated",
             "skipped", "removed", "nextCursor", "next_cursor",
+            "message", "error", "quota_exhausted", "quotaExhausted",
+            "quotaDailyRemaining", "quota_daily_remaining",
+            "quotaMonthlyRemaining", "quota_monthly_remaining",
         )
-        summary = {key: value[key] for key in allowed if key in value and isinstance(value[key], (str, int, float, bool, type(None)))}
+        summary = {}
+        for key in allowed:
+            if key not in value or not isinstance(value[key], (str, int, float, bool, type(None))):
+                continue
+            item = value[key]
+            if key in {"message", "error"} and isinstance(item, str):
+                item = " ".join(item.split())[:300]
+            summary[key] = item
+        quota = value.get("quota")
+        if isinstance(quota, dict):
+            quota_summary = {}
+            for window_name, window in quota.items():
+                if not isinstance(window, dict) or not isinstance(window.get("remaining"), int):
+                    continue
+                quota_summary[str(window_name)] = {"remaining": window["remaining"]}
+            if quota_summary:
+                summary["quota"] = quota_summary
+        if value.get("quota_exhausted") is True or value.get("quotaExhausted") is True:
+            summary["effective_delivery_remaining"] = 0
         items = value.get("items")
         if isinstance(items, list):
             summary["item_count"] = len(items)
@@ -639,6 +660,13 @@ def interview_value(key: str, question: str, current: str, choices: list[str]) -
 def command_bootstrap_interview(args: argparse.Namespace) -> int:
     root = Path(args.project).resolve()
     analysis = detect(root)
+    if not args.non_interactive and not sys.stdin.isatty():
+        print(
+            "NON_INTERACTIVE_REQUIRED: stdin is not interactive; use --non-interactive "
+            "--answers-file answers.json --confirm after reviewing the proposal.",
+            file=sys.stderr,
+        )
+        return 2
     answers: dict[str, str] = {}
     if args.answers_file:
         try:

package/bundled-tools/clis/maggie_dash.py

@@ -102,8 +102,38 @@ def manifest_file_pairs(source: Path, manifest: dict[str, object], target: Path)
     return pairs
 
 
+def manifest_root_file_pairs(source: Path, manifest: dict[str, object], root: Path) -> list[tuple[Path, Path, Path]]:
+    """Return optional host-root files without changing the admin target contract."""
+    pairs: list[tuple[Path, Path, Path]] = []
+    for item in manifest.get("rootFiles", []):
+        if isinstance(item, str):
+            source_relative = Path(item)
+            target_relative = source_relative
+        elif isinstance(item, dict):
+            source_relative = Path(str(item.get("source", "")))
+            target_relative = Path(str(item.get("target", "")))
+        else:
+            raise RuntimeError("MaggieDash rootFiles entries must be strings or objects")
+        if not source_relative.parts or not target_relative.parts:
+            raise RuntimeError("MaggieDash rootFiles entries require source and target")
+        if source_relative.is_absolute() or target_relative.is_absolute() or ".." in source_relative.parts or ".." in target_relative.parts:
+            raise RuntimeError("unsafe MaggieDash rootFiles path")
+        source_item = source / source_relative
+        if source_item.is_file():
+            pairs.append((source_item, root / target_relative, source_relative))
+            continue
+        if not source_item.is_dir():
+            raise RuntimeError(f"MaggieDash rootFiles source is missing: {source_relative}")
+        for path in sorted(source_item.rglob("*")):
+            if path.is_file():
+                child = path.relative_to(source_item)
+                pairs.append((path, root / target_relative / child, source_relative / child))
+    return pairs
+
+
 def command_install_diff(source: Path, manifest: dict[str, object], target: Path, compare_dir: Path | None, force: bool) -> dict[str, object]:
     pairs = manifest_file_pairs(source, manifest, target)
+    root_pairs = manifest_root_file_pairs(source, manifest, target.parents[1])
     files: list[dict[str, str]] = []
     source_relative = {relative for _, _, relative in pairs}
     for source_file, destination, relative in pairs:
@@ -119,6 +149,15 @@ def command_install_diff(source: Path, manifest: dict[str, object], target: Path
         else:
             action = "update" if force else "preserve"
         files.append({"path": str(relative), "action": action, "comparePath": str(compare_file)})
+    for source_file, destination, relative in root_pairs:
+        compare_file = destination
+        if not compare_file.exists():
+            action = "add"
+        elif compare_file.read_bytes() == source_file.read_bytes():
+            action = "unchanged"
+        else:
+            action = "update" if force else "preserve"
+        files.append({"path": str(relative), "action": action, "comparePath": str(compare_file)})
     if compare_dir and compare_dir.exists():
         for existing in sorted(compare_dir.rglob("*")):
             if not existing.is_file():
@@ -204,6 +243,13 @@ def command_install(args: argparse.Namespace) -> int:
                     current_installed = [str(destination)]
             installed.extend(current_installed)
             preserved.extend(current_preserved)
+        for source_file, destination, _ in manifest_root_file_pairs(source, manifest, root):
+            if destination.exists() and not args.force:
+                preserved.append(str(destination))
+            else:
+                destination.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(source_file, destination)
+                installed.append(str(destination))
         state = {
             "schemaVersion": "maggiedash-install.v1",
             "status": "installed",
@@ -442,6 +488,62 @@ def command_api_contract(args: argparse.Namespace) -> int:
     return 0 if result["passed"] else 1
 
 
+def command_conformance(args: argparse.Namespace) -> int:
+    """Validate sanitized runtime evidence for every declared host endpoint."""
+    project = Path(getattr(args, "project", ".")).resolve()
+    def input_path(value: str) -> Path:
+        path = Path(value)
+        return path if path.is_absolute() else project / path
+    contract = json.loads(input_path(args.contract).read_text(encoding="utf-8"))
+    evidence = json.loads(input_path(args.evidence).read_text(encoding="utf-8"))
+    endpoints = contract.get("x-endpoints") or contract.get("endpoints") or contract.get("properties", {}).get("endpoints", {}).get("x-endpoints", [])
+    observations = evidence.get("observations") if isinstance(evidence, dict) else None
+    errors: list[str] = []
+    if not isinstance(endpoints, list) or not endpoints:
+        errors.append("contract must declare at least one endpoint")
+        endpoints = []
+    if not isinstance(observations, list):
+        errors.append("evidence.observations must be an array")
+        observations = []
+    by_id = {str(item.get("id")): item for item in observations if isinstance(item, dict) and item.get("id")}
+    checked = []
+    for endpoint in endpoints:
+        endpoint_id = str(endpoint.get("id", "")) if isinstance(endpoint, dict) else ""
+        item_errors: list[str] = []
+        observation = by_id.get(endpoint_id)
+        if not observation:
+            item_errors.append("missing runtime observation")
+        else:
+            if observation.get("method") != endpoint.get("method"):
+                item_errors.append("observed method does not match contract")
+            if observation.get("route") != endpoint.get("route"):
+                item_errors.append("observed route does not match contract")
+            status = observation.get("httpStatus")
+            if not isinstance(status, int) or isinstance(status, bool) or not 200 <= status < 300:
+                item_errors.append("endpoint did not return a 2xx status")
+            expected_type = endpoint.get("response", {}).get("contentType")
+            if observation.get("contentType") != expected_type:
+                item_errors.append("observed content type does not match contract")
+            fields = observation.get("responseFields")
+            required = endpoint.get("response", {}).get("requiredFields", [])
+            if not isinstance(fields, list) or not set(required).issubset(set(fields)):
+                item_errors.append("response is missing one or more declared fields")
+            if observation.get("passed") is not True:
+                item_errors.append("runtime observation is not passed")
+        checked.append({"id": endpoint_id, "passed": not item_errors, "errors": item_errors})
+    duplicate_ids = len(by_id) != len(observations)
+    if duplicate_ids:
+        errors.append("evidence contains duplicate or invalid observation ids")
+    report = {"schemaVersion": "maggiedash-host-conformance.v1", "checked": len(checked), "endpoints": checked, "errors": errors, "passed": not errors and bool(checked) and all(item["passed"] for item in checked)}
+    if args.output:
+        output = input_path(args.output)
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(report, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        report["output"] = str(output)
+    emit(report)
+    return 0 if report["passed"] else 1
+
+
 def command_schema_audit(args: argparse.Namespace) -> int:
     value = json.loads(Path(args.inventory).resolve().read_text(encoding="utf-8"))
     result = audit_schema_inventory(value, fail_on_unread=args.fail_on_unread)
@@ -603,6 +705,12 @@ def parser() -> argparse.ArgumentParser:
     api_contract = sub.add_parser("api-contract", help="validate a local or live declared request and success-response contract")
     api_contract.add_argument("--spec", required=True, help="local JSON file or HTTPS URL (loopback HTTP is allowed for development)")
     api_contract.set_defaults(func=command_api_contract)
+    conformance = sub.add_parser("conformance", help="validate one sanitized runtime observation for every declared MaggieDash endpoint")
+    conformance.add_argument("--project", default=".", help="host project root for relative contract, evidence, and output paths")
+    conformance.add_argument("--contract", required=True, help="MaggieDash host adapter contract JSON")
+    conformance.add_argument("--evidence", required=True, help="sanitized endpoint observations JSON")
+    conformance.add_argument("--output")
+    conformance.set_defaults(func=command_conformance)
     schema_audit = sub.add_parser("schema-audit", help="find declared tables with missing reader evidence")
     schema_audit.add_argument("--inventory", required=True, help="host-produced schema inventory JSON")
     schema_audit.add_argument("--fail-on-unread", action="store_true")

package/bundled-tools/clis/maggie_deployment.py

@@ -55,8 +55,7 @@ def preflight(project: Path, target: str, environment: str) -> dict:
         rollback_passed = False
         if rollback_evidence.exists():
             try:
-                evidence = json.loads(rollback_evidence.read_text(encoding="utf-8"))
-                rollback_passed = bool(evidence.get("passed") is True and evidence.get("environment") == "production" and evidence.get("previousRelease") and evidence.get("testedAt"))
+                rollback_passed = validate_rollback_evidence(json.loads(rollback_evidence.read_text(encoding="utf-8"))) ["passed"]
             except (OSError, json.JSONDecodeError):
                 rollback_passed = False
         migration_manifest = project / ".maggie" / "migration-manifest.json"
@@ -79,12 +78,14 @@ def preflight(project: Path, target: str, environment: str) -> dict:
     return result
 
 
-def vps_plan(domain: str, service: str, release_root: str, node_port: int) -> dict:
+def vps_plan(domain: str, service: str, release_root: str, node_port: int | None) -> dict:
     """Create reviewable, secret-free VPS service and reverse-proxy artifacts."""
     if not re.fullmatch(r"[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?", domain):
         raise ValueError("domain must be a hostname without a scheme or path")
     if not re.fullmatch(r"[A-Za-z0-9_.@-]+", service):
         raise ValueError("service must contain only safe systemd name characters")
+    if node_port is None:
+        raise ValueError("node port must be supplied explicitly; choose an unused port for this host")
     if not 1024 <= node_port <= 65535:
         raise ValueError("node port must be between 1024 and 65535")
     root = release_root.rstrip("/")
@@ -97,6 +98,12 @@ def vps_plan(domain: str, service: str, release_root: str, node_port: int) -> di
         "release_root": root,
         "current_release": current,
         "node_port": node_port,
+        "proxy": {
+            "trust_forwarded_proto": True,
+            "forwarded_headers": ["X-Forwarded-Host", "X-Forwarded-Proto"],
+            "origin_check": "Astro security.checkOrigin remains enabled",
+            "allowed_domains_required": True,
+        },
         "release_layout": f"{root}/releases/<immutable-release> plus current symlink",
         "retention": {"keep": 2, "preserve": [current, f"{root}/releases/<previous-release>"], "prune": f"find {root}/releases -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\\n' | sort -nr | tail -n +3 | cut -d' ' -f2- | xargs -r rm -rf --"},
         "staging_first": True,
@@ -141,6 +148,32 @@ def validate_data_checkpoint(path: Path) -> dict:
     return {"passed": not errors, "declared": True, "errors": errors}
 
 
+def validate_rollback_evidence(value: object) -> dict:
+    """Validate release rollback evidence, including the explicitly safe first release."""
+    if not isinstance(value, dict):
+        return {"passed": False, "errors": ["rollback evidence must be an object"]}
+    errors = []
+    if value.get("schemaVersion") not in {None, "maggie-deployment-rollback.v1"}:
+        errors.append("rollback evidence schemaVersion is unsupported")
+    if value.get("passed") is not True:
+        errors.append("rollback evidence is not passed")
+    if value.get("environment") != "production":
+        errors.append("rollback evidence must target production")
+    if not value.get("testedAt"):
+        errors.append("rollback evidence testedAt is required")
+    release_kind = value.get("releaseKind", "upgrade")
+    if release_kind not in {"first", "upgrade"}:
+        errors.append("rollback evidence releaseKind must be first or upgrade")
+    if release_kind == "first":
+        if value.get("previousRelease"):
+            errors.append("first release evidence must not claim a previous release")
+        if not value.get("notApplicableReason"):
+            errors.append("first release evidence needs notApplicableReason")
+    elif not value.get("previousRelease"):
+        errors.append("upgrade rollback evidence requires previousRelease")
+    return {"passed": not errors, "errors": errors}
+
+
 def validate_scheduler_request(method: str, origin: str | None, has_auth: bool) -> dict:
     errors = []
     if method.upper() == "POST":
@@ -210,6 +243,7 @@ WantedBy=multi-user.target
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Host $host;
         proxy_set_header X-Forwarded-Proto $scheme;
     }}
 }}
@@ -230,10 +264,15 @@ set -euo pipefail
 
 # Migration precedes the symlink flip; later releases carry agent state.
 : "${{RELEASE_ID:?set RELEASE_ID to an immutable release name}}"
+RELEASE_KIND="${{RELEASE_KIND:-upgrade}}"
 RELEASE_ROOT="{root}"
 CURRENT="{current}"
 RELEASE="$RELEASE_ROOT/releases/$RELEASE_ID"
 PREVIOUS="$(readlink -f "$CURRENT" 2>/dev/null || true)"
+if [ "$RELEASE_KIND" != "first" ] && [ -z "$PREVIOUS" ]; then
+  echo "No previous release found; set RELEASE_KIND=first for the initial production release." >&2
+  exit 2
+fi
 mkdir -p "$RELEASE"
 cd "$RELEASE"
 
@@ -277,7 +316,7 @@ def main() -> int:
     parser.add_argument("--domain", help="canonical hostname for --vps-plan")
     parser.add_argument("--service", default="maggie-site", help="systemd service name")
     parser.add_argument("--release-root", default="/var/www/maggie-site", help="immutable release root")
-    parser.add_argument("--node-port", type=int, default=4321)
+    parser.add_argument("--node-port", type=int, required=False, default=None, help="unused host port; required with --vps-plan")
     parser.add_argument("--plan-dir", help="directory for generated VPS artifacts")
     parser.add_argument("--runner-output", help="write a reviewable ordered VPS release runner")
     parser.add_argument("--retention-plan", action="store_true", help="create a read-only release prune candidate plan")

package/bundled-tools/clis/maggie_marketplace.py

@@ -25,7 +25,7 @@ DEFAULT_SAMPLE_ID = "medical-spa-landing-001"
 PUBLISHED_STATUSES = {"published", "ready"}
 PHOSPHOR_BRAND_ICONS = {"ph-instagram-logo", "ph-facebook-logo", "ph-x-logo", "ph-linkedin-logo", "ph-youtube-logo", "ph-tiktok-logo"}
 PHOSPHOR_CDN = "https://cdn.jsdelivr.net/npm/@phosphor-icons/web@2.1.1/src/regular/style.css"
-JOB_PHASES = ("CREATED", "IMPORTED", "WAITING_FOR_ASSETS", "COMPLETED", "VALIDATED", "READY", "FAILED")
+JOB_PHASES = ("CREATED", "IMPORTED", "WAITING_FOR_ASSETS", "COMPLETED", "VALIDATED", "READY", "STALE", "FAILED")
 
 
 class MetadataParser(HTMLParser):
@@ -1738,8 +1738,16 @@ def run_marketplace_job(args: argparse.Namespace) -> int:
     if existing_path.exists() and not args.force:
         existing = load_job(root, args.id)
         if existing.get("phase") == "READY":
-            print(f"marketplace job already ready: {args.id}")
-            return 0
+            destination = template_path(root, args.id)
+            # READY is a claim, not a permanent exemption from newer
+            # validators. Re-check it on every reuse and make a stale package
+            # explicitly resumable when the contract has moved on.
+            if validate_template(destination, args.sample.resolve() if args.sample else None) == 0:
+                print(f"marketplace job already ready: {args.id}")
+                return 0
+            set_job_phase(root, existing, "STALE", staleReason="current validator rejected the recorded READY package")
+            print(f"STALE: marketplace job {args.id} must be resumed or rebuilt")
+            return 1
         args = args_from_job(existing)
     job = load_job(root, args.id) if existing_path.exists() else {
         "id": args.id,
@@ -1823,7 +1831,7 @@ def resume_marketplace_job(args: argparse.Namespace) -> int:
         print(f"marketplace job already ready: {args.job_id}")
         return 0
     resumed = args_from_job(job)
-    if job.get("phase") == "FAILED":
+    if job.get("phase") in {"FAILED", "STALE"}:
         destination = template_path(root, args.job_id)
         # A post-import failure must resume from the completion checkpoint;
         # importing again would erase generated assets and task evidence.

package/bundled-tools/integrations/maggie-api-pull.md

@@ -23,8 +23,11 @@ feedback payloads, or public repositories.
 
 `/history` rejects invalid pagination with `422`; do not request more than 50
 records per page. Empty `/posts` or `/updates` responses are normal and mean
-there is currently no queued item. The public OpenAPI contract does not include
-`/whoami`; resolve configuration from the API key and project context instead.
+there is currently no queued item. Quota responses must expose the effective
+delivery allowance: when `quota_exhausted` is true, report the relevant daily
+remaining value as zero and preserve a bounded provider `message`/error
+summary. The public OpenAPI contract does not include `/whoami`; resolve
+configuration from the API key and project context instead.
 
 Returned content may expose provider-specific fields such as `content`,
 `content_markdown`, `content_html`, `content_portable_text`, `body`, or `html`.
@@ -56,8 +59,9 @@ python3 tools/clis/maggie.py api lifecycle --project . \
 The first command is always dry-run. The executing command persists key-scoped
 context, remote IDs, versions, slugs, canonicals, and hashes under
 `.maggie/ai-cmo-lifecycle.json`. Raw provider responses are not copied into
-the checkpoint. Pulled content is projected as draft-only state; no lifecycle
-step publishes local content.
+the checkpoint; only bounded messages, effective quota fields, and safe scalar
+outcomes are retained. Pulled content is projected as draft-only state; no
+lifecycle step publishes local content.
 
 To prepare and explicitly import the projection into MaggieDash drafts:
 

package/bundled-tools/runtime/maggie_dash_store.py

@@ -108,6 +108,26 @@ class MaggieDashStore:
 
     def init_project(self, project_id: str, name: str, adapter: str = "maggiedash-sqlite", locale: str = "en-GB") -> dict[str, Any]:
         timestamp = now()
+        # The default CLI identity is a provisional row. Once the operator
+        # supplies a real project id, converge that row instead of leaving an
+        # orphan project behind in the local store.
+        if project_id != "local-project":
+            has_target = self.connection.execute("SELECT 1 FROM maggiedash_projects WHERE id=?", (project_id,)).fetchone()
+            has_default = self.connection.execute("SELECT 1 FROM maggiedash_projects WHERE id=?", ("local-project",)).fetchone()
+            if not has_target and has_default:
+                # Create the destination first so SQLite's foreign-key checks
+                # remain enabled while project-scoped rows are moved.
+                self.connection.execute(
+                    "INSERT INTO maggiedash_projects (id,name,adapter,locale,status,created_at,updated_at) "
+                    "SELECT ?,name,adapter,locale,status,created_at,updated_at FROM maggiedash_projects WHERE id=?",
+                    (project_id, "local-project"),
+                )
+                existing_tables = {row[0] for row in self.connection.execute("SELECT name FROM sqlite_master WHERE type='table'")}
+                for table in ("maggiedash_memberships", "maggiedash_documents", "maggiedash_redirects", "maggiedash_audit_events", "maggiedash_section_presets"):
+                    if table not in existing_tables:
+                        continue
+                    self.connection.execute(f"UPDATE {table} SET project_id=? WHERE project_id=?", (project_id, "local-project"))
+                self.connection.execute("DELETE FROM maggiedash_projects WHERE id=?", ("local-project",))
         self.connection.execute(
             "INSERT INTO maggiedash_projects (id,name,adapter,locale,created_at,updated_at) VALUES (?,?,?,?,?,?) "
             "ON CONFLICT(id) DO UPDATE SET name=excluded.name, adapter=excluded.adapter, locale=excluded.locale, updated_at=excluded.updated_at",

package/package.json

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

package/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/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