@topy-ai/maggie 0.7.26 → 0.7.28

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.
@@ -2053,6 +2061,47 @@ def apply_template(args: argparse.Namespace) -> int:
     return 0
 
 
+def enrichment_report(args: argparse.Namespace) -> int:
+    """Normalize privacy-safe enrichment evidence for a marketplace candidate."""
+    try:
+        payload = read_json(args.input.resolve())
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(json.dumps({"status": "failed", "errors": [f"cannot read enrichment evidence: {error}"]})); return 1
+    errors = []
+    if payload.get("schemaVersion") != "maggie-marketplace-enrichment-input.v1": errors.append("schemaVersion is unsupported")
+    candidate = payload.get("candidate") if isinstance(payload.get("candidate"), dict) else {}
+    candidate_id = str(candidate.get("candidateId") or "")
+    if not ID_PATTERN.fullmatch(candidate_id): errors.append("candidate.candidateId must be marketplace-safe")
+    crawl = payload.get("crawl") if isinstance(payload.get("crawl"), dict) else {}
+    audit = payload.get("audit") if isinstance(payload.get("audit"), dict) else {}
+    snapshot = payload.get("snapshot") if isinstance(payload.get("snapshot"), dict) else {}
+    for field, item in (("crawl", crawl), ("audit", audit), ("snapshot", snapshot)):
+        if not item: errors.append(f"{field} evidence is required")
+        if item.get("status") not in {"passed", "failed", "not-found", "blocked", "unavailable"}: errors.append(f"{field}.status is unsupported")
+        if item.get("error") and not re.fullmatch(r"[a-z0-9][a-z0-9._:-]{0,119}", str(item["error"])): errors.append(f"{field}.error must be a safe error code")
+    fields = payload.get("rawAuditFields", {})
+    if not isinstance(fields, dict): errors.append("rawAuditFields must be an object")
+    safe_fields = {}
+    for key, value in (fields.items() if isinstance(fields, dict) else []):
+        if re.fullmatch(r"[A-Za-z][A-Za-z0-9_.:-]{0,79}", str(key)) and not re.search(r"path|secret|token|password|cookie|header|body|html", str(key), re.I) and isinstance(value, (str, int, float, bool)) and not (isinstance(value, str) and re.search(r"(?:^|/)(?:home|Users|tmp|var|private)/", value)):
+            safe_fields[str(key)] = str(value)[:240] if isinstance(value, str) else value
+    backfill = payload.get("seoBackfill") if isinstance(payload.get("seoBackfill"), dict) else {}
+    report = {
+        "schemaVersion": "maggie-marketplace-enrichment.v1", "candidateId": candidate_id,
+        "status": "passed" if not errors else "failed", "passed": not errors, "errors": errors,
+        "candidate": {"source": str(candidate.get("source") or "")[:120], "market": str(candidate.get("market") or "global")[:20], "locale": str(candidate.get("locale") or "en")[:20]},
+        "crawl": {"status": crawl.get("status"), "pages": crawl.get("pages", 0) if isinstance(crawl.get("pages", 0), int) else 0, "error": crawl.get("error")},
+        "audit": {"status": audit.get("status"), "fields": safe_fields, "error": audit.get("error")},
+        "snapshot": {"status": snapshot.get("status"), "revision": str(snapshot.get("revision") or "")[:120], "error": snapshot.get("error")},
+        "seoBackfill": {"status": backfill.get("status"), "updated": backfill.get("updated", 0) if isinstance(backfill.get("updated", 0), int) else 0, "error": backfill.get("error")},
+        "retry": {"allowed": bool(errors), "reason": ";".join(errors)[:240] if errors else None},
+        "privacy": {"rawHtmlIncluded": False, "responseBodiesIncluded": False, "localPathsIncluded": False, "secretsRedacted": True},
+    }
+    output = args.output.resolve() if args.output else args.project.resolve() / "docs" / "marketplace-enrichment.json"
+    output.parent.mkdir(parents=True, exist_ok=True); output.write_text(json.dumps(report, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps({"status": report["status"], "candidateId": candidate_id, "report": str(output), "retry": report["retry"]}, ensure_ascii=False)); return 0 if not errors else 1
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--marketplace", type=Path, default=Path("marketplace"))
@@ -2122,6 +2171,11 @@ def main() -> int:
     apply.add_argument("--project", type=Path, default=Path.cwd())
     apply.add_argument("--allow-draft", action="store_true")
     apply.set_defaults(func=apply_template)
+    enrichment = sub.add_parser("enrichment-report", help="normalize safe candidate crawl and audit evidence")
+    enrichment.add_argument("--project", type=Path, default=Path.cwd())
+    enrichment.add_argument("--input", type=Path, required=True)
+    enrichment.add_argument("--output", type=Path)
+    enrichment.set_defaults(func=enrichment_report)
     args = parser.parse_args()
     try:
         return int(args.func(args) or 0)

package/bundled-tools/clis/maggie_migration.py

@@ -56,6 +56,8 @@ def validate_project(project: Path, environment: str) -> dict:
 
 
 IDENTITY_SCHEMA = "maggie-database-identity.v1"
+PREFLIGHT_SCHEMA = "maggie-migration-preflight.v1"
+SAFE_NAME = re.compile(r"^[A-Za-z][A-Za-z0-9_.:-]{0,119}$")
 
 
 def _identity_fingerprint(identity: dict) -> str:
@@ -119,7 +121,48 @@ def identity_main(argv: list[str]) -> int:
     return 0 if result["passed"] else 1
 
 
+def preflight_main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description="Validate secret-free migration privilege, column, and constraint evidence.")
+    parser.add_argument("--evidence", required=True)
+    parser.add_argument("--output")
+    args = parser.parse_args(argv)
+    errors: list[str] = []
+    try:
+        payload = json.loads(Path(args.evidence).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        payload = {}; errors.append(f"cannot read migration preflight evidence: {error}")
+    if not isinstance(payload, dict): payload = {}; errors.append("preflight evidence must be an object")
+    if payload.get("schemaVersion") != PREFLIGHT_SCHEMA: errors.append(f"schemaVersion must be {PREFLIGHT_SCHEMA}")
+    if payload.get("environment") not in {"development", "staging", "production"}: errors.append("environment is invalid")
+    privileges = payload.get("privileges") if isinstance(payload.get("privileges"), dict) else {}
+    for field in ("canCreateTable", "canAlterTable", "canCreateIndex", "passed"):
+        if privileges.get(field) is not True: errors.append(f"privileges.{field} must be true")
+    columns = payload.get("requiredColumns")
+    if not isinstance(columns, list) or not columns: errors.append("requiredColumns must not be empty")
+    for index, item in enumerate(columns if isinstance(columns, list) else []):
+        if not isinstance(item, dict) or not SAFE_NAME.fullmatch(str(item.get("table") or "")) or not SAFE_NAME.fullmatch(str(item.get("column") or "")) or item.get("present") is not True:
+            errors.append(f"requiredColumns[{index}] must identify a present table column")
+    constraints = payload.get("uniqueConstraints")
+    if not isinstance(constraints, list) or not constraints: errors.append("uniqueConstraints must not be empty")
+    for index, item in enumerate(constraints if isinstance(constraints, list) else []):
+        if not isinstance(item, dict) or not SAFE_NAME.fullmatch(str(item.get("table") or "")) or not isinstance(item.get("columns"), list) or not item["columns"] or any(not SAFE_NAME.fullmatch(str(value)) for value in item["columns"]) or item.get("present") is not True:
+            errors.append(f"uniqueConstraints[{index}] must identify a present unique constraint")
+    idempotency = payload.get("idempotency") if isinstance(payload.get("idempotency"), dict) else {}
+    if idempotency.get("safe") is not True or idempotency.get("onConflictHandled") is not True: errors.append("idempotency must be safe and handle conflicts")
+    migration = payload.get("migration") if isinstance(payload.get("migration"), dict) else {}
+    for field in ("currentVersion", "targetVersion"):
+        if not SAFE_NAME.fullmatch(str(migration.get(field) or "")): errors.append(f"migration.{field} must be a safe identifier")
+    if migration.get("currentVersion") == migration.get("targetVersion"): errors.append("migration targetVersion must advance")
+    if migration.get("passed") is not True: errors.append("migration evidence did not pass")
+    result = {"schemaVersion": PREFLIGHT_SCHEMA, "environment": payload.get("environment"), "status": "passed" if not errors else "failed", "passed": not errors, "errors": errors, "checks": {"privileges": True, "requiredColumns": True, "uniqueConstraints": True, "idempotency": True, "migration": True}, "mutation": "not executed"}
+    if args.output:
+        output = Path(args.output); output.parent.mkdir(parents=True, exist_ok=True); output.write_text(json.dumps(result, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps(result, indent=2)); return 0 if not errors else 1
+
+
 def main() -> int:
+    if sys.argv[1:2] == ["preflight"]:
+        return preflight_main(sys.argv[2:])
     if sys.argv[1:2] == ["identity"]:
         return identity_main(sys.argv[2:])
     parser = argparse.ArgumentParser(description=__doc__)

package/bundled-tools/clis/maggie_service_booking.py

@@ -7,7 +7,7 @@ import xml.etree.ElementTree as ET
 from datetime import datetime, timezone
 from html.parser import HTMLParser
 from pathlib import Path
-from urllib.parse import quote, urljoin, urlsplit
+from urllib.parse import quote, urljoin, urlsplit, urlparse
 from urllib.request import Request, urlopen
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
@@ -1148,6 +1148,85 @@ def cmd_variant_render_audit(args):
     result={"schemaVersion":"1.0","generatedAt":NOW(),"environment":args.environment,"status":"passed" if not errors else "failed","variants":results,"errors":errors,"passed":not errors}
     out=project/"docs"/"service-variant-render-audit.json"; out.parent.mkdir(parents=True,exist_ok=True); out.write_text(json.dumps(result,indent=2)+"\n",encoding="utf-8")
     print(json.dumps({**result,"report":str(out)},indent=2)); return 0 if not errors else 1
+SAFE_WORKER_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$")
+SAFE_EVIDENCE_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:/=-]{0,159}$")
+RESOLVER_OUTCOMES = {"resolved", "resolved-no-menu", "not-found", "blocked", "timeout", "unavailable"}
+
+
+def cmd_worker_health(args):
+    """Validate bounded queue, lease, retry, timeout, and cancellation evidence."""
+    try:
+        payload = json.loads(Path(args.evidence).resolve().read_text(encoding="utf-8"))
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        print(json.dumps({"status": "failed", "errors": [f"cannot read worker evidence: {exc}"]}, indent=2))
+        return 1
+    errors = []
+    if payload.get("schemaVersion") != "maggie-booking-worker-health-input.v1": errors.append("schemaVersion is unsupported")
+    if payload.get("environment") not in {"development", "staging", "production"}: errors.append("environment is invalid")
+    worker_id = str(payload.get("workerId") or "")
+    if not SAFE_WORKER_ID.fullmatch(worker_id): errors.append("workerId must be a safe identifier")
+    queue = payload.get("queue") if isinstance(payload.get("queue"), dict) else {}
+    for field in ("maxDepth", "maxConcurrency"):
+        if not isinstance(queue.get(field), int) or isinstance(queue.get(field), bool) or queue[field] < 1: errors.append(f"queue.{field} must be a positive integer")
+    if queue.get("bounded") is not True: errors.append("queue must be bounded")
+    leases = payload.get("leases") if isinstance(payload.get("leases"), dict) else {}
+    if leases.get("enabled") is not True or not isinstance(leases.get("ttlSeconds"), int) or leases.get("ttlSeconds", 0) < 1: errors.append("leases must have a positive TTL")
+    if leases.get("staleReclaimed") is not True: errors.append("stale leases must be reclaimed")
+    timeouts = payload.get("timeouts") if isinstance(payload.get("timeouts"), dict) else {}
+    for field in ("jobSeconds", "providerSeconds"):
+        if not isinstance(timeouts.get(field), int) or isinstance(timeouts.get(field), bool) or timeouts[field] < 1: errors.append(f"timeouts.{field} must be positive")
+    retry = payload.get("retry") if isinstance(payload.get("retry"), dict) else {}
+    if not isinstance(retry.get("maxAttempts"), int) or isinstance(retry.get("maxAttempts"), bool) or retry["maxAttempts"] < 0: errors.append("retry.maxAttempts must be non-negative")
+    if retry.get("backoff") not in {"fixed", "exponential", "exponential-jitter"}: errors.append("retry.backoff must be an approved strategy")
+    cancellation = payload.get("cancellation") if isinstance(payload.get("cancellation"), dict) else {}
+    if cancellation.get("supported") is not True or cancellation.get("cleanupVerified") is not True: errors.append("cancellation cleanup is not verified")
+    health = payload.get("health") if isinstance(payload.get("health"), dict) else {}
+    if not isinstance(health.get("path"), str) or not health["path"].startswith("/") or health.get("passed") is not True: errors.append("health endpoint did not pass")
+    if payload.get("orphanedJobs", 0) != 0: errors.append("orphanedJobs must be zero")
+    report = {"schemaVersion": "maggie-booking-worker-health.v1", "environment": payload.get("environment"), "workerId": worker_id, "status": "passed" if not errors else "failed", "passed": not errors, "errors": errors, "checks": {"boundedQueue": True, "leases": True, "timeouts": True, "retryBackoff": True, "cancellationCleanup": True, "healthEndpoint": True}}
+    project = root(args)
+    output = Path(args.output) if args.output else project / "docs/booking-worker-health.json"
+    if not output.is_absolute(): output = project / output
+    output = output.resolve()
+    output.parent.mkdir(parents=True, exist_ok=True); output.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps({"status": report["status"], "report": str(output), "errors": errors}, indent=2)); return 0 if not errors else 1
+
+
+def cmd_resolver_audit(args):
+    """Classify booking URL outcomes using safe canonical URL evidence."""
+    try:
+        payload = json.loads(Path(args.evidence).resolve().read_text(encoding="utf-8"))
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        print(json.dumps({"status": "failed", "errors": [f"cannot read resolver evidence: {exc}"]}, indent=2)); return 1
+    errors = []
+    if payload.get("schemaVersion") != "maggie-booking-resolver-input.v1": errors.append("schemaVersion is unsupported")
+    observations = payload.get("observations")
+    if not isinstance(observations, list) or not observations or len(observations) > 200: errors.append("observations must contain 1–200 items")
+    safe = []
+    for index, item in enumerate(observations if isinstance(observations, list) else []):
+        prefix = f"observations[{index}]"
+        if not isinstance(item, dict): errors.append(f"{prefix} must be an object"); continue
+        service_id = str(item.get("serviceId") or ""); outcome = item.get("outcome")
+        if not SAFE_WORKER_ID.fullmatch(service_id): errors.append(f"{prefix}.serviceId must be a safe identifier")
+        if outcome not in RESOLVER_OUTCOMES: errors.append(f"{prefix}.outcome is unsupported")
+        canonical = item.get("canonicalUrl")
+        if outcome in {"resolved", "resolved-no-menu"}:
+            parsed = urlparse(str(canonical or ""))
+            if parsed.scheme != "https" or not parsed.netloc or parsed.username or parsed.password: errors.append(f"{prefix}.canonicalUrl must be a public HTTPS URL")
+        elif canonical: errors.append(f"{prefix}.canonicalUrl is only allowed for resolved outcomes")
+        evidence = item.get("evidenceIds")
+        if not isinstance(evidence, list) or not evidence or any(not SAFE_EVIDENCE_ID.fullmatch(str(value)) for value in evidence[:20]): errors.append(f"{prefix}.evidenceIds must contain safe identifiers")
+        if not isinstance(item.get("durationMs"), int) or isinstance(item.get("durationMs"), bool) or item["durationMs"] < 0: errors.append(f"{prefix}.durationMs must be non-negative")
+        safe.append({"serviceId": service_id, "outcome": outcome, "canonicalUrl": canonical if outcome in {"resolved", "resolved-no-menu"} else None, "evidenceIds": [str(value) for value in evidence[:20]] if isinstance(evidence, list) else [], "durationMs": item.get("durationMs")})
+    counts = {outcome: sum(item.get("outcome") == outcome for item in safe) for outcome in sorted(RESOLVER_OUTCOMES)}
+    report = {"schemaVersion": "maggie-booking-resolver.v1", "status": "passed" if not errors else "failed", "passed": not errors, "errors": errors, "counts": counts, "observations": safe, "privacy": {"rawResponsesIncluded": False, "credentialsIncluded": False}}
+    project = root(args)
+    output = Path(args.output) if args.output else project / "docs/booking-resolver-audit.json"
+    if not output.is_absolute(): output = project / output
+    output = output.resolve(); output.parent.mkdir(parents=True, exist_ok=True); output.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps({"status": report["status"], "report": str(output), "counts": counts, "errors": errors}, indent=2)); return 0 if not errors else 1
+
+
 def main():
     p=argparse.ArgumentParser(); sub=p.add_subparsers(dest="command",required=True)
     for name in ("import","sync","run"):
@@ -1173,6 +1252,8 @@ def main():
     q=sub.add_parser("variant-audit"); q.add_argument("--project",default="."); q.add_argument("--variants",required=True,help="draft service-page variant JSON"); q.add_argument("--as-of",help="ISO timestamp for expiry checks"); q.add_argument("--environment",choices=("development","staging","production"),default="staging")
     q=sub.add_parser("category-visual-audit"); q.add_argument("--project",default="."); q.add_argument("--screenshot-dir",required=True); q.add_argument("--min-bytes",type=int,default=5000); q.add_argument("--environment",choices=("development","staging","production"),default="staging")
     q=sub.add_parser("variant-render-audit"); q.add_argument("--project",default="."); q.add_argument("--variants",required=True); q.add_argument("--rendered-dir",required=True); q.add_argument("--environment",choices=("development","staging","production"),default="staging")
+    q=sub.add_parser("worker-health"); q.add_argument("--project",default="."); q.add_argument("--evidence",required=True); q.add_argument("--output")
+    q=sub.add_parser("resolver-audit"); q.add_argument("--project",default="."); q.add_argument("--evidence",required=True); q.add_argument("--output")
     for name in ("validate","inspect","status"):
         q=sub.add_parser(name); q.add_argument("--project",default=".")
     a=p.parse_args(); project=root(a)
@@ -1198,6 +1279,8 @@ def main():
     if a.command=="variant-audit": return cmd_variant_audit(a)
     if a.command=="category-visual-audit": return cmd_category_visual_audit(a)
     if a.command=="variant-render-audit": return cmd_variant_render_audit(a)
+    if a.command=="worker-health": return cmd_worker_health(a)
+    if a.command=="resolver-audit": return cmd_resolver_audit(a)
     if a.command=="inspect": return cmd_inspect(a)
     if a.command=="status": return cmd_status(a)
     data=load(project) if path(project).exists() else {}; errors=validate(data); print(json.dumps({"status":"passed" if not errors else "failed","errors":errors,"services":len(data.get("services",[]))},indent=2)); return 0 if not errors else 1

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.26",
+  "version": "0.7.28",
   "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