@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/app-cross-platform-dev/references/ios-dev.md

@@ -0,0 +1,72 @@
+# iOS Dev
+
+## Architecture
+
+- Use SwiftUI for new UI when the repo supports it; keep UIKit work behind clear boundaries when the repo or platform feature requires UIKit.
+- Compose screens from small views, but keep durable state and side effects outside leaf views.
+- Use State, Binding, Observable-style objects, environment, and model ownership deliberately. The source of truth should be obvious.
+- **For new code on iOS 17+, prefer the `@Observable` macro (Observation framework) over `ObservableObject` + `@Published`** — `@Observable` tracks property reads finer-grained per view (less invalidation, fewer rebuilds), and migration drops the `@Published` wrappers + switches `@StateObject` to `@State`. Keep `ObservableObject` only where (a) targets older than iOS 17 must be supported, or (b) existing Combine pipelines on `@Published` properties are load-bearing — `@Observable` does not expose Combine publishers, so a refactor must replace those pipelines.
+- Keep URLSession/API clients, persistence, permissions, notifications, and native SDK calls isolated behind services or protocols.
+- Use async/await where it fits the repo; preserve cancellation and main-actor boundaries. **Swift 6 strict concurrency** (compiler-enforced `Sendable` and actor isolation checking) is opt-in on Swift 5 / Swift 6 compilers — enabling it surfaces real data-race bugs but requires explicit `nonisolated` / `@MainActor` annotations across the codebase; turn on per-target incrementally, not big-bang.
+
+## App And Platform Behavior
+
+- Treat scene lifecycle, app restore, push/deep-link entry, background execution, files/media, share sheet, biometrics, and in-app purchases as platform contracts.
+- Model unavailable capability, denied permission, interrupted task, expired session, and offline state explicitly.
+- Keep schemes, configurations, signing, entitlements, Info.plist changes, and store-sensitive capabilities reviewable.
+- **Runtime permission UX (TCC) is separate from the Privacy Manifest gate**: every TCC-gated capability (Camera / Photos / Microphone / Location / Contacts / Calendars / Reminders / FaceID / Bluetooth / LocalNetwork / Tracking) MUST have a clear, specific `NS<Capability>UsageDescription` string in Info.plist explaining the user-visible purpose (Apple rejects vague / generic strings). The app must also model the four states explicitly: not-yet-asked / granted / denied / restricted — and provide a Settings-app deep link (`UIApplication.openSettingsURLString`) when denied. Privacy Manifest declares what IS collected; usage strings + state handling are how it appears at runtime.
+- **Sign in with Apple (`ASAuthorization`) for App Store Review Guideline 4.8**: apps offering third-party social login (Google / Facebook / etc.) must offer an equivalent privacy-respecting login option — Sign in with Apple satisfies the requirement, but the rule is "another login service with these features", not literal Apple SDK. When using `ASAuthorization`, handle credential-revoked state on app launch (`getCredentialState`), the relay-email path (Apple proxies the user's real email), and an explicit account-deletion path the user can find without contacting support.
+- **Privacy Manifest (`PrivacyInfo.xcprivacy`) — App Store Connect gate since 2024-05-01**: the app bundle MUST ship a privacy manifest declaring (a) collected data types per Apple's taxonomy, (b) required-reason API usage (file timestamp / system boot time / disk space / active keyboards / `UserDefaults`), and (c) tracking domains if any. Every third-party SDK on Apple's named "commonly used SDKs" list MUST ship its own privacy manifest; when the SDK is delivered as a binary dependency, the binary must also be code-signed. Apple's enforcement point is App Store Connect submission, not local `xcodebuild archive` — missing manifest fails submission, not local build, so the check belongs in pre-submission CI / dependency-upgrade checklist, not at submission time.
+
+## Theme And Brand Color
+
+Shared design discipline lives in `product-ui-ux-design/references/multi-project-token-consistency.md`; consult it before applying the iOS-specific implementation rules below.
+
+- **Xcode scaffold color asset is empty by default**: a freshly generated iOS project ships `Assets.xcassets/AccentColor.colorset/Contents.json` with `colors: [{ idiom: "universal" }]` — no `color.components` field, so the asset resolves to system default. An app that leaves `AccentColor` empty AND has no other brand-color asset / theme module renders system blue throughout. Audit signal: empty `AccentColor.colorset` + no other named brand color asset = no native brand theme.
+- **Brand color must live in the asset catalog or a typed token module, not scattered hex literals**: define brand colors as named entries in `Assets.xcassets` (color sets with light + dark variants and per-display-gamut variants where relevant) OR as a Swift constant module (`enum BrandColor { static let primary = Color(hex: ...) }`). Per-view `Color(red:..., green:..., blue:...)` literals duplicate the brand and silently diverge.
+- **Vendor-default literal leak in custom theme** (cross-stack rule): system-default colors typed deliberately into the brand layer — `UIColor.systemBlue` / `Color.blue` as a brand color, Material defaults copied from cross-platform code, Apple HIG sample palette values — fall under the shared anti-pattern in `multi-project-token-consistency.md`. Detection: any literal in the brand-color asset or token module that matches a known system / vendor default. A hit resolves to one of three classes per the shared rule: **leak** (replace with brand token), **deliberate documented reuse** (keep with rationale comment), or **legitimate convergence** (brand role independently resolves to the same hex — keep but reference the brand token, not the literal).
+
+### WebView-wrapper iOS shells
+
+An iOS app whose main product flows are hosted in a `WKWebView` plus a thin shell of native helper screens (`AppDelegate`, network, photo upload, image picker, network-error fallback, splash, settings) is a **hybrid WebView shell**. The audit verdict is per-surface, not per-app: WebView-hosted product flows route their brand audit to the loaded web app; native-owned shell screens (splash, login, settings, offline / network-error fallback, permission prompts, photo upload modal chrome, status-bar / safe-area chrome, deep-link landing) are audited as native surfaces with normal three-layer evidence.
+
+- Detection signals: very small Swift source count relative to the app's feature scope, primary content loaded into `WKWebView`, JS-bridge dependency (`WebViewJavascriptBridge`, `WKScriptMessageHandler`-based bridge), no SwiftUI / UIKit screen classes for product features (only infra: `AppDelegate`, `Network`, `PhotoUpload`, `ImagePicker`, `NetworkErrorView`).
+- Audit verdict is **per-surface, not per-app**: WebView-hosted product flows → `native-theme: not-applicable (webview-hosted, brand audited via loaded URL)`; native-owned iOS surfaces in the SAME app (splash, login, settings, offline / network-error fallback, permission prompts, photo upload modal chrome, status-bar / safe-area styling, deep-link landing) → `audit native brand tokens normally`. A whole-app `not-applicable` verdict is wrong whenever the iOS shell ships ANY native screen with brand-relevant chrome.
+- Wrapper-specific native concerns: JS-bridge auth + URL-allowlist, WebView file/camera permission plumbing (`UIImagePickerController` integration, `Photos` permission), safe-area + status-bar styling under the WebView, deep-link handoff into the loaded URL, the native error / offline fallback view's branding (since the user sees this when the WebView fails), and any native modal flows (photo upload, login bridge) whose chrome belongs to the iOS app not the web. Those still need native brand attention even when the main visual brand lives in the web app.
+
+## Data Persistence
+
+- **SwiftData (iOS 17+) is a niche default, not a universal one**: SwiftData is appropriate for SwiftUI-native new modules with light schema, simple migrations, and no cross-platform schema sync needs. For apps with complex migrations, server-synced schemas, audit / history requirements, or large legacy Core Data models, Core Data (or a hand-rolled SQLite layer behind a service) remains the safer choice — SwiftData is still adding history / custom store / inheritance capabilities. When mixing both, the Core Data and SwiftData schemas must stay in lockstep (`NSManagedObjectModel` materialization is required for new SwiftData fields).
+- **Keychain for credentials and secrets**; `UserDefaults` for non-sensitive preferences only. Cross-process sharing requires explicit entitlements: `keychain-access-groups` (Keychain access groups) for credential sharing across sibling apps / extensions, and `com.apple.security.application-groups` (App Group identifiers) for shared container / shared `UserDefaults(suiteName:)` for widgets / extensions / sibling apps. Use sparingly and clear on logout. Storing tokens in `UserDefaults` / file is a security finding regardless of obfuscation.
+
+## Capability Contracts
+
+For each platform capability the app uses, model success / cancel / denial / unsupported / timeout / recovery explicitly — these are the same axes mini-program skill enforces but Apple's contract is per-capability:
+
+- **APNs / UserNotifications (`UNUserNotificationCenter`)**: registration / device token retrieval / token rotation; authorization status (provisional / authorized / denied / ephemeral); foreground presentation options; deep-link payload schema; silent push (`content-available`) for background refresh; `UNNotificationServiceExtension` for payload mutation; APNs vs. third-party push provider boundary.
+- **WidgetKit** (iOS 14+): use when there is a clear glanceable use case (calendar / status / metric snapshot); `TimelineProvider` returns entries — keep timeline budget realistic; widgets read from App Group / shared container, not from main app's `UserDefaults`.
+- **Live Activities / ActivityKit (iOS 16.1+)**: scope to genuinely ongoing real-time state (delivery / live game / call / countdown). **Dynamic Island is hardware-specific** — iPhone 14 Pro / 14 Pro Max and later supported Pro models; never hardcode a model list, runtime-detect via `ActivityAuthorizationInfo` / capability check, and design Lock Screen presentation first as the fallback. Apple enforces duration limits, data-update frequency, and 4KB payload caps.
+- **App Intents (iOS 16+, evolving 17+/18+)**: replace SiriKit + manual Shortcuts donation for new apps; expose discrete user-meaningful actions for Spotlight / Shortcuts / Siri / Focus / Controls / widgets; do NOT model complex transactional flows here.
+- **AVFoundation / AVPlayer / AVCaptureSession**: required for video / audio / capture. Handle `AVAudioSession` category + interruption (call / Siri / other audio); `AVPlayerItem` failure / stall / preroll states; for background playback, enable Background Modes capability with `UIBackgroundModes=audio` in Info.plist AND set the matching `AVAudioSession.Category` (e.g., `.playback`).
+- **MapKit / CoreLocation**: bind to TCC (precise vs reduced accuracy, when-in-use vs always); explain background-location usage in the usage string; respect battery — request the lowest accuracy that works.
+
+## Dependencies
+
+- **Swift Package Manager is the default for new Apple-platform dependencies** — `Package.swift` integrated into Xcode, every recent Apple-shipped framework / WWDC sample uses SPM. CocoaPods entered maintenance mode in 2024; the public CocoaPods Trunk / Specs repository is announced to go read-only on 2026-12-02 (new podspecs / new versions no longer accepted after that — the `pod` tool itself keeps working against existing data). New code should not introduce CocoaPods; existing CocoaPods projects migrate at their own pace with test evidence.
+- **Binary SDKs (XCFramework) need three checks** before adoption: (1) Xcode 15+ verifies the SDK's signing identity if signed — fail fast if signature is missing or untrusted; (2) Privacy Manifest present if the SDK is on Apple's "commonly used SDKs" list (App Store Connect submission gate); (3) per-architecture slices match the app's deployment matrix (arm64 / arm64e / x86_64 simulator).
+
+## Tests And Verification
+
+- Unit test models, reducers/view models, API clients with fakes, persistence boundaries, validation, mapping, and error handling.
+- UI tests should assert expected elements and outcomes for critical flows.
+- Use previews for fast inspection, but do not treat a preview as proof of runtime integration.
+- Verify dynamic type, VoiceOver labels/order, contrast, safe areas, keyboard behavior, and localization-sensitive layout when touched.
+- **Swift Testing (Xcode 16+) vs XCTest**: Swift Testing's `#expect` / `#require` macros + parameterized tests + parallel execution by default + cross-platform support are the right defaults for new test code in Swift Testing-capable Xcode targets. XCTest remains valid for UI tests (`XCUITest`) and legacy suites; the two coexist in the same target — migrate incrementally, do not rewrite.
+- **Mocking discipline**: prefer protocol + fake-by-hand for adapter / network / persistence boundaries (clearer dependency graph, no codegen). Code-generated mocks (`Mockingbird` / `Cuckoo` / `Sourcery` / `MockoLo`) are appropriate only when the protocol surface is large (10+ methods) AND the test suite already depends on the codegen path — do not introduce a mock framework for new small surfaces.
+
+## Performance
+
+- Keep launch initialization fast; move noncritical work after initial UI.
+- Watch main-thread work, large view recomputation, image decoding, memory pressure, and list scrolling.
+- Use Instruments or Xcode diagnostics for suspected performance defects.
+- **MetricKit (`MXMetricPayload`) for production observability**: Apple's daily-aggregated metric payload (crash diagnostics, hang diagnostics, app launch / responsiveness / disk / memory / energy / animation / network metrics) is delivered to the app via `MXMetricManagerSubscriber`. Subscribe early in app lifecycle, forward to the crash backend (per `mobile-quality-release.md` symbolication gate) — MetricKit fills the gap between user-reported issues and crash reports for non-crash perf regressions (hang / slow launch / energy).

package/dist/assets/marketplace/plugins/ccl-skills/skills/app-cross-platform-dev/references/kotlin-multiplatform.md

@@ -0,0 +1,93 @@
+# Kotlin Multiplatform (KMP) + Compose Multiplatform
+
+KMP is a Kotlin-first technology for sharing business / domain / data / API-client logic across mobile (Android + iOS), desktop, server, and (beta) web. Compose Multiplatform extends that to share UI built with Jetpack Compose. The mature production pattern is **shared logic + native UI**; one-codebase-for-everything is a separate, narrower bet (see Compose MP section below).
+
+This ref is for Android/iOS teams evaluating or operating KMP. For pure Android (single platform), see `android-dev.md`. For pure iOS, see `ios-dev.md`. For Flutter / React Native, see `flutter-dev.md`.
+
+## Adoption Decision Matrix
+
+| Signal | KMP shared logic | Compose Multiplatform iOS |
+|---|---|---|
+| Team owns Kotlin Android codebase + native iOS app | strong fit | weaker fit (depends on iOS team) |
+| iOS team is independent / SwiftUI-owning | shared logic only via stable framework boundary | poor fit unless explicitly negotiated |
+| Existing Flutter / React Native product | do NOT introduce KMP "while we're at it" | wrong stack |
+| Goal: reduce duplicate business logic, keep native UI freedom | mature, production-proven path | not the right tool |
+| Goal: one UI codebase across both platforms | use Flutter or accept Compose MP trade-offs | possible since Compose MP 1.8.0 (2025-05) Stable, but evaluate per Compose MP section |
+
+## Source Set Hierarchy and expect/actual
+
+- **Source set layout**: `commonMain` (platform-agnostic) → `androidMain` / `iosMain` / `jvmMain` (target-specific). KMP defaults now use the **default source set hierarchy** introduced in Kotlin 1.9.20 (Stable) — `iosMain` automatically aggregates over `iosArm64Main` / `iosX64Main` / `iosSimulatorArm64Main`, etc. Do not hand-roll the old `intermediate-source-set` declaration unless a sibling project's pinned Kotlin version requires it.
+- **`expect` / `actual` for platform-specific implementations**: declare `expect fun method(): T` (or `expect interface X { fun method(): T }`) in `commonMain`, provide `actual fun method(): T = ...` in each platform source set. `expect class` is also supported but per Kotlin docs is Beta — prefer `expect fun` / `expect interface` for non-Beta surface. Use sparingly — every `expect` is a divergence the team must maintain; prefer pure-`common` code with platform impls injected via constructor / interface where possible.
+
+## iOS Integration
+
+- **iOS consumes a generated framework** (regular framework, static framework, or **XCFramework** for multi-arch). Three integration paths per Kotlin docs, pick by team workflow:
+  - **Direct integration** (simplest): the Xcode build invokes a Gradle script that produces the framework; Xcode picks it up via framework search path. Best for monorepo / tightly-coupled teams.
+  - **CocoaPods**: the Kotlin CocoaPods Gradle plugin generates a `podspec`; iOS team consumes via `pod install`. Required path if the KMP module needs to import other CocoaPods dependencies (`pod(...)` Gradle DSL).
+  - **Swift Package Manager**: produce XCFramework + `Package.swift`, distribute via separate Git repos for the manifest vs the framework. Per Kotlin docs the SwiftPM export path is the recommended remote-distribution workflow when no Pod dependencies are needed.
+- **Swift interop limits**: cinterop generates Kotlin bindings from Objective-C / C headers. Pure-Swift APIs are NOT directly consumable — Swift must expose `@objc` (or `@objcMembers`) to be visible to Kotlin. **Swift Export** (the reverse — exposing Kotlin to Swift without Obj-C bridging) had basic support since Kotlin 2.1.0; Kotlin 2.2.20 made experimental Swift Export available by default. Do not depend on it for production-critical interop yet.
+
+## Kotlin/Native Runtime
+
+- **New memory model is default since Kotlin 1.7.20**: no `freeze()` for cross-thread sharing, concurrent GC, GC pauses observable via Xcode Instruments (signposts). The freeze-based mental model is obsolete; if migrating from a pre-1.7 KMP project, remove `freeze()` calls and verify behavior.
+- **Memory + perf still need measurement on iOS**: GC pause characteristics differ from JVM; large heaps + frequent allocation can surface as scroll jank on lower-end iOS devices. Profile via Xcode Instruments, not by JVM intuition.
+- **C interop memory management**: the new memory manager manages Kotlin objects only — for C-allocated memory use `memScoped { ... }`, `Arena`, or `createCleaner`. C heap leaks are a real failure mode the GC does not catch.
+
+## Compose Multiplatform for iOS
+
+- **Stable since Compose Multiplatform 1.8.0** (released 2025-05 per JetBrains blog): API surface finalized; JetBrains claims feature parity with Jetpack Compose for popular use cases, first-class accessibility (VoiceOver, AssistiveTouch, Full Keyboard Access), and native-feel scrolling / text editing / RTL. This is a real "Stable" milestone, not a marketing-only label — but per Apple HIG conformance is your team's evaluation, not a JetBrains certification.
+- **Stable ≠ universally production-ready for every team**. Adopt only when ALL hold: (a) team is Kotlin-first (iOS engineers comfortable reading Compose / Kotlin code, or pure-Compose-MP UI team), (b) the design system tolerates Compose's rendering of iOS UI (or a native escape hatch is mature for the surfaces that need pure SwiftUI / UIKit), (c) the iOS team accepts the build / debugging / profiling tooling trade-off (Xcode Instruments + Android Studio rather than Xcode-only), (d) concrete native-feel parity evidence on iOS (component fidelity, gesture / scroll physics, accessibility behavior on real devices).
+- **Native escape hatch via UIKit / SwiftUI interop**: Compose MP supports embedding UIKit `UIViewController` into a Compose surface and vice versa; SwiftUI interop is also documented but adds complexity (state ownership, lifecycle, navigation). Treat interop as an architecture boundary, not as ad-hoc per-screen mixing.
+
+## Code Reuse Discipline — Tier by Layer
+
+Reject "80%+ code shared" marketing as a planning input. Realistic ranges per layer:
+
+| Layer | Typical reuse | Why |
+|---|---|---|
+| Domain logic / use cases | 80%+ | language-agnostic business rules |
+| API client / serialization | 70-90% | shared Ktor / kotlinx.serialization wrapper |
+| Local persistence | 50-80% | SQLDelight cross-platform; platform-specific storage details may diverge |
+| ViewModel / presenter | 50-80% | when shared; varies if platform UIs need different state shapes |
+| UI | 0% (native UI) to 80% (Compose MP) | depends on Compose MP adoption decision above |
+
+A project's actual reuse percentage is an outcome of architecture choices, not a goal — published case-study numbers (e.g., Forbes 80%+, Respawn 96%) reflect those teams' specific architecture + product surface, not a generic target.
+
+## Build and Toolchain
+
+- **Convention plugins (`build-logic`) prevent Gradle drift across multi-target modules**: KMP projects have meaningfully more Gradle complexity than single-target Android (target declarations, source-set wiring, framework export config). Encapsulate shared build logic in convention plugins consumed by each module — without them, the build files become the project's largest maintenance surface.
+- **Kotlin/Native compile time is non-trivial**: native compilation (LLVM lowering + linking) is slow vs JVM compile. Reserve dev workflow for incremental builds; full clean builds should run in CI, not at every desk-side iteration.
+
+## Testing Matrix
+
+- **`commonTest`** holds tests for pure-common code using `kotlin.test` — runs on every target.
+- **Platform-specific test source sets** (`androidUnitTest` / `iosTest` / etc.) hold tests that need real platform APIs or test framework features.
+- **iOS test on simulator AND device for release-gating flows**: simulator catches most issues but background tasks, push, biometrics, and capability gates need device runs (per `mobile-quality-release.md` runtime-test rules).
+- **Mocking on KMP**: `mockative` (codegen) and `mockmp` (manual) are options when interfaces are mocked across common code. Default to interface + hand-rolled fake first per `ios-dev.md` mocking discipline; reach for codegen mocking only when the protocol surface is large.
+
+## Platform Stability (per Kotlin docs)
+
+| Target | Stability |
+|---|---|
+| Android / iOS (Native) / Desktop JVM / Server JVM | Stable |
+| Web based on Kotlin/JS | Stable |
+| WebAssembly (`wasmJs`) | Beta |
+| Linux / Windows desktop native | Stability varies; consult current Kotlin docs before betting on them |
+
+Treat the Stable table as the only source for adoption decisions; do not infer stability from the existence of a target in `kotlin.targets`.
+
+## Rejected as Hype (do not write into rules)
+
+- "Compose Multiplatform replaces Flutter / React Native" — different value props; Compose MP is a Kotlin-first team's UI-sharing bet, not a general cross-platform default.
+- "One codebase, ship everywhere" — true only if every platform accepts Compose MP UI; otherwise the realistic model is shared logic + native UI.
+- "80%+ code reuse guaranteed" — reuse is an outcome, not a goal (see tiering table above).
+- "Hot reload across platforms" — verify per-target before claiming; not all platforms support equivalent hot-reload at production-quality.
+- "Wasm production-ready for mobile" — Wasm is Beta; not a mobile path.
+- "Cinterop seamlessly bridges Swift" — cinterop targets Objective-C / C ABI; Swift APIs require `@objc` exposure.
+
+## Sibling Routing
+
+- iOS-native design judgment (Material vs native iOS feel, gesture, accessibility): `product-ui-ux-design` owns the design call; this skill does not.
+- Pure Android implementation (not in `commonMain`): `android-dev.md`.
+- Pure iOS implementation (not consuming KMP framework): `ios-dev.md`.
+- Cross-platform release verification (multi-target test matrix, symbolication, image library audit): `mobile-quality-release.md`.

package/dist/assets/marketplace/plugins/ccl-skills/skills/app-cross-platform-dev/references/mobile-platform-boundaries.md

@@ -0,0 +1,77 @@
+# Mobile Platform Boundaries
+
+## Platform Choice
+
+- Choose Flutter when shared product behavior, speed of delivery, and consistent UI are more important than heavy native specialization.
+- Choose native Android or iOS when the feature depends on deep platform APIs, strict platform conventions, mature native modules, store policy nuance, or existing repo ownership.
+- Use mixed architecture only with a clear ownership split: shared UI/module boundary, native host boundary, build ownership, release ownership, and fallback plan.
+
+## Boundary Checklist
+
+- Route model: tabs, stacks, modal flows, back behavior, deep links, universal/app links, and unauthenticated entry.
+- State model: transient screen state, session state, cached data, optimistic changes, sync state, and invalidation trigger.
+- API model: typed request/response, auth/session refresh, cancellation, retry, timeout, pagination, upload/download, streaming or websocket if used.
+- Local model: key-value storage, database, file cache, encryption needs, migration, cleanup, and offline source of truth.
+- Platform model: permissions, background work, notifications, camera/media/files, clipboard/share, payments, biometrics, widgets/extensions, and OS policy.
+- Native bridge model: initialization, capability detection, callback id generation, callback cleanup, fallback to old bridge or degraded mode, timeout/failure mapping, and visible recovery when the host bridge is missing or stale.
+- Delivery model: build flavors/schemes, environment config, signing, app versioning, store review risk, telemetry, and rollback flags.
+- UI/UX model: define the visual focus, entry/current/next/return path, interruption recovery, safe retry/cancel behavior, and user confidence cues for each mobile task. Cross-platform consistency is not enough if the screen feels cramped, ambiguous, or unrecoverable on a real device.
+
+## Cross-Platform Rules
+
+- Keep shared behavior explicit. Document intentional differences by platform instead of letting them emerge from implementation drift.
+- Treat deep links, push opens, auth redirects, and app restore as first-class flows.
+- Model every async feature with loading, empty, partial, success, failure, retry, permission-denied, and offline states where applicable.
+- Keep platform adapters narrow and testable. UI code should not directly know transport, permission, or native SDK details unless the repo pattern requires it.
+- **Kotlin Multiplatform (KMP) / Compose Multiplatform are evidence-driven, not defaults**: KMP is appropriate for shared domain / data / API-client logic across an existing Kotlin Android codebase and a native iOS app (mature production pattern: shared logic + native UI). Compose Multiplatform iOS reached Stable in 1.8.0 (2025-05) — UI-sharing is a narrower Kotlin-first team bet that needs explicit native-feel parity evidence, native escape hatch, and iOS team acceptance. For products where the iOS team owns SwiftUI, Flutter / React Native is already the cross-platform path, do not introduce KMP "while we're at it". For adoption decision matrix, expect/actual + source-set discipline, iOS framework integration paths (direct / CocoaPods / SPM), Kotlin/Native runtime, Compose MP iOS scope, code-reuse tiering by layer, build/test matrix, and platform stability table, read `references/kotlin-multiplatform.md`.
+
+## Cross-Platform Brand Color Boundary
+
+The shared rule on brand-color divergence across platforms (web, native mobile, mini-program) is owned by `product-ui-ux-design/references/multi-project-token-consistency.md` "Cross-platform brand divergence — a recurring sub-case" and `design-system-source-of-truth.md` Anti-Patterns. Mobile-side implementation responsibilities:
+
+- **Audit each mobile shell for its actual rendered brand primary**, then compare against the web brand primary for the same product. Two different values are NOT automatically drift — first run the Migration-State Classification in `multi-project-token-consistency.md` (`current` / `target` / `in-flight` / `drift`); a documented staged brand refresh with named migration signals (upgrade-plan artifact, deprecation marker, parallel-runs switch, tracked work item, deliberate partial rollout) is a planned rollout, not a per-platform-role failure. After that classification: when the divergence is **permanent intentional** cross-platform branding, the design source must use explicit per-platform role naming (`colorPrimary-web` / `colorPrimary-native` / per-platform variable collection); when the divergence is **drift** (no migration signal, no per-platform role), escalate the fix.
+- **When the divergence IS permanent intentional**, the mobile theme module must comment-link to the design-source variable name and the product-decision owner (PM / brand owner) — e.g. `// brand: colorPrimary-native per <design-system file> Variables panel, owner: <role>`. Implicit "we just always used this color" is the same risk as no decision record.
+- **Algorithmic secondary / tertiary derivation** falls into two paths per the shared rule in `multi-project-token-consistency.md` Anti-Patterns: **custom derivation** (HSV shift, alpha tint, complementary, lightness step) requires a one-line designer/date sign-off in the theme file AND a brand-refresh derived-color visual check; **standards-based platform schemes** (Material You's `ColorScheme.fromSeed` / `dynamicLightColorScheme`, antd's automatic palette from `colorPrimary`, MUI's `createTheme` tonal palette) require recording the variant/version in use, accessibility/contrast checks against the brand seed, and visual QA on canonical screens — designer sign-off applies to the policy adoption + seed/canonical pass, not to every runtime-generated tonal value. The two paths are distinct; do not collapse them.
+
+## WebView-Wrapper App Recognition
+
+A mobile app whose main product flows are hosted in a `WebView` (Android) / `WKWebView` (iOS) plus a thin shell of native helper screens (network error, photo upload, auth bridge, splash, settings) is a **hybrid WebView shell**. The audit verdict is per-surface, not per-app: WebView-hosted product flows route their brand audit to the loaded web app; native-owned shell screens are audited as native surfaces with normal three-layer evidence. Recognition rule below applies to both Android and iOS shells:
+
+- **Native-source-count signal**: typical wrapper has very few native UI screen classes (no Compose `@Composable` screens, no SwiftUI `View` for product flows). The native source is dominated by infrastructure (AppDelegate / MainActivity, network, file/image helpers, JS bridge).
+- **JS-bridge signal**: dependency on `WebViewJavascriptBridge`, `WKScriptMessageHandler` patterns, or equivalent web-to-native bridging libraries.
+- **Audit verdict is per-surface, not per-app**: WebView-hosted product flows → `native-theme: not-applicable (webview-hosted, brand audited via loaded URL)`; native-owned surfaces in the SAME app (splash, login, settings, offline / network-error fallback, permission prompts, deep-link landing, native modal flows, status bar / safe-area chrome) → `audit native brand tokens normally`. A whole-app `not-applicable` verdict is the failure mode — auditors then skip visible native surfaces in a "wrapper" app.
+- **Wrapper-specific native concerns still apply**: status bar / safe area styling under the WebView, the native fallback / network-error screen's branding (since users see it when the WebView fails), permission-prompt chrome (camera, photos, location), deep-link handoff into the WebView URL, login bridge modal chrome, and any native modal flows whose visual chrome is owned by the native app. These must still align with the product brand even when the main UI is web-rendered.
+- **Desktop wrappers (Electron / Tauri / Wails / .NET MAUI Blazor Hybrid) are NOT automatically covered by this mobile-side rule**. Per `multi-stack-strategy.md`, Electron classifies as `native`. Desktop wrappers carry their own per-surface split — web-rendered content vs native shell chrome (window chrome, menu bar, system tray, native dialogs, updater UI, app icon, splash) — and the desktop shell chrome IS brand-relevant. Route desktop wrapper audits through the desktop platform skill that owns them; do not analogize the mobile WebView-wrapper verdict to Electron.
+- See per-platform implementation in `android-dev.md` and `ios-dev.md` Theme And Brand Color sections.
+- Gate debug consoles, mock login, and local bypasses to development or explicit test builds. Production app/H5 surfaces must not expose debug entry points through query strings, default accounts, or visible console tooling.
+- Device or native-capability flows need explicit status taxonomies. Convert raw native codes into user-facing states, retry safety, support evidence, and terminal failure paths instead of showing generic bridge errors.
+- Mobile layouts must be validated through the same four layers as design: aesthetic focus and density, interaction path, behavioral recovery, and psychology of certainty/control. Safe-area, keyboard, orientation, permission, background/foreground restore, and host-bridge absence are part of the product experience, not only platform plumbing.
+
+## Bridge Protocol Contract Discipline
+
+Hybrid apps that expose native capabilities to a hosted H5 layer almost always grow two parallel bridge implementations (iOS WKWebView + Android WebView) plus the H5 caller. Without an explicit contract, the three sides drift.
+
+- **The bridge surface is a typed contract, not a coincidence.** Enumerate every handler/method name, request payload shape, callback response shape, status taxonomy, and timeout in one place that both native sides and the H5 side consume. Free-form `callHandler("openCamera", anyJSON)` calls are how silent drift accumulates.
+- **Status semantics must be uniform.** Pick one numeric or string enum (e.g. `Success / Cancel / Fail`) and apply it across every bridge call on every platform. Mixing `0/1/-1` on one side and `"ok"/"cancelled"/"error"` on the other forces every caller to write platform-aware branches.
+- **Payload encoding must be uniform.** If one platform passes a JSON object and the other passes a JSON string in a single `data` field, every H5 caller pays a `JSON.parse + typeof` cost on every callback. Pick one and codify it.
+- **Capability asymmetry must be enumerated, not silent.** If one platform supports `exportLogs` and the other does not, the H5 caller must detect this and degrade gracefully — never crash the page on a missing handler. Maintain a capability map keyed on platform.
+- **Long-lived `window.<callbackId>` injection patterns must clean up — and namespacing alone is not enough.** Android-style bridges that attach the resolve/reject to `window[callbackId]` and rely on the native side to fire it leak globals and fire into unmounted React trees. Moving the slot under a namespaced object (e.g. `window.NativeBridge.callbacks[id]`) is a step but not the answer — the registry is still enumerable, the dispatcher is still monkey-patchable by any script that loads before the bridge, and a co-running script does not need to *guess* an id when it can enumerate the map. The complete pattern is: (a) install one locked, immutable dispatcher *value* before any third-party script loads — `Object.defineProperty(window, '__nativeBridge', { value: dispatcher, writable: false, configurable: false })` is necessary but NOT sufficient on its own, because the dispatcher object's *methods* are still mutable; harden the value itself by defining each public method as a non-writable / non-configurable property, calling `Object.freeze` on the dispatcher (and any nested objects it exposes), and preferring a `Object.create(null)` prototype so prototype-chain pollution cannot replace methods. The acceptance test is: a third-party script that loads after the dispatcher must not be able to replace `dispatch`, `settle`, or any registered handler. (b) Hold the callback map inside a closure private to the dispatcher rather than as a property of the bridge object — the map must not be reachable via `window.__nativeBridge.callbacks` or any other enumerable path. (c) Generate ids from a cryptographic source as defence-in-depth. (d) Wrap the registry in a one-shot settle (the callback is removed in a finally block before it resolves). (e) Attach a timeout that rejects + cleans up if the native side never fires. (f) Validate `(callbackId, op, generation)` triple on every fire so a stale or wrong-op response cannot resolve a different pending call. Each of (a)–(f) is necessary; none alone is sufficient.
+- **Bridge initialization handshake is a separate state, and the queue must be session-scoped.** WKWebView's bridge loads via a one-shot iframe ping; before that fires, `window.WebViewJavascriptBridge` is undefined. Every page that calls the bridge during mount must either wait on the handshake or queue the call — not assume the bridge is ready. The queue must carry a session/route generation token, must drop entries when the user logs out / navigates / unmounts before the handshake completes, must enforce a maximum queue depth and TTL, and must explicitly re-prompt the user for privileged calls (payment, secure storage write, biometric auth) rather than auto-replaying them. A bridge queue that fires `purchase` or `writeSecureStorage` after a logout/navigation is a real incident class, not a theoretical one.
+- **Two-side codegen beats handwriting — and codegen alone is not version negotiation.** When a portfolio has more than one bridge handler and more than one platform, hand-rolling each native handler + each H5 caller is anti-pattern. Generate from a shared IDL (TypeScript types, protobuf, JSON Schema, or framework-specific) so the contract cannot drift unobserved. The IDL must also carry a version number: H5 is updated from CDN/route at any time, native apps update at store cadence, so the H5 caller routinely runs against an older native handler set. Encode min/max compatible bridge versions on both sides, capability-probe the native version on handshake, and degrade gracefully when a method or field the H5 expects is unavailable. A capability map that is only updated when the H5 ships, never when native ships, will go stale silently.
+- **Cross-platform storage is three abstractions.** Native Android key-value, native iOS key-value, and H5 `localStorage` / IndexedDB / framework persistence stores are not interchangeable. If the same business value must round-trip across all three, define one canonical encoding and one ownership rule (which side writes the source of truth) before code lands.
+
+## Native ↔ H5 Data Channel Decision Rule
+
+When choosing whether business data flows over native bridge or over HTTP, follow this rule. Native-exclusive capability goes through the bridge; everything else stays on HTTP.
+
+- **Bridge channel is for native-exclusive capability**: camera, secure storage, biometric auth, file system, deep link consumption, lifecycle events, native UI dialogs, background tasks, in-app updates, share/permission sheets. The bridge is the only path to these — and they are the only things that justify the bridge cost.
+- **Payment is not a single bucket — split by authority, not by surface.** Decide per payment phase, with the authority always sitting on the side that owns the secret, the contract, or the truth:
+  - **Server-owned**: payment intent creation (the intent ID and secret are minted server-side), PSP webhook reception and verification, receipt verification against the PSP/store, entitlement grant (the source-of-truth flip that says "this user now has X"). These never live on the client — neither native nor H5. The mobile app receives results, it does not produce them.
+  - **Native-owned (via bridge)**: opening the native pay sheet (Apple Pay / Google Pay / PSP pay sheet) so card data never enters the merchant app; in-app purchase / store-policy-bound subscription confirmation (App Store IAP, Google Play Billing); SDK confirmation callbacks where the SDK requires a native context; 3DS / SCA challenge surfaces that must render in a native webview controlled by the PSP. The bridge surfaces these to H5 as opaque "ask native to take payment, here's the result token" calls — never as raw card data.
+  - **H5-owned (via HTTP)**: payment metadata UI only — order history, invoice list, billing settings labels, statement download, refund request submission (which goes to server, not the PSP directly), payment-method labels (not card data). The H5 caller never sees an intent secret, a card number, or a webhook payload.
+  - **Either side, but pick one and own it**: payment status polling (UI display) and receipt reconciliation rendering can sit on either side, but cannot sit on both — pick the owner, document it, and have the other side read through that owner.
+  - PCI scope, store policy, regulator scope, and PSP contract take precedence over what is convenient. PCI scope reduction depends on whether card data ever touches the merchant-controlled app: a native pay sheet that hands the merchant a token (rather than a PAN) typically reduces scope to SAQ-A class, but this MUST be confirmed against the specific PSP contract, store policy, and regulator before relying on it — none of this rule can be a substitute for the PCI/store/regulator review.
+- **HTTP channel is for business data**: reports, analytics, user profile, content lists, comments, settings, search results, **plus the payment metadata listed above**. H5 is a capable HTTP client and the native side does not need to be on this path. Routing business data through the bridge to use native auth headers, native HTTP stack, or native caching is almost always premature optimisation that costs more in contract surface than it saves in network.
+- **Hybrid is fine, mixed-channel is not**: a feature where the photo comes from native (bridge) and the AI analysis comes from server (HTTP) is healthy hybrid. A feature where some of the report data is bridged from a cached native blob and the rest is fetched from server is mixed-channel — the H5 caller has to reconcile two sources, and the cache invalidation story is not actually free.
+- **The bridge contract should shrink over time, not grow.** When a capability moves from "native-only" to "available in browser" (new web API ships, framework adds a JS shim), the bridge handler retires. A bridge surface that only grows is a smell.
+- **Failure isolation**: a native bridge failure should not blank the entire H5 surface. Wrap every bridge call with timeout + fallback + explicit user-facing state, so a stuck native side does not stall the page.

package/dist/assets/marketplace/plugins/ccl-skills/skills/app-cross-platform-dev/references/mobile-quality-release.md

@@ -0,0 +1,77 @@
+# Mobile Quality And Release
+
+## API Client Recipe
+
+For mobile and cross-platform apps, centralize these mechanics in the shared API client or platform adapter:
+
+| Concern | Required behavior | Test evidence |
+| --- | --- | --- |
+| Request metadata | Attach or preserve request id, trace id, operation name, app version/build, platform, auth context, and upload/long-running classification where available | Fast client tests assert metadata and redaction |
+| Response parsing | Classify canonical envelope, empty body, invalid JSON, non-2xx envelope, backend error envelope, and malformed success separately | Fast API-client tests for each response shape |
+| Cancellation and lifecycle | Distinguish user cancel, route dispose, app background, timeout, and network failure | Unit/widget tests plus device smoke for an interrupted flow when risky |
+| Auth and permission | Convert expired auth, forbidden, feature-closed, and scope mismatch into route/session/permission state without losing recovery context | Widget or integration tests for session and permission states |
+| Offline/weak network | Preserve pending intent only when safe; expose retry/final status and avoid duplicate irreversible actions | State-machine tests and one device smoke for recovery |
+| Long work | Expose task id/status, polling/backoff, refresh or foreground recovery, terminal success/failure, and support identifier where needed | Client test plus installable-device smoke for one pending-to-final path |
+
+## Test Layers
+
+- Fast tests: pure logic, state transitions, mapping, validation, API client parsing, retry decisions, cache policy, and permission state mapping.
+- UI/widget/component tests: loading, empty, partial, success, error, retry, disabled, permission-denied, offline, and optimistic states.
+- Integration/device tests: native plugins, deep links, push opens, auth redirects, camera/files/media, background work, local database, and installable build smoke.
+- Manual or screenshot verification: required for nontrivial UI layout, gesture, animation, visual hierarchy, and platform-specific fit.
+- Scenario tests: build the scenario matrix in `testing-strategy`; for app surfaces, map each scenario to fast state/API tests, widget tests, device integration, and only the necessary installable-device smoke.
+- **E2E / UI tests benefit from Robot pattern for non-trivial flow suites**: regardless of the underlying runner (Maestro for declarative cross-platform flows, Detox / Patrol for React Native + Flutter, XCUITest for iOS, UIAutomator / Espresso for Android), wrapping selectors + actions in per-screen Robot objects (`loginScreen.enterEmail(...).tapNext()`) means a UI structural change touches one file, not every test. Apply when the suite has ≥5 tests touching the same screen or when test churn from UI refactors is the visible pain — for a single smoke or one-off, the wrapper is overhead. Tool choice routes to repo / platform owner; the pattern survives the tool.
+
+## UI/UX Judgment Checks
+
+- Aesthetic: verify hierarchy, density, rhythm, contrast, motion, and material treatment on real target devices or screenshots. The screen should not become cramped, bland, or visually noisy after implementation.
+- Interaction: verify navigation stack, back/close, bottom sheet/dialog return, gesture conflict, keyboard path, and orientation-specific toolbar/preview behavior.
+- Behavioral: verify disabled reasons, duplicate tap protection, pending/final state, retry/cancel, offline/weak-network behavior, foreground/background recovery, and app restart recovery where relevant.
+- Psychology: verify the screen reduces uncertainty and perceived risk. Users should know what is happening, whether it is safe to wait or retry, and how to recover if the app is interrupted.
+- Adaptation: check safe-area insets, keyboard-covered inputs/actions, text scale, landscape where supported, narrow/large phones, and tablet/foldable layouts when in scope.
+- Native capability and device tasks: verify missing host/permission/device, wait state, success continuation, raw status-code mapping, retry/report path, callback cleanup, and production debug gating.
+
+## Mobile Client STS Upload Lifecycle
+
+When the mobile client uploads directly to object storage (TOS / S3 / GCS) using short-lived STS credentials minted by the backend, the client-side lifecycle has rules distinct from the server-side STS broker contract (which lives in `platform-release-engineering/references/secret-and-config-management.md` Pattern C-adjacent — Cloud Session Token Brokering):
+
+- **STS-version / bucket selection is a remote-config decision with a security-incident-grade TTL, not a build-time constant**: the client asks the backend for the current `(bucket, sts_version, region)` tuple at upload time. Cache TTL is bounded by the incident-response budget — typical: low single-digit minutes for the security-sensitive fields (bucket, sts_version, region, kill-switch), longer is acceptable only for non-security fields. Hardcoding the bucket in `BuildConfig` / `Info.plist` constants forces a store-cadence release every time ops switch bucket, region, or STS major version. The build-time constant remains as the degraded-mode fallback when remote config is unreachable.
+- **Backend kill-switch and revocation handling**: the remote-config response includes an explicit kill-switch flag per upload class; when set, the client fails closed (no upload, structured error to caller) until the next config fetch clears it. When the backend revokes a bucket / region / STS version, every still-cached client config must converge within the TTL above; clients receiving "bucket revoked" / "sts version retired" from the upload API fail-close immediately and force a config refresh, never retry against the revoked target.
+- **Degraded-mode fallback is explicit and logged**: when the remote-config fetch fails (network down, bad response, parse error), the client falls back to the build-time bucket + a fixed STS version (typically v1 / oldest-supported). The fallback is logged as a degraded path (warning level, with the failure cause); silent fallback hides incidents where the remote config has been wrong for weeks. Fallback is itself subject to the kill-switch: if the backend has revoked the fallback target, no upload happens until config is refreshed.
+- **Token request is per-upload-session, not per-app-launch**: short-lived STS tokens (typical 15-60 min) are fetched at the start of an upload session and re-fetched on token expiry within a long session, NOT cached across app launches. App-launch caching produces "first upload after launch tries with an expired token from yesterday" failures.
+- **Log redaction at the boundary, including DEBUG paths**: the upload-coordinator logger emits `ak_prefix=<first-8-chars>`, `token_len=<int>`, `bucket=<bucket>`, `sts_version=<enum>` — NEVER the full access key, secret key, session token, or signed URL. The redaction lives in the client SDK and applies in DEBUG builds too — `#if DEBUG` / `BuildConfig.DEBUG` blocks logging the raw STS response is a real leak class because (a) DEBUG-flagged builds reach beta/internal users on real STS credentials, (b) developer devices that log raw tokens upload them via crash report attachments / diagnostic export / log-share buttons. The same redaction applies to HTTP interceptors (OkHttp logging interceptor, URLSession metrics observer), crash-breadcrumb collectors, analytics body capture, and any third-party SDK that records request/response bodies — disable body capture on the upload path or scrub credentials before the third-party SDK sees them. Mobile logs leave the device through too many channels to leave any one uncovered.
+- **Multi-version STS coexistence**: when the backend supports more than one STS version (v1 legacy, v2 new), the client picks the version from remote config, not from local logic. The version selector wires into the upload SDK as the request shape (header / query param), so backend rollout of v2 does not require a client release.
+- **Upload-coordinator is the single seam — enforced by lint, not by convention**: bucket selection + STS fetch + retry on credential expiry + upload progress + cancellation all live in one coordinator class; callers (camera flow, document picker, log-export, etc.) call `coordinator.upload(file, metadata)` and never touch credentials. Enforcement: a build/CI lint rule (gradle / xcodebuild custom check, or grep gate) fails the build when any file outside the coordinator imports the TOS SDK directly, calls the STS token-fetch API, or constructs an upload signing header. Per-feature upload helpers that fetch credentials independently are a real recurring drift class, not a hypothetical — the lint catches it before review.
+
+## TLS Trust And Certificate Pinning
+
+When the mobile app must talk to internal-CA / enterprise-CA / self-signed hosts (typical: a development environment, a corporate intranet, a partner integration with a private CA), the trust override rules:
+
+- **The override gates by distribution channel + data sensitivity, not just an environment enum**: a check like `Environment.Current != .Production` is too coarse — staging, preview, canary, TestFlight, internal-distribution, and dogfood builds routinely carry real user sessions, real auth tokens, and real (or partially-real) PII. A trust override that fires on those builds is the same MITM vector as a production override. The correct gate combines (a) the distribution channel / signing identity (debug-keystore / development-provisioning-profile only, never any distribution channel that touches real users including TestFlight and staged-rollout), (b) the build flavor's data sensitivity (no real auth tokens, no real PII), and (c) the hostname allowlist below. All three must be satisfied; production hosts on a dev build still get system-default validation.
+- **Hostname allowlist with suffix-match boundary**: the override accepts the server trust only when the request's hostname matches an explicit allowlist with a strict suffix-match: `host == allowed || host.hasSuffix("." + allowed)`. The leading-dot boundary is mandatory — without it, a host like `<allowed>.<attacker>.tld` matches and accepts a hostile cert. Blanket accept-any-cert in non-prod is still a leak vector when the device joins a hostile network — the dev build a developer carries through public Wi-Fi accepts forged certs for any host.
+- **Production hosts use public-CA certificates**: the production hostname MUST use a publicly-trusted CA. Falling back to the internal-CA override path on a production hostname is a deployment / ops bug to fix, not a client-side trust-override extension.
+- **Trust handler is delegate-scoped at the right TLS layer, not at an interceptor layer**: implement the override as a custom `URLSessionDelegate` (iOS, hooking `urlSession(_:didReceive:completionHandler:)` for `NSURLAuthenticationMethodServerTrust`) or as a custom `X509TrustManager` + `SSLSocketFactory` (and where pinning is wanted, a `CertificatePinner`) attached to the dedicated `OkHttpClient` for internal hosts. Android `OkHttp` interceptors run AFTER the TLS handshake and cannot affect certificate validation — implementing the override as an OkHttp interceptor is a no-op that looks like it works and silently leaves system-default validation in place (or worse, gives a false sense of security). The handler is attached only to the dedicated client that targets the internal hosts; the global default (`URLSession.shared`, system OkHttp default) keeps system-default validation so a third-party SDK using shared session is never weakened.
+- **Pinning for high-trust endpoints, when used, pins to the public key (SPKI) not the leaf cert**: leaf certificates rotate (every 90 days for many public CAs); pinning to the leaf bricks the app on next rotation. Pin to the issuing CA's SPKI or the project's long-lived intermediate. Ship at least one backup pin (the next-issuing CA's SPKI) so a CA-rotation incident does not require a store release; when both pinned CAs are revoked simultaneously the only recovery is a forced app update, so the backup-pin set is reviewed at every release to track the active rotation horizon. Audit the pin set every release; a pin set that never updates will eventually brick.
+- **Pin-failure UX**: when a pin fails (network MITM detected, expired pin, CA rotation outpaced the app), the app surfaces a structured "secure connection failed" message with a support code, NOT silently retries or falls back to unpinned. Silent fallback is the bug pinning was meant to prevent.
+
+## Accessibility
+
+- Check labels, hints, focus order, keyboard/switch control where relevant, dynamic type/text scale, contrast, touch target size, and readable error messages.
+- Do not add icon-only actions without accessible names.
+
+## Performance And Reliability
+
+- Watch app startup, frame/render stability, scroll performance, memory, image loading, network retry behavior, offline handling, crash-free path, and app size.
+- Add observability for critical flows: crash breadcrumbs, analytics events, performance traces, and meaningful client-side errors.
+- **Crash report symbolication is a release gate for public / staged-rollout traffic**: every release going to public traffic MUST upload Android R8 / ProGuard mapping (`mapping.txt` + per-ABI native debug symbols / `*.so` symbols) AND iOS dSYM bundles to the crash backend (Crashlytics / Sentry / Bugsnag / equivalent) before traffic — without them obfuscated stack traces are unreadable and "crash-free path" is unverifiable. Wire the upload into the release pipeline; do not rely on manual upload. Internal / closed-test builds may downgrade this gate by risk acceptance. Note: bitcode is deprecated since Xcode 14 and App Store no longer accepts bitcode submissions from Xcode 14, so dSYM upload is the only practical iOS symbolication path.
+- **Image loading verdict is by capability surface, not by library name**: regardless of which library is in use (Coil / Glide / Picasso / SDWebImage / Kingfisher / Nuke / cached_network_image / FastImage), audit the same surface: decode happens off the main thread, memory + disk cache configured with bounded size, placeholder + error + retry states defined, network failure modeled in UI state, large-image / thumbnail strategy for lists, memory peak under realistic list scroll measured.
+
+## Release Readiness
+
+- Verify build variants/flavors/schemes, signing, environment config, app version/build number, feature flags, rollback path, store policy implications, and install smoke.
+- Store release notes and screenshots are release artifacts; keep them consistent with shipped behavior.
+- For staged rollout, define the monitored metrics and stop/rollback condition before release.
+- **Debug-only instrumentation must be structurally excluded from every real-user build, and the exclusion verified on the exact shipped artifact — a runtime flag is not the guard.** The class is broad: debug bridges, in-app state/inspection servers, dev overlays/menus, network inspectors, remote WebView debugging, verbose token/PII logging, mock-auth or auth-bypass hooks, and any QA state-export or runtime-introspection surface — including ones with no visible UI that are still reachable via deep link, push action, JS bridge message, or custom URL scheme. Any of these is an attack surface and data-exposure risk (an in-app state server can bind a port and dump app state on a real user's device) if it reaches a build that can touch real users, real auth, or real PII. **Scope by distribution channel + data sensitivity, not a single `isProduction`/`isDebug` enum**: the gate covers App Store / Play production AND TestFlight, enterprise / ad-hoc, dogfood, Play internal/closed testing, and staged rollout — all carry real users (same channel-not-enum boundary as **TLS Trust And Certificate Pinning** above).
+  - **Exclude at the dependency/target level, per real-user variant — not just a runtime flag, and not just the variant named `release`.** An `if (isDebug)` check still compiles the code — and any bound port/server — into the binary; even `kDebugMode` / `__DEV__` only strip the Dart/JS call path while a native plugin/module/platform-channel stays linked. The primary guarantee is that the debug dependency/target is absent from the release classpath / target membership / build flavor of *every variant that reaches real users*, verified per variant: iOS `#if DEBUG` plus Debug-only target membership — CocoaPods can scope a pod to Debug configurations (`:configurations => ['Debug']`), but SwiftPM has no build-configuration-scoped *package dependency*, so a debug package must be confined to a debug-only target/scheme and left unlinked by every real-user target rather than gated by a `Package.swift` condition; also confirm no real-user scheme (TestFlight / enterprise / staging) inherits `DEBUG` in `SWIFT_ACTIVE_COMPILATION_CONDITIONS` / `GCC_PREPROCESSOR_DEFINITIONS`, or `#if DEBUG` code compiles straight into it; Android a `debugImplementation` / debug source-set dependency, NOT `implementation` plus a runtime check (a manifest `ContentProvider`/initializer or reflection keep-rule runs it anyway) — and note a `debug` / `qaDebug` buildType shipped to dogfood/internal testing IS a real-user build that includes those deps, so real-user channels must use release-class variants with debug deps excluded; Flutter/RN remove the package from the release flavor at the platform level (a native plugin autolinks/registers into the binary via podspec/Gradle/manifest unless excluded from the release target, even when the Dart/JS guard is stripped).
+  - **Verify on the exact final signed/packaged upload artifact per channel and variant, and treat a symbol/string grep as a backstop, not proof.** A single `nm -j` / `strings` / dexdump / grep is defeated by R8 / Hermes / LTO renaming (`DevInspector` → `a.b.C`), dynamic loading (`dlopen`, Android dynamic feature, RN/Flutter OTA bundle, remote WebView JS), and non-code surfaces (debug assets, URL schemes, manifest providers/services, plist keys, debug entitlements). *Discover* the inventory from the dependency graph, manifest/plist, entitlements, and route/deep-link/bridge registries — not a remembered list, since an unlisted transitive SDK initializer or debug bridge handler is exactly the gap — then for each assert absence across binary, dex/native libs, assets/resources, manifest/plist, entitlements (`get-task-allow` is debug-only; Local Network / ATS / cleartext exceptions are security-sensitive plist/capability config that need production justification, not necessarily debug), and the OTA/dynamic-load channels reachable by that release (a passing artifact digest does NOT bind a debug bundle pushed later via CodePush/Expo/remote WebView JS, so real-user OTA/remote channels must not serve debug payloads). Run it on the post-signing artifact you actually upload (record its digest), across every shipped platform / scheme / flavor / extension, never on an intermediate `assembleRelease`. (`__DEV__` / `kDebugMode` elimination is also minifier-dependent and has silently regressed historically, so the source guard alone is never proof.)
+  - **Make it a release-blocking evidence row, not MR prose** (otherwise the gate is decorative — a team ships from local Xcode/Fastlane, self-marks "checked", or never adds the CI job). The row is machine-generated, tied to the uploaded artifact digest + variant, and verified by someone other than the author; it records the digest, distribution channel, variant matrix, and check-command output, and the release/upload lane fails closed on a missing row. **Risk acceptance cannot waive structural exclusion** of debug-only instrumentation in any real-user / real-auth / real-PII build: an exception may only reclassify the channel as non-real-user / no-real-data, or apply to a production-intended diagnostic that ships its own auth + redaction controls (at which point it is no longer debug-only instrumentation) — otherwise the release stays blocked, an unbounded "accepted" is not a valid disposition. Guidance cannot force a given repo's pipeline to fail closed — that mechanical enforcement is the release-pipeline owner's job (route to `platform-release-engineering`); absent the row the status is not release-ready, the same way missing device smoke leaves a slice `pre-runtime-test ready`. A manual removal/teardown flow is a convenience path for a one-off exit, never the mechanism that keeps debug code out of real-user builds.

package/dist/assets/marketplace/plugins/ccl-skills/skills/app-cross-platform-dev/references/source-evidence-map.md

@@ -0,0 +1,64 @@
+# App Client Source Evidence Map
+
+Use this reference when auditing or re-extracting mobile app guidance. The rules below describe *how* to classify Flutter/native Android/native iOS/H5/WebView/RN sources; specific local repository paths and dated cross-check logs live in the private provenance archive outside this skill tree. Mini-program sources route to `miniapp-product-dev`.
+
+Users without code access can still apply the distilled patterns in this file. Do not require access to specific paths unless the task explicitly asks to audit, update, or re-extract implementation evidence.
+
+## Source Coverage
+
+For each app subproject in scope, classify before extracting rules. The shape below is the classification frame; specific entries live in the private archive.
+
+| Dimension | Typical stack signature | Useful extraction | Decision |
+| --- | --- | --- | --- |
+| Broad app inventory | Batch manifest scan across Flutter `pubspec.yaml`, Android `build.gradle`, iOS `Podfile`, H5/Webview projects, and third-party test apps | App skill must classify Flutter, native Android, native iOS, mini-app, H5/webview-like, or mixed host/module before implementation | Keep |
+| Flutter app sources | Flutter manifests including assets, Material/Cupertino, chat/PDF/markdown, Dio, shared_preferences, provider, url launcher | Supports Flutter shared app workflows, asset handling, API clients, local persistence, document rendering, rendered device verification | Keep |
+| Native Android sources | Gradle manifests in product app and third-party test-app areas | Native Android evidence exists but some is third-party/test-app; classify source quality before extraction | Keep only product-app mechanics; discard third-party test-app noise |
+| Native iOS sources | Xcode/Podfile-based app projects, WKWebView shells, JSBridge | Supports iOS shell contracts, native bridge handlers, orientation/safe-area/status sync | Keep |
+| Mobile/H5 sources | React H5 apps with safe-area shell, keyboard avoidance, dialogs, upload/image crop, bottom tabs, route guards, responsive containers, async/error/retry | Strong evidence for mobile interaction states even when implemented as web/H5; route browser specifics to `web-react-dev` | Merge state/interaction mechanics, keep stack boundary clear |
+| React Native sources | `react-native` + navigation/storage/image-picker deps | Supports cross-platform navigation, storage, image-picker contracts; not a substitute for native shell when the product hosts a WebView | Keep when present, otherwise note absence |
+| Mini-app sources | Taro/UniApp/wepy manifests with platform plugins for h5/weapp/alipay/jd | Supports mini-program shell, page lifecycle, platform variant builds, host-bridge differences | Route implementation, platform APIs, developer-tool verification, review, and release to `miniapp-product-dev`; keep only H5/WebView evidence that runs inside a native app host |
+| Design-system mobile source | Published mobile design-system Figma + mobile UI files | Supports safe area, navigation, modal/bottom sheet, toast, image viewer, review landscape/portrait, compact state rules | Route visual/UX rules to `product-ui-ux-design` |
+
+## Source Classification Method
+
+Before extracting rules from a subproject:
+
+1. Confirm the stack signature from manifests (`pubspec.yaml`, `build.gradle`, `Podfile`, `package.json` with native or RN deps). Directory-name guesses alone are not evidence.
+2. For default-empty checked-out branches, inspect remote branches (feature, develop, or release patterns are common; the active prefix list is recorded in the private archive). Pick the one with real content. Many native projects keep `main` as a scaffold and ship from a feature branch.
+3. Note whether the subproject is a true native app, a WebView host, an RN bridge, a Taro mini-app, or a pure H5 surface. Each has a different contract with the design source.
+4. Treat third-party test apps and demo folders as noise. Use them only when explicitly required, never as positive baselines.
+
+## Cross-Skill Routing
+
+- Visual/UX judgment → `product-ui-ux-design`.
+- React/browser implementation → `web-react-dev`.
+- Native/Flutter/RN implementation → stays here.
+- Mini-program/Taro/UniApp implementation → `miniapp-product-dev`.
+- Test-layer planning → `testing-strategy`.
+
+## Keep / Merge / Discard
+
+- **Keep**: verify each affected platform explicitly; one platform passing does not prove all platforms.
+- **Keep**: app-hosted H5/WebView features need explicit checks for full-screen container behavior, safe-area normalization, keyboard mode, orientation bridge/fallback, native bridge/session state, foreground/background recovery, public/guest/auth route gating, in-region retry, and development-only debug tooling.
+- **Keep**: native WebView shells require branch discovery as part of evidence collection when the checked-out default branch is empty; inspect candidate remote branches before declaring native code unavailable.
+- **Keep**: native bridge contracts need typed handler payloads, scoped callback ids, terminal callback states, storage sync failure handling, permission denial, orientation cleanup, network/load retry, and production debug gating.
+- **Keep**: native media/update flows need platform-specific state coverage: permission denied/cancel/unavailable/upload failure/success callback for camera, and store handoff versus APK download/install-permission paths for updates.
+- **Keep**: mobile feature flows need device-behavior tests for inputs, bottom sheets, list refresh/pagination, chart/card overflow, media retry/zoom, custom keypads, persisted control placement, and portrait/landscape variants.
+- **Keep**: mobile precision workspaces need source-of-truth state for task context, selected item or batch, cached tasks/media, geometry/scale, timer/quality gates, shell orientation, unlock/exit, and final submission. Media reliability, gesture conflict handling, and orientation cleanup are implementation requirements, not polish.
+- **Keep**: app-hosted mobile products need lifecycle and dense-data tests for state restore expiry, sensitive-field handling, route/context mismatch, orientation failure, landscape table geometry, active selector auto-scroll, overflow-only motion, temporary settings validation, and cleanup on exit.
+- **Keep**: AI media extraction and account-risk flows need staged state machines and tests for capture/crop/upload/analyze/render/classify/save, retake/retry, disabled-save reasons, disclosure loading, acknowledgement gates, second confirmation, session cleanup, and post-action navigation.
+- **Keep**: native-assisted media extraction needs parity checks between preview and final upload, runtime upload-config fallback, redacted observability, and host/web bridge cleanup; do not treat a returned native callback as sufficient if the H5 destination page has not mounted and acknowledged readiness.
+- **Keep**: app startup/account flows need native plus web verification for splash, privacy consent, login, registration/binding, first-login password setup, verification restore, logout/delete cache cleanup, and deterministic return to login or onboarding.
+- **Keep**: platform capabilities need permission, denial, retry, and fallback UI states.
+- **Keep** (external-skill benchmark): a debug-instrumentation teardown skill (external reference, sanitized) showed that a manual removal flow is a convenience path, not the safety mechanism — debug-only instrumentation must be structurally excluded from every real-user build at the dependency/target level (per variant, scoped by channel + data sensitivity) and the exclusion verified on the exact signed artifact (dependency/manifest/plist/entitlement/OTA checks, with a symbol/string grep only as a backstop) via a release-blocking evidence row. Landed in `mobile-quality-release.md` Release Readiness and the SKILL Non-Negotiable Rules; this extends the existing "production debug gating" rules from runtime-flag framing to structural exclusion + signed-artifact verification.
+- **Keep** (external-skill benchmark + sibling-sync): an external iOS codegen-resync skill (sanitized) confirmed mobile codegen needs a regeneration discipline that the backend stacks own in parallel (per-stack attribution at the end of this row): never hand-edit generated files, edit source-of-truth then regenerate, never blind-overwrite hand-maintained/user-edited files (gate on the pre-overwrite preimage), and after a generator/toolchain upgrade force a fresh no-cache regen and review the diff vs expected drift — clean/no-op is valid when semantically neutral; confirm the runtime reflects a new schema when a shape change is expected OR appears in the diff (input-only cache keys serve stale output across a generator bump). Closed the sibling-coverage gap in SKILL.md Step 5. Backend stacks unchanged (not extended this round): `go-microservice-dev` already owns the fuller parallel discipline (guarded-backup overwrite, fresh-regen shape-change smoke, regenerate-and-verify); `python-service-dev` owns the core (never hand-edit generated, source-then-regenerate, verify clean/reviewed) but not the guarded-backup/no-cache-smoke specifics — narrowed to what each actually owns rather than claiming full parity.
+- **Merge**: React implementation details route to `web-react-dev`; visual density and interaction acceptance route to `product-ui-ux-design`.
+- **Merge**: Flutter feature implementation, native Android/iOS boundaries, mobile rendered verification, app build/release checks stay here.
+- **Route**: React H5/browser implementation to `web-react-dev`; design acceptance to `product-ui-ux-design`; test-layer planning to `testing-strategy`.
+- **Discard**: third-party native test-app folders, source-domain nouns, visual style from low-quality UI, debug logs/tooling in production, and provider-specific storage or bridge names.
+
+Coverage label: broad manifest inventory plus representative file-level refresh, not node-by-node mobile source inventory.
+
+## Where The Specific Provenance Lives
+
+Specific subproject paths, real branch names, manifest signatures, and dated cross-check logs live in the maintainer's private archive. They are not included in this file, so any cross-organization use of this skill stays clean.