@topy-ai/maggie 0.7.23 → 0.7.25

package/README.md

@@ -60,6 +60,10 @@ 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
+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:
 
@@ -87,7 +91,9 @@ maggie qa assertion-audit --project . \
 
 For a dialog or drawer, include a browser-runtime `scroll-owner-count` check
 with `expected: 1`. This catches the fixed-shell plus inner-content double
-scrollbar that static class checks can miss.
+scrollbar that static class checks can miss. For icon controls, use
+`icon-rendered` with a visible glyph, positive width/height, and an accessible
+label; this catches a missing runtime glyph that build/typecheck cannot see.
 
 Dashboard and documentation audits are provider-neutral and keep host data
 behind explicit evidence files:
@@ -211,10 +217,10 @@ 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
+maggie service ...                # import, sync/report, catalogue, lifecycle, validate
 maggie seo performance ...       # sampled PageSpeed/CWV report and baseline
 maggie seo images ...             # inventory, variants, confirmation, validate
 maggie seo sitemap ...            # typed/semantic plan, agent-files, apply, rollback
@@ -224,6 +230,7 @@ maggie seo head-tags ...          # rendered-shell head metadata drift audit
 maggie ops favicon-check ...      # served favicon behaviour check
 maggie deployment | migration | release | analytics | schedule
 maggie deployment readiness --project PATH
+maggie deployment parity --project PATH --evidence FILE --output FILE
 maggie migration identity --identity-file FILE [--expected-file FILE]
 maggie deployment canary --asset URL=SHA256 --render-report report.json
 maggie design icon-inventory --source-dir src --runtime assets/icons.css
@@ -298,6 +305,11 @@ maggie design icon-inventory --project . --source-dir src \
   --runtime public/assets/icons.css --output docs/icon-inventory.json
 ```
 
+The inventory covers compound selectors such as `.ph.ph-arrow-square-out`
+and is only static name coverage. Pair changed icon controls with a
+browser-runtime `icon-rendered` assertion so the host adapter proves that the
+glyph is visible, has positive dimensions, and has an accessible label.
+
 After deployment, compare an immutable asset fingerprint and validate the
 browser adapter's rendered report:
 
@@ -312,8 +324,23 @@ The canary report requires a screenshot and zero console errors, missing
 assets, and visual placeholders for every route. It records safe cache headers
 only and never stores response bodies, cookies, or credentials.
 
+When workers, migrations, browser drivers, import jobs, or route APIs are part
+of the deployment, validate their sanitized parity evidence before the canary:
+
+```bash
+maggie deployment parity --project . \
+  --evidence .maggie/verification/runtime-parity-input.json \
+  --output .maggie/verification/runtime-parity.json
+```
+
+The parity contract checks required worker configuration, migration
+privileges, route API status, stale resident processes, source-job IDs, and
+browser/driver compatibility. Add the resulting report to readiness with
+`--runtime-parity`; a failed report blocks the gate.
+
 Unit regression does not establish runtime release readiness. Produce unit
-evidence and then validate all five release evidence slots:
+evidence and then validate all required release evidence slots; add
+`--runtime-parity` when the deployment uses the worker/browser surfaces above:
 
 ```bash
 python3 tools/tests/run_regression.py \
@@ -323,13 +350,27 @@ maggie deployment readiness --project . \
   --browser-report .maggie/verification/browser-evidence.json \
   --rendered-canary .maggie/deployment-canary.json \
   --deployment-preflight .maggie/release-preflight.json \
+  --runtime-parity .maggie/verification/runtime-parity.json \
   --output .maggie/deployment-readiness.json
 ```
 
 The readiness report follows `maggie-deployment-readiness.v1`. It reports unit
 regression, package smoke, host browser evidence, rendered canary, and
 deployment preflight separately. Missing host adapter evidence is
-`inconclusive`; only five passing slots produce `passed`.
+`inconclusive`; only all configured slots produce `passed`.
+
+For service-booking hosts, validate independent import, local-search, and
+website-research jobs before public generation:
+
+```bash
+maggie service orchestration-validate --project . \
+  --manifest .maggie/booking/onboarding-orchestration.json \
+  --output docs/service-onboarding-orchestration.json
+```
+
+The contract requires unique idempotency keys, bounded retry history, pollable
+status references, and disjoint field ownership so one onboarding workflow
+cannot overwrite another.
 
 ### Localization and analytics release gates
 
@@ -356,8 +397,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.23 update --project . --force
-npx @topy-ai/maggie@0.7.23 cleanup --project .
+npx @topy-ai/maggie@0.7.25 update --project . --force
+npx @topy-ai/maggie@0.7.25 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -367,7 +408,12 @@ as a command-line argument:
 node scripts/publish-npm.mjs --maggie-env-file ../.env
 ```
 
-The 0.7.23 workflow adds the single-scroll-owner MaggieDash modal primitive,
+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
 identity-mirror semantics, and `scroll-owner-count` browser QA evidence. The
 0.7.22 workflow adds provider-catalogue authority checks, field/variant
@@ -514,6 +560,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.23 init --agent all
+npx @topy-ai/maggie@0.7.25 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 
@@ -25,6 +25,12 @@ 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
+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
 設定規則、optional identity mirror 的 best-effort 邊界，以及 QA 的
 `scroll-owner-count` browser evidence。0.7.22 加入 provider catalogue authority check、field/variant sync report、

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]
@@ -108,10 +110,12 @@ Usage:
   maggie service validate --project PATH
   maggie service inspect --project PATH
   maggie service status --project PATH
+  maggie service orchestration-validate --project PATH --manifest FILE
   maggie service convert-page <page-path> --project PATH
   maggie service match-pages --project PATH --pages-dir src/pages
   maggie deployment --project PATH --target vps-with-cloudflare-dns
   maggie deployment readiness --project PATH
+  maggie deployment parity --project PATH --evidence FILE --output FILE
   maggie deployment canary --project PATH --asset URL=SHA256 --render-report report.json --output docs/deployment-canary.json
   maggie migration --project PATH --environment staging
   maggie migration identity --identity-file FILE [--expected-file FILE]
@@ -301,7 +305,8 @@ function marketplace(args) {
 
 function service(args) {
   const root = projectRoot(args);
-  const script = join(root, "tools", "clis", "maggie_service_booking.py");
+  const scriptName = args[0] === "orchestration-validate" ? "maggie_service_onboarding.py" : "maggie_service_booking.py";
+  const script = join(root, "tools", "clis", scriptName);
   if (!existsSync(script)) throw new Error(`service booking CLI is missing: ${script}`);
   const result = spawnSync("python3", [script, ...args], { stdio: "inherit", cwd: root, env: { ...process.env, MAGGIE_VERSION: PACKAGE_VERSION } });
   if (result.error) throw result.error;
@@ -324,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;
 }
@@ -413,6 +419,7 @@ try {
   else if (command === "ops") workflowCli("maggie_ops.py", args);
   else if (command === "deployment" && args[0] === "canary") workflowCli("maggie_deployment_canary.py", args.slice(1));
   else if (command === "deployment" && args[0] === "readiness") workflowCli("maggie_deployment_readiness.py", args.slice(1));
+  else if (command === "deployment" && args[0] === "parity") workflowCli("maggie_deployment_parity.py", args.slice(1));
   else if (command === "deployment") workflowCli("maggie_deployment.py", args);
   else if (command === "migration") workflowCli("maggie_migration.py", args);
   else if (command === "schedule") workflowCli("maggie_schedule.py", args);

package/bundled-contracts/maggie-deployment/readiness-v1.schema.json

@@ -16,7 +16,8 @@
         "packageSmoke": {"$ref": "#/$defs/check"},
         "browserEvidence": {"$ref": "#/$defs/check"},
         "renderedCanary": {"$ref": "#/$defs/check"},
-        "deploymentPreflight": {"$ref": "#/$defs/check"}
+        "deploymentPreflight": {"$ref": "#/$defs/check"},
+        "runtimeParity": {"$ref": "#/$defs/check"}
       }
     }
   },

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

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggie.noblox.app/contracts/deployment-runtime-parity-v1.json",
+  "title": "Maggie deployment worker and browser runtime parity evidence",
+  "type": "object",
+  "required": ["schemaVersion", "environment", "passed", "worker", "browser"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-deployment-runtime-parity.v1"},
+    "environment": {"enum": ["development", "staging", "production"]},
+    "passed": {"const": true},
+    "worker": {
+      "type": "object",
+      "required": ["config", "migration", "routeApis", "residentProcesses", "sourceJobs"],
+      "properties": {
+        "config": {"$ref": "#/$defs/config"},
+        "migration": {"type": "object", "required": ["privilegeCheck"], "properties": {"privilegeCheck": {"$ref": "#/$defs/passed"}}},
+        "routeApis": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/route"}},
+        "residentProcesses": {"$ref": "#/$defs/processes"},
+        "sourceJobs": {"type": "array", "items": {"$ref": "#/$defs/job"}}
+      },
+      "additionalProperties": true
+    },
+    "browser": {
+      "type": "object",
+      "required": ["browserVersion", "driverVersion", "compatible"],
+      "properties": {"browserVersion": {"type": "string", "minLength": 1}, "driverVersion": {"type": "string", "minLength": 1}, "compatible": {"const": true}},
+      "additionalProperties": true
+    }
+  },
+  "$defs": {
+    "passed": {"type": "object", "required": ["passed"], "properties": {"passed": {"const": true}}, "additionalProperties": true},
+    "config": {"type": "object", "required": ["required", "missing", "passed"], "properties": {"required": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}, "missing": {"type": "array", "maxItems": 0}, "passed": {"const": true}}, "additionalProperties": true},
+    "route": {"type": "object", "required": ["method", "path", "status", "passed"], "properties": {"method": {"type": "string"}, "path": {"type": "string", "pattern": "^/"}, "status": {"type": "integer", "minimum": 200, "maximum": 399}, "passed": {"const": true}}, "additionalProperties": true},
+    "processes": {"type": "object", "required": ["checked", "unexpected", "stale", "passed"], "properties": {"checked": {"const": true}, "unexpected": {"type": "array", "maxItems": 0}, "stale": {"type": "array", "maxItems": 0}, "passed": {"const": true}}, "additionalProperties": true},
+    "job": {"type": "object", "required": ["jobId", "passed"], "properties": {"jobId": {"type": "string", "minLength": 1}, "passed": {"const": true}}, "additionalProperties": true}
+  },
+  "additionalProperties": true
+}

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-contracts/maggie-service-booking/onboarding-orchestration-v1.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggie.noblox.app/contracts/service-onboarding-orchestration-v1.json",
+  "title": "Maggie provider-neutral asynchronous service onboarding orchestration",
+  "type": "object",
+  "required": ["schemaVersion", "workflows", "fieldOwnership"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-service-onboarding-orchestration.v1"},
+    "workflows": {"type": "array", "minItems": 3, "maxItems": 3, "items": {"$ref": "#/$defs/workflow"}},
+    "fieldOwnership": {"type": "object", "minProperties": 1, "additionalProperties": {"enum": ["import", "search", "research"]}}
+  },
+  "$defs": {
+    "workflow": {
+      "type": "object",
+      "required": ["name", "jobId", "idempotencyKey", "state", "history", "attempt", "maxAttempts", "owner", "statusRef", "nextAction", "writes"],
+      "properties": {
+        "name": {"enum": ["import", "search", "research"]},
+        "jobId": {"type": "string", "minLength": 1},
+        "idempotencyKey": {"type": "string", "minLength": 1},
+        "state": {"enum": ["queued", "running", "succeeded", "failed", "blocked", "cancelled"]},
+        "history": {"type": "array", "minItems": 1, "items": {"type": "object", "required": ["state", "at"], "properties": {"state": {"type": "string"}, "at": {"type": "string"}}}},
+        "attempt": {"type": "integer", "minimum": 1},
+        "maxAttempts": {"type": "integer", "minimum": 1},
+        "owner": {"type": "string", "minLength": 1},
+        "statusRef": {"type": "string", "minLength": 1},
+        "nextAction": {"type": "string", "minLength": 1},
+        "writes": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+        "errorCode": {"type": ["string", "null"]}
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

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

@@ -2,7 +2,7 @@
 name: maggie-deployment
 description: Deploy and operate Maggie blog projects with Cloudflare Workers as the default target, while preserving an adapter boundary for VPS, GCP, and AWS.
 metadata:
-  version: 1.3.0
+  version: 1.4.0
 ---
 
 # Maggie Deployment
@@ -37,12 +37,33 @@ visitor-facing files. The canary must include screenshots, zero console or
 network errors, and zero placeholder matches. Query-driven routes belong in
 behavior/API checks, not static byte baselines.
 
+## Worker/browser runtime parity
+
+Before a canary when the release depends on workers, migrations, browser
+automation, import jobs, or route APIs, collect sanitized host-adapter evidence
+and validate it before traffic moves:
+
+```bash
+maggie deployment parity --project . \
+  --evidence .maggie/verification/runtime-parity-input.json \
+  --output .maggie/verification/runtime-parity.json
+```
+
+The `maggie-deployment-runtime-parity.v1` contract checks required worker
+configuration and missing bindings, migration privileges, route API status,
+stale/unexpected resident import processes, non-empty source-job IDs, and
+browser/driver compatibility. It is provider-neutral: the host adapter runs
+the environment checks and supplies only safe facts; Maggie validates the
+evidence and never receives credentials, cookies, or response bodies. A failed
+parity report blocks the readiness command and therefore the canary.
+
 ## Release readiness evidence
 
 Unit regression is necessary but does not prove runtime release readiness. The
-readiness command keeps five evidence slots separate: dependency-free unit
-regression, package smoke, host browser evidence, rendered canary, and
-deployment preflight:
+readiness command keeps five required evidence slots separate: dependency-free
+unit regression, package smoke, host browser evidence, rendered canary, and
+deployment preflight. Add the optional `runtimeParity` slot whenever the
+release uses the worker/browser surfaces described above:
 
 ```bash
 python3 tools/tests/run_regression.py \
@@ -52,12 +73,13 @@ maggie deployment readiness --project . \
   --browser-report .maggie/verification/browser-evidence.json \
   --rendered-canary .maggie/deployment-canary.json \
   --deployment-preflight .maggie/release-preflight.json \
+  --runtime-parity .maggie/verification/runtime-parity.json \
   --output .maggie/deployment-readiness.json
 ```
 
 The report follows `maggie-deployment-readiness.v1`. A failed evidence file
 returns `failed`; a missing or unavailable host/browser adapter returns
-`inconclusive`; only five passing evidence slots return `passed`. Maggie does
+`inconclusive`; only all configured evidence slots return `passed`. Maggie does
 not fabricate browser, rendered, or deployment evidence and does not deploy
 from this command. See
 [`readiness-v1.schema.json`](../../bundled-contracts/maggie-deployment/readiness-v1.schema.json).

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.4.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
@@ -55,9 +55,18 @@ Use `missing`, `unknown`, and `coverage` from the versioned
 name map is reported as evidence only; it must not be treated as proof that a
 glyph exists. Fix the source token or add the runtime definition before
 shipping. The inventory compares a scoped runtime icon family (`ph-*`, `fa-*`,
-or `lucide-*`), normalizes family prefixes, and ignores inline SVG IDs and font
-filename noise. Do not paste private source, URLs with credentials, or user
-data into the report.
+or `lucide-*`), including compound CSS selectors such as
+`.ph.ph-arrow-square-out`, normalizes family prefixes, and ignores inline SVG
+IDs and font filename noise. Do not paste private source, URLs with
+credentials, or user data into the report.
+
+Inventory is static name coverage, not proof that the browser painted a glyph.
+For every new or changed icon control, pair it with the QA `icon-rendered`
+assertion: the host browser adapter must record a visible glyph, positive
+rendered width and height, and an accessible label. If the runtime font/map
+cannot render the icon, add an approved runtime definition or inline SVG
+fallback and rerun both checks. Never release a source token solely because
+typecheck or build succeeded.
 
 ## Automatic memory hook
 
@@ -193,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-skills/maggie-qa-workflow/SKILL.md

@@ -2,7 +2,7 @@
 name: maggie-qa-workflow
 description: Run scenario-based browser QA with explicit evidence, fix/retest lifecycle, and release-gate decisions for web projects.
 metadata:
-  version: 1.1.0
+  version: 1.2.0
 ---
 
 # Maggie QA Workflow
@@ -91,10 +91,14 @@ HTTP status evidence, a screenshot/reference, and boolean results for runtime
 checks such as `text-present`, `text-absent`, `meta`, `link-absent`, or
 `redirect`. For dialogs and drawers, `scroll-owner-count` records the browser
 runtime's computed number of intentional scroll owners and must use
-`expected: 1`. Source/class/markup-only checks are rejected. The audit stores
-assertion IDs and safe pass/fail metadata, never response bodies, credentials,
-or cookies. A passing assertion audit complements browser evidence; it does
-not replace the host adapter's actual HTTP and screenshot capture.
+`expected: 1`. For an icon control, `icon-rendered` records browser-runtime
+evidence with `actual.visible: true`, positive `actual.width` and
+`actual.height`, and `actual.accessibleLabel: true`; a blank glyph, zero-sized
+glyph, or unlabelled control fails the audit even when build/typecheck passes.
+Source/class/markup-only checks are rejected. The audit stores assertion IDs
+and safe pass/fail metadata, never response bodies, credentials, or cookies. A
+passing assertion audit complements browser evidence; it does not replace the
+host adapter's actual HTTP and screenshot capture.
 
 ## Gate and release evidence