@_nazmiforreal/flutter-ota 0.1.26 → 0.1.28

package/dart-src/packages/cli-tools/lib/src/commands/init.dart

@@ -314,24 +314,52 @@ class InitCommand extends FlutterPatcherCommand {
       warn('pubspec.yaml not found; skipping dependency injection.');
       return;
     }
-    var content = pubspec.readAsStringSync();
+    final content = pubspec.readAsStringSync();
     if (content.contains(RegExp(r'^\s*flutter_ota_kit\s*:', multiLine: true))) {
       step('pubspec.yaml already references flutter_ota_kit');
       return;
     }
-    const dep = '  flutter_ota_kit: ^0.1.4\n';
+    // Prefer `flutter pub add`, which resolves the LATEST published version and
+    // writes a proper caret constraint — so the CLI never hardcodes (and never
+    // goes stale on) a version number.
+    final exe = _flutterOrDart();
+    if (exe != null) {
+      final res = Process.runSync(exe, ['pub', 'add', 'flutter_ota_kit']);
+      if (res.exitCode == 0) {
+        step('Added `flutter_ota_kit` (latest) via `$exe pub add`');
+        return;
+      }
+      warn('`$exe pub add flutter_ota_kit` failed; falling back to a manual '
+          'edit. Run it yourself if the constraint looks wrong.');
+    }
+    // Fallback: append an unpinned dependency so `pub get` picks the latest
+    // compatible release. Still no hardcoded version.
     final marker = '\ndependencies:';
     final idx = content.indexOf(marker);
     if (idx == -1) {
-      warn(
-        'Could not find a `dependencies:` block; add `flutter_ota_kit` manually.',
-      );
+      warn('Could not find a `dependencies:` block; add `flutter_ota_kit` '
+          'manually (run `flutter pub add flutter_ota_kit`).');
       return;
     }
     final insertAt = idx + marker.length;
-    content = content.replaceRange(insertAt, insertAt, '\n$dep');
-    pubspec.writeAsStringSync(content);
-    step('Added `flutter_ota_kit` dependency to pubspec.yaml');
+    final updated =
+        content.replaceRange(insertAt, insertAt, '\n  flutter_ota_kit: any\n');
+    pubspec.writeAsStringSync(updated);
+    step('Added `flutter_ota_kit` dependency to pubspec.yaml '
+        '(run `flutter pub get` to resolve the latest version)');
+  }
+
+  /// Resolve the `flutter` executable (preferred) or `dart` for `pub add`.
+  String? _flutterOrDart() {
+    for (final exe in const ['flutter', 'dart']) {
+      try {
+        final r = Process.runSync(exe, ['--version']);
+        if (r.exitCode == 0) return exe;
+      } catch (_) {
+        // not on PATH; try next
+      }
+    }
+    return null;
   }
 
   void _addInternetPermission() {

package/dart-src/packages/cli-tools/lib/src/commands/pocketbase.dart

@@ -6,7 +6,7 @@ import 'dart:convert';
 import 'dart:io';
 
 import 'package:args/args.dart';
-import 'package:flutter_ota_kit_pocketbase/flutter_ota_kit_pocketbase.dart';
+import 'package:flutter_ota_kit/src/pkg/pocketbase/flutter_ota_kit_pocketbase.dart';
 import 'package:path/path.dart' as p;
 
 import '../cli_base.dart';

package/dart-src/packages/cli-tools/lib/src/commands/rollback.dart

@@ -1,5 +1,5 @@
 import 'package:flutter_ota_kit_cli/flutter_ota_kit_cli.dart';
-import 'package:flutter_ota_kit_core/flutter_ota_kit_core.dart';
+import 'package:flutter_ota_kit/src/pkg/core/flutter_ota_kit_core.dart';
 
 import '../ui/ui.dart';
 

package/dart-src/packages/cli-tools/lib/src/config.dart

@@ -1,13 +1,13 @@
 import 'dart:convert';
 import 'dart:io';
 
-import 'package:flutter_ota_kit_aws/flutter_ota_kit_aws.dart';
+import 'package:flutter_ota_kit/src/pkg/aws/flutter_ota_kit_aws.dart';
 import 'package:postgres/postgres.dart';
-import 'package:flutter_ota_kit_cloudflare/flutter_ota_kit_cloudflare.dart';
-import 'package:flutter_ota_kit_pocketbase/flutter_ota_kit_pocketbase.dart';
-import 'package:flutter_ota_kit_postgres/flutter_ota_kit_postgres.dart';
+import 'package:flutter_ota_kit/src/pkg/cloudflare/flutter_ota_kit_cloudflare.dart';
+import 'package:flutter_ota_kit/src/pkg/pocketbase/flutter_ota_kit_pocketbase.dart';
+import 'package:flutter_ota_kit/src/pkg/postgres/flutter_ota_kit_postgres.dart';
 
-import 'package:flutter_ota_kit_supabase/flutter_ota_kit_supabase.dart';
+import 'package:flutter_ota_kit/src/pkg/supabase/flutter_ota_kit_supabase.dart';
 import 'package:path/path.dart' as p;
 
 /// Resolved configuration for the flutter_ota_kit CLI.

package/dart-src/packages/cli-tools/lib/src/operations.dart

@@ -2,8 +2,8 @@ import 'dart:convert';
 import 'dart:io';
 
 import 'package:crypto/crypto.dart';
-import 'package:flutter_ota_kit_core/flutter_ota_kit_core.dart';
-import 'package:flutter_ota_kit_plugin_core/flutter_ota_kit_plugin_core.dart';
+import 'package:flutter_ota_kit/src/pkg/core/flutter_ota_kit_core.dart';
+import 'package:flutter_ota_kit/src/pkg/plugin_core/flutter_ota_kit_plugin_core.dart';
 
 import 'backend.dart';
 import 'sign.dart';

package/dart-src/packages/cli-tools/pubspec.yaml

@@ -8,6 +8,7 @@ publish_to: none
 
 environment:
   sdk: '>=3.13.2 <4.0.0'
+  flutter: '>=3.47.2'
 
 dependencies:
   args: '>=2.4.0 <3.0.0'
@@ -17,13 +18,11 @@ dependencies:
   collection: ^1.18.0
   cryptography: ^2.7.0
   postgres: ^3.4.0
-  flutter_ota_kit_core: ^0.1.6
-  flutter_ota_kit_plugin_core: ^0.0.8
-  flutter_ota_kit_supabase: ^0.1.8
-  flutter_ota_kit_postgres: ^0.1.7
-  flutter_ota_kit_cloudflare: ^0.1.7
-  flutter_ota_kit_aws: ^0.1.7
-  flutter_ota_kit_pocketbase: ^0.1.4
+  # All former sub-packages (core, plugin-core, backends) now live inside the
+  # merged `flutter_ota_kit` package under lib/src/pkg/. The CLI depends on the
+  # single package instead of eight. NOTE: `flutter_ota_kit` is a Flutter plugin,
+  # so building the CLI now requires the Flutter SDK (not just the Dart SDK).
+  flutter_ota_kit: ^0.2.1
   http: ^1.2.0
   shelf: ^1.4.0
 
@@ -31,17 +30,5 @@ dev_dependencies:
   test: ^1.25.0
 
 dependency_overrides:
-  flutter_ota_kit_core:
-    path: ../core
-  flutter_ota_kit_plugin_core:
-    path: ../../plugins/plugin-core
-  flutter_ota_kit_supabase:
-    path: ../../plugins/supabase
-  flutter_ota_kit_postgres:
-    path: ../../plugins/postgres
-  flutter_ota_kit_cloudflare:
-    path: ../../plugins/cloudflare
-  flutter_ota_kit_aws:
-    path: ../../plugins/aws
-  flutter_ota_kit_pocketbase:
-    path: ../../plugins/pocketbase
+  flutter_ota_kit:
+    path: ../../root

package/dart-src/packages/cli-tools/test/backends_test.dart

@@ -1,9 +1,9 @@
 import 'dart:io';
 
-import 'package:flutter_ota_kit_aws/flutter_ota_kit_aws.dart';
+import 'package:flutter_ota_kit/src/pkg/aws/flutter_ota_kit_aws.dart';
 import 'package:flutter_ota_kit_cli/flutter_ota_kit_cli.dart';
-import 'package:flutter_ota_kit_cloudflare/flutter_ota_kit_cloudflare.dart';
-import 'package:flutter_ota_kit_plugin_core/flutter_ota_kit_plugin_core.dart';
+import 'package:flutter_ota_kit/src/pkg/cloudflare/flutter_ota_kit_cloudflare.dart';
+import 'package:flutter_ota_kit/src/pkg/plugin_core/flutter_ota_kit_plugin_core.dart';
 import 'package:test/test.dart';
 
 import 'mocks/mock_aws_s3_client.dart' as aws;

package/dart-src/packages/cli-tools/test/cli_test.dart

@@ -2,7 +2,7 @@ import 'dart:io';
 import 'dart:typed_data';
 
 import 'package:flutter_ota_kit_cli/flutter_ota_kit_cli.dart';
-import 'package:flutter_ota_kit_supabase/src/supabase_client_adapter.dart';
+import 'package:flutter_ota_kit/src/pkg/supabase/src/supabase_client_adapter.dart';
 import 'package:path/path.dart' as p;
 import 'package:test/test.dart';
 

package/dart-src/packages/cli-tools/test/mocks/mock_aws_s3_client.dart

@@ -1,9 +1,9 @@
 import 'dart:convert' show utf8;
 
-import 'package:flutter_ota_kit_plugin_core/flutter_ota_kit_plugin_core.dart'
+import 'package:flutter_ota_kit/src/pkg/plugin_core/flutter_ota_kit_plugin_core.dart'
     show StorageObject;
 
-import 'package:flutter_ota_kit_aws/flutter_ota_kit_aws.dart'
+import 'package:flutter_ota_kit/src/pkg/aws/flutter_ota_kit_aws.dart'
     show AwsS3ClientLike, AwsS3StorageConfig;
 
 /// In-memory store backing [MockAwsS3Client].

package/dart-src/packages/cli-tools/test/mocks/mock_d1_client.dart

@@ -1,13 +1,13 @@
 import 'dart:convert' show jsonDecode;
 
-import 'package:flutter_ota_kit_cloudflare/flutter_ota_kit_cloudflare.dart'
+import 'package:flutter_ota_kit/src/pkg/cloudflare/flutter_ota_kit_cloudflare.dart'
     show
         CloudflareWorkerDatabaseConfig,
         D1ClientLike,
         D1DatabaseConfig,
         cloudflareWorkerDatabase,
         d1Database;
-import 'package:flutter_ota_kit_plugin_core/flutter_ota_kit_plugin_core.dart'
+import 'package:flutter_ota_kit/src/pkg/plugin_core/flutter_ota_kit_plugin_core.dart'
     show DatabasePlugin;
 
 /// In-memory store backing [MockD1Client], mirroring the D1 tables.

package/dart-src/packages/cli-tools/test/mocks/mock_pocketbase_client.dart

@@ -5,7 +5,7 @@
 /// `backends_test.dart`.
 library;
 
-import 'package:flutter_ota_kit_pocketbase/flutter_ota_kit_pocketbase.dart';
+import 'package:flutter_ota_kit/src/pkg/pocketbase/flutter_ota_kit_pocketbase.dart';
 import 'package:http/http.dart' as http;
 
 class MockPocketBaseClient implements PocketBaseClient {
@@ -18,6 +18,9 @@ class MockPocketBaseClient implements PocketBaseClient {
   String? _email;
   String? _password;
 
+  @override
+  String get authToken => (_email != null && _password != null) ? 'mock-token' : '';
+
   @override
   void adminCredentials(String email, String password) {
     _email = email;

package/dart-src/packages/cli-tools/test/mocks/mock_postgres_client.dart

@@ -1,8 +1,8 @@
 import 'dart:typed_data';
 
-import 'package:flutter_ota_kit_plugin_core/flutter_ota_kit_plugin_core.dart';
+import 'package:flutter_ota_kit/src/pkg/plugin_core/flutter_ota_kit_plugin_core.dart';
 
-import 'package:flutter_ota_kit_postgres/flutter_ota_kit_postgres.dart';
+import 'package:flutter_ota_kit/src/pkg/postgres/flutter_ota_kit_postgres.dart';
 
 /// In-memory store backing [MockPostgresClient]. Mirrors the `bundles` and
 /// `bundle_patches` tables (snake_case row maps).

package/dart-src/packages/cli-tools/test/pocketbase_smoke_test.dart

@@ -1,4 +1,4 @@
-import 'package:flutter_ota_kit_pocketbase/flutter_ota_kit_pocketbase.dart';
+import 'package:flutter_ota_kit/src/pkg/pocketbase/flutter_ota_kit_pocketbase.dart';
 import 'package:test/test.dart';
 
 import 'mocks/mock_pocketbase_client.dart' as pb;

package/dart-src/root/README.md

@@ -0,0 +1,334 @@
+# flutter_ota_kit
+
+[![pub package](https://img.shields.io/pub/v/flutter_ota_kit.svg)](https://pub.dev/packages/flutter_ota_kit)
+[![Platform](https://img.shields.io/badge/platform-Android-brightgreen)](https://flutter.dev)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+### Ship Dart & asset hotfixes over the air. Your backend. No store review. No monthly bill.
+
+**flutter_ota_kit** is open-source code push for **Flutter Android**. Push a bug
+fix or a new screen, and your users get it on the next cold start — no Play
+Store round-trip, no vendor lock-in, no per-seat pricing. The patch lives on
+**your** infrastructure (Supabase, Postgres, Cloudflare, AWS S3, PocketBase, or
+your own CDN), signed and integrity-checked, with automatic crash rollback if
+anything goes wrong.
+
+If you've used [Shorebird](https://shorebird.dev/),
+[CodePush](https://learn.microsoft.com/en-us/appcenter/distribution/codepush/),
+or [Expo EAS Update](https://docs.expo.dev/eas-update/introduction/), this is the
+same idea for Flutter Android — MIT-licensed, self-hosted, and yours to keep.
+
+![Feature demo: apply a patch, cold restart, and rollback](doc/feature-presentation.gif)
+
+```yaml
+dependencies:
+  flutter_ota_kit: ^0.2.0   # one package — every backend included
+```
+
+> **v0.2.0 is a single package.** Everything — the device SDK plus all five
+> backends — now ships inside `flutter_ota_kit`. There are no more
+> `flutter_ota_kit_supabase` / `_postgres` / `_cloudflare` / `_aws` /
+> `_pocketbase` packages to add. One import, one dependency.
+
+---
+
+## Why teams pick it
+
+- **You own the pipeline.** Patches sit in your Supabase project, your S3
+  bucket, your Cloudflare account — not someone else's cloud. No third party
+  sees your code or your users.
+- **Zero recurring cost.** MIT-licensed. The only bill is your own storage,
+  which for OTA payloads is pennies.
+- **Ships in one dependency.** Add `flutter_ota_kit`, run `flutter-ota init`,
+  deploy. Five backends are built in; you configure the one you use.
+- **Safe by default.** MD5 + Ed25519 verification, automatic crash rollback,
+  a bad-patch blacklist, and staged rollouts — all on by default.
+- **Zero-code forced-update UI.** Opt in and the SDK renders a polished
+  full-screen install progress screen for you. Write no UI.
+
+---
+
+## How it compares
+
+|                          | flutter_ota_kit                                          | Shorebird                     | CodePush (React Native)      |
+|--------------------------|----------------------------------------------------------|-------------------------------|------------------------------|
+| **Framework**            | Flutter                                                  | Flutter                       | React Native                 |
+| **Platforms**            | Android                                                  | Android + iOS                 | Android + iOS (retired 2025) |
+| **Hosting**              | Your backend / your CDN — see [Backends](doc/backends.md) | Shorebird cloud (managed)     | AppCenter cloud (deprecated) |
+| **Update scope**         | Dart AOT + Flutter assets                                | Dart code (engine-level diff) | JS bundle                    |
+| **Takes effect**         | Next cold start                                          | Next restart                  | Next restart                 |
+| **Cost**                 | Free (MIT) — you pay only your own storage               | Free tier + paid plans        | —                            |
+| **Backend flexibility**  | Supabase / Postgres / Cloudflare / AWS / PocketBase / BYO CDN | Cloud-managed only       | —                            |
+| **Forced updates**       | Yes — built-in progress UI                               | Yes                           | Yes                          |
+| **Crash rollback**       | Automatic + bad-patch blacklist                          | Yes                           | Yes                          |
+| **Signing**              | Ed25519 (Android 13+) + MD5                              | Yes                           | —                            |
+
+**Choose Shorebird** if you need iOS today or want a fully managed cloud.
+
+**Choose flutter_ota_kit** if you want OTA on infrastructure you control —
+enterprise apps, regional distribution, air-gapped deployments, or non-Play
+channels. Bring your own backend, CDN, and auth.
+
+> Google Play and some stores restrict downloading executable code at runtime.
+> flutter_ota_kit targets self-controlled, enterprise, or permissive
+> distribution channels. Verify your channel's policy before shipping.
+
+---
+
+## Features
+
+- **OTA code push** — replaces the Dart AOT `libapp.so` and Flutter assets on
+  the next cold start, with MD5 + Ed25519 integrity checks.
+- **Five backends, built in** — Supabase (fully automated), Postgres,
+  Cloudflare (D1 + R2), AWS (S3 + optional CloudFront), and **PocketBase**
+  (single-binary, self-hosted). Or point at your own CDN.
+- **Automatic crash rollback** — a patch that fails to boot is rolled back and
+  blacklisted so it's never retried. Tunable via `maxCrashCount` /
+  `verifyAfter`. A runtime crash *hours* after a healthy boot no longer reverts
+  a good patch (bounded crash-attribution window).
+- **Forced updates with a built-in UI** — set `autoApplyUpdates: true` and wrap
+  your app in `FlutterOtaApp`; the SDK shows a full-screen terminal-style
+  install screen (steps, live progress bar, speed/ETA, server message) and
+  cold-restarts into the new build. You write no UI.
+- **Staged rollout** — server-side cohort math (per-mille + target cohorts) lets
+  you ship 1% → 5% → 20% → 50% → 100% safely.
+- **Batteries-included tooling** — the `flutter-ota` CLI (`init`, `build`,
+  `deploy`, `bundle`, `channel`, `rollback`, `migrate`, `doctor`, and a bundled
+  PocketBase manager), plus runtime diagnostics and a sample app.
+
+---
+
+## Try it in 5 minutes (no server needed)
+
+```bash
+git clone https://github.com/HYPER12755/flutter-ota-kit.git
+cd flutter-ota-kit/example
+flutter pub get
+flutter build apk --release
+flutter install
+```
+
+1. Launch the app — it shows the **original** demo screen.
+2. Tap **Apply patch**.
+3. Swipe the app away from recents and reopen.
+4. The screen has changed — the patch took effect.
+5. Tap **Rollback** → restart → the original is back.
+
+The example bundles a precompiled patch; everything runs offline on the device.
+For a full backend walkthrough, see the [Beginner Guide](doc/beginner-guide.md)
+or [Getting Started](doc/getting-started.md).
+
+---
+
+## Requirements
+
+| Item                     | Requirement                                              |
+|--------------------------|----------------------------------------------------------|
+| **Platform**             | Android only (iOS / macOS / Windows / Linux / Web are no-ops) |
+| **Dart SDK**             | `>=3.13.2 <4.0.0`                                        |
+| **Flutter**              | `>=3.47.2`                                               |
+| **Android `minSdk`**     | 24                                                       |
+| **Android `compileSdk`** | 36                                                       |
+| **ABI**                  | `armeabi-v7a` / `arm64-v8a` / `x86_64`                   |
+| **NDK**                  | 27.0.12077973+                                          |
+| **Java / JVM**           | 17                                                       |
+
+On non-Android platforms every API is safe to call but is a **no-op** — the
+plugin logs a one-time warning and returns safe defaults, so you can ship
+`flutter_ota_kit` in cross-platform code without guarding every call site.
+
+---
+
+## Quick start
+
+### 1. Install
+
+```yaml
+dependencies:
+  flutter_ota_kit: ^0.2.0
+```
+
+### 2. Scaffold your backend (CLI)
+
+```bash
+# installs the flutter-ota CLI globally
+npm i -g @_nazmiforreal/flutter-ota
+
+# scaffold config + a generated setup file for your backend
+flutter-ota init supabase   # or: postgres | cloudflare | aws | pocketbase
+```
+
+`init` writes a `.flutter_ota_kit/config.json`, an `.env` template for secrets,
+and a `lib/flutter_ota_kit_setup.dart` helper you call from `main()`.
+
+### 3. Initialize in your app
+
+Call the generated `setupFlutterOta()` (or wire it by hand) before `runApp`:
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:flutter_ota_kit/flutter_ota_kit.dart';
+import 'flutter_ota_kit_setup.dart'; // generated by `flutter-ota init`
+
+Future<void> main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  await setupFlutterOta();               // configures the backend + forced updates
+  runApp(const FlutterOtaApp(child: MyApp()));
+}
+```
+
+`FlutterOtaApp` is the zero-code wrapper that lets the SDK render its built-in
+forced-update screen. Disable it app-wide with
+`FlutterPatcher.showUpdateUi = false` (or `FlutterOtaApp(showUpdateUi: false)`),
+or host it yourself by setting `MaterialApp.navigatorKey =
+FlutterPatcher.navigatorKey`.
+
+Prefer wiring the backend directly? Every backend has a `configureX` helper:
+
+```dart
+FlutterPatcher.configureSupabase(SupabaseUpdateConfig(
+  supabaseUrl: 'https://<ref>.supabase.co',
+  anonKey: '<anon-key>',            // public, RLS-protected reads
+  bucket: 'bundles',
+  channel: 'production',
+  platform: Platform.android,
+  updateStrategy: UpdateStrategy.appVersion,
+  appVersion: '1.0.0',              // or omit — auto-detected from versionName
+));
+await FlutterPatcher.init(autoApplyUpdates: true);
+```
+
+### 4. Build a patch
+
+Rebuild the release APK, then pack it into a device-ready `patch.zip`:
+
+```bash
+flutter build apk --release
+flutter-ota build \
+  --apk build/app/outputs/flutter-apk/app-release.apk \
+  --version 1.0.1 \
+  --target-version-code 100
+```
+
+Every ABI in the APK is included, so one bundle serves all devices. Add
+`--assets assets/hero.png,assets/strings/zh.json` to overlay updated assets.
+
+### 5. Deploy
+
+```bash
+flutter-ota deploy \
+  --source dist \
+  --channel production \
+  --target-app-version 1.0.0 \
+  --force
+```
+
+That's it — devices pick up the patch on their next check.
+
+### 6. Roll back (server side)
+
+```bash
+flutter-ota rollback --channel production
+```
+
+Or on the device, `FlutterPatcher.rollback()` deletes the local patch and
+reverts to the APK's built-in version on the next cold start.
+
+---
+
+## How it works
+
+```text
+  ┌─────────────────┐  Supabase / Postgres / Cloudflare / AWS / PocketBase / CDN
+  │  Your backend    │  stores: patch.zip (the diff) + manifest.json (metadata)
+  └────────▲────────┘
+           │  1. check-for-update on launch
+           │  2. backend returns PatchInfo (url, md5, signature, force flag)
+  ┌────────┴────────┐
+  │   The app       │  3. download patch.zip
+  │                 │  4. verify MD5 + Ed25519 signature
+  │                 │  5. write to local patch dir (atomic rename)
+  │                 │  6. cold-restart (forced) OR next cold start (staged)
+  │                 │  7. loader hook reads patched libapp.so + asset overlays
+  │                 │  8. boot ok → keep · boot fails → auto-rollback + blacklist
+  └─────────────────┘
+```
+
+A patch is a byte-for-byte diff of the new APK's `libapp.so` against the
+version the user has installed; asset patches overlay `flutter_assets/` by path.
+Nothing is swapped into the running process — it loads on the next cold start.
+
+Full internals: [Architecture](doc/architecture.md).
+
+---
+
+## What can and can't be patched
+
+| ✅ Hot-patchable                                     | ❌ Not hot-patchable                                     |
+|------------------------------------------------------|----------------------------------------------------------|
+| Anything in `lib/` — widgets, logic, routes, constants | Native code (Kotlin / Java / C++ in `android/src/main/`) |
+| Pure-Dart package upgrades (same native side)        | `AndroidManifest.xml` changes                            |
+| Flutter asset files registered in `pubspec.yaml`     | APK `res/` (icons, layouts, strings.xml)                 |
+| New `Image.asset()` / `rootBundle.load()` calls      | Flutter Engine upgrades                                  |
+|                                                      | Adding or removing native plugins                        |
+|                                                      | Removing assets that exist in the base APK               |
+
+See [API Reference → What can be patched](doc/api-reference.md#what-can-and-cannot-be-patched)
+for edge cases (ProGuard/R8, multi-ABI/flavors, state migrations).
+
+---
+
+## Safety
+
+- **Crash protection (on by default).** If a patch fails to boot, the SDK
+  auto-rolls back and blacklists the offending version. Tune with
+  `maxCrashCount` (default 1) and `verifyAfter` (default 5s). Crash attribution
+  is bounded to a boot window, so an unrelated crash long after a healthy boot
+  won't revert a working patch. See [Crash Protection](doc/crash-protection.md).
+- **Integrity & signing.** MD5 is strongly recommended; Ed25519 signature
+  verification is available on Android 13+ (falls back to MD5-only below, with a
+  warning). Patches are bound to the host APK's `versionCode`, so stale patches
+  expire after an app upgrade. Keep private signing keys on your server, never
+  in the app bundle.
+- **Staged rollout.** Ship 1% → 5% → 20% → 50% → 100% and watch crash rate at
+  each stage. The SDK records `lastBootDiagnostic` per device.
+
+Full release workflow: [Production Playbook](doc/production-playbook.md).
+
+---
+
+## Documentation
+
+**Guides**
+
+- [Beginner Guide](doc/beginner-guide.md) — zero to first OTA, narrated
+- [Getting Started](doc/getting-started.md) — scaffold → build → deploy
+- [Developer Guide](doc/developer-guide.md) — full workflow reference
+- [Configuration](doc/configuration.md) — env vars, `.env`, resolution order
+- [Backends](doc/backends.md) — Supabase / Postgres / Cloudflare / AWS / PocketBase setup
+- [Production Playbook](doc/production-playbook.md) — staged rollout, diagnostics, rollback
+
+**Reference**
+
+- [API Reference](doc/api-reference.md) — `FlutterPatcher`, configs, overlay, error codes
+- [Architecture](doc/architecture.md) — internals, protocol, signing
+- [CLI Reference](doc/cli-reference.md) — every command and flag
+- [Crash Protection](doc/crash-protection.md) — rollback, blacklist, Android differences
+- [FAQ](doc/faq.md) — versioning, cold start, store policy
+
+---
+
+## Contributing
+
+Issues and PRs welcome. Before submitting:
+
+- `flutter analyze` reports no issues
+- `flutter test` is fully green
+- If you touched native code, run a real-device patch / rollback end-to-end
+- Document new public APIs (they surface on pub.dev)
+
+---
+
+## License
+
+MIT

package/dart-src/root/analysis_options.yaml

@@ -0,0 +1,21 @@
+# Root analysis options for the flutter_ota_kit monorepo.
+#
+# The repo is a monorepo: `packages/*`, `plugins/*`, and `example/` are each
+# standalone Dart/Flutter packages that are analyzed (and lint-configured)
+# independently. Excluding them here keeps `dart analyze .` focused on the root
+# device-SDK package (`lib/` + `test/`), which is the only thing the root
+# package owns. Each sub-package is analyzed on its own and is already clean.
+analyzer:
+  exclude:
+    - packages/**
+    - plugins/**
+    - example/**
+    - node_modules/**
+    - npm/**
+    - build/**
+    - android/**
+    - ios/**
+    - web/**
+    - windows/**
+    - macos/**
+    - linux/**