@topy-ai/maggie 0.7.24 → 0.7.26

package/README.md

@@ -60,6 +60,11 @@ 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
+contract (`maggie design app-init`/`app-validate`), direct Astro route
+resolution, correlated feedback batches, and runtime package-version capture.
+
 For repeatable browser QA, create a project-owned scenario manifest and record
 the test, fix, and retest lifecycle:
 
@@ -213,7 +218,7 @@ maggie design ...                # authorized interior-page design
 maggie clone-to-template ...     # URL → validated marketplace template
 maggie marketplace ...           # catalog and on-demand template workflow
 maggie memory ...                # confirmed preferences and lessons
-maggie feedback ...              # redact, preview, submit, list
+maggie feedback ...              # redact, preview, batch, submit, list
 maggie qa ...                    # scenario browser QA, fix/retest, release gate
 maggie localization ...          # plan, validate, review, publish, stale
 maggie service ...                # import, sync/report, catalogue, lifecycle, validate
@@ -393,8 +398,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.24 update --project . --force
-npx @topy-ai/maggie@0.7.24 cleanup --project .
+npx @topy-ai/maggie@0.7.26 update --project . --force
+npx @topy-ai/maggie@0.7.26 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -404,7 +409,10 @@ as a command-line argument:
 node scripts/publish-npm.mjs --maggie-env-file ../.env
 ```
 
-The 0.7.24 workflow adds browser-runtime `icon-rendered` assertions, sanitized
+The 0.7.25 workflow adds host-owned mobile app surface plans with signed-in
+camera-state QA, direct `.astro` route resolution, correlated feedback batch
+drafts, and runtime package-version precedence. The 0.7.24 workflow adds
+browser-runtime `icon-rendered` assertions, sanitized
 worker/browser parity preflight evidence, and the provider-neutral asynchronous
 service-onboarding contract. The 0.7.23 workflow adds the single-scroll-owner MaggieDash modal primitive,
 server-runtime-only auth/provider configuration guidance, best-effort optional
@@ -553,6 +561,15 @@ maggie feedback submit .maggie/feedback/<feedback-id>.json \
   --endpoint https://feedback.noblox.app/api/feedback --confirm
 ```
 
+For related observations, create 1–50 local drafts with shared correlation
+metadata and review them before submitting:
+
+```bash
+maggie feedback batch --project . --batch-file ./feedback-batch.json
+```
+
+The batch command never submits automatically or writes active memory.
+
 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.24 init --agent all
+npx @topy-ai/maggie@0.7.26 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 
@@ -25,6 +25,10 @@ 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
+camera-state QA、直接 Astro route resolution、correlated feedback batch，以及
+runtime package version capture。
+
 0.7.24 加入 `icon-rendered` browser QA assertion、worker/browser deployment parity
 preflight，以及 import/search/research 的非同步 service onboarding contract。
 0.7.23 加入 dashboard dialog 單一 scroll owner、server runtime-only auth/provider

package/bin/maggie.js

@@ -88,6 +88,8 @@ Usage:
   maggie design reference-ui --project PATH --reference PATH --surface blog,service --confirm
   maggie design init --project PATH --surface blog|service --reference-run PATH --confirm
   maggie design validate-ui --project PATH --plan PATH --rendered-dir PATH --confirm
+  maggie design app-init --project PATH --route /app/valuation --auth-mode email-password --confirm
+  maggie design app-validate --project PATH --plan PATH --runtime-evidence FILE --rendered-dir PATH --confirm
   maggie design icon-inventory --project PATH --source-dir src --runtime assets/icons.css --output docs/icon-inventory.json
   maggie design author --project PATH --route /about --purpose TEXT --audience TEXT --confirm
   maggie design in-place --project PATH --route /pricing [--content-source PATH]
@@ -124,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
@@ -327,7 +329,8 @@ function workflowCli(name, args) {
   const root = projectRoot(args);
   const script = join(root, "tools", "clis", name);
   if (!existsSync(script)) throw new Error(`${name} is missing: ${script}`);
-  const result = spawnSync("python3", [script, ...args], { stdio: "inherit", cwd: root });
+  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 });
   if (result.error) throw result.error;
   process.exitCode = result.status ?? 1;
 }

package/bundled-contracts/maggie-design/mobile-app-surface-v1.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/contracts/maggie-design/mobile-app-surface-v1.schema.json",
+  "title": "Maggie mobile app surface contract",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "workflow",
+    "mode",
+    "route",
+    "auth",
+    "shell",
+    "camera",
+    "viewports",
+    "requiredSteps",
+    "publicWrite"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "maggie-mobile-app-surface.v1"
+    },
+    "workflow": {
+      "const": "maggie-design"
+    },
+    "mode": {
+      "const": "app-view-init"
+    },
+    "route": {
+      "type": "string",
+      "pattern": "^/"
+    },
+    "auth": {
+      "type": "object",
+      "required": ["mode", "required", "credentialPolicy"],
+      "properties": {
+        "mode": {
+          "enum": ["email-password", "existing-session", "none"]
+        },
+        "required": {
+          "type": "boolean"
+        },
+        "credentialPolicy": {
+          "const": "use-host-auth-without-recording-credentials"
+        }
+      },
+      "additionalProperties": true
+    },
+    "shell": {
+      "type": "object",
+      "required": ["fixedHeader", "fixedFooter", "oneScrollOwner"],
+      "properties": {
+        "fixedHeader": {"const": true},
+        "fixedFooter": {"const": true},
+        "oneScrollOwner": {"const": true}
+      },
+      "additionalProperties": true
+    },
+    "camera": {
+      "type": "object",
+      "required": ["requiredStates", "controls", "fallback"],
+      "properties": {
+        "requiredStates": {
+          "type": "array",
+          "contains": {"const": "permission"}
+        },
+        "controls": {
+          "type": "array",
+          "minItems": 4
+        },
+        "fallback": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": true
+    },
+    "viewports": {
+      "type": "object",
+      "required": ["desktop", "tablet", "mobile"],
+      "additionalProperties": {
+        "type": "array",
+        "prefixItems": [
+          {"type": "integer", "minimum": 1},
+          {"type": "integer", "minimum": 1}
+        ],
+        "minItems": 2,
+        "maxItems": 2
+      }
+    },
+    "requiredSteps": {
+      "type": "array",
+      "contains": {"const": "signed-in-browser-qa"}
+    },
+    "publicWrite": {
+      "const": false
+    }
+  },
+  "additionalProperties": true
+}

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

@@ -2,7 +2,7 @@
 name: maggie-design
 description: Design authorized interior pages, review rendered responsive layouts, or explicitly rebrand a packaged homepage/template. Use rebrand only with a named source brand and target brand.
 metadata:
-  version: 1.5.0
+  version: 1.6.0
 ---
 
 # Maggie Design
@@ -10,7 +10,7 @@ metadata:
 ## In-place route evidence
 
 `maggie design in-place --project . --route /example` resolves local source
-files and falls back to a discovered `[...slug]`/`[[...slug]]` file. A catch-all
+files, including direct `src/pages/<route>.astro` files, and falls back to a discovered `[...slug]`/`[[...slug]]` file. A catch-all
 is recorded as `resolution: unproven` unless `--content-source` names the
 actual DB/content resolver. A source candidate is not proof that the concrete
 URL is served: verify the HTTP response, content identity, and framework route
@@ -202,6 +202,33 @@ semantics from `maggie-blog`. For service UI, preserve provider identity,
 variants, booking URLs, duplicate canonical/noindex decisions, and service
 sitemap semantics from `maggie-service-booking`.
 
+## Mobile app surfaces
+
+Use the app surface contract for camera, scan, inventory, valuation, or other
+authenticated app views. It is a general host contract, not a replacement for
+the project's auth or camera implementation:
+
+    maggie design app-init --project . --route /app/valuation \
+      --auth-mode email-password --confirm
+
+The initializer records the fixed header/footer, one-scroll-owner rule,
+camera permission/ready/gallery/scan/unavailable states, decision-critical UI,
+and desktop/tablet/mobile evidence requirements. It never collects credentials
+or copies private project data. Use `existing-session` only when the host
+already supplies a safe signed-in session; use `none` for public app surfaces.
+
+After implementation, validate sanitized runtime evidence and screenshots:
+
+    maggie design app-validate --project . \
+      --plan .maggie/design/app-view/app-<id>/plan.json \
+      --runtime-evidence ./qa/mobile-app-evidence.json \
+      --rendered-dir ./qa/screenshots --confirm
+
+The evidence must prove the auth state, fixed shell, exactly one scroll owner,
+all required camera states, and valid PNGs at 390px, 768px, and desktop
+widths. The machine-readable contract is
+[mobile-app-surface-v1.schema.json](../../bundled-contracts/maggie-design/mobile-app-surface-v1.schema.json).
+
 ## Explicit homepage rebrand mode
 
 The homepage `review` mode only compares screenshots. It does not rebrand a

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

@@ -2,7 +2,7 @@
 name: maggie-feedback
 description: Collect, review, and explicitly submit privacy-safe feedback about a Maggie skill run, workflow result, bug, or feature request.
 metadata:
-  version: 1.0.0
+  version: 1.1.0
 ---
 
 # Maggie Feedback
@@ -39,6 +39,41 @@ If a draft is marked fixed with `--fixed` (or the supplied run report says
 also scrubs common POSIX/home/temp and Windows absolute paths by default while
 preserving public URLs and route paths.
 
+The CLI records the executing Maggie package version when it is available from
+the runtime environment or `node_modules/@topy-ai/maggie/package.json`. A
+stale `.maggie/install.json` is only a fallback; conflicting runtime package
+versions fail closed as `unknown`.
+
+## Correlated feedback batches
+
+When several observations belong to one workflow run, create bounded drafts
+with one shared correlation ID instead of losing their relationship:
+
+    maggie feedback batch --project . --batch-file ./feedback-batch.json
+
+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.
+
+Example:
+
+    {
+      "batchId": "run-review-001",
+      "skill": "maggie-design",
+      "runId": "design-001",
+      "phase": "post-release-review",
+      "priority": "normal",
+      "affectedCli": "design",
+      "items": [
+        {"type": "bug", "summary": "Route evidence is incomplete", "expected": "Direct route resolves", "actual": "Fallback was used"},
+        {"type": "feature", "summary": "Need an app-surface QA contract", "expected": "Reusable evidence plan", "actual": "Only public-page rules exist"}
+      ]
+    }
+
 ## Submit explicitly
 
 The CLI never submits automatically. After reviewing the draft:

package/bundled-tools/clis/maggie_design.py

@@ -157,6 +157,114 @@ def validate_content_ui(project: Path, plan_path: Path, rendered_dir: Path | Non
     output = plan_path.parent / "validation.json"; output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"); print(json.dumps(result, indent=2, ensure_ascii=False)); return 0 if not errors else 1
 
 
+def app_surface_init(project: Path, route: str, auth_mode: str, force: bool, confirm: bool) -> int:
+    """Create a host-owned mobile app surface contract and QA manifest."""
+    project = project.resolve()
+    if not route.startswith("/") or "?" in route or "#" in route:
+        raise ValueError("route must be a path beginning with / and must not contain a query or hash")
+    if auth_mode not in {"email-password", "existing-session", "none"}:
+        raise ValueError("auth mode must be email-password, existing-session, or none")
+    contract = require_design_contract(project)
+    relative = route.strip("/")
+    candidates = [
+        project / relative,
+        project / "src" / "pages" / relative,
+        project / "src" / "pages" / f"{relative}.astro",
+        project / "src" / "pages" / f"{relative}.html",
+        project / "src" / "app" / relative,
+        project / "src" / "app" / relative / "page.tsx",
+    ]
+    source = next((path for path in candidates if path.is_file()), None)
+    digest = hashlib.sha256((str(project) + "\n" + route + "\n" + auth_mode).encode()).hexdigest()[:12]
+    output_dir = project / ".maggie" / "design" / "app-view" / f"app-{digest}"
+    if output_dir.exists() and not force:
+        print((output_dir / "plan.json").read_text(encoding="utf-8"), end="")
+        return 0
+    output_dir.mkdir(parents=True, exist_ok=True)
+    viewports = {"desktop": REVIEW_VIEWPORTS["desktop"], "tablet": REVIEW_VIEWPORTS["tablet"], "mobile": REVIEW_VIEWPORTS["mobile"]}
+    plan = {
+        "schemaVersion": "maggie-mobile-app-surface.v1",
+        "id": f"app-{digest}",
+        "workflow": "maggie-design",
+        "mode": "app-view-init",
+        "phase": "ready",
+        "route": route,
+        "routeSource": str(source) if source else None,
+        "designContract": contract,
+        "auth": {"mode": auth_mode, "required": auth_mode != "none", "credentialPolicy": "use-host-auth-without-recording-credentials"},
+        "shell": {"fixedHeader": True, "fixedFooter": True, "oneScrollOwner": True, "cameraMayUseFullScreenViewport": True, "hostShellSourceOfTruth": "existing homepage shell"},
+        "camera": {"requiredStates": ["permission", "ready", "gallery", "scan", "unavailable"], "controls": ["close", "gallery", "shutter", "mode"], "fallback": "show an actionable unavailable state; never leave a black screen"},
+        "decisionCriticalUi": ["card normalization", "graded-price fallback", "grade-9-to-10 economics", "scan-to-inventory or valuation transition"],
+        "viewports": viewports,
+        "requiredSteps": ["inspect-host-shell", "define-auth-gate", "define-camera-states", "capture-desktop-tablet-mobile", "signed-in-browser-qa", "accessibility-check", "route-validation", "explicit-approval"],
+        "provenance": {"hostOwnsAuthAndCamera": True, "designContractReused": True, "privateDataCopied": False},
+        "publicWrite": False,
+        "createdAt": datetime.now(timezone.utc).isoformat(),
+    }
+    evidence = {
+        "schemaVersion": "maggie-mobile-app-evidence.v1",
+        "route": route,
+        "auth": plan["auth"],
+        "shell": plan["shell"],
+        "camera": plan["camera"],
+        "viewports": {name: {"screenshot": f"{name}.png", "captured": False} for name in viewports},
+        "status": "pending",
+    }
+    qa = {"schemaVersion": "maggie-mobile-app-qa.v1", "route": route, "auth": plan["auth"], "scenarios": [
+        {"id": "shell-scroll", "viewport": "mobile", "assertions": ["fixed header and footer remain usable", "exactly one scroll owner"]},
+        {"id": "camera-permission", "viewport": "mobile", "assertions": ["permission state is explained", "denied permission shows fallback"]},
+        {"id": "camera-scan", "viewport": "mobile", "assertions": ["gallery/shutter/mode/close controls are reachable", "scan result can enter inventory or valuation"]},
+        {"id": "valuation-auth", "viewport": "desktop", "assertions": ["signed-in route does not redirect unexpectedly", "grade economics and fallback price remain legible"]},
+    ]}
+    (output_dir / "plan.json").write_text(json.dumps(plan, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    (output_dir / "qa-scenarios.json").write_text(json.dumps(qa, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    (output_dir / "validation.json").write_text(json.dumps(evidence, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    (output_dir / "screenshots").mkdir(exist_ok=True)
+    print(json.dumps({"plan": str(output_dir / "plan.json"), "qaScenarios": str(output_dir / "qa-scenarios.json"), "surface": "app", "phase": "ready", "publicWrite": False}, indent=2, ensure_ascii=False))
+    return 0
+
+
+def validate_app_surface(project: Path, plan_path: Path, rendered_dir: Path | None, runtime_evidence: Path | None, confirm: bool) -> int:
+    """Validate signed-in app evidence and responsive screenshots."""
+    project = project.resolve(); plan_path = plan_path.resolve()
+    if not plan_path.exists(): raise ValueError(f"app surface plan not found: {plan_path}")
+    plan = json.loads(plan_path.read_text(encoding="utf-8")); errors = []
+    if plan.get("workflow") != "maggie-design" or plan.get("mode") != "app-view-init": errors.append("invalid mobile app surface plan")
+    if plan.get("publicWrite") is not False: errors.append("publicWrite must remain false before approval")
+    if not plan.get("shell", {}).get("oneScrollOwner"): errors.append("app surface must define one scroll owner")
+    if not plan.get("auth", {}).get("credentialPolicy"): errors.append("app surface must define a credential policy")
+    try: require_design_contract(project)
+    except ValueError as error: errors.append(str(error))
+    evidence = {}
+    evidence_path = runtime_evidence.resolve() if runtime_evidence else plan_path.parent / "runtime-evidence.json"
+    if evidence_path.is_file():
+        try: evidence = json.loads(evidence_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError: errors.append("runtime evidence is not valid JSON")
+    else:
+        errors.append("runtime evidence file is required")
+    if evidence:
+        if evidence.get("schemaVersion") != "maggie-mobile-app-evidence.v1": errors.append("runtime evidence schemaVersion is invalid")
+        if evidence.get("route") != plan.get("route"): errors.append("runtime evidence route does not match plan")
+        auth = evidence.get("auth", {})
+        if plan.get("auth", {}).get("required") and auth.get("signedIn") is not True: errors.append("signed-in evidence is required for this app route")
+        shell = evidence.get("shell", {})
+        if shell.get("fixedHeader") is not True or shell.get("fixedFooter") is not True or shell.get("scrollOwnerCount") != 1: errors.append("runtime evidence must prove fixed shell and one scroll owner")
+        camera = evidence.get("camera", {})
+        camera_states = set(camera.get("states", [])) if isinstance(camera, dict) else set()
+        if not set(plan.get("camera", {}).get("requiredStates", [])).issubset(camera_states): errors.append("runtime evidence is missing a required camera state")
+    screenshot_status = {}
+    for name in ("desktop", "tablet", "mobile"):
+        path = (rendered_dir / f"{name}.png") if rendered_dir else plan_path.parent / "screenshots" / f"{name}.png"
+        valid = path.is_file() and path.read_bytes()[:8] == b"\x89PNG\r\n\x1a\n"
+        screenshot_status[name] = {"path": str(path), "validPng": valid}
+        if not valid: errors.append(f"missing valid {name} screenshot")
+    result = {"schemaVersion": "maggie-mobile-app-validation.v1", "plan": str(plan_path), "route": plan.get("route"), "screenshots": screenshot_status, "runtimeEvidence": str(evidence_path), "checks": {"fixedShell": not any("fixed shell" in error for error in errors), "signedInRoute": not any("signed-in" in error for error in errors), "cameraStates": not any("camera state" in error for error in errors), "publicWriteBlocked": plan.get("publicWrite") is False}, "status": "passed" if not errors else "failed", "errors": errors, "validatedAt": datetime.now(timezone.utc).isoformat()}
+    if confirm:
+        plan_path.parent.joinpath("validation.json").write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if not errors else 1
+
+
 def rebrand_template(args: argparse.Namespace) -> int:
     """Apply an explicit brand identity to a packaged homepage template."""
     template = args.template.resolve()
@@ -547,6 +655,7 @@ def in_place_job(project: Path, routes: list[str], force: bool = False, content_
             project / relative,
             project / "src" / "pages" / relative,
             project / "src" / "app" / relative,
+            project / "src" / "pages" / f"{relative}.astro",
             project / "src" / "pages" / f"{relative}.html",
             project / "src" / "app" / relative / "page.tsx",
         ]
@@ -680,7 +789,7 @@ commands:
   status       show a design job and its per-step progress
   resume       restart a failed design workflow
   author       plan an original first-party page
-  reference-ui, init, validate-ui, rebrand, review
+  reference-ui, init, validate-ui, app-init, app-validate, rebrand, review
 """)
         return 0
     if len(sys.argv) > 1 and sys.argv[1] == "reference-ui":
@@ -719,6 +828,30 @@ commands:
             return validate_content_ui(args.project, args.plan, args.rendered_dir, args.confirm)
         except (OSError, ValueError, json.JSONDecodeError) as error:
             print(f"BLOCKED: maggie-design validate-ui: {error}", file=sys.stderr); return 1
+    if len(sys.argv) > 1 and sys.argv[1] == "app-init":
+        command = argparse.ArgumentParser(description="Create a mobile app surface contract with signed-in QA scenarios.")
+        command.add_argument("--project", type=Path, default=Path.cwd())
+        command.add_argument("--route", required=True)
+        command.add_argument("--auth-mode", choices=["email-password", "existing-session", "none"], default="email-password")
+        command.add_argument("--force", action="store_true")
+        command.add_argument("--confirm", action="store_true")
+        args = command.parse_args(sys.argv[2:])
+        try:
+            return app_surface_init(args.project, args.route, args.auth_mode, args.force, args.confirm)
+        except (OSError, ValueError, json.JSONDecodeError) as error:
+            print(f"BLOCKED: maggie-design app-init: {error}", file=sys.stderr); return 1
+    if len(sys.argv) > 1 and sys.argv[1] == "app-validate":
+        command = argparse.ArgumentParser(description="Validate mobile app runtime evidence and responsive screenshots.")
+        command.add_argument("--project", type=Path, default=Path.cwd())
+        command.add_argument("--plan", type=Path, required=True)
+        command.add_argument("--rendered-dir", type=Path)
+        command.add_argument("--runtime-evidence", type=Path)
+        command.add_argument("--confirm", action="store_true")
+        args = command.parse_args(sys.argv[2:])
+        try:
+            return validate_app_surface(args.project, args.plan, args.rendered_dir, args.runtime_evidence, args.confirm)
+        except (OSError, ValueError, json.JSONDecodeError) as error:
+            print(f"BLOCKED: maggie-design app-validate: {error}", file=sys.stderr); return 1
     if len(sys.argv) > 1 and sys.argv[1] == "rebrand":
         rebrand = argparse.ArgumentParser(description="Apply an explicit brand identity to a packaged marketplace template.")
         rebrand.add_argument("--template", type=Path, required=True)

package/bundled-tools/clis/maggie_feedback.py

@@ -27,6 +27,7 @@ LOCAL_PATH_RE = re.compile(
     r"\\\\[^\\/\s,;:)\]}]+(?:[\\/]+[^\\/\s,;:)\]}]+)+)"
 )
 VERSION_RE = re.compile(r"\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?")
+SAFE_BATCH_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$")
 ACKNOWLEDGEMENT_KEYS = ("status", "feedbackId", "requestId")
 REPO_ROOT = Path(__file__).resolve().parents[2]
 
@@ -45,10 +46,25 @@ def project_fingerprint(project: Path) -> str:
 
 
 def installed_version(project: Path) -> str:
-    """Resolve the exact runtime version and fail closed on source drift."""
+    """Resolve the exact runtime version, preferring the running package."""
     if os.environ.get("MAGGIE_VERSION"):
         value = safe_text(os.environ["MAGGIE_VERSION"])
         return value if VERSION_RE.fullmatch(value) else "unknown"
+
+    # A consumer project can retain an old .maggie/install.json after npm
+    # upgrade. The package actually being executed is stronger evidence.
+    package_versions = []
+    for parent in (project.resolve(), *project.resolve().parents):
+        package_path = parent / "node_modules" / "@topy-ai" / "maggie" / "package.json"
+        try:
+            value = json.loads(package_path.read_text(encoding="utf-8")).get("version", "")
+            if VERSION_RE.fullmatch(str(value)):
+                package_versions.append(str(value))
+        except (OSError, ValueError, json.JSONDecodeError, AttributeError):
+            continue
+    if package_versions:
+        return package_versions[0] if len(set(package_versions)) == 1 else "unknown"
+
     install_path = project / ".maggie" / "install.json"
     try:
         value = json.loads(install_path.read_text(encoding="utf-8")).get("version", "")
@@ -102,6 +118,20 @@ def collect(args: argparse.Namespace) -> int:
     validation = safe_text(args.validation or report.get("validation"))
     if fixed and (not resolution or not validation):
         raise ValueError("fixed feedback requires non-empty --resolution and --validation")
+    batch_id = safe_text(getattr(args, "batch_id", ""))
+    batch_index = getattr(args, "batch_index", None)
+    batch_size = getattr(args, "batch_size", None)
+    if batch_id:
+        if not SAFE_BATCH_ID_RE.fullmatch(batch_id):
+            raise ValueError("batch ID is invalid")
+        if not isinstance(batch_index, int) or isinstance(batch_index, bool) or batch_index < 0:
+            raise ValueError("batch index is required when batch ID is provided")
+        if not isinstance(batch_size, int) or isinstance(batch_size, bool) or batch_size < 1 or batch_index >= batch_size:
+            raise ValueError("batch size must be positive and greater than batch index")
+    priority = safe_text(getattr(args, "priority", "") or "normal").lower()
+    if priority not in {"low", "normal", "high", "critical"}:
+        raise ValueError("priority must be low, normal, high, or critical")
+    affected_cli = safe_text(getattr(args, "affected_cli", ""))
     context = {"projectFingerprint": project_fingerprint(project)}
     if args.allow_project_context and args.context_note:
         context["note"] = safe_text(args.context_note)
@@ -124,12 +154,16 @@ def collect(args: argparse.Namespace) -> int:
         "fixed": fixed,
         "resolution": resolution,
         "validation": validation,
+        "priority": priority,
+        "affectedCli": affected_cli,
         "attachments": [attachment(value) for value in args.screenshot],
         "environment": {"os": platform.system().lower(), "python": platform.python_version()},
         "privacy": {"secretsRedacted": True, "projectContextAllowed": bool(args.allow_project_context)},
         "projectContext": context if args.allow_project_context else None,
         "submission": {"status": "draft"},
     }
+    if batch_id:
+        data["batch"] = {"batchId": batch_id, "index": batch_index, "size": batch_size}
     directory = project / ".maggie" / "feedback"
     directory.mkdir(parents=True, exist_ok=True)
     path = directory / f"{data['feedbackId']}.json"
@@ -144,7 +178,11 @@ def collect(args: argparse.Namespace) -> int:
 
 
 def to_markdown(data: dict) -> str:
-    lines = [f"# Maggie feedback: {data.get('summary') or data.get('type')}", "", "<!-- Generated by maggie feedback. Secrets and local paths are omitted. -->", "", "## Run", "", f"- Skill: `{data.get('skill')}`", f"- Maggie version: `{data.get('maggieVersion')}`", f"- Run ID: `{data.get('runId') or 'not provided'}`", f"- Phase: `{data.get('phase') or 'not provided'}`", f"- Status: `{data.get('status')}`", f"- Error fingerprint: `{data.get('errorFingerprint') or 'not provided'}`", "", "## Report", "", f"**Summary:** {data.get('summary') or 'Not provided'}", "", f"**Expected:** {data.get('expected') or 'Not provided'}", "", f"**Actual:** {data.get('actual') or 'Not provided'}", ""]
+    batch = data.get("batch") or {}
+    lines = [f"# Maggie feedback: {data.get('summary') or data.get('type')}", "", "<!-- Generated by maggie feedback. Secrets and local paths are omitted. -->", "", "## Run", "", f"- Skill: `{data.get('skill')}`", f"- Maggie version: `{data.get('maggieVersion')}`", f"- Run ID: `{data.get('runId') or 'not provided'}`", f"- Phase: `{data.get('phase') or 'not provided'}`", f"- Status: `{data.get('status')}`", f"- Priority: `{data.get('priority') or 'normal'}`", f"- Affected CLI: `{data.get('affectedCli') or 'not provided'}`", f"- Error fingerprint: `{data.get('errorFingerprint') or 'not provided'}`"]
+    if batch:
+        lines.append(f"- Batch: `{batch.get('batchId')}` ({batch.get('index', 0) + 1}/{batch.get('size')})")
+    lines += ["", "## Report", "", f"**Summary:** {data.get('summary') or 'Not provided'}", "", f"**Expected:** {data.get('expected') or 'Not provided'}", "", f"**Actual:** {data.get('actual') or 'Not provided'}", ""]
     if data.get("stepsToReproduce"):
         lines += ["**Steps to reproduce:**", ""] + [f"{index}. {step}" for index, step in enumerate(data["stepsToReproduce"], 1)] + [""]
     lines += [f"**Fixed:** {'yes' if data.get('fixed') else 'no'}", f"**Resolution:** {data.get('resolution') or 'Not provided'}", f"**Validation:** {data.get('validation') or 'Not provided'}", "", "## Privacy", "", f"- Project context allowed: `{bool(data.get('privacy', {}).get('projectContextAllowed'))}`", f"- Attachments: `{len(data.get('attachments', []))}` metadata-only reference(s)", ""]
@@ -211,6 +249,57 @@ def list_feedback(args: argparse.Namespace) -> int:
     return 0
 
 
+def collect_batch(args: argparse.Namespace) -> int:
+    """Create one privacy-safe draft per item while retaining shared batch context."""
+    manifest = load_json(Path(args.batch_file).expanduser().resolve())
+    batch_id = safe_text(manifest.get("batchId"))
+    if not SAFE_BATCH_ID_RE.fullmatch(batch_id):
+        raise ValueError("batch file requires a safe batchId")
+    items = manifest.get("items")
+    if not isinstance(items, list) or not items or len(items) > 50:
+        raise ValueError("batch file requires between 1 and 50 items")
+    shared = {
+        "skill": safe_text(manifest.get("skill")),
+        "run_id": safe_text(manifest.get("runId")),
+        "phase": safe_text(manifest.get("phase")),
+        "priority": safe_text(manifest.get("priority") or "normal"),
+        "affected_cli": safe_text(manifest.get("affectedCli")),
+    }
+    paths = []
+    for index, item in enumerate(items):
+        if not isinstance(item, dict):
+            raise ValueError(f"items[{index}] must be an object")
+        values = {
+            "project": args.project,
+            "run_report": None,
+            "skill": safe_text(item.get("skill") or shared["skill"]),
+            "run_id": safe_text(item.get("runId") or shared["run_id"]),
+            "type": item.get("type", "bug"),
+            "phase": safe_text(item.get("phase") or shared["phase"]),
+            "summary": item.get("summary", ""),
+            "expected": item.get("expected", ""),
+            "actual": item.get("actual", ""),
+            "error_fingerprint": item.get("errorFingerprint", ""),
+            "reproduce": item.get("stepsToReproduce", []),
+            "fixed": item.get("fixed") is True,
+            "resolution": item.get("resolution", ""),
+            "validation": item.get("validation", ""),
+            "screenshot": item.get("screenshots", []),
+            "allow_project_context": False,
+            "context_note": "",
+            "batch_id": batch_id,
+            "batch_index": index,
+            "batch_size": len(items),
+            "priority": item.get("priority") or shared["priority"],
+            "affected_cli": item.get("affectedCli") or shared["affected_cli"],
+        }
+        if not isinstance(values["reproduce"], list): values["reproduce"] = []
+        if not isinstance(values["screenshot"], list): values["screenshot"] = []
+        paths.append(collect(argparse.Namespace(**values)))
+    print(json.dumps({"batchId": batch_id, "count": len(paths), "status": "drafts-created"}, ensure_ascii=False))
+    return 0
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--project", default=".")
@@ -235,6 +324,14 @@ def main() -> int:
     collect_parser.add_argument("--screenshot", action="append", default=[])
     collect_parser.add_argument("--allow-project-context", action="store_true")
     collect_parser.add_argument("--context-note", default="")
+    collect_parser.add_argument("--batch-id", default="")
+    collect_parser.add_argument("--batch-index", type=int)
+    collect_parser.add_argument("--batch-size", type=int)
+    collect_parser.add_argument("--priority", choices=("low", "normal", "high", "critical"), default="normal")
+    collect_parser.add_argument("--affected-cli", default="")
+    batch_parser = sub.add_parser("batch")
+    batch_parser.add_argument("--project", default=argparse.SUPPRESS)
+    batch_parser.add_argument("--batch-file", required=True)
     preview_parser = sub.add_parser("preview")
     preview_parser.add_argument("feedback")
     preview_parser.add_argument("--format", choices=("json", "markdown"), default="json")
@@ -246,6 +343,7 @@ def main() -> int:
     args = parser.parse_args()
     try:
         if args.command == "collect": return collect(args)
+        if args.command == "batch": return collect_batch(args)
         if args.command == "preview": return preview(args)
         if args.command == "submit": return submit(args)
         return list_feedback(args)

package/package.json

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