b2c-app-builder 0.221.39

package/examples/workspace/business/store/app-store-listing/SCREENSHOTS.md

@@ -0,0 +1,246 @@
+# {{APP_NAME}} Store Screenshots Packet
+
+Docs refreshed: Pending
+Status: partial
+Owner: design-guru + marketing-guru + orchestrator
+
+Raw device captures prove the product exists. Final store screenshots are composed marketing assets that combine real app UI, copy, device framing, current device wells, and visual QA.
+
+## Source Ledger
+
+| Source                                                                   | Role                                                   | Status  | Notes                                                                                                                                                                                                                                                                                                                                                                                        |
+| ------------------------------------------------------------------------ | ------------------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DESIGN.md`                                                              | tokens, type, color, frame style, App Icon direction   | Pending | Required before production composition                                                                                                                                                                                                                                                                                                                                                       |
+| `design.md`                                                              | screen inventory and screenshot-critical states        | Pending | Use real or faithful production screens                                                                                                                                                                                                                                                                                                                                                      |
+| `11_STAR_EXPERIENCE.md`                                                  | V1 scalable slice and line of feasibility              | Pending | Screenshot claims must stay inside this line                                                                                                                                                                                                                                                                                                                                                 |
+| `APP_STORE_LISTING.md`                                                   | metadata, privacy, pricing, CPP/event alignment        | Pending | Copy and offers must match listing truth                                                                                                                                                                                                                                                                                                                                                     |
+| `CONTENT_ASSETS.md`                                                      | Higgsfield/Remotion route, license, outputs, approvals | Pending | Required when generated/rendered assets are used                                                                                                                                                                                                                                                                                                                                             |
+| MobAI raw captures                                                       | real app proof layer                                   | Pending | Use approved fallback only after founder approval                                                                                                                                                                                                                                                                                                                                            |
+| In-app iOS Simulator (Claude Code Desktop pane / Codex `build-ios-apps`) | zero-setup raw capture layer                           | Pending | Local macOS session only. Capture with the pane's screenshot/record shortcuts (Cmd+S / Cmd+R), copy off the Desktop into `screenshots/raw/`, and record the device, OS, and fixture account in `engineering/PRODUCTION_READINESS.md`. Fixture or sandbox accounts only — the agent's device screenshots leave the machine. Simulated devices only: no physical-device and no Android capture |
+| Codex Desktop native iOS / XcodeBuildMCP                                 | Apple simulator/device proof layer                     | Pending | Record `session_show_defaults`, project/scheme/simulator, tool names, and output paths in `engineering/PRODUCTION_READINESS.md`                                                                                                                                                                                                                                                              |
+| SnapshotPreviews                                                         | preview snapshot proof layer                           | Pending | Preview-only PNG/JSON evidence via `TEST_RUNNER_SNAPSHOTS_EXPORT_DIR`; not runtime E2E proof                                                                                                                                                                                                                                                                                                 |
+| serve-sim                                                                | browser-visible simulator proof layer                  | Pending | Record booted simulator/device, `http://localhost:3200` or chosen port, actions, logs, and limitations                                                                                                                                                                                                                                                                                       |
+| ParthJadhav/app-store-screenshots                                        | production screenshot editor and bulk export board     | Pending | Use for copy-led iPhone/iPad/Play decks when installed or approved                                                                                                                                                                                                                                                                                                                           |
+| `asc-screenshot-resize`                                                  | device wells, size, alpha, color space                 | Pending | Refresh current ASC sizing first                                                                                                                                                                                                                                                                                                                                                             |
+
+## Asset Knowledge Brief
+
+Store assets are not generic marketing — they are engineered from everything the launch already knows. Fill this brief before composing any screenshot or app preview, then feed it to the screenshot ASO skill and the `app-preview-video` skill. Generic, knowledge-free assets are a launch miss and an audit finding.
+
+| Knowledge source                                                   | What it feeds into the assets                                                                                                                     |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `strategy/RESEARCH.md`                                             | target user, the problem in their own pain language, top objections to answer, competitor visual conventions to break from                        |
+| `11_STAR_EXPERIENCE.md`                                            | the one magical V1 moment — this is the hook payoff and Screenshot 1                                                                              |
+| `EMOTIONAL_DESIGN.md` + `knowledge/experience/experience-cards.md` | the Emotional North Star (the feeling the 5-second hook must create), the target emotional curve, and which Experience Card the hook instantiates |
+| `DESIGN.md` + `strategy/BRAND.md`                                  | tokens, type, color, motion, and voice so every asset is design-aligned                                                                           |
+| `APP_STORE_LISTING.md`                                             | keyword/positioning alignment so captions reinforce the metadata                                                                                  |
+
+### Per-Slot Knowledge Map
+
+| Slot                                  | Knowledge drawn on                            | Emotion / Experience Card targeted                                                                          | Headline | Truthfulness check                        |
+| ------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------- |
+| Hook video — first frame + first 3–5s | 11-star magical moment + Emotional North Star | the hook's target feeling + card (e.g. Intent Mirroring "made for me", Variable Reward "look what you get") | Pending  | shows real app; matches what the app does |
+| Screenshot 1                          | magical moment + main outcome                 | primary emotional beat                                                                                      | Pending  | no unsupported outcome claim              |
+| Screenshot 2                          | differentiated proof / core loop              | competence, trust                                                                                           | Pending  | real UI                                   |
+| Screenshot 3                          | conversion/result + objection answered        | confidence, momentum                                                                                        | Pending  | pricing matches `revenue/REVENUE_OPS.md`  |
+| Screenshot 4–5                        | secondary benefit / breadth / trust           | belonging, relief                                                                                           | Pending  | one idea; no fake ratings/endorsement     |
+
+## Narrative
+
+| Slot | Purpose                   | Headline | Copy overlay | Source screen    | Claim/risk check                                  | Status   |
+| ---- | ------------------------- | -------- | ------------ | ---------------- | ------------------------------------------------- | -------- |
+| 1    | hook and main outcome     | Pending  | Pending      | onboarding/value | no unsupported outcome claim                      | blocked  |
+| 2    | differentiated proof      | Pending  | Pending      | core loop        | real UI required                                  | blocked  |
+| 3    | conversion/revenue moment | Pending  | Pending      | paywall/result   | pricing/trial must match `revenue/REVENUE_OPS.md` | blocked  |
+| 4    | secondary feature         | Pending  | Pending      | feature state    | one idea only                                     | optional |
+| 5    | trust or breadth          | Pending  | Pending      | settings/proof   | no fake ratings/endorsement                       | optional |
+
+## Raw Capture Matrix
+
+| Slot | Platform    | Device     | Locale | Source screen | Capture tool                                                                                                                                                                      | Raw path                                | Version localization ID | Status   |
+| ---- | ----------- | ---------- | ------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ----------------------- | -------- |
+| 1    | iOS         | iPhone 6.9 | en-US  | Pending       | in-app iOS Simulator (Cmd+S, fixture account), MobAI, Codex Desktop native iOS, XcodeBuildMCP, serve-sim, or approved fallback; SnapshotPreviews only for preview/component proof | `screenshots/raw/iphone-69-slot-1.png`  | Pending                 | blocked  |
+| 1    | iOS         | iPad 13    | en-US  | Pending       | in-app iOS Simulator (Cmd+S, fixture account), MobAI, Codex Desktop native iOS, XcodeBuildMCP, serve-sim, or approved fallback; SnapshotPreviews only for preview/component proof | `screenshots/raw/ipad-13-slot-1.png`    | Pending                 | blocked  |
+| 1    | Google Play | phone      | en-US  | Pending       | MobAI or approved fallback                                                                                                                                                        | `screenshots/raw/play-phone-slot-1.png` | n/a                     | optional |
+
+## Production Composition Matrix
+
+| Slot            | Target      | Headline | Copy overlay | Layout                           | Supporting asset                             | Route                                  | Final upload path                                   | Dimensions        | Alpha/color space               | Visual QA         |
+| --------------- | ----------- | -------- | ------------ | -------------------------------- | -------------------------------------------- | -------------------------------------- | --------------------------------------------------- | ----------------- | ------------------------------- | ----------------- |
+| 1               | iPhone 6.9  | Pending  | Pending      | framed App Store screenshot      | Higgsfield background or design-system frame | Remotion/HTML composition from real UI | `screenshots/final/iphone-69-slot-1.png`            | current ASC size  | alpha removed, sRGB color space | thumbnail pending |
+| 1               | iPad 13     | Pending  | Pending      | framed iPad App Store screenshot | design-system frame                          | Remotion/HTML composition from real UI | `screenshots/final/ipad-13-slot-1.png`              | current ASC size  | alpha removed, sRGB color space | iPad QA pending   |
+| Feature graphic | Google Play | Pending  | Pending      | wide brand/product frame         | Higgsfield or design-system artwork          | content asset route                    | `screenshots/final/google-play-feature-graphic.png` | current Play size | sRGB color space                | optional          |
+
+## Composition And Export Route
+
+Preferred local route: ParthJadhav/app-store-screenshots.
+
+Inputs:
+
+- real app captures from `screenshots/raw/`
+- `app-icon/app-icon-1024.png`
+- `DESIGN.md`, and `11_STAR_EXPERIENCE.md`
+- headline/copy story from `APP_STORE_LISTING.md`
+- Higgsfield supporting art only when recorded in `CONTENT_ASSETS.md`
+
+Outputs:
+
+- screenshot editor or board: `screenshots/index.html` or generated app-store-screenshots workspace
+- reusable deck state: `app-store-screenshots.json` when the external skill is used
+- final no-alpha PNGs under `screenshots/final/<locale>/<device-well>/`
+- ASC validation output and `asc-shots-pipeline` upload dry-run output in `store/STORE_CONSOLE.md`
+
+## Device Wells
+
+Run current sizing before export. Record ready, blocked, or not needed for each target.
+
+| Platform    | Well               | Required/scaled decision                                               | ASC device_type | Screenshot count                        | Current Apple size basis                                                                      | Target file | Validation proof                | Status   |
+| ----------- | ------------------ | ---------------------------------------------------------------------- | --------------- | --------------------------------------- | --------------------------------------------------------------------------------------------- | ----------- | ------------------------------- | -------- |
+| iOS         | iPhone 6.9         | required for current iPhone coverage when provided                     | Pending         | 1-10 screenshots                        | from `asc screenshots sizes --all`; Apple currently accepts 1320x2868 portrait for this class | Pending     | `asc-screenshot-resize` pending | blocked  |
+| iOS         | iPhone 6.5         | required if 6.9 is not provided, otherwise scaled when allowed         | Pending         | 1-10 screenshots                        | Apple currently accepts 1284x2778 or 1242x2688 portrait                                       | Pending     | `asc-screenshot-resize` pending | blocked  |
+| iOS         | iPhone 6.3         | scaled from accepted larger wells when allowed by current ASC spec     | Pending         | 1-10 screenshots                        | current ASC size matrix                                                                       | Pending     | `asc-screenshot-resize` pending | blocked  |
+| iOS         | iPhone 6.1         | scaled from accepted larger wells when allowed by current ASC spec     | Pending         | 1-10 screenshots                        | current ASC size matrix                                                                       | Pending     | `asc-screenshot-resize` pending | blocked  |
+| iPadOS      | iPad 13            | required when iPad is supported                                        | Pending         | 1-10 screenshots                        | Apple currently accepts 2064x2752 or 2048x2732 portrait                                       | Pending     | `asc-screenshot-resize` pending | blocked  |
+| iPadOS      | iPad 12.9          | scaled from 13 inch when allowed by current ASC spec                   | Pending         | 1-10 screenshots                        | current ASC size matrix                                                                       | Pending     | `asc-screenshot-resize` pending | blocked  |
+| iPadOS      | iPad 11/10.5/9.7   | explicit, scaled, or not needed based on current device-family support | Pending         | 1-10 screenshots                        | current ASC size matrix                                                                       | Pending     | `asc-screenshot-resize` pending | blocked  |
+| Google Play | phone screenshots  | required for Play listing                                              | n/a             | screenshot count from Play Console spec | Pending                                                                                       | Pending     | Play Console spec check pending | optional |
+| Google Play | tablet screenshots | optional or required based on distribution target                      | n/a             | screenshot count from Play Console spec | Pending                                                                                       | Pending     | Play Console spec check pending | optional |
+| Google Play | feature graphic    | required for many Play acquisition surfaces                            | n/a             | one graphic                             | Pending                                                                                       | Pending     | Play Console spec check pending | optional |
+
+## App Icon
+
+| Asset              | Source                                | Route                                      | Output                       | QA                                                                     | Status  |
+| ------------------ | ------------------------------------- | ------------------------------------------ | ---------------------------- | ---------------------------------------------------------------------- | ------- |
+| 1024x1024 App Icon | `DESIGN.md` + competitor icon context | Higgsfield or designer/founder-owned asset | `app-icon/app-icon-1024.png` | no alpha, no rounded corners, thumbnail test, category differentiation | blocked |
+
+## App Preview Video (Autoplay Hook)
+
+The app preview video is the most underused growth lever on the App Store. Treat it as a **required** asset for any iOS launch (mark `deferred` only with a founder-approved reason). Verified Apple behavior (refresh against the App Store sources in `checks/validation/repository/source-registry.yaml` before upload):
+
+- You can upload **up to 3 app previews** per device size and language, and **app previews always precede screenshots** at the top of the product page.
+- On the product page, **app previews autoplay with muted audio** — Apple's own guidance: "make sure the first few seconds of your video are visually compelling." The first preview is a hook the user watches whether they intended to or not.
+- Length is **up to 30 seconds** (Apple's accepted range is 15–30s; confirm the current min/max in the app preview specifications before render). The **poster frame** displays whenever the video does not autoplay, so it must sell on its own.
+- Source MUST be real in-app footage (captured via the in-app iOS Simulator (Cmd+R recording), MobAI, Codex Desktop native iOS/XcodeBuildMCP, serve-sim, or on-device), never generated UI. SnapshotPreviews can support preview/component regression evidence but does not replace runtime App Preview footage.
+
+### The 5-Second Muted Hook (required spec)
+
+Because the first preview plays silent and unrequested, its first ~3–5 seconds must:
+
+- Communicate the core value with **no audio dependency** — on-screen text/captions carry the message.
+- **Show the payoff first** — the magical V1 moment from `11_STAR_EXPERIENCE.md` — not a logo, splash, or slow intro.
+- Land the **Emotional North Star** feeling instantly and instantiate the hook's Experience Card from the Asset Knowledge Brief (`EMOTIONAL_DESIGN.md` + `knowledge/experience/experience-cards.md`).
+- Read at a glance with motion that is legible muted.
+- Have a **poster frame** that already sells if autoplay is blocked.
+- Be **truthful** — the hook must match what the app actually does; no bait-and-switch, fake UI, or oversold outcome.
+
+### Production Route (mandatory)
+
+Both screenshots and the app preview run through the screenshot ASO skill; they are never hand-composed one-offs:
+
+- **Screenshots:** `ParthJadhav/app-store-screenshots` (the screenshot ASO skill), `ios-screenshots`, and `aso-skills:screenshot-optimization`, from real UI, App Icon, and design tokens.
+- **App preview:** script/storyboard via `aso-skills:app-preview-video`; capture real footage via the in-app iOS Simulator (Cmd+R), MobAI, Codex Desktop native iOS/XcodeBuildMCP, or serve-sim — MobAI stays the route for a polished multi-device recording; edit and caption via Remotion; produce all Apple/Play resolution variants (9:16 / 1:1 / 16:9) from a single master via the Higgsfield `reframe` MCP tool (Master → All Platforms recipe in `knowledge/process/tool-recipes/visual-and-motion-production.md`) — reframe reformats aspect ratio only, never substitutes UI.
+- A/B test variants with `aso-skills:ab-test-store-listing` (Product Page Optimization) where available.
+
+| Preview                       | Knowledge-leveraged hook (first 3–5s) | Emotion / Card                 | Poster frame     | Captions (muted) | Skill route                                    | Output                       | Status   |
+| ----------------------------- | ------------------------------------- | ------------------------------ | ---------------- | ---------------- | ---------------------------------------------- | ---------------------------- | -------- |
+| iOS Preview 1 (autoplay hook) | magical V1 moment shown as the payoff | North Star feeling + hook card | must sell silent | required         | app-preview-video → MobAI → Remotion → reframe | `previews/ios-preview-1.mp4` | blocked  |
+| iOS Preview 2–3 (optional)    | secondary proof / breadth             | secondary beat                 | Pending          | required         | same                                           | `previews/ios-preview-2.mp4` | optional |
+| Google Play promo             | hook payoff, YouTube-hosted           | North Star feeling             | n/a              | recommended      | same                                           | YouTube URL pending          | optional |
+
+Produce required resolution variants by `reframe`-ing one master rather than re-rendering per size; the source must be real app footage. See the Master → All Platforms recipe in `knowledge/process/tool-recipes/visual-and-motion-production.md`.
+
+## Definition of Good: Present / Proven / Optimized
+
+This section is the machine-readable contract for `check:store-screenshots`. Each layer has a defined enforcement mode.
+
+### PRESENT — packet filled (hard-error when lane is "partial" or "done")
+
+The SCREENSHOTS.md packet is filled: no cell in any required matrix still reads "Pending", "Blocked", or is empty. Specifically:
+
+- Every required row in the Raw Capture Matrix has a non-empty source screen, capture tool, raw path, and status.
+- Every required row in the Production Composition Matrix has a non-empty headline, route, final upload path, and dimensions.
+- Every required Device Wells row has a confirmed required/scaled/not-needed decision.
+- The Narrative table has headings and copy for every required slot.
+- The Per-Slot Knowledge Map is filled for every slot.
+
+### PROVEN — objective on-disk evidence (hard-error when lane is "done")
+
+Evidence that the work actually happened, not just that it was declared:
+
+1. **Raw captures exist on disk** at the exact paths listed in the Raw Capture Matrix (e.g. `screenshots/raw/iphone-69-slot-1.png`). A filled path that points to a non-existent file is a hard error.
+2. **`app-store-screenshots.json` exists** and is a valid schema-v2 file. Its `rawPaths` (or equivalent field) reference files that exist on disk.
+3. **Final PNGs exist** under `screenshots/final/<locale>/<device-well>/` for every required device well at the correct ASC dimensions. Alpha-removed, sRGB. The validator checks existence; the dimensions/color-space proof is in the upload log.
+4. **One deck per Tier-1 locale**: for every locale listed in `LOCALIZATION_MARKET_RESEARCH.md` that is marked Tier-1, a final screenshot deck exists under `screenshots/final/<locale>/`.
+5. **Theme is token-derived**: `app-store-screenshots.json` must reference `DESIGN.md` or contain a `tokensSource` field pointing to it. The ParthJadhav theme was generated FROM design tokens, not hand-coded colors.
+6. **Captions contain keyword tokens from `APP_STORE_LISTING.md`**: at least one headline in `app-store-screenshots.json` contains a keyword that also appears in the `keywords` field of `APP_STORE_LISTING.md`. ASO fold-in is data-wired, not declared.
+7. **Upload proof in `store/STORE_CONSOLE.md`**: the `asc-shots-pipeline` dry-run or upload output is recorded there before the lane is marked "done".
+
+### OPTIMIZED — quality bar (warning + logged override; taste stays human)
+
+Rubric scores are recorded in `screenshot-rubric-scores.json`. For every required slot/locale:
+
+- Either `pass: true` (weighted-high dimensions all >= 2, overall weighted score >= threshold in `SCREENSHOT_RUBRIC.md`), OR
+- A non-empty `override.reason` is logged by the founder.
+
+A slot with no score entry at all is an error when the lane is "done" and a warning when "partial".
+
+**Producer != Verifier (Tier 2 enforcement):** The ledger root must carry distinct non-empty `builder` and `grader` identity fields. The agent or session that built the deck may not grade it. The validator errors (when "done") or warns (when "partial") if `grader` is missing, if `grader === builder`, or if any required slot lacks non-empty `grader_notes`. See `SCREENSHOT_RUBRIC.md` for the full grader protocol.
+
+**Suspicious perfect score:** When every high dimension is scored 3 and `grader_notes` is very short, the validator fires `store_screenshots.suspicious_perfect` warning. A perfect score needs proportionally detailed justification.
+
+**Tier-1 anti-gaming:** `screenshot-rubric-scores.json` that is byte-identical to `screenshot-rubric-scores.example.json` or smaller than 200 bytes is rejected as an unmodified scaffold copy.
+
+**Tier-3 PNG reality checks:** For every `final_png` in the ledger, the validator reads the real PNG IHDR bytes (width, height, bit depth, color type) and verifies that declared device-well dimensions match the file and that no alpha channel is present when `alpha removed` is claimed in the Production Composition Matrix.
+
+### Pipeline Spine
+
+This is the canonical end-to-end pipeline. Every step must be evidenced before the lane can be "done".
+
+```
+Capture (in-app iOS Simulator / MobAI / ios-screenshots / XcodeBuildMCP / serve-sim)
+  → real app frames at screenshots/raw/<device>/<locale>/
+
+Compose (ParthJadhav/app-store-screenshots)
+  → themed from DESIGN.md          [token fold-in: data-wired]
+  → copy/headlines from APP_STORE_LISTING.md keywords  [ASO fold-in: data-wired]
+  → one deck per Tier-1 locale from LOCALIZATION_MARKET_RESEARCH.md
+  → outputs: app-store-screenshots.json (schema v2) + screenshots/index.html
+
+Grade (SCREENSHOT_RUBRIC.md + SEPARATE grader agent/session — never the builder)
+  → builder identity recorded at ledger root "builder" field
+  → grader identity recorded at ledger root "grader" field (must differ from builder)
+  → per-slot grader_notes written (non-empty, explains each dimension)
+  → scores written to screenshot-rubric-scores.json
+  → pass or founder override logged
+
+Resize / validate (asc-screenshot-resize)
+  → final PNGs at screenshots/final/<locale>/<device-well>/
+  → alpha removed, sRGB, correct ASC dimensions
+
+Upload (asc-shots-pipeline)
+  → dry-run output and upload proof in store/STORE_CONSOLE.md
+```
+
+## Visual QA
+
+- [ ] An iOS app preview video exists (or a founder-approved deferral is recorded); the first preview is the autoplay hook and precedes the screenshots.
+- [ ] The first 3–5 seconds communicate the core value MUTED, with on-screen text and the magical V1 moment shown first (no logo/splash intro).
+- [ ] The poster frame sells on its own when autoplay is blocked.
+- [ ] The hook lands the Emotional North Star feeling and instantiates its Experience Card per the Asset Knowledge Brief.
+- [ ] The hook is truthful — real app footage, no fake UI or oversold outcome.
+- [ ] Both screenshots and the app preview were produced via the screenshot ASO skill (`ParthJadhav/app-store-screenshots` / `ios-screenshots` / `app-preview-video`), not hand-composed one-offs.
+- [ ] Every screenshot slot and the hook draw on the Asset Knowledge Brief (`strategy/RESEARCH.md` user/problem, `11_STAR_EXPERIENCE.md` magical moment, `EMOTIONAL_DESIGN.md` emotion/cards).
+- [ ] Headlines are readable at App Store search thumbnail size.
+- [ ] Copy overlay uses one idea per slide and matches `APP_STORE_LISTING.md`.
+- [ ] Real app UI remains visible and truthful in every production composition.
+- [ ] Captures taken from an agent-driven simulator used a fixture or sandbox account. No real founder, customer, store, bank, or provider account was signed in on a device the agent controlled, and no real user data, real payment state, or production credential appears in any frame.
+- [ ] Cmd+S / Cmd+R captures were exported off the macOS Desktop into `screenshots/raw/` and committed, and their native pixel dimensions were verified against the target display well; no store asset cites a frame that exists only in a conversation.
+- [ ] Generated Higgsfield assets are supporting visuals, not fake product proof.
+- [ ] Remotion or HTML compositions record source inputs, license status, render proof, and outputs in `CONTENT_ASSETS.md`.
+- [ ] ParthJadhav/app-store-screenshots deck state or equivalent export board is saved when used, including app icon, locale, iPhone/iPad deck, and final PNG paths.
+- [ ] Pricing, trial, renewal, subscription, and feature claims match `revenue/REVENUE_OPS.md`, paywall copy, and legal docs.
+- [ ] Alpha transparency is removed and color space is acceptable for upload.
+- [ ] iPhone and iPad safe areas, text fit, overlap, and contrast are checked.
+- [ ] Localized screenshot copy is reviewed for each shipped locale.
+- [ ] Founder approval is recorded before screenshot upload, App Icon replacement, App Preview upload, CPP/event media submission, or paid asset generation.
+- [ ] `screenshot-rubric-scores.json` exists and every required slot has either `pass: true` or a non-empty `override.reason`.

package/examples/workspace/business/store/app-store-listing/SCREENSHOT_RUBRIC.md

@@ -0,0 +1,202 @@
+# Screenshot Rubric
+
+Version: 1.2
+Status: active
+Owner: design-guru + marketing-guru + founder (override authority)
+
+This rubric is the scored taste layer for the PRESENT/PROVEN/OPTIMIZED framework defined in SCREENSHOTS.md. Rubric scores fire as WARNINGS with a logged override; technical-correctness and Proven-existence checks are HARD ERRORS. Taste stays human.
+
+## Dimensions
+
+Each dimension is scored 0–3 per slot per locale. Weighted-high dimensions must each reach >= 2 for a slot to auto-pass. The overall weighted score must reach the stated threshold.
+
+| #   | Dimension                     | Weight                           | Score 0                                                                                                     | Score 1                                                                | Score 2 (threshold)                                                                                        | Score 3                                                                                                                          |
+| --- | ----------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **Thumbnail legibility**      | HIGH                             | headline or key UI is unreadable at 60 px wide; text overlaps UI beyond recognition                         | legible at 120 px but not 60 px; marginal contrast                     | legible at 60 px; key text and icon clear at App Store search size                                         | instantly clear at 40 px; headline dominates; zero ambiguity                                                                     |
+| 2   | **Hook-first ordering**       | HIGH                             | slot 1 shows a splash, logo, or secondary feature; no clear payoff                                          | slot 1 hints at value but does not show the magical V1 moment          | slot 1 shows the 11-star V1 payoff; emotional beat lands                                                   | slot 1 is so compelling a user stops scrolling; ordering tells a complete narrative across all slots                             |
+| 3   | **Truthfulness**              | HIGH                             | shows UI that does not exist in the shipped build; outcome claims unsupported; fake ratings or endorsements | shows real UI but adds unsupported superlatives ("best", "#1")         | shows real app UI; every visible claim matches `revenue/REVENUE_OPS.md` and legal docs; no bait-and-switch | real UI AND claim-checked against `revenue/REVENUE_OPS.md`; reviewer note drafted; no edge case that could trigger Guideline 5.2 |
+| 4   | **One-idea-per-slot**         | MEDIUM                           | multiple unrelated ideas compete in one slot; visual noise                                                  | two ideas present but one dominates                                    | one clear idea per slot; supporting elements reinforce not distract                                        | single idea, zero visual noise; a user can state the idea in four words                                                          |
+| 5   | **Brand-token fidelity**      | MEDIUM                           | colors, type, or motion diverge from `DESIGN.md` without a recorded override                                | minor variance (one secondary color off-token)                         | all primary colors, type scale, and frame style match `DESIGN.md`                                          | pixel-perfect token adherence; composition would pass a design-system audit                                                      |
+| 6   | **ASO keyword reinforcement** | MEDIUM                           | no visible keyword from `APP_STORE_LISTING.md` appears in any headline or copy overlay                      | one keyword present, buried in body copy                               | primary keyword and one secondary keyword visible in headlines across the deck                             | every headline reinforces a targeted keyword naturally; copy reads human, not stuffed                                            |
+| 7   | **Emotional North Star**      | LOW                              | screenshot evokes no recognizable emotion; neutral or cold                                                  | some warmth or aspiration but the target emotion is not clearly landed | the target Emotional North Star from `EMOTIONAL_DESIGN.md` is felt within 2 seconds                        | shot is emotionally decisive; an independent viewer can name the exact emotion without context                                   |
+| 8   | **Localization quality**      | LOW (only for non-en-US locales) | machine-translated copy with obvious errors; RTL layout broken                                              | human-reviewed copy but awkward phrasing; RTL partially correct        | natural-sounding translated copy; RTL layout correct; no truncation                                        | native-speaker-approved; locale-specific cultural references used; RTL pixel-checked on device                                   |
+
+### Weighted Score Formula
+
+```
+weighted_score = (legibility * 3 + hook_first * 3 + truthfulness * 3
+               + one_idea * 2 + brand_token * 2 + aso_keyword * 2
+               + emotional_north_star * 1 + localization * 1)
+             / (3+3+3+2+2+2+1+1)   # denominator = 17
+
+pass_threshold = 0.65   # 65% of max weighted score = 11.05 out of 17
+high_dimension_minimum = 2  # all three HIGH dimensions must reach >= 2
+```
+
+For non-en-US locales the localization dimension is included. For en-US it is excluded and the denominator drops to 16.
+
+## Separate-Pass Protocol
+
+### CRITICAL: Producer != Verifier Requirement
+
+**The agent or session that builds the screenshot deck MUST NOT be the same agent or session that grades it.**
+
+This separation exists because the builder has motivated reasoning to pass their own work. A grader with no stake in the outcome notices copy that is too small at thumbnail size, hooks that bury the payoff, and claims that are slightly broader than the shipped UI — the builder reads over these because the work feels familiar.
+
+In v1.2, grading is an **explicitly routed, separately invoked pass** — not just a separate string in the ledger. The `grade-screenshots.ts` scaffold is the entry point for the grading pass. It verifies PNG dimensions from the real IHDR headers, emits a structured grading task template (one block per slot), and validates the assembled ledger before writing `screenshot-rubric-scores.json`.
+
+#### Workflow
+
+1. **Builder session** writes final PNGs to `screenshots/final/` and records `builder: { agent, session_id }` in the ledger header.
+2. After final PNGs are written, the builder session stops and hands off — it must not run the grading pass itself. There is no hook to enforce this; `check:store-screenshots` catches a skipped or same-session grading pass after the fact by rejecting a ledger whose `builder.session_id` equals `grader.session_id`.
+3. **A separate grader session** (different `session_id`) is spawned. It runs:
+   ```bash
+   npx tsx tooling/grade-screenshots.ts --root . --state state/business-state.json
+   ```
+   This emits a grading task template listing each slot, its real IHDR dimensions, and the rubric dimensions to score.
+4. **Grader vision agent** opens each PNG and fills in the task template: dimension scores, `grader_notes` (minimum one paragraph), and `observed_evidence` (one line referencing something actually seen in the PNG — headline text, dominant color, a specific UI element).
+5. **Grader session** assembles the ledger and validates it:
+   ```bash
+   npx tsx tooling/grade-screenshots.ts \
+     --root . --state state/business-state.json \
+     --grading-input /tmp/grading-output.json \
+     --write screenshot-rubric-scores.json
+   ```
+6. The validator (`npm run check:store-screenshots`) will ERROR if `grading_pass.separate_pass` is not `true`, if `builder.session_id` equals `grader.session_id`, or if any slot lacks `grader_notes` or `observed_evidence`.
+7. **store_console cannot be marked "done" until all steps above complete and the validator passes.**
+
+#### Bash-Written PNGs Are Also Covered
+
+The `settings.json` Write|Edit hook fires when the tool writes a file. If an agent instead writes final PNGs via a Bash command (`cp`, `mv`, `tee`, `install`, `ditto`, `sips`, `magick`/`convert -o`, or shell redirection `>`/`>>` into `screenshots/final/*.png`), the Bash PostToolUse hook intercepts the command and emits the identical BLOCKING grading-pass signal, then exits 1. This closes the Bash-write bypass.
+
+**Honest limit of the Bash hook:** the hook matches a regex against the Bash command string. A carefully constructed command string that uses the destination path in an unusual position could evade the pattern. It catches straightforward writes (copy, move, redirect) and is not a cryptographic guarantee.
+
+#### Honest Limit of This Control
+
+The validator enforces that:
+
+- `grading_pass.separate_pass: true` is explicitly asserted
+- `builder.session_id` and `grader.session_id` are distinct non-empty strings
+- every slot has substantive `grader_notes` (≥ 30 chars) and `observed_evidence` (≥ 15 chars)
+- `observed_evidence` is DISTINCT per slot — two or more slots sharing the exact same normalized evidence string fires `store_screenshots.observed_evidence_not_distinct` (ERROR at done, WARN at partial)
+- `observed_evidence` does not match a stock generic-phrase denylist (e.g. "looks good", "reads clearly", "headline visible") — matches fire `store_screenshots.observed_evidence_generic` (WARN)
+
+**What it cannot prove:** that two truly independent processes ran. A single agent that knows the schema can fabricate both session IDs, an `observed_evidence` field, and write distinct-but-fictional evidence per slot. These controls raise the bar significantly versus the v1.1 string-comparison control (faking now requires deliberate fabrication of two session identities, an explicit separation attestation, per-slot visual evidence notes, AND distinct non-generic observations per slot), but they do not eliminate the gap.
+
+**Founder approval is the ultimate backstop.** The founder's review of the final PNGs alongside the grading ledger is the only control that cannot be mechanically gamed. The validator is a raised-bar deterrent, not a proof.
+
+### Inputs (for the grader session)
+
+- Final PNGs under `screenshots/final/<locale>/<device-well>/`
+- `APP_STORE_LISTING.md` (keyword list)
+- `DESIGN.md` (brand tokens)
+- `EMOTIONAL_DESIGN.md` (Emotional North Star)
+- `revenue/REVENUE_OPS.md` (pricing/claim truth-check source)
+- This rubric file (current version)
+
+### Steps
+
+1. Run `npx tsx tooling/grade-screenshots.ts --root . --state state/business-state.json` to generate the grading task template. This reads SCREENSHOTS.md, verifies each final PNG exists, and reads its real IHDR width/height.
+2. For each slot in the task template, open the final PNG and score each dimension 0–3 using the criteria in the Dimensions table above.
+3. Compute the weighted score and the pass boolean.
+4. Fill in `grader_notes` for every slot — at minimum one paragraph explaining the score for each dimension that could plausibly change. Empty or missing `grader_notes`, or notes shorter than 30 characters, are treated by the validator as a grading skip.
+5. Fill in `observed_evidence` for every slot — one line referencing something you actually saw in the PNG (headline text, dominant color, a specific UI element). This is the per-slot anti-fabrication control. Rules:
+   - Minimum 15 characters.
+   - Must be DISTINCT across slots: two slots cannot share the same normalized observed_evidence — that signals the grader did not open each PNG separately.
+   - Must not be a stock generic phrase: "looks good", "reads clearly", "headline visible", "looks clean", "nice", "good", "clear", "ok" etc. are flagged as warnings.
+6. If pass is false AND the founder has not yet filed an override: emit a WARNING with the slot identifier, the failing dimension(s), and the score. Do NOT block launch from this alone.
+7. Assemble the complete ledger (identity block + all slot blocks) and run the validate+write command. The script enforces `builder.session_id != grader.session_id`, `grading_pass.separate_pass: true`, and notes presence before writing.
+8. If a founder override is provided: log `override.by`, `override.reason`, and `override.at` in the same record.
+
+### Ledger Schema (v1.2)
+
+The ledger root MUST contain:
+
+```json
+{
+  "rubric_version": "1.2",
+  "builder": {
+    "agent": "<agent-name-or-role>",
+    "session_id": "<unique session token>"
+  },
+  "grader": {
+    "agent": "<agent-name-or-role>",
+    "session_id": "<DIFFERENT unique session token>"
+  },
+  "grading_pass": {
+    "separate_pass": true,
+    "started_at": "<ISO-8601 timestamp>",
+    "method": "vision"
+  },
+  ...
+}
+```
+
+And each slot MUST contain both `grader_notes` AND `observed_evidence`:
+
+```json
+{
+  "grader_notes": "<paragraph explaining the score for each dimension>",
+  "observed_evidence": "<one line: e.g. headline reads 'Plan Your Day', dominant color is #1A1A2E>",
+  ...
+}
+```
+
+### Suspicious Perfect Score
+
+When all high-dimension scores are 3 and `grader_notes` is very short (fewer than 50 characters), the validator fires a `store_screenshots.suspicious_perfect` warning. A perfect score requires proportionally detailed justification — it should be harder to explain than an average score, not easier. If scores are genuinely all-3s, write at least one sentence per dimension explaining what specific visual evidence supports the score.
+
+### Auto-Pass Threshold
+
+A slot passes auto-grading when ALL of the following are true:
+
+- `legibility >= 2`
+- `hook_first >= 2`
+- `truthfulness >= 2`
+- `weighted_score >= 0.65`
+
+### Founder Override
+
+When auto-pass is false, the founder may override by recording:
+
+```json
+"override": {
+  "by": "founder",
+  "reason": "<one-sentence human rationale>",
+  "at": "<ISO-8601 timestamp>"
+}
+```
+
+An override with an empty or null `reason` is treated by the validator as no override (still emits WARNING).
+
+## Improve-Over-Time Loop
+
+The rubric is versioned. Each graded deck becomes a permanent fixture.
+
+### Fixture Accumulation
+
+Every time a deck is graded, the `screenshot-rubric-scores.json` is committed alongside the final PNGs. This creates a growing fixture corpus: scores + PNG paths + founder accept/override. The fixture corpus is the basis for future calibration.
+
+### Rubric Versioning
+
+When any dimension definition or threshold changes:
+
+1. Increment the `rubric_version` field (semver patch for threshold tweaks, minor for new dimensions).
+2. Re-grade any fixture that was graded under an older version and update `rubric_version` in the record (or mark it `stale: true`).
+3. Old fixtures with `stale: true` are excluded from threshold enforcement but kept for historical comparison.
+
+### Conversion Tuning (deferred)
+
+Linking rubric scores to downstream conversion metrics (PPO results, App Analytics impression-to-install) is deferred until the first 90-day post-launch window produces sufficient data. When that data is available: correlate per-dimension scores with conversion lift, re-weight accordingly, and commit a new `rubric_version`.
+
+## Notes for Maintainers
+
+- This rubric is the reference implementation for the PRESENT/PROVEN/OPTIMIZED pattern. Every other lane that adds an OPTIMIZED layer should mirror this structure: versioned rubric, scored fixture ledger, founder override path, improve-over-time loop.
+- The validator `check:store-screenshots` reads `screenshot-rubric-scores.json` and enforces this rubric. When the lane is "partial" a missing score is a WARNING. When the lane is "done" a missing score is an ERROR.
+- Do not collapse PROVEN checks into OPTIMIZED. A missing file on disk is always a hard error regardless of scores.
+- The ledger schema is at `rubric_version: 1.2`. Version 1.2 added `builder`/`grader` as structured objects (`{ agent, session_id }`), the `grading_pass` block (`{ separate_pass, started_at, method }`), and per-slot `observed_evidence`. Ledgers graded under v1.1 (plain string builder/grader) will fire `store_screenshots.grading_not_separate_pass` and `store_screenshots.grader_provenance_missing` warnings; re-grade them before marking the lane "done".
+- Tier-1 anti-gaming: the validator rejects `screenshot-rubric-scores.json` that is byte-identical to `screenshot-rubric-scores.example.json` or below 200 bytes. The example file is the scaffold; it must be replaced with real scores, not copied.
+- Tier-2 separate-pass enforcement: new in v1.2; tightened in v1.2.1. The validator errors on `store_console=done` if `grading_pass.separate_pass !== true`, if `builder.session_id === grader.session_id`, if any slot lacks `grader_notes` (≥ 30 chars) or `observed_evidence` (≥ 15 chars), if two or more slots share the same normalized `observed_evidence` (issue code: `store_screenshots.observed_evidence_not_distinct`), or if `observed_evidence` matches a stock generic-phrase denylist (issue code: `store_screenshots.observed_evidence_generic`, warning only). Issue codes: `store_screenshots.grading_not_separate_pass`, `store_screenshots.builder_equals_grader`, `store_screenshots.grader_provenance_missing`, `store_screenshots.observed_evidence_not_distinct`, `store_screenshots.observed_evidence_generic`.
+- Tier-3 PNG reality checks: for every `final_png` path in the ledger the validator reads the PNG IHDR header bytes and checks that the declared device-well dimensions and alpha-removal claim are true. A final PNG that carries an alpha channel after `alpha removed` is claimed is a hard error when the lane is "done".
+- The `grade-screenshots.ts` scaffold is the ONLY supported way to assemble and write the grading ledger. It validates the complete provenance chain before writing. Do not write `screenshot-rubric-scores.json` directly from a build agent.
+- The settings.json `Final PNG hook` exits non-zero after final PNG writes (BLOCKING). This is intentional — it forces the agent to route to the grading pass. Do not add `|| true` to this hook.