appstore-precheck 1.1.0 → 1.5.1

package/CHANGELOG.md

@@ -3,6 +3,157 @@
 All notable changes to this project are documented here. Versioning follows
 [SemVer](https://semver.org/). Released as git tags.
 
+## [1.5.1] - 2026-06-30
+
+### Changed
+
+- Plugin manifest descriptions no longer embed drifting check counts
+- README uninstall: Codex uses /plugins UI
+- cross-tool-verification.md plugin install paths documented
+- GitHub release v1.5.0 notes amended; npm 1.5.1 published
+
+## [1.5.0] - 2026-06-30
+
+### Added
+- **Tier B v1 — 6 heuristic Pierre deep-review checks** (28 total, up from 22). New Phase 4 items
+  in guideline order: **2.1** review notes / demo account quality, **2.2** beta/test language,
+  **2.3.4** app preview consistency, **2.3.9** incentivized review copy, **4.5.1–4.5.3** push /
+  HomeKit abuse patterns, **5.6.4–5.6.7** rating manipulation dark patterns. Marked † in docs;
+  higher false-positive risk — advisory `REVIEW-FINDING: WARN` only.
+- Expanded `covered_by_pierre_deep_review` in `guidelines-baseline.json` with 2.2, 2.3.4, 2.3.9,
+  4.5.1–4.5.3, 5.6.4–5.6.7.
+
+### Changed
+- Phase 4 checklist 22 → **28** across `pierre-deep-review.md`, `SKILL.md`, `methodology.md`, README
+  (full guideline-ordered table with † Tier B labels), plugin manifest, and social preview
+  (`41 static + 28 Pierre deep checks`).
+
+## [1.4.0] - 2026-06-30
+
+### Added
+- **Phase 4: Pierre deep review — 22 semantic checks.** After Phase 3 (explaining every scan
+  FAIL/WARN), Pierre runs a read-only Review Simulator: fetches privacy/support URLs, reads
+  screenshots, compares metadata claims to Swift code, validates paywall disclosure quality, and
+  cross-checks permissions vs policy. Each check emits `REVIEW-PASS:` or advisory
+  `REVIEW-FINDING: … WARN` (does not change GREEN/YELLOW/RED counts). Full checklist in
+  [`references/pierre-deep-review.md`](skills/appstore-precheck/references/pierre-deep-review.md).
+- **`covered_by_pierre_deep_review`** in `guidelines-baseline.json` (26 guideline numbers across
+  the 22 checks). Consolidation moves to **Phase 5** (6 phases total: 0–5).
+- [`examples/pierre-deep-review.md`](examples/pierre-deep-review.md) showing `REVIEW-FINDING` output.
+
+### Changed
+- Flow is now **6 phases (0–5)**: Phase 3 = scan commentary, Phase 4 = deep review, Phase 5 =
+  verdict + token. Updated `SKILL.md`, `methodology.md`, README (static table + deep-review table
+  in guideline order), examples, plugin manifest, and social preview copy (`41 static + 22 Pierre
+  deep checks`).
+
+## [1.3.1] - 2026-06-30
+
+### Changed
+- **Phase 3 (Pierre) now explains every FAIL and WARN** from Phases 0–2 in **2–3 sentences
+  each** — no more random 5-guideline sampling. Pierre repeats each machine line verbatim,
+  then explains why Apple cares, what the scan found, and what to fix. Updated `SKILL.md`,
+  `methodology.md`, the README example, `examples/red-reject.md`, and behavioral eval
+  assertions in lockstep.
+- Phase 4 presentation order clarified: trilingual verdict block → Pierre commentary → verbatim
+  scan lines + `file:line` fixes → verdict/token.
+- **Trilingual verdict block format:** each language in its own **bold label + blockquote**, separated
+  by horizontal rules (`---`) under a `### Pierre` heading — never FR/EN/user-lang compressed on one line.
+
+## [1.3.0] - 2026-06-30
+
+### Added
+- **Eleven new signal-gated advisory checks (30 → 41 rejection vectors), all WARN-only:**
+  - **2.1** a login-gated app with no demo account / credentials for App Review (fastlane
+    `review_information` or `.reviewPrepNotes`).
+  - **2.5.2** executable-code download / native hot-patching (JSPatch, Rollout, DynamicCocoa).
+    Allowed JS-bundle OTA (React Native CodePush) is deliberately **not** flagged.
+  - **2.5.4** a background mode declared in `UIBackgroundModes` with no matching API used in Swift.
+  - **3.1.5(a)** a cryptocurrency wallet / exchange / mining signal.
+  - **4.2.3** a thin WKWebView wrapper around a website (heuristic: WKWebView + very few Swift files).
+  - **4.2.7** a remote-desktop / host-mirroring signal.
+  - **4.4.2** a Safari content-blocker / web extension.
+  - **5.1.1(v)** account creation offered without an in-app account-deletion path (the real
+    5.1.1(v) Account Sign-In rule).
+  - **5.1.4** metadata targeting a child audience while a third-party ads/analytics SDK is linked.
+  - **5.3.4** real-money gambling language in metadata.
+  - **5.5** a Mobile Device Management (MDM) signal.
+- `tests/fixtures/risky-app-2` (advisory §31–§41 except web-wrapper) and `tests/fixtures/webview-app`
+  (the 4.2.3 heuristic), with assertions in `tests/run.sh`. Both are advisory-only (no FAIL).
+
+### Changed
+- **Corrected the Required Reason API label from `5.1.1(v)` to `5.1.1`.** Apple documents the
+  Required Reason API rules under 5.1.1 + the privacy-manifest developer docs; sub-item **(v)** is
+  "Account Sign-In", a different rule. The `(v)` label now belongs to the new account-deletion
+  check (vector 38). Updated `scan.sh` output, the methodology table, the README table, the
+  examples, and the field-test notes in lockstep.
+- §18 (support / privacy URL) now also cites the guidelines it satisfies: **1.5** (developer
+  contact via the support URL) and **5.1.1(i)** (privacy policy link).
+- Expanded `guidelines-baseline.json` `covered_by_scan` with 1.5, 2.5.2, 2.5.4, 3.1.5, 4.2.3,
+  4.2.7, 4.4.2, 5.1.4, 5.3.4, and 5.5.
+
+## [1.2.0] - 2026-06-30
+
+### Added
+- **Ten new signal-gated advisory checks (20 → 30 rejection vectors), all WARN-only:**
+  - **3.1.1** third-party payment SDK (Stripe, Braintree, PayPal, Square, Adyen, …) linked for
+    digital goods instead of in-app purchase.
+  - **1.2** user-generated content detected without a report / block / moderation affordance.
+  - **1.6** App Transport Security disabled app-wide (`NSAllowsArbitraryLoads=true`).
+  - **4.9** recurring Apple Pay without the renewal / cancel disclosure.
+  - **5.6.1** a direct App Store write-review link/prompt without the system `requestReview` API.
+  - **2.3.1** misleading marketing claims (iOS virus / malware scanners, fake speed boosters) in metadata.
+  - **2.3.8** "For Kids" / "For Children" wording outside the Kids Category.
+  - **4.4.1** keyboard extension requiring full access (`RequestsOpenAccess=true`).
+  - **5.1.3** HealthKit used together with an iCloud / CloudKit sync path.
+  - **5.4** VPN / NetworkExtension (`NEVPNManager`) usage.
+- `tests/fixtures/risky-app` plus assertions in `tests/run.sh` exercising all ten new vectors
+  (advisory only — the fixture is YELLOW, never RED).
+
+### Changed
+- **YELLOW threshold raised from 3+ to 5+ WARN.** The ten new advisory checks are signal-gated
+  (most apps trip only one or two), but the bump keeps a normal submission from sliding into
+  YELLOW on advisory noise alone. GREEN is now 0 FAIL and ≤4 WARN; YELLOW is 0 FAIL and ≥5 WARN.
+  Updated `verdict.sh`, the verdict tests, the output-contract tables, and the docs in lockstep.
+- Corrected the minimum-functionality check's label from `4.0` to `4.2` (its real guideline
+  number) in the scanner output, the methodology table, and the README.
+- Reconciled `guidelines-baseline.json` against the live guidelines (Last Updated June 8, 2026):
+  no structural section drift; expanded `covered_by_scan` to reflect every guideline the scan now
+  touches (adds 1.2, 1.6, 2.1, 2.3, 2.3.8, 3.1.1, 4.4.1, 4.8, 4.9, 5.1.3, 5.4, 5.6.1; 4.0 → 4.2).
+
+## [1.1.1] - 2026-06-30
+
+### Changed
+- **Pierre now speaks in a trilingual block.** The verdict opens with his native **French** line,
+  then an **English** rendering, then a rendering in the **user's conversation language** — each an
+  idiomatic, in-character re-expression in that language's own rhythm, not a literal translation.
+  Collapses to two lines when the user already converses in French or English. The block stays
+  flavor only; the FAIL/WARN list, `file:line` references, and fixes below it remain plain and
+  machine-faithful. Updated the output contract, Phase 4 step 3, and the behavioral eval
+  assertions accordingly.
+
+### Fixed
+- **Pierre no longer treats local-only files as Apple submission evidence.** The Phase 3 prompt
+  now scopes reject-risk evidence to Apple-facing artifacts (fastlane metadata, paywall Swift,
+  String Catalog, Info.plist, PrivacyInfo.xcprivacy). Internal/local files (`.planning/` notes,
+  `reviewPrepNotes` drafts, build scripts) and Google Play / non-Apple sections are out of scope —
+  cited at most as a WARN labeled "internal draft — not submitted to Apple", never REJECT-RISK. A
+  REJECT risk now requires a contradiction *within* submission-facing artifacts, not an internal
+  doc disagreeing with metadata. An eligibility-gated/conditional offer paired with metadata that
+  mentions it is WARN at most (unless the metadata promises it unconditionally). Prevents the
+  false REJECT-RISK overreach seen when dogfooding an already-approved build.
+- **2.3.7 locale check no longer hard-FAILs on a config/disk mismatch.** A locale listed in
+  `.appstore-precheck.json` `locales` but with no metadata folder on disk is now a WARN (with an
+  actionable "add it or remove it from the config" message), not a FAIL — that locale was simply
+  never submitted, so it must not turn an approved set RED. A missing *file* inside a present
+  locale folder is still a FAIL.
+- **2.1 placeholder check no longer false-fires on words containing "changeme".** The `changeme`
+  pattern is now word-bounded (`\bchangeme\b`) in both the metadata-URL and store-copy scans, so
+  legitimate copy such as the French "changement" ("change") is not flagged as unfinished.
+- Added regression coverage in `tests/test-config.sh` for both fixes.
+- CI: bumped `actions/checkout@v4 -> v7` and `actions/setup-node@v4 -> v6` to clear the
+  GitHub Actions Node.js 20 deprecation warning (both now run natively on Node 24).
+
 ## [1.1.0] - 2026-06-28
 
 ### Added

package/README.md

@@ -16,8 +16,10 @@
 
 `appstore-precheck` is a read-only, pre-submission gate for iOS apps. It statically scans the most
 common rejection vectors, runs Apple's own metadata linter, watches the App Store Review Guidelines
-for drift, and finishes with an adversarial review pass, then hands you a single **GREEN / YELLOW /
-RED** verdict. It never edits your code.
+for drift, has Pierre explain every FAIL and WARN, then runs **28 semantic deep-review checks**
+(22 high-confidence Tier A + 6 heuristic Tier B v1 — beta language, review notes quality, app preview,
+incentivized review, push/HomeKit abuse, rating manipulation).
+It hands you a single **GREEN / YELLOW / RED** verdict. It never edits your code.
 
 It ships as a portable [Agent Skill](https://agentskills.io): the same `SKILL.md` runs natively in
 Claude Code, OpenAI Codex, Cursor, and Gemini CLI. The scanner is plain Bash, so you can also run it
@@ -28,95 +30,243 @@ by hand or wire it into CI.
 <img src="assets/mascot.png" align="right" width="124" alt="Pierre, the French app reviewer">
 
 Your verdict is delivered by **Pierre**, a French critic who has seen ten thousand rejections and is
-impressed by none of them. He reviews your build harder than Apple would, in private. A GREEN from
+impressed by none of them. He reviews your build harder than Apple would, in private — first with a
+fast static scan, then with **28 deep semantic checks** (22 confident + 6 heuristic). A GREEN from
 Pierre means Apple will wave you through.
 
 - 🔴 **RED**: *"Non. Restore Purchases, absent. Guideline 3.1.2. Suivant."*
 - 🟡 **YELLOW**: *"A few small uglinesses. I would not reject. But I noticed."*
 - 🟢 **GREEN**: *"Hmf. I find nothing. Acceptable. Do not make me regret this."*
 
-The verdict line is in Pierre's voice. The breakdown beneath it, every `file:line` and fix, stays
-plain and surgical.
+The verdict line is in Pierre's voice — **three separate language blocks** (bold label + blockquote
+each, divided by horizontal rules), not one compressed sentence. The breakdown beneath it, every
+`file:line` and fix, stays plain and surgical.
 
 ## What it checks
 
-20 rejection vectors across code, fastlane metadata, screenshots, `PrivacyInfo.xcprivacy`, and the paywall:
+41 rejection vectors across code, fastlane metadata, screenshots, `PrivacyInfo.xcprivacy`, and the paywall:
 
 | Guideline | Check |
 |-----------|-------|
-| **5.1.1(v)** | Privacy Manifest ↔ Required Reason API parity |
-| **5.1.1** | A non-empty purpose string for every sensitive framework |
-| **5.1.2** | ATT usage ↔ `NSUserTrackingUsageDescription` |
-| **2.3.10** | No other-platform / competitor names in metadata |
+| **1.2** | User-generated content without a report / block / moderation mechanism |
+| **1.6** | App Transport Security disabled app-wide (`NSAllowsArbitraryLoads`) |
+| **2.1** | No placeholder / dummy copy (lorem ipsum, TODO, `example.com`) in store metadata |
+| **2.1** | A login-gated app ships demo credentials / review notes for App Review |
+| **2.3** | A working support URL and a privacy URL in fastlane metadata (no placeholders) — also satisfies 1.5 and 5.1.1(i) |
 | **2.3.1** | Metadata length limits (name, subtitle, keywords, promo, description) |
-| **2.3.7** | Localized metadata parity across every locale |
+| **2.3.1** | Misleading marketing claims (iOS virus / malware scanners, fake speed boosters) in metadata |
 | **2.3.3** | At least one screenshot per locale |
+| **2.3.7** | Localized metadata parity across every locale |
+| **2.3.8** | "For Kids" / "For Children" wording outside the Kids Category |
+| **2.3.10** | No other-platform / competitor names in metadata |
+| **2.5.1** | No private / banned APIs |
+| **2.5.2** | No executable-code download / native hot-patching (JSPatch, Rollout, …) |
+| **2.5.4** | Background modes declared in `UIBackgroundModes` but never used |
+| **3.1.1** | Third-party payment SDK (Stripe, Braintree, PayPal, …) linked for digital goods instead of in-app purchase |
+| **3.1.1(a)** | External purchase link entitlement + disclosure, when external purchase APIs are used |
 | **3.1.2** | Trial & auto-renew subscription disclosures |
 | **3.1.2** | Restore Purchases + Terms (EULA) + Privacy Policy on the paywall |
-| **2.5.1** | No private / banned APIs |
-| **4.0** | Minimum functionality (real navigation) |
+| **3.1.5(a)** | Cryptocurrency wallet / exchange / mining signal |
+| **4.2** | Minimum functionality (real navigation) |
+| **4.2.3** | Thin WKWebView wrapper around a website |
+| **4.2.7** | Remote-desktop / host-mirroring app |
+| **4.4.1** | Keyboard extension that requires full access (`RequestsOpenAccess`) |
+| **4.4.2** | Safari content-blocker / web extension |
 | **4.8** | Sign in with Apple offered when a third-party social login is used |
-| **3.1.1(a)** | External purchase link entitlement + disclosure, when external purchase APIs are used |
-| **5.1.5** | Sensitive-API justification *(opt-in)* |
+| **4.9** | Recurring Apple Pay (`PKRecurringPaymentRequest`) — verify the renewal / cancel disclosure |
+| **5.1.1** | A non-empty purpose string for every sensitive framework |
+| **5.1.1** | Analytics SDK present ↔ `PrivacyInfo.xcprivacy` declares collected data / tracking domains |
+| **5.1.1** | Privacy Manifest ↔ Required Reason API parity |
+| **5.1.1(v)** | Account creation offered without an in-app account-deletion path |
+| **5.1.2** | ATT usage ↔ `NSUserTrackingUsageDescription` |
 | **5.1.2** | Tracking / IDFA SDK (AdMob, AppLovin, AppsFlyer, Adjust, …) shipped without an ATT prompt |
+| **5.1.3** | HealthKit data with an iCloud / CloudKit sync path |
+| **5.1.4** | Kids-audience metadata shipping a third-party ads / analytics SDK |
+| **5.1.5** | Sensitive-API justification *(opt-in)* |
+| **5.3.4** | Real-money gambling language in metadata |
+| **5.4** | VPN / NetworkExtension usage (org account + on-screen data disclosure) |
+| **5.5** | Mobile Device Management (MDM) signal |
+| **5.6.1** | A custom App Store review prompt instead of the system `requestReview` API |
 | **encryption** | `ITSAppUsesNonExemptEncryption` set, so App Store Connect skips the export-compliance question |
-| **2.3** | A working support URL and a privacy URL in fastlane metadata (no placeholders) |
-| **5.1.1** | Analytics SDK present ↔ `PrivacyInfo.xcprivacy` declares collected data / tracking domains |
-| **2.1** | No placeholder / dummy copy (lorem ipsum, TODO, `example.com`) in store metadata |
 
-Paywall checks are skipped automatically when no in-app-purchase signals are present.
+Paywall checks are skipped automatically when no in-app-purchase signals are present, and the
+signal-gated advisory checks stay silent unless their triggering signal is found.
+
+### Pierre deep review (28 semantic checks)
+
+After the static scan, Pierre reads your project end-to-end and runs **28 evidence-based checks**
+the grep layer cannot fully judge. These emit advisory `REVIEW-FINDING:` lines (they do **not**
+change the GREEN/YELLOW/RED verdict). Full procedure:
+[`references/pierre-deep-review.md`](skills/appstore-precheck/references/pierre-deep-review.md).
+
+**22 checks (Tier A)** are high-confidence cross-reads (privacy policy fetch, claims vs code,
+screenshots, paywall copy). **6 checks (Tier B v1, marked †)** are heuristic — useful pre-submit
+signals with a higher false-positive rate; Pierre prefers `not applicable` when no signal is present.
+
+| Guideline | Deep check |
+|-----------|------------|
+| **1.2.1** | User-generated content → is there a real report / block / moderation UI flow? |
+| **1.4.1** | Health or medical claims in metadata/UI without appropriate disclaimers? |
+| **2.1** | Store metadata claims match features actually implemented in code |
+| **2.1** † | App Review demo account / review notes actionable (credentials, steps — not placeholder) |
+| **2.2** † | Beta, test, preview, or work-in-progress language in store-facing copy or UI |
+| **2.3.2** | Primary App Store category fits the app type |
+| **2.3.4** † | App preview video/assets (if in-repo) match shipped features and metadata |
+| **2.3.5** | Screenshot images match shipped features (no misleading frames or missing UI) |
+| **2.3.6** | Metadata pricing / subscription language matches the paywall |
+| **2.3.9** † | Incentivized review copy ("rate 5 stars", "review for reward") in metadata or UI |
+| **2.3.11–2.3.13** | Cross-locale metadata materially consistent (trial terms, features, URLs) |
+| **3.1.1** | Digital goods unlocked via external purchase links (web checkout in WebView, etc.) |
+| **3.1.2** | Trial, auto-renew, and cancel disclosures are legible sentences — not keyword stubs |
+| **4.2.1–4.2.2** | Minimum functionality beyond a thin WebView shell or template app |
+| **4.5.1–4.5.3** † | Push notification or HomeKit entitlement used as intended (no spam-push / HomeKit without home UI) |
+| **4.8** | Third-party login → Sign in with Apple offered, or a valid exempt case |
+| **5.1.1(i)** | Privacy policy text (fetched live) matches code, PrivacyInfo, and SDK usage |
+| **5.1.1(ii)** | Purpose strings are specific and tied to a visible feature |
+| **5.1.1(iii)** | Permissions and SDKs proportionate to the app's stated purpose |
+| **5.1.1(iv)** | Permission denial handled without forced re-prompt loops |
+| **5.1.2** | ATT prompt, tracking description, privacy policy, and ad SDK usage align |
+| **5.1.3** | HealthKit data not used for advertising or marketing |
+| **5.1.4** | Kids-audience signals → parental gate before external links / IAP / account areas |
+| **5.4** | VPN / NetworkExtension → on-screen disclosure copy visible in UI strings |
+| **5.2.1–5.2.3** | Obvious third-party trademark or brand misuse in metadata or UI copy |
+| **5.3.1–5.3.3** | Contest / sweepstakes copy includes official rules and eligibility |
+| **5.6.2–5.6.3** | Developer identity consistent (app name, support URL content, domains) |
+| **5.6.4–5.6.7** † | Rating / review manipulation dark patterns (withhold features until 5 stars, write-review links without `requestReview`) |
+
+Pierre runs **all 28 every time** and reports each as `REVIEW-PASS:` or `REVIEW-FINDING:`. When the
+static scan already flagged a guideline, the deep check adds semantic context the scanner could not see.
+† Tier B v1 items are heuristic — treat findings as "verify before submit", not automatic blockers.
+
+### Supported app types
+
+Every check that reads store metadata, the privacy manifest, screenshots, or the export-compliance
+key works on **any iOS app**. The code-level checks read Swift source, so their coverage depends on
+how the app is built:
+
+| App type | Coverage |
+|----------|----------|
+| 🟢 **Native Swift / SwiftUI** | **Full.** All 41 vectors apply. |
+| 🟡 **React Native / Flutter** | Metadata, privacy manifest, screenshots, and export compliance apply in full. The Swift-source checks (ATT, paywall links, private API, SDK detection, navigation) **under-detect rather than misfire**: that logic lives in JS/Dart, so they stay quiet instead of blocking. |
 
 ## Quick start
 
-**Claude Code**: install as a plugin:
+One `SKILL.md`, every host. **Claude Code, Cursor, and Codex** install as native **plugins** from
+this GitHub repo. **Gemini CLI** installs the same skill with `gemini skills install` (no plugin
+marketplace yet). [`install.sh`](install.sh) remains the fallback for vendoring into a project.
+
+### Install the full skill (Pierre + all phases)
+
+| Host | Install method |
+|------|----------------|
+| **Claude Code** | Plugin (recommended) |
+| **Cursor** | Plugin (recommended) |
+| **OpenAI Codex** | Plugin (recommended) |
+| **Gemini CLI** | `gemini skills install` one-liner |
+
+**Claude Code:**
 
 ```
 /plugin marketplace add berkayturk/appstore-precheck
 /plugin install appstore-precheck@appstore-precheck
 ```
 
-**Run instantly with npx** (no clone, no install):
+**Cursor** — import this repo as a marketplace, then install the plugin:
+
+1. **Customize → Plugins → Import marketplace**
+2. Repo URL: `https://github.com/berkayturk/appstore-precheck`
+3. Install **appstore-precheck**
+
+After the plugin is listed on the [Cursor Marketplace](https://cursor.com/marketplace), you can
+install from **Customize → Plugins** without importing the repo.
+
+**OpenAI Codex:**
 
 ```bash
-npx appstore-precheck            # scans the current directory, prints the verdict
-npx appstore-precheck --fail-on YELLOW
+codex plugin marketplace add berkayturk/appstore-precheck
+```
+
+Then run `codex`, open `/plugins`, select the **appstore-precheck** marketplace tab, and install
+**appstore-precheck**. Start a new thread after install.
+
+On newer Codex builds you may also be able to run:
+
+```bash
+codex plugin add appstore-precheck@appstore-precheck
 ```
 
-It runs the static scan over the current directory and exits non-zero on RED (or on YELLOW with
-`--fail-on YELLOW`). Read-only, like everything else here.
+Refresh after repo updates:
 
-**Codex, Cursor, Gemini, Claude**: clone, then run the installer from inside your iOS project:
+```bash
+codex plugin marketplace upgrade appstore-precheck
+```
+
+**Gemini CLI** (native skill install — no plugin marketplace):
+
+```bash
+gemini skills install https://github.com/berkayturk/appstore-precheck.git \
+  --path skills/appstore-precheck --scope workspace
+```
+
+Use `--scope user` for a global install. Verify with `gemini skills list`.
+
+**Fallback — `install.sh`** (vendors the skill into `.claude/skills/` and/or `.agents/skills/`):
 
 ```bash
 git clone https://github.com/berkayturk/appstore-precheck.git
-/path/to/appstore-precheck/install.sh        # → ./.claude/skills and ./.agents/skills
+cd your-ios-app
+/path/to/appstore-precheck/install.sh              # all hosts → .claude/skills + .agents/skills
+/path/to/appstore-precheck/install.sh cursor       # Cursor only
+/path/to/appstore-precheck/install.sh codex        # Codex only
+/path/to/appstore-precheck/install.sh gemini       # Gemini only
+/path/to/appstore-precheck/install.sh claude user  # Claude Code user-wide → ~/.claude/skills
+```
+
+Then ask your agent to run the precheck before you submit. See [Cross-tool support](#cross-tool-support)
+for which directory each host reads. Maintainer notes for marketplace submission:
+[`docs/publishing-plugins.md`](docs/publishing-plugins.md).
+
+### Scan only (no agent skill install)
+
+**npx** — static scan + verdict in the terminal; no clone, no skill vendoring (Phases 3–4 Pierre
+commentary require an agent with the skill installed):
+
+```bash
+npx appstore-precheck            # scans the current directory, prints the verdict
+npx appstore-precheck --fail-on YELLOW
 ```
 
-**Standalone**: the scanner is just Bash:
+**Standalone Bash** — same static scan, run by hand or in CI:
 
 ```bash
-bash skills/appstore-precheck/scripts/scan.sh
+bash skills/appstore-precheck/scripts/scan.sh   # from a clone of this repo
 ```
 
-**CI**: drop the static scan into a workflow with the bundled composite action. It fails the
+### CI
+
+Drop the static scan into a workflow with the bundled composite action. It fails the
 job on a RED verdict; set `fail-on: YELLOW` to be stricter:
 
 ```yaml
-- uses: berkayturk/appstore-precheck@v1.0.0
+- uses: berkayturk/appstore-precheck@v1.5.0
   with:
-    working-directory: .   # optional
-    fail-on: RED           # optional (RED | YELLOW)
+    working-directory: .   # optional, default: . (repo root)
+    fail-on: RED           # optional, default: RED (RED | YELLOW)
 ```
 
+Both inputs are optional: with none set, the action scans the repo root and fails the job only on
+a RED verdict. No App Store Connect credentials are needed; the action runs the static scan only.
+
 ## How it works
 
 | Phase | Step |
 |-------|------|
 | **0** | **Guideline drift**: diff the live App Store Review Guidelines against a tracked baseline. Never blocks. |
-| **1** | **Static scan**: `scan.sh` over the 20 vectors above. |
+| **1** | **Static scan**: `scan.sh` over the 41 vectors above. |
 | **2** | **`fastlane precheck`**: Apple's own metadata rule engine. |
-| **3** | **Adversarial review**: Pierre role-plays a skeptical reviewer and drafts realistic rejection notices. |
-| **4** | **Verdict**: GREEN / YELLOW / RED, and a `.precheck-pass` token the upload guard gates on. |
+| **3** | **Pierre commentary**: explains **every** FAIL and WARN from Phases 0–2 in 2–3 sentences each. |
+| **4** | **Pierre deep review**: 28 semantic checks (22 Tier A + 6 Tier B v1 heuristic). Advisory only. |
+| **5** | **Verdict**: GREEN / YELLOW / RED from Phases 0–2 counts, plus `.precheck-pass` token the upload guard gates on. |
 
 ## Demo
 
@@ -129,25 +279,45 @@ counts are deterministic ([`verdict.sh`](skills/appstore-precheck/scripts/verdic
 
 ## Example
 
+### Pierre
+
+**Français**
+> *Non. Trois fautes. Apple en aurait trouvé moins. Suivant.*
+
+---
+
+**English**
+> *No. Three faults. Apple would have found fewer. Next.*
+
+---
+
+**Türkçe**
+> *Hayır. Üç hata. Apple daha azını bulurdu. Sıradaki.*
+
+**RED — 3 FAIL** · submission blocked
+
+```
+FAIL: 3.1.2 Restore Purchases — not found in SubscriptionView.swift
+Pierre: Apple requires a Restore Purchases control on every subscription paywall …
 ```
-🔴 Pierre: "Non. Three faults. Apple would have found one. Suivant."
 
-RED: 3 FAIL
-• 3.1.2 Restore Purchases missing    SubscriptionView.swift:14 → add restorePurchases()
-• 2.3.10 "Android" in metadata        en-US/description.txt:1 → remove the reference
-• 5.1.1(v) FileTimestamp undeclared   PrivacyInfo.xcprivacy → declare the reason
-Submission blocked.
+**Phase 4 (deep review, excerpt):**
+
+```
+REVIEW-FINDING: 5.1.1(i) WARN — privacy policy says "no location data" but ContentView.swift uses CLLocationManager
+Pierre: Apple compares your privacy policy to actual SDK and permission usage under 5.1.1(i) …
 ```
 
-See [`examples/`](examples/) for full [GREEN](examples/green-pass.md) and [RED](examples/red-reject.md) runs,
-plus real [Phase 0 drift-check](examples/drift-check.md) and [Phase 2 `fastlane precheck`](examples/fastlane-precheck.md) results.
+See [`examples/`](examples/) for full [GREEN](examples/green-pass.md), [RED](examples/red-reject.md), and
+[deep-review](examples/pierre-deep-review.md) runs, plus real [Phase 0 drift-check](examples/drift-check.md)
+and [Phase 2 `fastlane precheck`](examples/fastlane-precheck.md) results.
 
 ## Output
 
 | State | Meaning | Token | Upload guard |
 |-------|---------|-------|--------------|
-| 🟢 **GREEN** | 0 FAIL, ≤2 WARN | written (60 min) | allowed |
-| 🟡 **YELLOW** | 0 FAIL, 3+ WARN | not written | blocked; needs confirmation |
+| 🟢 **GREEN** | 0 FAIL, ≤4 WARN | written (60 min) | allowed |
+| 🟡 **YELLOW** | 0 FAIL, 5+ WARN | not written | blocked; needs confirmation |
 | 🔴 **RED** | ≥1 FAIL | removed | blocked; shows the FAIL list |
 
 ## Configuration
@@ -177,8 +347,13 @@ App Store apps (DuckDuckGo, Pocket Casts, Wikipedia).
 
 ## Requirements
 
-`bash`, `git`, `grep`, `find` · `jq` (config + String Catalog checks) · `python3` (exact Unicode
-length counts) · `fastlane` + an App Store Connect API key for Phase 2 only.
+`bash`, `git`, `grep`, `find` are all the static scan, `npx appstore-precheck`, and the GitHub
+Action need, and they run with **zero credentials and no network**. `jq` (config + String Catalog
+checks) and `python3` (exact Unicode length counts) are optional and sharpen a few checks.
+
+Only the **optional Phase 2** (`fastlane precheck`) needs `fastlane` and an
+[App Store Connect API key](https://developer.apple.com/documentation/appstoreconnectapi/creating-api-keys-for-app-store-connect-api).
+Everything else works without one.
 
 **Secrets**: the ASC API key is read from your environment at runtime and deleted immediately after
 `fastlane precheck`. Never commit it; `.gitignore` blocks `*asc-key*.json` and `.env`.
@@ -186,16 +361,22 @@ length counts) · `fastlane` + an App Store Connect API key for Phase 2 only.
 ## Uninstall
 
 ```bash
-/plugin uninstall appstore-precheck@appstore-precheck                        # Claude Code plugin
-rm -rf .claude/skills/appstore-precheck .agents/skills/appstore-precheck     # manual install
-rm -f .precheck-pass                                                         # runtime token
+/plugin uninstall appstore-precheck@appstore-precheck   # Claude Code plugin
+# Codex: run `codex`, open `/plugins`, uninstall appstore-precheck (CLI 0.125.x has no `plugin remove`)
+# Cursor: Customize → Plugins → appstore-precheck → Uninstall
+gemini skills uninstall appstore-precheck                 # Gemini (if installed via gemini skills)
+rm -rf .claude/skills/appstore-precheck                # install.sh (Claude Code / Cursor)
+rm -rf .agents/skills/appstore-precheck                # install.sh (Codex / Cursor / Gemini)
+rm -rf .cursor/skills/appstore-precheck                # if you mirrored there manually
+rm -rf .gemini/skills/appstore-precheck                # if installed to workspace scope manually
+rm -f .precheck-pass                                   # runtime token
 ```
 
 ## Development
 
 ```bash
 npm run lint            # bash -n on every script
-npm run check-versions  # plugin.json / package.json / SKILL.md in lockstep
+npm run check-versions  # plugin manifests / package.json / SKILL.md in lockstep
 npm test                # run scan.sh against fixture projects and assert
 claude plugin validate .
 ```
@@ -204,9 +385,11 @@ CI runs ShellCheck, JSON validation, the version-consistency guard, and the fixt
 
 ## Disclaimer
 
-This is a static heuristic tool. A GREEN result **lowers but does not eliminate** rejection risk;
-Apple's guidelines change frequently and reviewer decisions are judgment calls. It performs no runtime
-crash testing; always do a final manual review before you submit. Not affiliated with Apple.
+This is a static heuristic tool plus Pierre's semantic deep review. A GREEN result **lowers but does
+not eliminate** rejection risk; Apple's guidelines change frequently and reviewer decisions are
+judgment calls. `REVIEW-FINDING` lines are advisory and do not block the token by themselves. It
+performs no runtime crash testing; always do a final manual review before you submit. Not affiliated
+with Apple.
 
 ## Star History
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appstore-precheck",
-  "version": "1.1.0",
-  "description": "Read-only iOS App Store pre-submission check, packaged as a portable Agent Skill / Claude Code plugin and an npx CLI.",
+  "version": "1.5.1",
+  "description": "Read-only iOS App Store pre-submission check, packaged as a portable Agent Skill with native Claude Code, Cursor, and Codex plugins, plus an npx CLI.",
   "license": "MIT",
   "author": "Berkay Turk (https://github.com/berkayturk)",
   "homepage": "https://github.com/berkayturk/appstore-precheck",