@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/app-store-review/SKILL.md

@@ -1,363 +1,343 @@
 ---
 name: app-store-review
-description: "Prepare for App Store review and prevent rejections. Covers App Store review guidelines, app rejection reasons, PrivacyInfo.xcprivacy privacy manifest requirements, required API reason codes, in-app purchase IAP and StoreKit rules, App Store Guidelines compliance, ATT App Tracking Transparency, EU DMA Digital Markets Act, HIG compliance checklist, app submission preparation, review preparation, metadata requirements, entitlements, widgets, and Live Activities review rules. Use when preparing for App Store submission, fixing rejection reasons, auditing privacy manifests, implementing ATT consent flow, configuring StoreKit IAP, or checking HIG compliance."
+description: "App Store submission readiness and rejection prevention: Review Guidelines 2.1, 2.3, 2.5.1, 3.1.1, 4.2 and 5.1.2, PrivacyInfo.xcprivacy manifests and required-reason codes, IAP and StoreKit rules, ATT consent, EU DMA distribution, entitlements and usage strings, metadata limits, screenshots, TestFlight, phased release, Resolution Center appeals, HIG review items, widget and Live Activity review rules. Use when preparing a submission, fixing a rejection, auditing a privacy manifest, implementing the ATT prompt or checking IAP compliance. Not for keyword research, ranking, conversion copy, screenshot order or A/B tests (app-store-optimization)."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
-# App Store Review Preparation
+# App Store Review Readiness
 
-Guidance for catching App Store rejection risks before submission. Apple's May 2026 fraud-prevention update says App Review evaluated more than 9.1 million submissions in 2025 and rejected more than 2 million, so treat rejection prevention as a normal release-readiness step and re-check official Apple sources before quoting annual statistics.
+Most rejections are predictable. They come from a missing demo account, a
+privacy declaration that disagrees with what the binary actually sends, a
+purchase path that skips StoreKit, or metadata that promises something the app
+does not do. This skill finds those before App Review does.
 
-## Contents
+Apple publishes a yearly App Store fraud-prevention report with the number of
+submissions App Review looked at and turned down. Quote those figures only from
+the current report, never from memory.
 
-- [Overview](#overview)
-- [Top Rejection Reasons and How to Avoid Them](#top-rejection-reasons-and-how-to-avoid-them)
-- [PrivacyInfo.xcprivacy -- Privacy Manifest Requirements](#privacyinfoxcprivacy-privacy-manifest-requirements)
-- [Data Use, Sharing, and Privacy Policy (Guideline 5.1.2)](#data-use-sharing-and-privacy-policy-guideline-512)
-- [In-App Purchase and StoreKit Rules (Guideline 3.1.1)](#in-app-purchase-and-storekit-rules-guideline-311)
-- [HIG Compliance Checklist](#hig-compliance-checklist)
-- [App Tracking Transparency (ATT)](#app-tracking-transparency-att)
-- [EU Digital Markets Act (DMA) Considerations](#eu-digital-markets-act-dma-considerations)
-- [Entitlements and Capabilities](#entitlements-and-capabilities)
-- [Submission Workflow](#submission-workflow)
-- [Metadata Best Practices](#metadata-best-practices)
-- [Appeal Process](#appeal-process)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+## Scope and boundaries
 
-## Overview
+- Metadata questions (name, subtitle, keywords, captions, product page) are
+  answered here only from the compliance side: accuracy, field limits,
+  misleading content and screenshot rules.
+- Keyword research, ranking strategy, conversion copy, screenshot order and
+  A/B tests belong to `app-store-optimization`.
+- Clean Swift 6 concurrency or a tidy StoreKit wrapper is not evidence of
+  compliance. Check the guideline, not the code quality.
 
-Use this SKILL.md for quick guidance on common rejection reasons and key policies. Use the references for detailed checklists and privacy manifest specifics.
+Limits to state on every metadata answer:
 
-For prompts about keywords, screenshot captions, product-page metadata, or metadata rejection risk, answer from a compliance angle and explicitly defer keyword research, ranking strategy, conversion optimization, screenshot ordering, and A/B testing to `app-store-optimization`. Keep App Review metadata guidance limited to accuracy, field limits, misleading-content risk, and screenshot compliance. Always surface the rejection-prone format checks: app name 30 characters, subtitle 30 characters, keyword field 100 characters with comma-separated keywords and no spaces after commas, screenshots showing actual app UI, 6.9-inch iPhone screenshots as the primary current iPhone set, and 13-inch iPad screenshots when the app runs on iPad.
-
-For full submission readiness audits, separate blocking upload/review issues from ordinary cleanup. Treat Xcode 26+ with the relevant platform SDK 26+ as a blocking App Store Connect upload requirement after April 28, 2026. Cross-check privacy manifests, App Store privacy nutrition labels, privacy policy, ATT state, runtime network behavior, and SDK behavior against each other; the declarations and observed behavior must align.
-
-### Blocking Submission Checks
-
-Escalate these as blockers before ordinary cleanup:
-
-- Uploads after April 28, 2026 that are not built with Xcode 26+ and the relevant platform SDK 26+
-- Privacy manifest, privacy label, privacy policy, ATT state, SDK transmissions, or audited runtime network behavior mismatches
-- Digital goods and subscriptions that bypass StoreKit IAP, or external purchase paths/links/buttons/CTAs for digital goods, unless current rules or approved entitlements allow them
-- Missing required screenshot sets: 6.9-inch iPhone screenshots, and 13-inch iPad screenshots when the app runs on iPad
-- Login-gated or non-obvious features without demo credentials, demo mode, and clear App Review notes
-
-## Top Rejection Reasons and How to Avoid Them
-
-### Guideline 2.1 -- App Completeness
-
-The app must be fully functional when reviewed. Apple rejects for:
-
-- Placeholder content, lorem ipsum, or test data visible anywhere
-- Broken links or empty screens
-- Features behind logins without demo credentials provided in App Review notes
-- Features that require hardware Apple does not have access to
-
-**Prevention:**
-- Provide demo account credentials in the App Review Information notes field in App Store Connect
-- Walk through every screen and verify real content is present
-- Test all flows end-to-end, including edge cases like empty states and error conditions
-
-### Guideline 2.3 -- Accurate Metadata
-
-- App name must match what the app actually does
-- Screenshots must show the actual app UI, not marketing renders or mockups
-- Description must not contain prices (they vary by region)
-- No references to other platforms ("Also available on Android")
-- Keywords must be relevant -- no competitor names or unrelated terms
-- Category must match the app's primary function
-
-### Guideline 4.2 -- Minimum Functionality
-
-Apple rejects apps that are too simple or are just websites in a wrapper:
-
-- WKWebView-only apps are rejected unless they add meaningful native functionality
-- Single-feature apps may be rejected if the feature is better suited as part of another app
-- Apps that duplicate built-in iOS functionality without significant improvement are rejected
-
-### Guideline 2.5.1 -- Software Requirements
-
-- Must use public APIs only -- private API usage is an instant rejection
-- As of April 28, 2026, uploads to App Store Connect must be built with Xcode 26 or later using the relevant platform SDK 26 or later
-- Deployment target support is a product and compatibility decision, not an App Review rule
-- Must not download or execute code that introduces or changes app features or functionality after review, except where Apple guidelines and agreements explicitly allow interpreted code
-
-## PrivacyInfo.xcprivacy -- Privacy Manifest Requirements
-
-A privacy manifest is required when your app code, an executable, a dynamic library, or a third-party SDK uses Apple's required-reason API categories or declares collected data/tracking behavior.
-
-**See:** [references/privacy-manifest.md](references/privacy-manifest.md) for the full structure, reason codes, and checklists.
-
-### Summary
-
-- Required-reason API categories are file timestamps, system boot time, disk space, active keyboards, and UserDefaults; each requires an approved reason code when used.
-- Before final submission, re-check Apple's current required-reason API documentation and do not choose broad, convenient, or invented reason codes.
-- Required-reason API declarations belong in the bundle that contains the code using the API; every app target, executable, dynamic library, framework, or SDK bundle containing manifest-relevant code needs the matching manifest declarations.
-- Each SDK, executable, or dynamic library that collects data, uses required-reason APIs, enables data collection/tracking, or contacts tracking domains needs manifest attention in the bundle containing that code; SDK code cannot rely on the host app's manifest to report the SDK's own usage.
-- Manifest declarations must match App Store privacy nutrition labels, SDK behavior, and the app's presented functionality.
-
-## Data Use, Sharing, and Privacy Policy (Guideline 5.1.2)
-
-- A privacy policy URL must be set in App Store Connect AND accessible within the app
-- The privacy policy must accurately describe what data you collect, how you use it, and who you share it with
-- App Store privacy nutrition labels must match your actual data collection practices
-- Privacy labels, privacy manifests, SDK disclosures, and runtime behavior should tell the same story
-
-## In-App Purchase and StoreKit Rules (Guideline 3.1.1)
-
-IAP rules are strict and heavily enforced.
-
-### What Generally Requires Apple IAP
-
-Digital content, features, subscriptions, and services unlocked in the app generally must use Apple's In-App Purchase system unless a specific App Review guideline exception, regional rule, or approved entitlement applies. Remove external purchase paths unless the current rules or an approved entitlement allow them:
-
-- Premium features or content unlocks
-- Subscriptions to app functionality
-- Virtual currency, coins, gems
-- Ad removal
-- Digital tips or donations
-
-### What Does NOT Require IAP
-
-- Physical products (e-commerce)
-- Ride-sharing, food delivery, real-world services
-- One-to-one services (tutoring, consulting booked through the app)
-- Enterprise/B2B apps distributed through Apple Business Manager
-
-### Subscription Display Requirements
-
-- Price, duration, and auto-renewal terms must be clearly displayed before purchase
-- Free trials must clearly show trial duration, post-trial price, billing frequency, auto-renewal, and cancellation terms before purchase
-- Remove external purchase links, buttons, calls to action, or purchase paths for digital goods unless the current storefront rules or an approved entitlement explicitly allow them
-- "Reader" apps (Netflix, Spotify) may link to external sign-up but cannot offer IAP bypass
-
-### StoreKit Implementation Checklist
-
-- Consumables, non-consumables, and subscriptions must be correctly categorized in App Store Connect
-- Restore purchases functionality must be present and working
-- Transaction verification should use StoreKit 2 `Transaction.currentEntitlements` or server-side validation
-- Handle interrupted purchases, deferred transactions, and ask-to-buy gracefully
-
-## HIG Compliance Checklist
-
-See [references/review-checklists.md](references/review-checklists.md) for the full HIG checklist (navigation, modals, widgets, system feature support, launch screen, empty states). This section stays intentionally brief to keep SKILL.md concise.
-
-## App Tracking Transparency (ATT)
-
-### When ATT Is Required
-
-If your app tracks users across other companies' apps or websites, you must:
-
-1. Request permission via `ATTrackingManager.requestTrackingAuthorization` before any cross-app or cross-website tracking occurs, including tracking-capable SDK behavior
-2. Respect the user's choice -- disable cross-app and cross-website tracking if the user denies permission
-3. Not gate app functionality behind tracking consent ("Accept tracking or you cannot use this app" is rejected)
-4. Provide a clear purpose string in `NSUserTrackingUsageDescription` explaining what tracking is used for
-
-### When ATT Is NOT Required
-
-If you do not track users across apps or websites, do not show the ATT prompt. Apple rejects unnecessary ATT prompts.
-
-### ATT Implementation
+| Field | Rule |
+|---|---|
+| App name | 30 characters |
+| Subtitle | 30 characters |
+| Keyword field | 100 characters, comma-separated, no space after a comma |
+| iPhone screenshots | 6.9-inch set is the primary set |
+| iPad screenshots | 13-inch set for any app that supports iPad |
+| Screenshot content | the real app UI |
+
+## Triage: blockers first
+
+A full audit reports two lists: things that stop upload or review, and cleanup.
+Treat these as blockers:
+
+1. The build is uploaded after April 28, 2026 and was not produced with Xcode 26
+   or later against the platform's 26 SDK or later.
+2. The privacy manifest, the nutrition label, the privacy policy, the ATT state,
+   what bundled SDKs transmit and what the app does on the network (audited at
+   runtime) do not tell the same story.
+3. Digital goods or subscriptions are sold outside StoreKit IAP, or the app shows
+   an outside checkout (link, button, call to action or any other route) for
+   them, without a storefront rule or granted entitlement that allows it.
+4. The 6.9-inch iPhone screenshot set is missing, or the 13-inch iPad set is
+   missing for an app that runs on iPad.
+5. Features behind a login, or features a reviewer would not find alone, ship
+   with no demo credentials, no demo mode and no App Review notes.
+
+Everything else (copy polish, an optional screenshot, a HIG nit) is cleanup.
+
+## Guidelines that cause most rejections
+
+### 2.1 App Completeness
+
+Rejected: placeholder text, lorem ipsum or visible test records; broken links and
+empty screens; login-gated features with no demo credentials in the review notes;
+features that need hardware Apple does not have.
+
+Prevent it: put working demo credentials in the notes field under App Review
+Information in App Store Connect, walk every screen to confirm real content, and
+run every flow from start to finish including its empty and error states.
+
+### 2.3 Accurate Metadata
+
+- The name reflects what the app does. Screenshots show the running app, not a
+  marketing render or device mockup of screens that do not exist.
+- Leave prices out of the description; they differ per storefront.
+- Do not mention other platforms (for example, "also on Android").
+- Keywords describe the app itself; competitor names and off-topic terms do not
+  belong. The primary
+  category must match the main function.
+
+### 4.2 Minimum Functionality
+
+- A shell around `WKWebView` is rejected unless it adds meaningful native
+  features.
+- A single-feature app can be rejected when it would fit better inside another
+  app.
+- Recreating a built-in iOS feature without a significant improvement is
+  rejected.
+
+### 2.5.1 Software Requirements
+
+- Public APIs only. Private API use is rejected outright.
+- From April 28, 2026, uploads need Xcode 26+ and the matching 26+ platform SDK.
+- The minimum deployment target is a product and compatibility choice; App
+  Review does not set it.
+- The app may not download or run code that adds or changes features after
+  review. The exception is interpreted code that Apple's guidelines and
+  agreements explicitly allow.
+
+## Privacy manifest in brief
+
+`PrivacyInfo.xcprivacy` is needed whenever code in the app, in an executable, in
+a dylib or in a vendor SDK calls a required-reason API, or when that code
+collects data or tracks. Five API categories carry this requirement (boot time,
+`UserDefaults`, file timestamps, free disk space and the list of active
+keyboards), and every use needs an approved reason code.
+
+- Pick the code that describes the actual use. Never pick a broad or convenient
+  one, and never make one up. Re-read Apple's current list before each release.
+- Declare the use inside whichever bundle ships the calling code: app target,
+  executable, dylib, framework or SDK bundle. An SDK cannot lean on the host
+  app's manifest for its own calls.
+- The manifest has to agree with the nutrition label, with SDK behaviour and with
+  the features the app presents.
+
+Codes, plist layout and SDK rules: [privacy manifest reference](references/privacy-manifest.md).
+
+## 5.1.2 Privacy policy and data disclosure
+
+- The policy URL appears in App Store Connect, and the app links to the same
+  policy from its own UI.
+- The policy describes what is collected, why, and who receives it.
+- Nutrition labels reflect real collection. Labels, manifests, SDK disclosures
+  and runtime behaviour must all agree.
+
+## 3.1.1 Paying for digital things
+
+When the app unlocks digital content, a feature, a subscription or a digital
+service, the sale normally runs through Apple IAP, unless a guideline exception, a regional rule or
+an approved entitlement says otherwise.
+
+| Needs IAP | Does not need IAP |
+|---|---|
+| Unlocking premium features | Physical goods |
+| Subscriptions to app functionality | Real-world services such as rides or food delivery |
+| Virtual currency | Person-to-person services, for example a live tutor or consultant |
+| Removing ads | Business apps for organizations, distributed as custom apps via Apple Business Manager |
+| Digital tips to creators | Donations to approved nonprofits (see 3.2.1 and 3.2.2) |
+
+Rules around the purchase:
+
+- Before a subscription is bought, the paywall states what it costs, how long a
+  period lasts and that it renews on its own.
+- For a free trial, show the trial length, the price after it, how often billing
+  happens, that it renews automatically, and how to cancel, all before purchase.
+- Strip any route to an outside checkout for digital goods, whether a link, a
+  button or a nudge in copy, unless the storefront's current rule or a granted
+  entitlement permits it. These rules differ by region and have changed recently; read the
+  current 3.1.1(a) and 3.1.3 text for the target storefront.
+- Reader apps may link out to account sign-up with the matching entitlement, but
+  may not offer a way around IAP for in-app purchases.
+
+StoreKit checks:
+
+- Products are typed correctly in App Store Connect (consumable, non-consumable,
+  subscription).
+- A Restore Purchases control exists and works.
+- Entitlements are verified with StoreKit 2 `Transaction.currentEntitlements` or
+  on the server.
+- A purchase that is interrupted, or deferred while a parent approves it through
+  Ask to Buy, leaves the UI in a sane state.
+
+## HIG items App Review looks at
+
+Navigation, modals, system features and widgets are listed in the
+[HIG section of the checklists](references/review-checklists.md#hig-compliance-checklist);
+launch screen and empty-state rules sit in the Design block of the
+[pre-submission list](references/review-checklists.md#pre-submission-checklist).
+
+## App Tracking Transparency
+
+- Tracking a user across other companies' apps or sites, SDK tracking included,
+  needs `ATTrackingManager.requestTrackingAuthorization` to return authorized
+  first.
+- If the user says no, turn that tracking off.
+- Never lock a feature behind tracking consent; that is rejected.
+- Add an `NSUserTrackingUsageDescription` string.
+- An app that does not track must not show the prompt. Apple rejects needless
+  prompts.
 
 ```swift
 import AppTrackingTransparency
 
+protocol AdServing {
+    func configure(personalized: Bool)
+}
+
 @MainActor
-func requestTrackingPermission() async {
+func resolveAdPersonalization(using ads: AdServing) async {
     let status = await ATTrackingManager.requestTrackingAuthorization()
     switch status {
     case .authorized:
-        // Enable tracking, initialize ad SDKs with tracking
-        break
+        ads.configure(personalized: true)
     case .denied, .restricted:
-        // Use non-personalized ads and disable cross-app/cross-website tracking
-        break
+        ads.configure(personalized: false)
     case .notDetermined:
-        // Should not happen after request, handle gracefully
-        break
+        ads.configure(personalized: false)
     @unknown default:
-        break
+        ads.configure(personalized: false)
     }
 }
 ```
 
-**Timing:** Request ATT permission after the app is active and the user has context for why tracking is being requested. Do not show the prompt immediately on first launch or stack it with another system permission prompt.
-
-## EU Digital Markets Act (DMA) Considerations
+`.notDetermined` can come back when the app was not active; keep the safe
+default and ask again later. Ask only when the app is in the foreground
+and the user can see why, never as the first thing on first launch, and never right
+behind another system permission alert.
 
-For apps distributed in the EU, and for other region-specific distribution models as Apple updates them:
+## EU Digital Markets Act
 
-- Alternative browser engines are permitted on iOS in the EU
-- Alternative app marketplaces exist -- apps may be distributed outside the App Store
-- External payment links may be allowed under specific conditions, with Apple's commission structure adjusted
-- Notarization is required even for sideloaded apps distributed outside the App Store
-- Apps using alternative distribution must still meet Apple's notarization requirements for security
+- Alternative browser engines are allowed on iOS in the EU.
+- Alternative app marketplaces and web distribution exist, so an app can ship
+  outside the App Store there.
+- External payment links can be allowed, under conditions and with a different
+  commission.
+- An app shipped through a marketplace or the web still goes through Apple's iOS
+  notarization and must meet its security requirements.
 
-## Entitlements and Capabilities
+## Entitlements and usage strings
 
-Every entitlement must be justified. Apple reviews these closely:
+Every entitlement needs a reason App Review can see in the product.
 
-| Entitlement | Apple Scrutiny |
+| Capability | What review expects |
 |---|---|
-| Camera | Must explain purpose in `NSCameraUsageDescription` |
-| Location (Always) | Must have clear, user-visible reason for background location |
-| Push Notifications | Must not be used for marketing without user opt-in |
-| HealthKit | Must actually use health data in a meaningful way |
-| Background Modes | Each mode (audio, location, VoIP, fetch) must be justified and actively used |
-| App Groups | Must explain what shared data is needed |
-| Associated Domains | Universal links must actually resolve and function |
-
-### Usage Description Strings
-
-Usage descriptions in Info.plist must be specific about what data is accessed and why:
-
-```xml
-// REJECTED -- too vague
-
-// APPROVED -- specific purpose
-"Your location is used to show nearby restaurants on the map."
-
-// REJECTED -- too vague
-"This app needs access to your camera."
-
-// APPROVED -- specific purpose
-"The camera is used to scan barcodes for price comparison."
-```
-
-Apple rejects vague usage descriptions. Always state what the data is used for in user-facing terms.
-
-## Submission Workflow
-
-### Pre-Submission Steps
-
-1. **Archive in Xcode.** Product > Archive (requires a Distribution signing identity). Verify the archive builds clean with zero warnings in Release configuration.
-2. **Upload to App Store Connect.** Use the Organizer window (Distribute App > App Store Connect) or `xcodebuild -exportArchive`. Automated uploads via `altool` or Transporter also work.
-3. **TestFlight internal testing.** The build is available to internal testers (your team) within minutes of processing. Walk through every screen and flow on at least two device sizes.
-4. **TestFlight external testing.** External groups require Beta App Review before first external distribution. Use this to validate with real users before full submission.
-5. **Submit for App Review.** In App Store Connect, select the build, fill in all metadata fields, attach screenshots, and click Submit for Review. Review timing varies; allow buffer for rejections, appeals, and metadata fixes.
-
-### Expedited Review Requests
-
-Apple grants expedited reviews for critical situations only:
-
-- Critical bug fix affecting existing users
-- Time-sensitive event (holiday launch, legal compliance deadline)
-- Security vulnerability patch
-
-Request via the Contact Us form in App Store Connect (App Review > Expedite Request). Provide a specific, factual justification. Do not request expedited review for initial launches or feature updates.
-
-### Phased Release
-
-After approval, you can enable phased release to gradually roll out the update:
-
-| Day | Percentage of Users |
-|-----|---------------------|
-| 1   | 1%                  |
-| 2   | 2%                  |
-| 3   | 5%                  |
-| 4   | 10%                 |
-| 5   | 20%                 |
-| 6   | 50%                 |
-| 7   | 100%                |
-
-Users who manually check for updates in the App Store will receive the update immediately regardless of phased release stage. You can pause, resume, or complete the rollout at any time from App Store Connect.
-
-## Metadata Best Practices
+| Camera | a clear `NSCameraUsageDescription` |
+| Location (Always) | a visible reason the user benefits from background location |
+| Push notifications | no marketing pushes without the user's opt-in |
+| HealthKit | health data used in a meaningful feature |
+| Background Modes | every declared mode (audio, location, VoIP, fetch) has a feature that uses it |
+| App Groups | the shared data is explained |
+| Associated Domains | universal links resolve and open the app |
 
-### App Name and Subtitle
+A usage string names the data and the user-facing reason:
 
-- **30 characters max** for the app name. Keep it memorable and unique.
-- **30 characters max** for the subtitle. Use it for a concise value proposition.
-- No generic terms that describe a category ("Photo Editor" alone is likely rejected).
-- No competitor names or trademarked terms you do not own.
-- No pricing information in the name or subtitle.
-- Name must be unique on the App Store -- Apple rejects duplicates.
-
-### Screenshot Requirements
-
-- Provide 1-10 screenshots per required platform and localization.
-- For iPhone, use the current App Store Connect screenshot specifications. As of May 2026, 6.9-inch iPhone screenshots are the primary accepted iPhone set; 6.5-inch screenshots are required only when 6.9-inch screenshots are not provided, and smaller iPhone displays can use scaled screenshots from larger sets.
-- For iPad apps, 13-inch iPad screenshots are required; smaller iPad displays can use scaled screenshots from larger sets.
-- Screenshots must show the **actual app UI** -- no misleading content, no features that do not exist.
-- Text overlays and marketing frames are allowed but must not obscure or misrepresent the actual interface.
-- Up to 10 screenshots per localization.
-- Screenshots for different localizations should show localized UI.
-
-### Keyword Field Compliance
-
-- 100-character limit, comma-separated, no spaces after commas.
-- Do not duplicate words already in your app name or subtitle (Apple indexes those automatically).
-- Use singular or plural, not both ("game" not "game,games").
-- No competitor names, trademarked terms, or irrelevant words.
-
-### App Preview Videos
-
-- **30 seconds max** per preview video.
-- Up to 3 preview videos per localization.
-- Must show the actual app running on device -- no pre-rendered animations of features that look different in practice.
-- App audio is captured; narration and background music are optional.
-- Avoid any framing, hand footage, or visual treatment that makes the preview misleading about the actual app experience.
-- First frame is used as the poster frame on the product page (choose carefully).
-
-## Appeal Process
-
-### Replying to Rejections
-
-All rejections appear in the **Resolution Center** in App Store Connect. To respond:
-
-1. Read the rejection message carefully -- it cites the specific guideline violated.
-2. Reply directly in the Resolution Center thread with a clear, factual explanation.
-3. If you made a fix, describe exactly what changed and resubmit the binary.
-4. If you believe the rejection is incorrect, explain why your app complies, with references to the specific guideline text.
-
-**Tone matters.** Be professional, specific, and concise. Provide demo credentials, screenshots, or screen recordings that demonstrate compliance. Avoid emotional language or threats.
-
-### Escalation to App Review Board
-
-If the Resolution Center exchange does not resolve the issue:
-
-1. Request an appeal to the **App Review Board** via the Resolution Center or the App Store Contact form (App Review > Appeal).
-2. The Board is a separate team from the original reviewer. Provide all context -- they review the full history.
-3. Board decisions are final for that submission, but you can always modify the app and resubmit.
-
-### Common Successful Appeal Strategies
-
-- **Provide a video walkthrough** showing the feature the reviewer could not find or access.
-- **Cite the specific guideline** and explain how the app satisfies each requirement.
-- **Include demo credentials** if the reviewer could not log in (the most common 2.1 rejection cause).
-- **Reference precedent** -- if similar apps exist on the App Store with the same pattern, note them (respectfully).
-- **Offer a compromise** -- if Apple objects to a specific implementation, propose an alternative that satisfies both sides.
-
-## Common Mistakes
-
-1. **Missing demo credentials.** Provide App Review login credentials in App Store Connect notes. Most Guideline 2.1 rejections are from reviewers unable to test behind a login.
-2. **Privacy manifest mismatch.** Declared data collection in PrivacyInfo.xcprivacy must match App Store privacy nutrition labels, SDK behavior, and app functionality.
-3. **Unnecessary ATT prompt.** Do not show the App Tracking Transparency prompt unless you actually track users across apps or websites. Apple rejects unnecessary prompts.
-4. **Vague usage descriptions.** "This app needs your location" is rejected. State the specific feature that uses the data.
-5. **Unapproved external purchase paths.** External payment links for digital goods are region- and entitlement-sensitive; do not add them without checking current Guideline 3.1.1(a) rules.
-6. **Treating code quality as review compliance.** Swift 6 concurrency annotations and StoreKit transaction handling matter, but they do not replace privacy, payment, metadata, and entitlement compliance checks.
-
-## Review Checklist
-
-Quick-check before every submission (full version in [references/review-checklists.md](references/review-checklists.md)):
-
-- [ ] No placeholder/test content; all features functional; demo credentials provided
-- [ ] App name matches functionality; screenshots are real; no prices in description; 6.9-inch iPhone and 13-inch iPad screenshots supplied when applicable
-- [ ] PrivacyInfo.xcprivacy present when required-reason APIs, tracking, collected data declarations, or SDK tracking domains apply; nutrition labels match reality
-- [ ] Privacy policy URL set and accessible in-app
-- [ ] Digital content uses IAP; subscription terms visible; restore purchases works; external purchase links/buttons/CTAs removed unless current rules or approved entitlements allow them
-- [ ] Dark Mode and Dynamic Type supported; standard navigation patterns
-- [ ] Built with Xcode 26+ and platform SDK 26+ for uploads after April 28, 2026; no private APIs; entitlements justified
-- [ ] ATT prompt only if cross-app or cross-website tracking occurs
+| Verdict | String |
+|---|---|
+| Approved | "We use where you are to place the closest charging stations on the map." |
+| Approved | "The camera scans a book's barcode so you can add it to your shelf." |
+| Rejected | "This app requires camera access." |
+| Rejected | "We use your photo library to improve your experience." |
+| Fixed | "Pick a photo from your library to use as your profile picture. Only the photo you choose is uploaded." |
+
+The second rejected string names a data type but gives no concrete purpose;
+"improve your experience" is the phrase review flags. The fixed version says
+which feature uses the data and what leaves the device.
+
+## Submission workflow
+
+1. Archive: Product > Archive with a Distribution signing identity, from a clean
+   Release build. Aim for zero warnings; it is good hygiene, not a review rule.
+2. Upload: in Organizer choose Distribute App, then App Store Connect; or run
+   `xcodebuild -exportArchive`. `altool` and Transporter also work.
+3. Internal TestFlight: internal testers see the build minutes after processing.
+   Try every flow on two or more screen sizes.
+4. External TestFlight: the first build sent to an external group goes through
+   Beta App Review.
+5. Submit: pick the build, complete metadata, attach screenshots, press Submit
+   for Review. Review time varies, so keep slack before a deadline.
+
+Expedited review is for a critical fix for existing users, a date-bound event
+(a holiday launch, a legal deadline) or a security patch. Ask through Contact
+Us > App Review > Expedite Request with a specific, factual reason. It is not for
+first launches or new features.
+
+Phased release for automatic updates: day 1 1%, day 2 2%, day 3 5%, day 4 10%,
+day 5 20%, day 6 50%, day 7 100%. Users who check for updates by hand get the
+build immediately. The rollout can be paused, resumed or finished early at any
+time.
+
+## Metadata rules
+
+- Name and subtitle: 30 characters each. The subtitle is a short value statement.
+  A bare category word such as "Photo Editor" is likely rejected; so are
+  competitor or trademarked terms and prices. The name must be unique.
+- Screenshots: 1 to 10 per required platform and localization. As of May 2026,
+  the 6.9-inch iPhone set is the primary one; the 6.5-inch set is required only
+  when there is no 6.9-inch set, and smaller iPhones get scaled images. Apps that
+  run on iPad need 13-inch iPad screenshots; smaller iPads are scaled.
+- Screenshot content: the real UI; never show a feature the build lacks. Captions and
+  frames are fine if they neither hide nor misstate the UI. Localized sets show
+  the localized UI.
+- Keywords: 100 characters, comma-separated with no spaces. Words already in the
+  name or subtitle are indexed, so do not repeat them. Use singular or plural,
+  not both. No competitor, trademark or unrelated terms.
+- App previews: up to 30 seconds, up to 3 per localization, captured from the app
+  on a device with the app's own audio (narration or music optional). No
+  misleading framing and no footage of hands holding a device. The first frame
+  is the poster frame.
+
+## Rejections and appeals
+
+- A rejection arrives in the Resolution Center with the guideline number.
+- Reply in that thread with facts. If you fixed the issue, say what changed and
+  upload a new binary. If you disagree, show how the app complies, quoting the
+  guideline.
+- Keep it professional, specific and short. Attach demo credentials, screenshots
+  or a screen recording. No emotional language, no threats.
+- For a formal appeal, go to the App Review Board through the Resolution Center or
+  Contact Us > App Review > Appeal. A separate team reads the whole history. The
+  ruling is final for that build; a changed build can still be submitted.
+
+What tends to work: a video walkthrough of the flagged feature, a point-by-point
+answer against the guideline text, fresh demo credentials (the usual 2.1 cause),
+a polite reference to comparable approved behaviour, and offering an alternative
+implementation.
+
+## Common mistakes
+
+1. No demo credentials; this drives most 2.1 rejections.
+2. The manifest disagrees with the nutrition label, an SDK, or the features.
+3. An ATT prompt in an app that does not track.
+4. Vague usage descriptions.
+5. External purchase routes without an approved path. This depends on region and
+   entitlement, so read the current 3.1.1(a).
+6. Treating good code (Swift 6 concurrency, careful StoreKit handling) as proof
+   of compliance.
+
+## Review checklist
+
+- [ ] No placeholder or test content; every feature works; demo credentials given
+- [ ] Name matches function; real screenshots; no prices in the description;
+      6.9-inch iPhone set, plus 13-inch iPad set for iPad-capable apps
+- [ ] Privacy manifest present wherever required-reason APIs, tracking, collected
+      data or SDK tracking domains apply; labels agree with it
+- [ ] Privacy policy URL in App Store Connect and inside the app
+- [ ] IAP for digital content; terms shown before purchase; restore works; no
+      external purchase CTAs unless allowed
+- [ ] Standard navigation; the UI holds up in Dark Mode and at large Dynamic Type
+- [ ] Toolchain is Xcode 26+ with a 26+ SDK (required from April 28, 2026); no
+      private APIs; every entitlement justified
+- [ ] ATT prompt only if the app tracks
+
+Full lists: [review checklists](references/review-checklists.md).
 
 ## References
 
-- Review checklists: [references/review-checklists.md](references/review-checklists.md)
-- Privacy manifest guide: [references/privacy-manifest.md](references/privacy-manifest.md)
-- Apple App Review Guidelines: https://developer.apple.com/app-store/review/guidelines/
-- Apple upcoming SDK requirements: https://developer.apple.com/news/upcoming-requirements/
-- App Store Connect screenshot specifications: https://developer.apple.com/help/app-store-connect/reference/app-information/screenshot-specifications/
-- Sosumi required-reason API docs: https://sosumi.ai/documentation/bundleresources/describing-use-of-required-reason-api
+- Guidelines text: https://developer.apple.com/app-store/review/guidelines/
+- SDK and Xcode deadlines: https://developer.apple.com/news/upcoming-requirements/
+- Screenshot sizes: https://developer.apple.com/help/app-store-connect/reference/screenshot-specifications/
+- Reason-code documentation: https://developer.apple.com/documentation/bundleresources/describing-use-of-required-reason-api
+- [Privacy manifest reference](references/privacy-manifest.md)
+- [Review checklists](references/review-checklists.md)