b2c-app-builder 0.221.39

package/catalog/generated/firstparty/examples/workspace/business/product/experience/ux-patterns/UX_PATTERNS.md

@@ -0,0 +1,144 @@
+# {{APP_NAME}} UX Patterns
+
+This packet records Refero or founder-approved fallback UX research. It is a pattern contract, not a mood board. Do not copy one source directly; adapt observed patterns to this product's strategy, `DESIGN.md`, analytics, privacy, and implementation constraints.
+
+## Refero Route
+
+- Refero docs checked: Pending
+- MCP/auth state: Pending
+- Route selected:
+  - [ ] Refero used
+  - [ ] founder-provided Refero export used
+  - [ ] founder-approved fallback used
+  - [ ] blocked waiting for access
+- Current docs basis to refresh before live use:
+  - `https://doc.refero.design/llms.txt`
+  - `https://doc.refero.design/mcp/getting-started`
+  - `https://doc.refero.design/mcp/tools`
+  - `https://doc.refero.design/mcp/data-model`
+  - `https://doc.refero.design/mcp/examples`
+
+If Refero is unavailable, stop for founder approval before using this free baseline route. Record the approval in `strategy/TOOL_DECISIONS.md`.
+
+For Android launches, treat Refero iOS/mobile records as journey evidence, not Android-specific proof. Adapt controls, navigation, permission copy, billing, and screenshots to Android-native expectations and verify on Android before marking the Android UX lane launch-ready.
+
+## Pattern Inventory
+
+| Surface | Platform | User goal | Pattern choice | Required states | Analytics | Proof |
+| --- | --- | --- | --- | --- | --- | --- |
+| Onboarding value promise | iOS/Android/web | Understand the app promise quickly | Product demo or guided promise before questions | loading, reduced motion, no video | `onboarding_started`, `demo_video_viewed` | `product/onboarding.html` |
+| Self-reported attribution | iOS/Android/web | Tell where they found the app | Required early source question with stable keys and `other` text | validation, other text, privacy note | `attribution_source_selected` | `product/ONBOARDING.md`, `analytics/ANALYTICS.md` |
+| Personalized plan | iOS/Android/web | See answers reflected back | Plan summary that mirrors user input | loading, edit/back, empty answers | `personalized_plan_viewed` | `product/onboarding.html` |
+| Paywall | iOS/Android/web | Choose whether to buy | Value-first paywall with restore, trial/renewal clarity, and close behavior | loading prices, purchase error, restore, premium active | `paywall_viewed`, `purchase_completed`, `restore_succeeded` | `revenue/REVENUE_OPS.md` |
+| Closing offer | iOS/Android/web | Reconsider after dismissing | Transparent downsell/trial/shorter commitment, no fake scarcity | accepted, rejected, expired, unavailable | `closing_offer_viewed`, `closing_offer_selected` | `product/onboarding.html` |
+| Permissions | iOS/Android/web | Understand why access is needed | Explain-before-native-prompt with skip/retry path | denied, limited, retry, settings link | `permission_prompt_viewed`, `permission_result` | `design.md` |
+| Empty state | app/web | Know what to do first | One primary action plus example content | loading, empty, error, offline | `empty_state_viewed`, `empty_state_cta_clicked` | `design/design-room.html` |
+| Error recovery | app/web | Recover without losing work | Plain-language error, retry, contact/support path | network, validation, payment, auth | `error_shown`, `retry_clicked` | `engineering/PRODUCTION_READINESS.md` |
+| Settings/account | app/web | Manage account and subscription | Grouped settings with billing, privacy, support, delete account | auth expired, restore, destructive confirm | `settings_viewed`, `account_delete_started` | `design.md` |
+| Support/contact | app/web/email | Get help with purchase/account issues | Support form/email path with SLA and context | sent, failed, reply expected | `support_started`, `support_submitted` | `growth/EMAIL_OPS.md` |
+| Referral/share | app/web | Share useful result or invite | Native share or copy link with clear value | copied, failed, unsupported | `share_started`, `share_completed` | `growth.html` |
+
+## Flow Map
+
+### Mobile Onboarding Playbook
+
+Keep this sequence unless a named experiment is approved:
+
+1. Value promise or short product demo.
+2. One or more personalization questions that change the product experience.
+3. Required attribution question within the first third of onboarding.
+4. Personalized plan or result preview that reflects answers.
+5. Review prompt only after a real delight moment and only through platform APIs.
+6. Paywall after value is clear, with restore purchases and legal links.
+7. Closing offer or reverse trial if monetization strategy supports it.
+8. First activation task after purchase or before paywall when the model requires it.
+
+### Web Funnel
+
+1. Landing page states the product category, outcome, and proof.
+2. CTA routes to waitlist, web purchase, or app-store preorder.
+3. Form captures email, attribution, consent, and referral code where relevant.
+4. Confirmation state explains next step and sends a branded Resend email.
+5. If web purchase exists, Stripe/RevenueCat entitlement mapping is verified before the app claims access.
+
+### Account, Billing, And Trust
+
+1. Settings exposes restore purchases, subscription management, support, privacy, terms, and account deletion.
+2. Billing errors explain the next action without blaming the user.
+3. Destructive actions use confirmation and recovery where platform rules allow it.
+4. Account deletion links match App Store and Google Play requirements.
+
+## State Matrix
+
+| State | UX rule | Build proof |
+| --- | --- | --- |
+| Loading | Preserve layout size; use skeletons or progress, not layout jumps. | UI test or screenshot |
+| Empty | Explain why it is empty and offer one primary action. | `design/design-room.html` |
+| Error | State what failed, whether work is safe, and how to retry/contact support. | E2E failure path |
+| Offline | Show cached state where possible and a retry path. | simulator/network test |
+| Permission denied | Explain consequence, alternate path, and settings route. | device test |
+| Premium locked | Show value, price path, restore, and legal links. | purchase sandbox test |
+| Restored purchase | Confirm access and update profile/backend entitlement. | RevenueCat/store proof |
+| Destructive confirm | Use explicit object name, consequence, and cancellation path. | UI test |
+
+## Bug Traps
+
+- Attribution is visible but not persisted to analytics/person/backend.
+- Paywall hides restore purchases or legal links.
+- `Other` attribution has no free text.
+- Permission prompt appears before the user understands why.
+- Loading states resize buttons or cards.
+- Empty states have no useful first action.
+- Web purchase does not map to mobile entitlement.
+- Account deletion exists in docs but not in the app/store console.
+- Mobile text fits in English but clips at larger accessibility sizes.
+- HTML proof uses different tokens than `DESIGN.md`.
+- Motion uses ad-hoc durations instead of the tokenized `motion.*` scale.
+- framer-motion / `motion` imports leak into the mobile binary (SwiftUI/Flutter) instead of staying on web surfaces.
+- Animations ignore `prefers-reduced-motion`.
+- Tappable controls are flat with no press state, so they feel broken.
+- Everything animates (theme-park motion) instead of motion that clarifies what just happened.
+- Haptics fire on navigation/scroll/every tap until they become noise.
+- Keyboard covers the input or hides the submit button; dismissal is jarring or impossible.
+- Loading shows a bare spinner and layout jumps instead of a size-preserving skeleton.
+
+## Motion Consistency And Reduced Motion
+
+Motion is a tokenized contract, not per-screen improvisation. Every transition reads the shared motion intent in `DESIGN.md`. Promotion emits CSS variables and stack-specific Swift, TypeScript, and Dart bindings.
+
+- **Web surfaces (landing pages, funnels, web paywall, Design Room preview):** this is where motion ships. Animate with framer-motion / the `motion` library, reading durations from the promoted `--motion-*` CSS variables. Use entrance/stagger, `AnimatePresence` for route/state changes, and `whileTap` press feedback.
+- **Mobile binary (SwiftUI / Flutter / React Native):** do not import framer-motion. Use the selected stack's native animation API and promoted token binding. Equivalent names do not establish equivalent behavior; verify the implementation on that stack.
+- **Motion Consistency:** one duration/easing scale across every surface; no ad-hoc millisecond values; transitions in the 150-300ms range for standard UI feedback.
+- **Reduced Motion:** honor `prefers-reduced-motion` (web `useReducedMotion()` plus reduced-motion CSS; native reduce-motion settings). Replace transforms with instant or opacity-only changes and never block first paint on an animation.
+
+When the `ui-ux-pro-max` skill is available, adapt its senior-grade pattern, motion, and anti-pattern guidance (visible focus states, smooth 150-300ms transitions, reduced-motion support). Reference it; do not copy its data verbatim into this repo.
+
+## Premium Craft Details
+
+Premium is not flashy; it is the compounding effect of many invisible decisions. These five details ship as platform-neutral component contracts plus a SwiftUI reference adapter. Expo or React Native, Flutter, and future stacks implement and prove their own native adapters. Full doctrine: `knowledge/design/premium-mobile-craft.md`.
+
+| Detail | Premium bar | Boilerplate | Reduced-motion / accessibility |
+| --- | --- | --- | --- |
+| Press states & spring physics | Every tappable control gives ~100ms physical feedback (scale/dim spring or iOS 26 Liquid Glass), never a flat rectangle | `.buttonStyle(.premiumPress)` / `.buttonStyle(.glass)`; `PremiumMotion.press` | Keep opacity/haptic cue; drop the scale transform |
+| Subtle animations | Motion only when it answers a question the user just asked; 150-300ms; tokenized, never improvised | `PremiumMotion.standard`; `.premiumAnimation(_:value:)` | Collapse to instant/opacity change; never block first paint |
+| Haptics | Confirm state changes and decisions only — not navigation, scrolling, or idle taps | `.sensoryFeedback(for:trigger:)`; `Haptics.Event.play()` | Respect system Haptics setting |
+| Keyboard behavior | Input/submit never covered; dismissal is intentional; focus/blur deliberate | `.premiumInteractiveKeyboardDismiss()`, `KeyboardDoneToolbar`, `.swipeFocusGesture` | Maintain visible focus order at large text sizes |
+| Loading & empty states | Size-preserving skeleton/shimmer (or status text), not a bare spinner; empty states explain what/why + one action | `.skeleton(isLoading)`, `EmptyStateView` | Static skeleton, no shimmer sweep, under Reduce Motion |
+
+These details are additive to the State Matrix above, not a replacement: the State Matrix defines *which* states each surface must handle; Premium Craft defines how they *feel*.
+
+## Source Ledger
+
+| Source | Type | What was learned | Adopted | Rejected |
+| --- | --- | --- | --- | --- |
+| Refero or fallback pending | style/screen/flow | Pending | Pending | Pending |
+
+## Acceptance Checklist
+
+- [ ] Refero used, export provided, blocked, or fallback approved.
+- [ ] Pattern inventory covers all launch-critical surfaces.
+- [ ] Flow maps preserve the onboarding playbook.
+- [ ] State matrix covers loading/error/offline/permission/premium/destructive states.
+- [ ] Premium Craft details (press states, subtle motion, haptics discipline, keyboard behavior, skeleton/empty states) are honored on in-app surfaces with reduced-motion handling.
+- [ ] `ux-patterns.html` or `design/design-room.html` renders the flow architecture.
+- [ ] Decisions map to `DESIGN.md`, `analytics/ANALYTICS.md`, `product/ONBOARDING.md`, `revenue/REVENUE_OPS.md`, and `engineering/PRODUCTION_READINESS.md`.

package/catalog/generated/firstparty/examples/workspace/business/state/LAUNCH_TRACE.md

@@ -0,0 +1,29 @@
+# Launch Trace
+
+Status: partial until research, product, design, onboarding, revenue, analytics, store, and engineering decisions are linked.
+
+## Decision Trace
+
+| Trace ID | Source evidence | Product decision | Design decision | Build contract | Verification |
+| --- | --- | --- | --- | --- | --- |
+| TRACE-001 | strategy/RESEARCH.md | PRODUCT.md | DESIGN.md | engineering/TECH_SPEC.md | engineering/PRODUCTION_READINESS.md |
+
+## Rejected Decisions
+
+Decisions considered and rejected, and why — so future sessions do not re-litigate them.
+
+| Rejected decision | Why rejected |
+| --- | --- |
+| replace with a rejected route | evidence pointed elsewhere |
+
+## Founder-Only Decisions
+
+Decisions that require founder approval, with approval status.
+
+| Decision | Status |
+| --- | --- |
+| replace with a founder-gated decision | pending |
+
+## Blockers
+
+Implementation blockers and proof blockers that keep trace rows from verifying.

package/catalog/generated/firstparty/examples/workspace/business/store/app-store-listing/APP_STORE_LISTING.md

@@ -0,0 +1,160 @@
+# {{APP_NAME}} App Store Listing Packet
+
+Docs refreshed: Pending
+ASC app ID: Pending
+Bundle ID: {{IOS_BUNDLE_ID}}
+Primary locale: en-US
+Status: partial
+
+This packet is the Apple listing source of truth. It connects ASO, App Store Connect fields, App Privacy, pricing, RevenueCat, web funnels, screenshots, localization, marketing surfaces, and the V1 scalable slice from `11_STAR_EXPERIENCE.md`.
+
+## Source Ledger
+
+| Source | Checked at | Decision affected | Notes |
+| --- | --- | --- | --- |
+| Apple App information docs | Pending | name, subtitle, privacy URL | Refresh before final paste |
+| Apple Platform version docs | Pending | promo text, description, keywords, review notes | Refresh before final paste |
+| Apple App Privacy docs | Pending | privacy questionnaire | Refresh before final paste |
+| Apple privacy manifest docs | Pending | `store/APPLE_APP_STORE_REQUIREMENTS.md`, `PrivacyInfo.xcprivacy`, required reason APIs, SDK manifests/signatures, Xcode privacy report | Refresh before ASC upload readiness |
+| Apple protected resources and ATT docs | Pending | `Info.plist` purpose strings, `NSUserTrackingUsageDescription`, permission fallback route | Refresh before ASC upload readiness |
+| Apple upload builds docs | Pending | archive/upload delivery warnings and processing status | Refresh before upload |
+| Apple IAP/pricing docs | Pending | products, prices, trials | Refresh before final paste |
+| ASO research | Pending | keywords, metadata, screenshots | AppKittie/ASO skill/App Store evidence |
+| RevenueCat/Stripe docs | Pending | entitlement and web funnel | Refresh before final pricing |
+| Rork ASC CLI skills | Pending | metadata sync, localization, screenshots, pricing, release validation | Refresh before CLI guidance |
+| 11-star experience | Pending | screenshot story, preview hook, CPP/event promise | `11_STAR_EXPERIENCE.md` |
+| ParthJadhav/app-store-screenshots | Pending | local screenshot composition/export board, locale decks, iPhone/iPad/Play PNG output | Refresh before using the external skill |
+| Screenshot packet | Pending | iPhone/iPad wells, App Icon, App Preview, copy overlay, final upload paths | `SCREENSHOTS.md` |
+
+## ASC CLI Route And IDs
+
+| Surface | ASC route | Current ID/path | Dry-run proof | Apply/upload status | Founder gate |
+| --- | --- | --- | --- | --- | --- |
+| App IDs | `asc-id-resolver` | app/app-info/version/localization IDs pending | Pending | read-only | no mutation |
+| App creation | `app-store-connect-cli.md` + `asc-app-create-ui` when needed | app record pending | preflight pending | blocked | approval before app creation |
+| Metadata | `asc-metadata-sync` | `metadata/` pending | `asc metadata validate/push --dry-run` pending | blocked | approval before push |
+| Localization | `asc-localize-metadata` | target locale files pending | field-limit validation pending | blocked | approval before upload |
+| Screenshots | `asc-screenshot-resize` + `asc-shots-pipeline` | version-localization ID pending | sizes/validate output pending | blocked | approval before upload |
+| Pricing | `asc-ppp-pricing` | base territory and import CSV pending | pricing summary/import dry-run pending | blocked | approval before price changes |
+| Subscriptions | `asc-subscription-localization` + `asc-revenuecat-catalog-sync` | product/subscription IDs pending | catalog diff pending | blocked | approval before create/update |
+| TestFlight | `asc-testflight-orchestration` | groups/testers/build state pending | beta distribution dry-run pending | blocked | approval before external distribution |
+| Release health | `asc-submission-health` + `asc-release-flow` | build/version IDs pending | `asc validate` pending | blocked | approval before submit/release |
+
+## Default Product Page
+
+| ASC page | Field | Limit | Paste value | Source | Status |
+| --- | --- | ---: | --- | --- | --- |
+| App Information | Name | 30 chars | Pending | brand | blocked |
+| App Information | Subtitle | 30 chars | Pending | ASO keyword map | blocked |
+| App Information | Category | n/a | Pending | category research | blocked |
+| App Information | Privacy Policy URL | URL | Pending | public legal page | blocked |
+| App Information | Privacy Choices URL | URL | Pending | account/data deletion page | blocked |
+| iOS App Version | Promotional Text | 170 chars | Pending | launch angle | blocked |
+| iOS App Version | Description | 4000 chars | Pending | metadata optimization | blocked |
+| iOS App Version | Keywords | 100 bytes | Pending | keyword research | blocked |
+| iOS App Version | Support URL | URL | Pending | support page | blocked |
+| iOS App Version | Marketing URL | URL | Pending | landing page | blocked |
+| Review Information | Notes | 4000 bytes | Pending | reviewer path | blocked |
+
+## App Privacy Questionnaire
+
+Worksheet: `app-privacy-questionnaire.html`
+Pre-ASC requirements packet: `store/APPLE_APP_STORE_REQUIREMENTS.md`
+
+| Apple data type | Collected | Linked | Tracking | Purposes | Source/vendor | Proof |
+| --- | --- | --- | --- | --- | --- | --- |
+| Email Address | Pending | Pending | Pending | account, support, email | auth/email provider | `trust/PRIVACY.md` |
+| User ID | Pending | Pending | Pending | account, entitlement | backend/RevenueCat | `analytics/ANALYTICS.md`, `revenue/REVENUE_OPS.md` |
+| Purchase History | Pending | Pending | Pending | entitlement, support | Apple/RevenueCat/Stripe | `revenue/REVENUE_OPS.md` |
+| Product Interaction | Pending | Pending | Pending | analytics, personalization | PostHog | `analytics/ANALYTICS.md` |
+| Crash Data | Pending | Pending | Pending | diagnostics | Sentry/Apple | `engineering/PRODUCTION_READINESS.md` |
+
+Do not publish App Privacy answers until this table matches `trust/PRIVACY.md`, `analytics/ANALYTICS.md`, `revenue/REVENUE_OPS.md`, SDK manifests, backend schema, vendor behavior, and `store/APPLE_APP_STORE_REQUIREMENTS.md`.
+
+## Apple Pre-ASC Requirements
+
+| Gate | Required proof | Source | Status |
+| --- | --- | --- | --- |
+| Privacy manifest | `PrivacyInfo.xcprivacy` exists in app target resources and declares `NSPrivacyCollectedDataTypes`, `NSPrivacyAccessedAPITypes`, `NSPrivacyAccessedAPITypeReasons`, `NSPrivacyTracking`, and `NSPrivacyTrackingDomains` as applicable | `store/APPLE_APP_STORE_REQUIREMENTS.md` | blocked |
+| Required reason APIs | Code and SDK audit records every required reason API category and Apple-approved reason | `store/APPLE_APP_STORE_REQUIREMENTS.md` | blocked |
+| Third-party SDKs | Apple-listed SDKs have bundled privacy manifests and SDK signatures where required | `store/APPLE_APP_STORE_REQUIREMENTS.md` | blocked |
+| Xcode privacy report | Archive-generated privacy report is reconciled with App Privacy answers and Privacy Nutrition Labels | `store/APPLE_APP_STORE_REQUIREMENTS.md`, `app-privacy-questionnaire.html` | blocked |
+| Protected resources and ATT | `Info.plist` `UsageDescription` strings, denied-permission fallbacks, `NSUserTrackingUsageDescription`, and App Tracking Transparency route are reviewed | `store/APPLE_APP_STORE_REQUIREMENTS.md` | blocked |
+| Review and upload | account deletion, review notes, archive/upload proof, App Store Connect delivery warnings, and founder approval are recorded | `store/APPLE_SIGNING.md`, `store/STORE_CONSOLE.md` | blocked |
+
+## Pricing And Revenue Matrix
+
+| Product | ASC product ID | Type | Base territory | Price | Trial/intro | PPP/import proof | Subscription localization | RevenueCat entitlement | Offering/package | Web funnel/Stripe | Status |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| Monthly | Pending | auto-renewable subscription | USA | Pending | Pending | `asc-ppp-pricing` pending | `asc-subscription-localization` pending | `premium` | `default/monthly` | Pending | blocked |
+| Annual | Pending | auto-renewable subscription | USA | Pending | Pending | `asc-ppp-pricing` pending | `asc-subscription-localization` pending | `premium` | `default/annual` | Pending | blocked |
+| Lifetime | Pending | non-consumable | USA | Pending | n/a | `asc-ppp-pricing` pending | IAP localization pending | `premium` | `default/lifetime` | Pending | optional |
+
+Founder approval required before creating live products, changing prices, changing trial or intro offers, publishing purchase links, submitting IAP/subscriptions, or enabling external purchase calls to action.
+
+## Screenshots And App Previews
+
+Canonical screenshot packet: `SCREENSHOTS.md`
+
+| Slot | ASC device_type | Device well | Required/scaled decision | Screenshot count | Version localization ID | Locale | Headline | Source screen | Supporting asset | Tool | Size/alpha validation | Final path | Status |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | current 6.9 iPhone value from `asc screenshots sizes --all` | iPhone 6.9 | required or scaled per current ASC matrix | 1-10 screenshots | Pending | en-US | Pending | onboarding/value | optional Higgsfield background or Remotion frame | in-app simulator/MobAI/native iOS raw capture plus ParthJadhav/app-store-screenshots composed final | `asc-screenshot-resize` + `asc-shots-pipeline` pending | `screenshots/final/iphone-69-slot-1.png` | blocked |
+| 1 | current iPad 13 value from `asc screenshots sizes --all` | iPad 13 or 12.9 | required if iPad is supported, otherwise not needed | 1-10 screenshots | Pending | en-US | Pending | onboarding/value | design-system iPad frame | in-app simulator/MobAI/native iOS raw capture plus ParthJadhav/app-store-screenshots composed final | `asc-screenshot-resize` + `asc-shots-pipeline` pending | `screenshots/final/ipad-slot-1.png` | blocked |
+| 2 | current 6.9 iPhone value from `asc screenshots sizes --all` | iPhone 6.9 | required or scaled per current ASC matrix | 1-10 screenshots | Pending | en-US | Pending | core feature | optional Higgsfield visual or Remotion frame | in-app simulator/MobAI/native iOS raw capture plus ParthJadhav/app-store-screenshots composed final | `asc-screenshot-resize` + `asc-shots-pipeline` pending | `screenshots/final/iphone-69-slot-2.png` | blocked |
+| 3 | current 6.9 iPhone value from `asc screenshots sizes --all` | iPhone 6.9 | required or scaled per current ASC matrix | 1-10 screenshots | Pending | en-US | Pending | paywall/result | optional Higgsfield visual or Remotion frame | in-app simulator/MobAI/native iOS raw capture plus ParthJadhav/app-store-screenshots composed final | `asc-screenshot-resize` + `asc-shots-pipeline` pending | `screenshots/final/iphone-69-slot-3.png` | blocked |
+
+Rules:
+- Real app UI capture is the proof layer; raw screenshots are not final upload assets.
+- Prefer ParthJadhav/app-store-screenshots for local production composition and bulk export when screenshot decks need copy-led iPhone/iPad/Play variants; save `app-store-screenshots.json` or the equivalent board state when used.
+- Final upload candidates need production composition: headline, copy overlay, device frame or intentional frameless treatment, export target, and visual QA.
+- Use current `asc screenshots sizes --all` before choosing device types; do not rely on stale dimension tables.
+- Final upload candidates need alpha transparency removed, color-space checked, size validated, and associated with the correct version localization ID.
+- Higgsfield may create supporting visuals, icons, backgrounds, mascots, CPP/event media, or thumbnails only when tied to `DESIGN.md`.
+- Store screenshots and previews should express the V1 scalable slice from `11_STAR_EXPERIENCE.md` without crossing the line of feasibility.
+- Remotion may render screenshot frames, app previews, captioned demo clips, CPP/event variants, or social/store cuts from real UI only after `CONTENT_ASSETS.md` records route approval, license status, source inputs, render proof, and output paths.
+- Generated or rendered visuals must not imply unsupported features, claims, prices, or endorsements.
+
+## App Icon And Preview Assets
+
+| Asset | Store surface | Source | Route | Output | QA | Status |
+| --- | --- | --- | --- | --- | --- | --- |
+| App Icon | App Store search, product page, device install | `DESIGN.md`, category/competitor icon audit | Higgsfield, designer/founder-owned asset, or approved fallback | `app-icon/app-icon-1024.png` | no alpha, no rounded corners, thumbnail contrast, category differentiation | blocked |
+| App Preview 1 | App Store search/product page | real in-app footage | in-app simulator (Cmd+R)/MobAI/native iOS recording + Remotion edit, or approved founder-deferred route | `previews/ios-preview-1.mp4` | muted readability, poster frame, in-app footage only, no unsupported CTA | blocked |
+| Google Play promo | Play Store product page | real app footage or approved marketing footage | Remotion, Higgsfield, or owned media | YouTube URL pending | Play metadata compliance, captions, thumbnail | optional |
+
+## Custom Product Pages
+
+| Page | Audience/channel | Keyword set | Screens/previews | Deep link | Campaign | Measurement | Status |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Pending | Pending | Pending | Pending | Pending | Pending | App Analytics/ASA | not needed |
+
+Do not create a custom product page without a traffic source, measurement plan, and founder approval.
+
+## In-App Events
+
+| Event | Purpose/badge | Name | Short desc | Long desc | Schedule | Deep link | Media | IAP required | Status |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | not needed |
+
+Only use In-App Events for real time-bound in-app content with working deep links and review-ready media.
+
+## Localization
+
+| Locale | Market reason | Metadata route | Keywords | Screenshots | Subscription/IAP display names | Privacy/support URLs | Reviewer | Status |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| en-US | primary | `asc-metadata-sync` pending | Pending | Pending | `asc-subscription-localization` pending | Pending | Pending | blocked |
+
+## Approval Gates
+
+- [ ] Official Apple docs refreshed.
+- [ ] `store/APPLE_APP_STORE_REQUIREMENTS.md` passes `npm run check:apple-requirements -- --root .`.
+- [ ] Rork ASC CLI skills and local `asc --help` refreshed for command syntax.
+- [ ] App Privacy answers reviewed from actual data inventory.
+- [ ] Screenshot and preview concepts map to `11_STAR_EXPERIENCE.md`.
+- [ ] Pricing/products approved by founder.
+- [ ] RevenueCat/Stripe/web funnel mapping verified.
+- [ ] PPP/base-territory and subscription/IAP localization status reviewed.
+- [ ] Screenshots/app previews approved and dimension-checked.
+- [ ] Custom product pages and In-App Events marked ready or not needed.
+- [ ] Localized metadata and screenshots reviewed for each target locale.
+- [ ] `store/STORE_CONSOLE.md` and `app-store-listing.html` show exact click paths and paste values.

package/catalog/generated/firstparty/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.