novaforge-appkit 0.1.0

package/kit/profiles/flutter.md

@@ -0,0 +1,45 @@
+# Profile: Flutter (default)
+
+The default cross-platform implementation profile. Optimized for small, local-first apps.
+
+## Defaults
+- **Framework**: Flutter (stable channel), Dart 3.
+- **State management**: start with `setState` / `ValueNotifier`. Introduce `provider` or
+  `riverpod` only when shared state across screens makes it worthwhile. No BLoC for small apps.
+- **Local storage**: `shared_preferences` for small key/value; `sqflite` or `drift` only when
+  there is a real relational/list dataset. Hide it behind a repository interface.
+- **Navigation**: `Navigator 2` via `go_router` if there are 3+ routes, otherwise plain
+  `Navigator`. Portrait-only unless content needs landscape.
+- **Ads**: `google_mobile_ads`, isolated behind an `AdService`/adapter. Test ad unit ids in
+  debug, real ids only via `--dart-define` in release.
+- **Config**: environment via `--dart-define` (`APP_ENV=dev|prod`); never hardcode prod ids.
+- **DI**: constructor injection. Avoid `get_it` unless the graph is genuinely large.
+
+## Minimum OS targets
+- **Android**: `minSdk 24` (Android 7.0), `targetSdk 35` / `compileSdk 35` (required by Google
+  Play for new apps since Aug 31 2025).
+- **iOS**: deployment target `iOS 15.0`.
+
+## Suggested structure
+```
+lib/
+├── app/         app.dart, routes.dart, theme.dart
+├── core/        config/, ads/, storage/, utilities/
+├── features/    home/, settings/, <core_feature>/
+└── main.dart
+test/            unit/, widgets/, helpers/
+integration_test/  critical_flow_test.dart, screenshot_flow_test.dart
+```
+
+## Quality commands
+- Format: `dart format .`
+- Analyze: `flutter analyze`
+- Test: `flutter test --coverage`
+- Build Android: `flutter build appbundle --release`
+- Build iOS: `flutter build ipa --release` (or `flutter build ios --release --no-codesign` on CI)
+- Integration: `flutter test integration_test/`
+
+## Testability rules
+- Keep business logic out of widgets so it is unit-testable.
+- Provide deterministic seed data for screenshot/integration runs (fixed clock, fixed ids).
+- Every screen state listed in `app-spec.md` must be reachable by a widget or integration test.

package/kit/profiles/ios.md

@@ -0,0 +1,32 @@
+# Profile: iOS targeting
+
+Applies on top of the Flutter profile for the iOS build.
+
+## Build configuration
+- Deployment target: iOS 15.0.
+- Bundle identifier: reverse-DNS, must match App Store Connect (e.g. `com.example.timer`).
+- `CFBundleShortVersionString` (marketing version) and `CFBundleVersion` (build, increasing).
+- Build with the current Xcode / latest iOS SDK (Apple requires builds against a recent SDK).
+
+## Privacy (Info.plist)
+- Every accessed resource needs a clear `*UsageDescription` string explaining why
+  (`NSCameraUsageDescription`, `NSLocationWhenInUseUsageDescription`, etc.). Missing or vague
+  strings are a top rejection cause (Guideline 5.1.1).
+- **Privacy manifest** (`PrivacyInfo.xcprivacy`): declare collected data types, tracking, and
+  reasons for required-reason APIs. Third-party SDKs (incl. Google Mobile Ads) must ship their
+  own privacy manifests and signatures — keep them updated.
+- **App Tracking Transparency**: if any SDK tracks across apps/sites, add
+  `NSUserTrackingUsageDescription` and request authorization before tracking.
+
+## Signing & release
+- Requires an Apple Developer Program account ($99/yr) — human owns this.
+- Certificates + provisioning profiles via Xcode automatic signing or App Store Connect API.
+- Output: `.ipa` via `flutter build ipa --release`, then upload via Xcode/Transporter.
+- Use **TestFlight** for review-equivalent testing before App Store submission.
+
+## Store essentials
+- App Privacy "nutrition label" (must match the privacy manifest and real behavior),
+  age rating, App Store screenshots per required device sizes, support URL, reviewer notes,
+  export-compliance answer (usually "no" for standard HTTPS / no custom crypto).
+- AdMob: set `GADApplicationIdentifier` in `Info.plist` (real id only in release) and add
+  `SKAdNetworkItems` provided by AdMob for attribution.

package/kit/scripts/_common.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Shared helpers for AppKit scripts. Source this from each script.
+set -uo pipefail
+
+APPKIT_DIR="${APPKIT_DIR:-.appkit}"
+PROJECT_ROOT="${PROJECT_ROOT:-$(pwd)}"
+
+c_red()  { printf '\033[31m%s\033[0m\n' "$*"; }
+c_grn()  { printf '\033[32m%s\033[0m\n' "$*"; }
+c_ylw()  { printf '\033[33m%s\033[0m\n' "$*"; }
+info()   { printf '• %s\n' "$*"; }
+ok()     { c_grn "✓ $*"; }
+warn()   { c_ylw "! $*"; }
+fail()   { c_red "✗ $*"; }
+
+have()   { command -v "$1" >/dev/null 2>&1; }
+
+# Skip cleanly (exit 0) when a required tool is missing, recording a gap rather than failing.
+need() {
+  if ! have "$1"; then
+    warn "SKIP: '$1' not found — recording an explicit verification gap (not a pass)."
+    exit 0
+  fi
+}

package/kit/scripts/analyze.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Static analysis.
+source "$(dirname "$0")/_common.sh"
+need flutter
+info "Running flutter analyze…"
+if flutter analyze; then ok "Analysis passed"; else fail "Analysis found issues"; exit 1; fi

package/kit/scripts/build-android.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Build the Android release App Bundle. Production ad ids/env passed via --dart-define.
+source "$(dirname "$0")/_common.sh"
+need flutter
+OUT="$APPKIT_DIR/release/builds/android"; mkdir -p "$OUT"
+info "Building release .aab (APP_ENV=prod)…"
+if flutter build appbundle --release --dart-define=APP_ENV=prod; then
+  AAB=$(ls -t build/app/outputs/bundle/release/*.aab 2>/dev/null | head -1)
+  if [ -n "${AAB:-}" ]; then cp "$AAB" "$OUT/" && ok "AAB -> $OUT/$(basename "$AAB")"; else warn "Build ok but .aab not found in default path"; fi
+else
+  fail "Android release build failed"; exit 1
+fi

package/kit/scripts/build-ios.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Build the iOS release. Requires macOS + Xcode. Without signing, build the app for archive prep.
+source "$(dirname "$0")/_common.sh"
+need flutter
+OUT="$APPKIT_DIR/release/builds/ios"; mkdir -p "$OUT"
+if [ "$(uname)" != "Darwin" ]; then
+  warn "iOS builds require macOS + Xcode. Writing archive instructions instead."
+  cat > "$OUT/ARCHIVE_INSTRUCTIONS.md" <<'EOF'
+# iOS Archive (run on macOS with Xcode)
+1. flutter build ipa --release --dart-define=APP_ENV=prod
+2. Or: open ios/Runner.xcworkspace, set Team & signing, Product > Archive.
+3. Validate the archive, then upload via Xcode Organizer / Transporter / App Store Connect API.
+EOF
+  ok "Wrote $OUT/ARCHIVE_INSTRUCTIONS.md"; exit 0
+fi
+info "Building iOS release archive (.ipa)…"
+if flutter build ipa --release --dart-define=APP_ENV=prod; then
+  IPA=$(ls -t build/ios/ipa/*.ipa 2>/dev/null | head -1)
+  [ -n "${IPA:-}" ] && cp "$IPA" "$OUT/" && ok "IPA -> $OUT/$(basename "$IPA")" || warn "Build ok; archive at build/ios/archive"
+else
+  warn "Signed IPA build failed (likely signing). Try: flutter build ios --release --no-codesign"
+  exit 1
+fi

package/kit/scripts/capture-screenshots.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Capture screenshot catalog via the integration_test driver into .appkit/screenshots/qa/.
+# Requires a running emulator/simulator or device.
+source "$(dirname "$0")/_common.sh"
+need flutter
+QA="$APPKIT_DIR/screenshots/qa"; mkdir -p "$QA"
+DRIVER="integration_test/screenshot_flow_test.dart"
+if [ ! -f "$DRIVER" ]; then
+  warn "No $DRIVER yet. Add a screenshot integration test that calls binding.takeScreenshot(id)."
+  exit 0
+fi
+if ! flutter devices 2>/dev/null | grep -qiE 'emulator|simulator|device'; then
+  warn "No device/emulator detected — recording a screenshot gap (not a pass)."; exit 0
+fi
+info "Capturing screenshots (APP_ENV=dev, seeded data)…"
+if flutter test "$DRIVER" --dart-define=APP_ENV=dev --dart-define=APPKIT_SCREENSHOTS=1; then
+  ok "Screenshots captured to $QA (test must write PNGs there)"
+else
+  fail "Screenshot run failed"; exit 1
+fi

package/kit/scripts/compare-goldens.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Compare captured QA screenshots against approved baselines (pixel-diff).
+# Establish baselines by copying qa/ -> baselines/ once approved.
+source "$(dirname "$0")/_common.sh"
+QA="$APPKIT_DIR/screenshots/qa"; BASE="$APPKIT_DIR/screenshots/baselines"
+mkdir -p "$BASE"
+[ -d "$QA" ] || { warn "No QA screenshots yet."; exit 0; }
+diffs=0; missing=0
+for img in "$QA"/*.png; do
+  [ -e "$img" ] || { warn "No QA PNGs found."; exit 0; }
+  name=$(basename "$img"); b="$BASE/$name"
+  if [ ! -f "$b" ]; then warn "No baseline for $name (new state)"; missing=$((missing+1)); continue; fi
+  if have compare; then
+    d=$(compare -metric AE "$img" "$b" null: 2>&1 || true)
+    if [ "${d%% *}" != "0" ]; then fail "$name differs (AE=$d)"; diffs=$((diffs+1)); else ok "$name matches"; fi
+  else
+    if cmp -s "$img" "$b"; then ok "$name matches (byte)"; else fail "$name differs (byte)"; diffs=$((diffs+1)); fi
+  fi
+done
+info "Golden compare: $diffs diffs, $missing without baseline."
+[ "$diffs" -eq 0 ] || exit 1

package/kit/scripts/extract-dependencies.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# List direct dependencies and flag known SDK categories for the privacy/SDK review.
+source "$(dirname "$0")/_common.sh"
+[ -f pubspec.yaml ] || { warn "No pubspec.yaml found."; exit 0; }
+echo "== Direct dependencies (pubspec.yaml) =="
+awk '/^dependencies:/{f=1;next} /^dev_dependencies:|^[a-z]/{if(f && $0 !~ /^[[:space:]]/) f=0} f && /^[[:space:]]+[a-z]/{print "  "$1}' pubspec.yaml | sed 's/://'
+echo
+echo "== Category flags =="
+flag() { grep -qiE "(^|[^a-z])$1" pubspec.yaml && echo "  [$2] $1"; }
+flag google_mobile_ads ADS
+flag firebase_analytics ANALYTICS
+flag firebase_crashlytics CRASH
+flag sentry CRASH
+flag google_sign_in AUTH
+flag firebase_auth AUTH
+flag http NETWORK
+flag dio NETWORK
+flag shared_preferences STORAGE
+flag sqflite STORAGE
+flag drift STORAGE
+echo
+info "Cross-check this inventory against the privacy declarations (mobile-privacy-and-permissions)."
+[ -n "$(command -v flutter)" ] && info "For the full tree run: flutter pub deps --style=compact"

package/kit/scripts/extract-permissions.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Extract declared permissions from Android manifests and iOS Info.plist usage strings.
+source "$(dirname "$0")/_common.sh"
+echo "== Android permissions =="
+found=0
+while IFS= read -r -d '' m; do
+  echo "-- $m"
+  grep -oE 'android:name="[^"]+"' "$m" | grep -i permission | sed 's/android:name=//; s/"//g' | sort -u
+  found=1
+done < <(find android -name AndroidManifest.xml -print0 2>/dev/null)
+[ "$found" = 1 ] || warn "No AndroidManifest.xml found."
+echo
+echo "== iOS usage-description keys (Info.plist) =="
+PLIST="ios/Runner/Info.plist"
+if [ -f "$PLIST" ]; then
+  grep -oE 'NS[A-Za-z]+UsageDescription' "$PLIST" | sort -u || warn "No usage-description keys."
+else
+  warn "No ios/Runner/Info.plist found."
+fi
+echo
+info "Map each permission to feature → user benefit → runtime text → store declaration in app-spec.md."
+info "Unjustified or high-risk permissions are release blockers (see policy-rules/privacy.md)."

package/kit/scripts/format.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# Format Dart/Flutter sources. CI mode (--check) fails if formatting is needed.
+source "$(dirname "$0")/_common.sh"
+need dart
+if [ "${1:-}" = "--check" ]; then
+  info "Checking formatting (dart format --set-exit-if-changed)…"
+  dart format --output=none --set-exit-if-changed . && ok "Formatting clean" || { fail "Needs formatting"; exit 1; }
+else
+  info "Formatting (dart format .)…"
+  dart format . && ok "Formatted"
+fi

package/kit/scripts/scan-secrets.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Heuristic secret scan over source + config. Flags likely keys; not a substitute for a vault.
+source "$(dirname "$0")/_common.sh"
+PATTERNS='(AIza[0-9A-Za-z_-]{30,}|-----BEGIN [A-Z ]*PRIVATE KEY-----|sk_live_[0-9A-Za-z]+|ghp_[0-9A-Za-z]{30,}|aws_secret_access_key|password\s*=\s*["'\''][^"'\'' ]{6,})'
+SCAN_DIRS="lib android/app ios/Runner"
+hits=0
+for d in $SCAN_DIRS; do
+  [ -e "$d" ] || continue
+  while IFS= read -r line; do echo "$line"; hits=$((hits+1)); done < <(grep -rInE "$PATTERNS" "$d" \
+    --include='*.dart' --include='*.gradle' --include='*.kts' --include='*.plist' \
+    --include='*.properties' --include='*.xml' --include='*.json' 2>/dev/null)
+done
+# Keystores / key.properties must never be committed.
+find android -name '*.jks' -o -name '*.keystore' 2>/dev/null | while read -r k; do fail "Keystore in tree: $k"; hits=1; done
+if [ "$hits" -eq 0 ]; then ok "No obvious secrets found"; else fail "$hits potential secret(s) — review above"; exit 1; fi

package/kit/scripts/test.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Run tests with coverage. Pass a path to scope (e.g. test/unit) for targeted runs.
+source "$(dirname "$0")/_common.sh"
+need flutter
+TARGET="${1:-}"
+info "Running flutter test ${TARGET:-(all)} --coverage…"
+if flutter test --coverage $TARGET; then
+  ok "Tests passed"
+  [ -f coverage/lcov.info ] && info "Coverage: coverage/lcov.info"
+else
+  fail "Tests failed"; exit 1
+fi

package/kit/scripts/validate-ad-ids.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Ensure test ad ids aren't shipped in release and prod ids aren't hardcoded in source.
+# Google sample/test ad unit ids contain 3940256099942544.
+source "$(dirname "$0")/_common.sh"
+TEST_ID="3940256099942544"
+issues=0
+# Test ids must not appear outside test/dev-guarded code in a way that ships to release.
+hits=$(grep -rInE "ca-app-pub-${TEST_ID}" lib 2>/dev/null || true)
+if [ -n "$hits" ]; then
+  warn "Test ad unit id referenced in lib/ — ensure it's only used when !AppConfig.isProduction:"
+  echo "$hits"
+fi
+# Real ad ids should come from env/config, not be hardcoded as production constants.
+prod=$(grep -rInE 'ca-app-pub-[0-9]{16}~[0-9]+|ca-app-pub-[0-9]{16}/[0-9]+' lib 2>/dev/null | grep -v "$TEST_ID" || true)
+if [ -n "$prod" ]; then
+  fail "Hardcoded production-looking ad id in lib/ — source from environment configuration:"
+  echo "$prod"; issues=$((issues+1))
+fi
+# AdMob App ID present in platform config?
+grep -rq "com.google.android.gms.ads.APPLICATION_ID" android 2>/dev/null && ok "Android AdMob App ID meta-data present" || warn "Android AdMob App ID meta-data not found (ok if no ads)"
+grep -rq "GADApplicationIdentifier" ios 2>/dev/null && ok "iOS GADApplicationIdentifier present" || warn "iOS GADApplicationIdentifier not found (ok if no ads)"
+[ "$issues" -eq 0 ] && ok "Ad id check passed" || { fail "Ad id issues found"; exit 1; }

package/kit/scripts/validate-release.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Static release-readiness checks: versions, ids, target API, env, debug leftovers.
+source "$(dirname "$0")/_common.sh"
+issues=0
+note_fail(){ fail "$1"; issues=$((issues+1)); }
+
+# Version present in pubspec
+if [ -f pubspec.yaml ]; then
+  v=$(grep -E '^version:' pubspec.yaml | awk '{print $2}')
+  [ -n "$v" ] && ok "pubspec version: $v" || note_fail "No version: in pubspec.yaml"
+else note_fail "No pubspec.yaml"; fi
+
+# Android target/compile SDK 35
+GR="android/app/build.gradle"; GRK="android/app/build.gradle.kts"
+gf=""; [ -f "$GR" ] && gf="$GR"; [ -f "$GRK" ] && gf="$GRK"
+if [ -n "$gf" ]; then
+  ts=$(grep -oE 'targetSdk(Version)?[ =]+[0-9]+' "$gf" | grep -oE '[0-9]+' | head -1)
+  if [ -n "$ts" ] && [ "$ts" -ge 35 ]; then ok "Android targetSdk=$ts (>=35)"; else note_fail "Android targetSdk=$ts (<35; Play requires 35)"; fi
+else warn "No android build.gradle found."; fi
+
+# Debug / placeholder leftovers in lib
+if grep -rInE '\b(TODO|FIXME|Lorem ipsum|placeholder)\b' lib >/dev/null 2>&1; then warn "Placeholder/TODO text in lib/ — review before release."; fi
+if grep -rInE '\bprint\(' lib >/dev/null 2>&1; then warn "print() calls in lib/ — prefer no debug logging in release."; fi
+
+# Run the ad-id and secret checks
+bash "$(dirname "$0")/validate-ad-ids.sh" || issues=$((issues+1))
+bash "$(dirname "$0")/scan-secrets.sh" || issues=$((issues+1))
+
+echo
+if [ "$issues" -eq 0 ]; then ok "Static release validation passed (still run a real release smoke test on device)."; else fail "$issues release issue(s) — see above."; exit 1; fi

package/kit/skills/admob-best-practices/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: admob-best-practices
+description: Plan and integrate safe, policy-compliant AdMob monetization. Use during Shape, Build and Verify for ad-format selection, banner/interstitial/rewarded/app-open placement rules, frequency and natural-transition rules, accidental-click prevention, test vs production ad ids, consent (UMP/GDPR), child-directed settings, failure/offline behavior and the AdMob release checklist.
+---
+
+# AdMob Best Practices
+
+Monetize without harming usability or violating policy. Ads are part of UX, decided in Shape.
+
+## Format selection (default preference order)
+1. **Anchored adaptive banner** — safe default, low risk, persistent.
+2. **Rewarded** — only user-initiated, with a clear value exchange.
+3. **Interstitial** — only at natural transitions (level end, save, screen completion).
+4. **App-open** — only on cold start / return to foreground, infrequently.
+5. **Native** — only when the app naturally has a feed; needs careful labeling.
+
+Avoid advanced formats unless the app naturally supports them. Many small utilities should
+ship **banner-only** or no ads.
+
+## Placement spec (every placement, in app-spec.md)
+```yaml
+placement_id: home_bottom_banner
+format: anchored_adaptive_banner
+screen: HOME
+trigger: screen_visible
+frequency: sdk_managed
+critical_interaction_conflict: false
+accidental_click_risk: low
+loading_behavior: preserve_layout
+failure_behavior: collapse_or_preserve_clean_space
+development_ad_id: test
+production_ad_id_source: environment_configuration
+```
+
+## Hard policy rules (AdMob / Google Play / Apple)
+- **Never** place ads where they obstruct content or sit next to interactive controls
+  (accidental clicks = policy violation and account risk).
+- **No** ads that simulate app UI, "X" buttons that lead to clicks, or unexpected fullscreen
+  ads. Interstitials must not appear on app launch or mid-action.
+- **Rewarded** ads must be explicitly user-initiated and clearly described before play.
+- **App-open** ads must not be shown aggressively or block the user repeatedly.
+- Do not click your own ads or encourage clicks. Do not place ads on screens with no content.
+- Maintain reasonable ad density; one banner per screen is plenty for small apps.
+
+## Test vs production ids
+- Use Google's **sample/test ad unit ids** (and register test devices) during development.
+- Real ad unit ids only in release via environment config. Hardcoded production ids in debug
+  builds or test ids in release are **critical** issues.
+- The AdMob **App ID** goes in `AndroidManifest.xml` and `Info.plist`; use the real id only in
+  release.
+
+## Consent & privacy
+- Implement Google **UMP / User Messaging Platform** for GDPR/EEA + UK consent and the CCPA
+  signal where required. Gate personalized ads on consent; fall back to non-personalized ads.
+- Reflect the advertising id / tracking in Data Safety, App Privacy, and the privacy manifest
+  (see `mobile-privacy-and-permissions`).
+- iOS: personalized ads that track require ATT authorization. Non-personalized ads avoid this.
+
+## Child-directed
+If the app targets children, set `tagForChildDirectedTreatment` / `tagForUnderAgeOfConsent`,
+serve only family-safe, non-personalized ads (or no ads), and confirm with the human first.
+
+## Failure & offline behavior
+- Ad load failure must degrade cleanly: collapse the slot or keep clean reserved space; never
+  block content or show error UI. The app must be fully usable offline with no ads.
+
+## Verify checklist
+- [ ] Test ids in dev, real ids only in release (scripted check).
+- [ ] App ID set per platform, env-gated.
+- [ ] Each placement matches `app-spec.md`; no obstruction / no risky adjacency.
+- [ ] Interstitials only at natural transitions; rewarded user-initiated; app-open not aggressive.
+- [ ] Failure & offline paths preserve usability.
+- [ ] Consent (UMP) wired; child-directed settings correct where relevant.
+- [ ] No hardcoded secrets.

package/kit/skills/mobile-app-development/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: mobile-app-development
+description: Implement small local-first Flutter mobile apps. Use during the Build and Fix phases for project setup, feature-oriented structure, state management, navigation, local storage, environment config, the AdMob adapter, dependency hygiene, release configuration and writing testable code.
+---
+
+# Mobile App Development
+
+Implementation guidance for the default Flutter profile. Keep architecture **proportional**
+to a small app — the goal is a shippable MVP, not a framework.
+
+## Project setup
+- `flutter create --org com.example --platforms=android,ios <name>`.
+- Set application id / bundle id immediately and consistently (they are hard to change later).
+- Pin the Flutter/Dart SDK constraint in `pubspec.yaml`. Commit `pubspec.lock`.
+- Configure `analysis_options.yaml` with `flutter_lints`.
+
+## Structure (feature-oriented)
+```
+lib/
+├── app/      app.dart (MaterialApp), routes.dart, theme.dart
+├── core/     config/ (env), ads/ (AdService), storage/ (repository), utilities/
+├── features/ <feature>/  -> screen widgets + a controller/notifier + models
+└── main.dart
+```
+- Separate **UI / state / storage**. Widgets render; controllers hold logic; repositories
+  persist. This keeps logic unit-testable and storage swappable.
+
+## State management
+- Default to `setState`/`ValueNotifier`/`ChangeNotifier`. Reach for `provider`/`riverpod`
+  only when state is shared across screens. No global mutable state unless justified.
+
+## Local storage
+- Hide persistence behind a `Repository` interface; provide an in-memory fake for tests.
+- `shared_preferences` for small key/value; `drift`/`sqflite` for lists/relations.
+- Support a trivial **migration** hook (a stored schema version) even in v1.
+
+## Navigation & UX
+- Portrait by default. Use `go_router` at 3+ routes.
+- Handle empty / loading / error states for every screen — they are spec'd and screenshotted.
+- Keyboard-aware: wrap forms in scroll views and respect `MediaQuery.viewInsets` so primary
+  actions never hide behind the keyboard.
+
+## Environment configuration
+- `APP_ENV` via `--dart-define`. A `core/config/AppConfig` exposes `isProduction`, ad ids, etc.
+- **Never** hardcode production ad ids or endpoints. Production values come from
+  `--dart-define` at release-build time only.
+
+## AdMob adapter
+- One `AdService` wraps `google_mobile_ads`. The rest of the app talks only to `AdService`.
+- It returns **test** ad unit ids unless `AppConfig.isProduction`. Loading failures must
+  return cleanly so the UI degrades gracefully (collapse/preserve space, never block content).
+- See `admob-best-practices` for placement rules.
+
+## Dependencies
+- Each new dependency must earn its place. Prefer the platform/std lib. Audit every package's
+  permissions, SDKs, and privacy impact before adding it (see `mobile-privacy-and-permissions`).
+
+## Release configuration hygiene
+- No debug menus, `print`/log spam, placeholder text, or test ad ids in release builds.
+- Correct application id, version, and `APP_ENV=prod`. Enable code shrinking on Android.
+
+## Change control
+Do not silently change product objective, target user, monetization, data collection,
+permissions, backend usage, store target, or acceptance criteria. If implementation forces a
+change, update `app-spec.md` and note the reason (constitution §9).
+
+## Testability
+Write tests alongside code (see `mobile-testing-and-visual-qa`). If something is hard to test,
+it is usually badly factored — move logic out of the widget.

package/kit/skills/mobile-privacy-and-permissions/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: mobile-privacy-and-permissions
+description: Ensure minimal data handling and accurate privacy declarations for mobile apps. Use across all phases for data and SDK inventory, personal/sensitive data classification, data minimization, permission justification and runtime messaging, privacy-policy drafting, and Google Data Safety + Apple App Privacy + iOS privacy manifest mapping from real implementation evidence.
+---
+
+# Mobile Privacy & Permissions
+
+Privacy is a release gate. Declarations must match what the code actually does.
+
+## Data inventory (build from evidence, not intent)
+For each piece of data the app touches, record:
+`name · type · source · stored where (local/remote) · transmitted? · purpose · retention ·
+deletion · linked to user identity? · used for tracking?`
+
+Local-first apps should be able to answer: "all data stays on device, nothing transmitted".
+If a third-party SDK breaks that, it must appear in the inventory.
+
+## SDK inventory
+List direct + relevant transitive dependencies and classify each: advertising, analytics,
+crash-reporting, auth, storage, network. For each, note what data it collects and whether it
+ships a privacy manifest (iOS). The classic small-app footprint is just **Google Mobile Ads**.
+
+## Data classification
+- **Personal**: name, email, precise location, device identifiers (incl. advertising id),
+  contacts, photos.
+- **Sensitive**: health, finance, sexual orientation, religion, precise location, children's
+  data, biometrics. Any sensitive data triggers human confirmation (constitution §8).
+
+## Minimization
+Collect nothing you do not use. Prefer on-device processing. No analytics unless justified and
+declared. No advertising id if ads can run non-personalized.
+
+## Permissions — justification map
+Each requested permission must map to: requirement → feature → user benefit → runtime
+explanation → store declaration. **An unjustified permission is a release blocker.**
+
+High-risk permissions (block unless human-confirmed): fine/background location, contacts, SMS,
+call log, accessibility service, VPN, device admin, all-files/external-storage,
+`QUERY_ALL_PACKAGES`, `REQUEST_INSTALL_PACKAGES`, camera/mic when not core.
+
+### Runtime messaging
+- Android: request at point of use with rationale; respect denial.
+- iOS: every accessed resource needs a clear `*UsageDescription` in `Info.plist`. Vague strings
+  are a top rejection cause (Guideline 5.1.1).
+
+## Google Play Data Safety mapping
+Fill the Data Safety form from the data inventory: data types collected/shared, whether linked
+to identity, whether used for tracking, encryption in transit, deletion request mechanism.
+Must match the in-app behavior and the privacy policy. Note the **advertising id** handling
+and declare the `AD_ID` permission consistently.
+
+## Apple App Privacy + privacy manifest mapping
+- App Privacy "nutrition label" in App Store Connect: data types, linkage, tracking — must
+  match real behavior and the privacy manifest.
+- `PrivacyInfo.xcprivacy`: declare collected data types, tracking flag, and **required-reason
+  API** usage. Bundled SDKs (incl. Google Mobile Ads) must provide their own manifests +
+  signatures; keep them current or the build is rejected.
+- **App Tracking Transparency**: if any SDK tracks across apps/sites, request authorization via
+  ATT and add `NSUserTrackingUsageDescription`. If you only show non-personalized ads, you can
+  avoid tracking and say so consistently.
+
+## Privacy policy
+Even a local-only app usually needs a hosted privacy policy URL (both stores require one when
+ads/SDKs are present). Draft from the data + SDK inventory. Use the template in
+`templates/privacy-policy.template.md`. Mark every placeholder (`<HOSTED_URL>`) clearly; never
+invent legal commitments — flag them for human review.
+
+## Children
+If the audience includes children: Google Play Families policy and Apple Kids Category apply,
+ads must use child-directed/`tagForChildDirectedTreatment` settings, no behavioral tracking,
+and COPPA/GDPR-K obligations attach. Always escalate to the human first.

package/kit/skills/mobile-store-release/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: mobile-store-release
+description: Guide store review, signing, metadata, screenshots, declarations, release preparation and rejection handling for Google Play and the Apple App Store. Use during Verify and Release for policy review, Android/iOS signing, versioning, store metadata, content rating, reviewer notes, test tracks/TestFlight, release checklists and store-rejection classification.
+---
+
+# Mobile Store Release
+
+Prepare complete, policy-aware release packages. The kit prepares; the human submits.
+
+## Google Play review (inspect)
+- **Functionality / minimum-functionality**: app must do something useful and complete — no
+  placeholder/"coming soon", no webview-only wrappers.
+- **Target API**: new apps & updates must target **API 35 (Android 15)** since Aug 31 2025.
+- **Permissions**: every permission justified; sensitive permissions need declarations.
+- **Data Safety** form consistent with real behavior + privacy policy; declare advertising id.
+- **Ads** declaration set; ad behavior compliant (see `admob-best-practices`).
+- **Content rating** via IARC questionnaire; **target audience & content** (Families if kids).
+- **Privacy policy URL** required (always when ads/SDKs present).
+- **Account/app access** info if there is a login or gated content.
+- **App signing**: enroll in Play App Signing; upload `.aab`.
+- **Testing track**: new personal developer accounts must run closed testing before production.
+- Correct, immutable **package name**; correct version code/name.
+
+## Apple App Store review (inspect)
+- **Guideline 2.1 App Completeness** (top rejection ~40%): no crashes, no bugs, no placeholder
+  content, all features functional, demo/login provided if needed.
+- **Guideline 5.1.1 Privacy**: clear permission purpose strings; App Privacy label matches
+  behavior; privacy manifest present; ATT if tracking.
+- **Stability**: must not crash on the reviewer's device / current iOS.
+- **Business model** clear; ads behave; no hidden/undocumented features.
+- **Metadata** accurate (no misleading screenshots/claims); **reviewer notes** explain
+  non-obvious behavior; demo account if applicable.
+- **Export compliance** answer (usually "no" for standard HTTPS).
+- Correct **bundle id**; signing & provisioning ready; build against current SDK.
+- Use **TestFlight** before submission.
+
+## Signing (never expose secrets)
+**Android**: create an upload keystore (`keytool`), store it + passwords outside the repo
+(secrets manager / CI secret); configure `signingConfigs` to read from env/`key.properties`
+(git-ignored); enroll in Play App Signing; verify with `apksigner`/`bundletool`.
+**iOS**: own bundle id in App Store Connect; team + certificates + provisioning profile (Xcode
+automatic or ASC API key); archive and validate before upload. The **human owns** signing
+identities and the developer accounts.
+
+## Versioning
+- Android: `versionName` (semver, e.g. `1.0.0`) + integer `versionCode` (always increasing).
+- iOS: `CFBundleShortVersionString` + increasing `CFBundleVersion`. Keep them in sync with
+  `pubspec.yaml` `version: 1.0.0+1`.
+
+## Store metadata
+App name · short/full description · subtitle (iOS) · keywords (iOS) · category · promotional
+text · release notes · privacy-policy/support/marketing URLs (placeholders OK, marked) ·
+reviewer notes. No misleading claims; do not show unavailable features.
+
+## Store screenshots
+Separate QA screenshots from marketing screenshots:
+`screenshots/qa/` · `screenshots/store-raw/` · `screenshots/store-final/`.
+Marketing shots reflect the real release build, use realistic safe sample data, match required
+platform dimensions, avoid debug data and misleading content.
+
+## Release checklist (per platform)
+- [ ] Verification READY (or approved with warnings), no critical/unresolved-major issues.
+- [ ] Correct app id / bundle id, version, `APP_ENV=prod`, real ad ids only here.
+- [ ] Signing configured, secrets out of repo.
+- [ ] Metadata, screenshots, privacy declarations, reviewer notes prepared.
+- [ ] Privacy policy + support URLs resolved.
+- [ ] Human approval recorded before submission.
+
+## Store-rejection classification (for `/appkit.fix rejection`)
+Map the rejection text to a category → requirement → code/metadata fix:
+minimum functionality · crash/bug · privacy/permission · metadata/screenshot · ads ·
+data-safety/privacy-label mismatch · account access · IP/content · signing/build config.
+Prefer the **minimal** change, add a regression test/check, update the affected declaration,
+then re-verify before resubmitting. Document the change for the resubmission notes.