chore: add deprecation notice

DEPRECATION.md

@@ -0,0 +1,89 @@
+# Mockingjay — Deprecation Notice & Migration Guide
+
+> **This package is deprecated and is no longer actively maintained.**
+> The repository remains public and available for the community to fork.
+
+---
+
+## Why is Mockingjay being deprecated?
+
+Mockingjay provides mock classes for testing Flutter's **Navigator 1.0** (imperative) APIs.
+The Flutter ecosystem has broadly shifted toward **Navigator 2.0** — the declarative navigation API —
+and packages like [`go_router`](https://pub.dev/packages/go_router) have become the de facto standard
+for navigation in modern Flutter applications.
+
+Given this shift, maintaining Mockingjay no longer aligns with the current direction of the Flutter
+community. Rather than let it languish with infrequent updates, we are making the deprecation official
+so users can plan accordingly.
+
+The package will remain available on [pub.dev](https://pub.dev/packages/mockingjay) and the source
+code will stay public and forkable. If there is enough community interest, anyone is welcome to create
+and maintain a community edition.
+
+---
+
+## What should I do if I'm using Mockingjay?
+
+You have two paths depending on how your app handles navigation:
+
+### Path 1 — Migrate to Navigator 2.0 (recommended)
+
+If you are building a new app or are willing to update your navigation layer, migrating to
+Navigator 2.0 is the recommended long-term path.
+
+1. **Adopt `go_router`** (or another Navigator 2.0-compatible package) for your app's routing.
+   See the [go_router documentation](https://pub.dev/packages/go_router) to get started.
+
+2. **Update your tests.** With `go_router`, navigation is driven by a `GoRouter` instance.
+   In tests, you can provide a custom router with a test-specific configuration rather than
+   mocking `Navigator` directly:
+
+   ```dart
+   final router = GoRouter(
+     initialLocation: '/',
+     routes: [
+       GoRoute(path: '/', builder: (_, __) => const HomeScreen()),
+       GoRoute(path: '/detail', builder: (_, __) => const DetailScreen()),
+     ],
+   );
+
+   testWidgets('navigates to detail', (tester) async {
+     await tester.pumpWidget(MaterialApp.router(routerConfig: router));
+     // Interact and assert normally
+   });
+   ```
+
+3. **Remove the `mockingjay` dependency** from your `pubspec.yaml` once all usages have been replaced.
+
+---
+
+### Path 2 — Continue using Navigator 1.0 (no migration)
+
+Navigator 1.0 is still part of Flutter and is not going away. If your project intentionally uses
+the imperative API and you rely on Mockingjay, you have two options:
+
+- **Fork the repository** and maintain your own copy. The source code is fully public under its
+  existing license.
+- **Use `NavigatorObserver` and manual test doubles** as a lightweight alternative, which requires
+  no third-party package.
+
+---
+
+## Timeline
+
+| Date | Milestone |
+|------|-----------|
+| April 2026 | Package marked as deprecated on pub.dev |
+| Ongoing | No new features or maintenance; critical bug reports may be considered on a best-effort basis |
+
+---
+
+## Resources
+
+- [go_router on pub.dev](https://pub.dev/packages/go_router)
+- [Flutter Navigation & Routing docs](https://docs.flutter.dev/ui/navigation)
+- [Navigator 2.0 overview](https://medium.com/flutter/learning-flutters-new-navigation-and-routing-system-7c9068155ade)
+
+---
+
+Thank you to everyone who used and contributed to Mockingjay over the years.

README.md

@@ -13,6 +13,14 @@ Developed with 💙 by [Very Good Ventures][very_good_ventures_link] 🦄
 
 ---
 
+> ⚠️ **This package is deprecated and no longer actively maintained.**
+>
+> The Flutter ecosystem has shifted toward Navigator 2.0 and declarative routing solutions such as [`go_router`][go_router_link]. Mockingjay, which targets Navigator 1.0 APIs, no longer aligns with the direction of the ecosystem.
+>
+> The repository remains public and available to fork. For full migration guidance, see [DEPRECATION.md](DEPRECATION.md).
+
+---
+
 A package that makes it easy to mock, test and verify navigation calls in Flutter. It works in tandem with [`mocktail`][mocktail], allowing you to mock a navigator the same way you would any other object, making it easier to test navigation behavior independently from the UI it's supposed to render.
 
 ## Usage
@@ -112,6 +120,7 @@ void main() {
 [license_link]: https://opensource.org/licenses/MIT
 [logo_black]: https://raw.githubusercontent.com/VGVentures/very_good_brand/main/styles/README/vgv_logo_black.png#gh-light-mode-only
 [logo_white]: https://raw.githubusercontent.com/VGVentures/very_good_brand/main/styles/README/vgv_logo_white.png#gh-dark-mode-only
+[go_router_link]: https://pub.dev/packages/go_router
 [mocktail]: https://pub.dev/packages/mocktail
 [pub_badge]: https://img.shields.io/pub/v/mockingjay.svg
 [pub_link]: https://pub.dartlang.org/packages/mockingjay