@bdayadev/flutter-ultra-mcp 1.12.0 → 1.14.0

package/skills/migrate-to-checks-package/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: migrate-to-checks-package
 description: Replace the usage of `expect` and similar functions from `package:matcher` to `package:checks` equivalents.
+  last_modified: Fri, 24 Apr 2026 15:15:22 GMT
 ---
 
 # Migrating Dart Tests to Package Checks
@@ -9,11 +10,14 @@ description: Replace the usage of `expect` and similar functions from `package:m
 
 - [Dependency Management](#dependency-management)
 - [Syntax Migration Guidelines](#syntax-migration-guidelines)
+- [Utilizing Dart MCP Tools](#utilizing-dart-mcp-tools)
 - [Migration Workflow](#migration-workflow)
 - [Examples](#examples)
 
 ## Dependency Management
 
+Manage dependencies using the Dart Tooling MCP Server `pub` tool or standard CLI commands.
+
 - Add `package:checks` as a `dev_dependency` using `dart pub add dev:checks`.
 - Remove `package:matcher` if it is explicitly listed in the `pubspec.yaml` (note: it is often transitively included by `package:test`, which is fine).
 - Import `package:checks/checks.dart` in all test files undergoing migration.
@@ -22,35 +26,47 @@ description: Replace the usage of `expect` and similar functions from `package:m
 
 Transition test assertions from the `package:matcher` syntax to the literate API provided by `package:checks`.
 
-- **Basic Equality:** Replace `expect(actual, equals(expected))` with `check(actual).equals(expected)`.
+- **Basic Equality:** Replace `expect(actual, equals(expected))` or `expect(actual, expected)` with `check(actual).equals(expected)`.
 - **Type Checking:** Replace `expect(actual, isA<Type>())` with `check(actual).isA<Type>()`.
 - **Property Extraction:** Replace `expect(actual.property, expected)` with `check(actual).has((a) => a.property, 'property name').equals(expected)`.
 - **Cascades for Multiple Checks:** Use Dart's cascade operator (`..`) to chain multiple expectations on a single subject.
 - **Asynchronous Expectations:**
   - If checking a `Future`, `await` the `check` call: `await check(someFuture).completes((r) => r.equals(expected));`.
-  - If checking a `Stream`, wrap it in a `StreamQueue` for multiple checks.
+  - If checking a `Stream`, wrap it in a `StreamQueue` for multiple checks, or use `.withQueue` for single/broadcast checks.
+
+## Utilizing Dart MCP Tools
+
+Leverage the Dart MCP Server tools to automate and validate the migration process.
+
+- Use `pub` to run `dart pub get` or `dart pub add`.
+- Use `analyze_files` to run static analysis on the project or specific paths.
+- Use `run_tests` to execute Dart or Flutter tests with an agent-centric UX. ALWAYS use this instead of shell commands like `dart test`.
+- Use `dart_fix` to apply automated fixes if applicable.
 
 ## Migration Workflow
 
-- [ ] Add `package:checks` as a dev dependency.
-- [ ] Identify all test files using `package:matcher` (`expect` calls).
-- [ ] Import `package:checks/checks.dart` in target test files.
-- [ ] Rewrite all `expect(...)` statements to `check(...)` statements.
-- [ ] Run static analyzer.
-- [ ] Run tests.
+Copy and use the following checklist to track progress when migrating a test suite:
+
+- [ ] **Task Progress**
+  - [ ] Add `package:checks` as a dev dependency.
+  - [ ] Identify all test files using `package:matcher` (`expect` calls).
+  - [ ] Import `package:checks/checks.dart` in target test files.
+  - [ ] Rewrite all `expect(...)` statements to `check(...)` statements.
+  - [ ] Run static analyzer (`analyze_files`).
+  - [ ] Run tests (`run_tests`).
 
 ### Feedback Loop: Static Analysis
 
-1. Run the analyzer on the modified test directories.
-2. Review any static analysis warnings or errors.
+1. Run the `analyze_files` tool on the modified test directories.
+2. Review any static analysis warnings or errors (e.g., missing imports, incorrect generic types on `isA`, unawaited futures).
 3. Fix the warnings.
-4. Repeat until zero issues.
+4. Repeat until the analyzer returns zero issues.
 
 ### Feedback Loop: Test Validation
 
-1. Run the tests.
-2. If tests fail, review the failure output. `package:checks` provides detailed context.
-3. Adjust the `check()` expectations or the underlying code.
+1. Run the `run_tests` tool.
+2. If tests fail, review the failure output. `package:checks` provides detailed context (e.g., `Which: has length of <2>`).
+3. Adjust the `check()` expectations or the underlying code to resolve the failure.
 4. Repeat until all tests pass.
 
 ## Examples
@@ -110,6 +126,22 @@ await check(Future.value(10)).completes((it) => it.equals(10));
 await check(Future.error('oh no')).throws<String>().equals('oh no');
 ```
 
+### Asynchronous Streams
+
+**Input (`matcher`):**
+
+```dart
+var stdout = StreamQueue(Stream.fromIterable(['Ready', 'Go']));
+await expectLater(stdout, emitsThrough('Ready'));
+```
+
+**Output (`checks`):**
+
+```dart
+var stdout = StreamQueue(Stream.fromIterable(['Ready', 'Go']));
+await check(stdout).emitsThrough((it) => it.equals('Ready'));
+```
+
 ## Flutter Ultra Integration
 
 Validate the migration with static analysis and tests:

package/skills/record-demo/SKILL.md

@@ -68,6 +68,26 @@ For responsive demos, resize the viewport between key interactions:
 
 Take screenshots at key moments for verification alongside the recording.
 
+### 3b. Web performance trace (optional, alongside video)
+
+For web demos where you also want a Chrome DevTools trace alongside the video:
+
+```
+mcp__plugin_flutter_flutter-ultra-browser__start_tracing
+  contextId: <id>
+  categories: ["blink", "v8", "disabled-by-default-devtools.timeline"]
+  outputPath: /tmp/flutter-demo-trace.json
+```
+
+Drive the UI flow, then stop:
+
+```
+mcp__plugin_flutter_flutter-ultra-browser__stop_tracing
+  contextId: <id>
+```
+
+Returns the trace JSON path. Open in `chrome://tracing` or Perfetto for frame-level analysis alongside the recorded video.
+
 ### 4. Stop recording
 
 #### Web

package/skills/resolve-package-conflicts/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: resolve-package-conflicts
 description: Workflow for fixing package version conflicts. Use this when `pub get` fails due to incompatible package versions.
+  last_modified: Fri, 24 Apr 2026 15:11:14 GMT
 ---
 
 # Managing Dart Dependencies
@@ -16,46 +17,54 @@ description: Workflow for fixing package version conflicts. Use this when `pub g
 
 ## Core Concepts
 
-Dart enforces a strict single-version rule for dependencies: a project and all its transitive dependencies must resolve to a single, shared version of any given package.
+Dart enforces a strict single-version rule for dependencies: a project and all its transitive dependencies must resolve to a single, shared version of any given package. This prevents runtime type mismatches but introduces the risk of "version lock."
+
+To mitigate version lock, Dart relies on version constraints rather than pinned versions in the `pubspec.yaml`. The `pubspec.lock` file maintains the exact resolved versions for reproducible builds.
 
 Understand the output columns of `dart pub outdated`:
 
 - **Current:** The version currently recorded in `pubspec.lock`.
 - **Upgradable:** The latest version allowed by the constraints in `pubspec.yaml`. `dart pub upgrade` resolves to this.
-- **Resolvable:** The absolute latest version that can be resolved when factoring in all other dependencies.
+- **Resolvable:** The absolute latest version that can be resolved when factoring in all other dependencies in the project.
 - **Latest:** The latest published version of the package (excluding prereleases).
 
 ## Version Constraints
 
-- **Use Caret Syntax:** Always use caret syntax (e.g., `^1.2.3`) for dependencies.
-- **Tighten Dev Dependencies:** Set the lower bound of `dev_dependencies` to the exact version currently used.
-- **Enforce Lockfiles in CI:** Use `dart pub get --enforce-lockfile` in CI/CD pipelines.
+- **Use Caret Syntax:** Always use caret syntax (e.g., `^1.2.3`) for dependencies in `pubspec.yaml`. This allows `pub` to select newer, non-breaking versions (up to, but not including, the next major version) during resolution.
+- **Tighten Dev Dependencies:** Set the lower bound of `dev_dependencies` to the exact version currently used. This reduces resolution complexity and prevents older, incompatible dev tools from being selected.
+- **Enforce Lockfiles in CI:** Use `dart pub get --enforce-lockfile` in CI/CD pipelines to ensure the exact versions tested locally are used in production.
 
 ## Workflow: Auditing Dependencies
 
+Run this workflow periodically to identify stale packages that may impact stability or performance.
+
 **Task Progress:**
 
 - [ ] Run `dart pub outdated`.
-- [ ] Review the **Upgradable** column.
-- [ ] Review the **Resolvable** column.
+- [ ] Review the **Upgradable** column to identify packages that can be updated without modifying `pubspec.yaml`.
+- [ ] Review the **Resolvable** column to identify packages that require constraint modifications in `pubspec.yaml` to update.
 - [ ] Identify any packages marked as retracted or discontinued.
 
 ## Workflow: Upgrading Dependencies
 
+Use conditional logic based on the audit results to upgrade dependencies.
+
 **Task Progress:**
 
 - [ ] **If updating to "Upgradable" versions:**
   - [ ] Run `dart pub upgrade`.
-  - [ ] Run `dart pub upgrade --tighten` to update lower bounds.
+  - [ ] Run `dart pub upgrade --tighten` to automatically update the lower bounds in `pubspec.yaml` to match the newly resolved versions.
 - [ ] **If updating to "Resolvable" versions (Major updates):**
-  - [ ] Manually edit `pubspec.yaml` to bump the version constraint.
-  - [ ] Run `dart pub upgrade` to resolve the new constraints.
+  - [ ] Manually edit `pubspec.yaml` to bump the version constraint to match the "Resolvable" column (e.g., change `^0.11.0` to `^0.12.1`).
+  - [ ] Run `dart pub upgrade` to resolve the new constraints and update `pubspec.lock`.
 - [ ] **Feedback Loop:**
   - [ ] Run `dart analyze` -> review errors -> fix breaking API changes.
   - [ ] Run `dart test` -> review failures -> fix regressions.
 
 ## Workflow: Resolving Version Conflicts
 
+When `pub` cannot find a set of concrete versions that satisfy all constraints, or when dealing with a retracted package version, manipulate the lockfile surgically.
+
 **NEVER** delete the entire `pubspec.lock` file and run `dart pub get`. This causes uncontrolled upgrades across the entire dependency graph.
 
 **Task Progress:**
@@ -63,7 +72,7 @@ Understand the output columns of `dart pub outdated`:
 - [ ] Open `pubspec.lock`.
 - [ ] Locate the specific YAML block for the conflicting or retracted package.
 - [ ] Delete ONLY that package's entry from the lockfile.
-- [ ] Run `dart pub get` to fetch the newest compatible version.
+- [ ] Run `dart pub get` to fetch the newest compatible, non-retracted version for that specific package.
 - [ ] **Feedback Loop:**
   - [ ] Run `dart pub deps` -> verify the dependency graph resolves correctly.
   - [ ] If resolution fails, identify the transitive dependency causing the lock, update its constraint in `pubspec.yaml`, and retry.
@@ -72,6 +81,8 @@ Understand the output columns of `dart pub outdated`:
 
 ### Tightening Constraints
 
+When `dart pub outdated` shows a package is resolvable to a higher minor/patch version, use the `--tighten` flag to update the `pubspec.yaml` automatically.
+
 **Input (`pubspec.yaml`):**
 
 ```yaml
@@ -94,7 +105,25 @@ dependencies:
 
 ### Surgical Lockfile Removal
 
-If `package_a` is retracted or locked in a conflict, remove only its block from `pubspec.lock`. Leave all other entries untouched. Run `dart pub get`.
+If `package_a` is retracted or locked in a conflict, remove only its block from `pubspec.lock`.
+
+**Before (`pubspec.lock`):**
+
+```yaml
+packages:
+  package_a:
+    dependency: 'direct main'
+    description:
+      name: package_a
+      url: 'https://pub.dev'
+    source: hosted
+    version: '1.0.0' # Retracted version
+  package_b:
+    dependency: 'direct main'
+    # ...
+```
+
+**Action:** Delete the `package_a` block entirely. Leave `package_b` untouched. Run `dart pub get`.
 
 ## Flutter Ultra Integration
 

package/skills/run-static-analysis/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: run-static-analysis
 description: Execute `dart analyze` to identify warnings and errors, and use `dart fix --apply` to automatically resolve mechanical lint issues. Use during development to ensure code quality and before committing changes.
+  last_modified: Fri, 24 Apr 2026 15:09:34 GMT
 ---
 
 # Analyzing and Fixing Dart Code
@@ -15,38 +16,48 @@ description: Execute `dart analyze` to identify warnings and errors, and use `da
 
 ## Analysis Configuration
 
-Configure the Dart analyzer using the `analysis_options.yaml` file at the package root.
+Configure the Dart analyzer using the `analysis_options.yaml` file located at the package root.
 
-- **Base Configuration:** Include a standard rule set (e.g., `package:lints/recommended.yaml` or `package:flutter_lints/flutter.yaml`).
-- **Strict Type Checks:** Enable `strict-casts: true`, `strict-inference: true`, and `strict-raw-types: true` under `analyzer: language:`.
-- **Linter Rules:** Enable or disable specific rules under `linter: rules:`. Do not mix list and map syntax in the same `rules` block.
-- **Formatter Configuration:** Configure `dart format` behavior under the `formatter:` node. Set `page_width` and `trailing_commas`.
+- **Base Configuration:** Always include a standard rule set (e.g., `package:lints/recommended.yaml` or `package:flutter_lints/flutter.yaml`) using the `include:` directive.
+- **Strict Type Checks:** Enable strict type checks under the `analyzer: language:` node to prevent implicit downcasts and dynamic inferences. Set `strict-casts: true`, `strict-inference: true`, and `strict-raw-types: true`.
+- **Linter Rules:** Explicitly enable or disable specific rules under the `linter: rules:` node. Use a key-value map (`rule_name: true/false`) when overriding included rules, or a list (`- rule_name`) when defining a fresh set. Do not mix list and map syntax in the same `rules` block.
+- **Formatter Configuration:** Configure `dart format` behavior under the `formatter:` node. Set `page_width` (default 80) and `trailing_commas` (`automate` or `preserve`).
+- **Analyzer Plugins:** Enable custom diagnostics by adding plugins under the `analyzer: plugins:` node. Ensure the plugin package is added as a `dev_dependency` in `pubspec.yaml`.
 
 ## Diagnostic Suppression
 
-- **File-level Exclusion:** Use `analyzer: exclude:` with glob patterns (e.g., `**/*.g.dart`).
-- **File-level Suppression:** Add `// ignore_for_file: <diagnostic_code>` at the top of a file.
-- **Line-level Suppression:** Add `// ignore: <diagnostic_code>` on the line above.
+When a diagnostic (lint or warning) yields a false positive or applies to generated code, suppress it explicitly.
+
+- **File-level Exclusion:** Use the `analyzer: exclude:` node in `analysis_options.yaml` to exclude entire files or directories (e.g., `**/*.g.dart`) using glob patterns.
+- **File-level Suppression:** Add `// ignore_for_file: <diagnostic_code>` at the top of a Dart file to suppress specific diagnostics for the entire file. Use `// ignore_for_file: type=lint` to suppress all linter rules.
+- **Line-level Suppression:** Add `// ignore: <diagnostic_code>` on the line directly above the offending code, or appended to the end of the offending line.
+- **Pubspec Suppression:** Add `# ignore: <diagnostic_code>` above the offending line in `pubspec.yaml` files (e.g., `# ignore: sort_pub_dependencies`).
+- **Plugin Diagnostics:** Prefix the diagnostic code with the plugin name when suppressing plugin-specific issues (e.g., `// ignore: some_plugin/some_code`).
 
 ## Workflow: Executing Static Analysis
 
+Use this workflow to identify type-related bugs, style violations, and potential runtime errors.
+
 **Task Progress:**
 
 - [ ] 1. Verify `analysis_options.yaml` exists at the project root.
-- [ ] 2. Run the analyzer: `dart analyze <target_directory>`.
+- [ ] 2. Run the analyzer using the `analyze_files` MCP tool (if available) or the CLI command `dart analyze <target_directory>`.
 - [ ] 3. Review the diagnostic output.
-- [ ] 4. If info-level issues must be treated as failures, append `--fatal-infos`.
-- [ ] 5. Resolve reported errors manually or proceed to Automated Fixes.
+- [ ] 4. If info-level issues must be treated as failures, append the `--fatal-infos` flag.
+- [ ] 5. Resolve reported errors manually or proceed to the Automated Fixes workflow.
 
 ## Workflow: Applying Automated Fixes
 
+Use this workflow to resolve outdated API usages, apply quick fixes, and migrate code (e.g., Dart 3 migrations).
+
 **Task Progress:**
 
-- [ ] 1. Preview proposed changes: `dart fix --dry-run`.
-- [ ] 2. Review the proposed fixes.
-- [ ] 3. Apply the fixes: `dart fix --apply`.
-- [ ] 4. Format the modified code: `dart format .`.
-- [ ] 5. Run static analysis again to verify all diagnostics are resolved.
+- [ ] 1. Execute a dry run to preview proposed changes using the `dart_fix` MCP tool or CLI command `dart fix --dry-run`.
+- [ ] 2. Review the proposed fixes to ensure they align with the intended architecture.
+- [ ] 3. If additional fixes are required, verify that the corresponding linter rules are enabled in `analysis_options.yaml`.
+- [ ] 4. Apply the fixes using the `dart_fix` MCP tool or CLI command `dart fix --apply`.
+- [ ] 5. Format the modified code using the `dart_format` MCP tool or CLI command `dart format .`.
+- [ ] 6. Run the static analysis workflow to verify all diagnostics are resolved.
 
 ## Examples
 
@@ -82,9 +93,11 @@ formatter:
 ### Inline Diagnostic Suppression
 
 ```dart
+// Suppress for the entire file
 // ignore_for_file: unused_local_variable, dead_code
 
 void processData() {
+  // Suppress for a specific line
   // ignore: invalid_assignment
   int x = '';
 

package/skills/setup/SKILL.md

@@ -12,6 +12,7 @@ Expected end state: `UltraFlutterBinding` initialized in the app entry point, `u
 ### 1. Verify the environment
 
 - `mcp__plugin_flutter_flutter-ultra-build__flutter_doctor` — stop if Flutter SDK, devices, or Dart show `[x]`.
+- `mcp__plugin_flutter_flutter-ultra-build__list_projects` — check if the target project already exists. If not, use `mcp__plugin_flutter_flutter-ultra-build__create_project` to scaffold it (an alternative to running `flutter create` manually), then proceed with setup steps below.
 - `mcp__plugin_flutter_flutter-ultra-build__project_info` — note entry points, `hasSentry`, `hasPatrol`, `hasUltraBinding`.
 - `mcp__plugin_flutter_flutter-ultra-runtime__list_devices` — verify at least one target device is available.
 - `mcp__plugin_flutter_flutter-ultra-build__list_dart_defines` — discover required dart-defines for launch.

package/skills/setup-declarative-routing/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: setup-declarative-routing
 description: Configure `MaterialApp.router` using a package like `go_router` for advanced URL-based navigation. Use when developing web applications or mobile apps that require specific deep linking and browser history support.
+  last_modified: Tue, 21 Apr 2026 21:08:03 GMT
 ---
 
 # Implementing Routing and Deep Linking
@@ -15,29 +16,46 @@ description: Configure `MaterialApp.router` using a package like `go_router` for
 
 ## Core Concepts
 
-Use the `go_router` package for declarative routing in Flutter.
+Use the `go_router` package for declarative routing in Flutter. It provides a robust API for complex routing scenarios, deep linking, and nested navigation.
 
-- **GoRouter**: Central configuration object defining the route tree.
-- **GoRoute**: Maps a URL path to a Flutter screen.
-- **ShellRoute / StatefulShellRoute**: Wraps child routes in a persistent UI shell (e.g., `BottomNavigationBar`). `StatefulShellRoute` maintains state of parallel branches.
-- **Path URL Strategy**: Removes the default `#` from web URLs.
+- **GoRouter**: The central configuration object defining the application's route tree.
+- **GoRoute**: A standard route mapping a URL path to a Flutter screen.
+- **ShellRoute / StatefulShellRoute**: Wraps child routes in a persistent UI shell (e.g., a `BottomNavigationBar`). `StatefulShellRoute` maintains the state of parallel navigation branches.
+- **Path URL Strategy**: Removes the default `#` fragment from web URLs, essential for clean deep linking across platforms.
 
 ## Workflow: Initializing the Application and Router
 
+Follow this workflow to bootstrap a new Flutter application with `go_router` and configure the root routing mechanism.
+
 ### Task Progress
 
 - [ ] Create the Flutter application.
-- [ ] Add `go_router`: `flutter pub add go_router`.
-- [ ] Configure URL strategy with `usePathUrlStrategy()`.
+- [ ] Add the `go_router` dependency.
+- [ ] Configure the URL strategy for web/deep linking.
 - [ ] Implement the `GoRouter` configuration.
 - [ ] Bind the router to `MaterialApp.router`.
 
+### 1. Scaffold the Application
+
+Run the following commands to create the app and add the required routing package:
+
+```bash
+flutter create <app-name>
+cd <app-name>
+flutter pub add go_router
+```
+
+### 2. Configure the Router
+
+Define a top-level `GoRouter` instance. Handle authentication or state-based routing using the `redirect` parameter.
+
 ```dart
 import 'package:flutter/material.dart';
 import 'package:go_router/go_router.dart';
 import 'package:flutter_web_plugins/url_strategy.dart';
 
 void main() {
+  // Use path URL strategy to remove the '#' from web URLs
   usePathUrlStrategy();
   runApp(const MyApp());
 }
@@ -61,25 +79,115 @@ final GoRouter _router = GoRouter(
 
 class MyApp extends StatelessWidget {
   const MyApp({super.key});
+
   @override
   Widget build(BuildContext context) {
-    return MaterialApp.router(routerConfig: _router, title: 'Routing App');
+    return MaterialApp.router(
+      routerConfig: _router,
+      title: 'Routing App',
+    );
   }
 }
 ```
 
 ## Workflow: Configuring Platform Deep Linking
 
+Configure the native platforms to intercept specific URLs and route them into the Flutter application.
+
 ### Task Progress
 
 - [ ] Determine target platforms (iOS, Android, or both).
-- [ ] **Android:** Add intent filter to `AndroidManifest.xml` + host `assetlinks.json`.
-- [ ] **iOS:** Set `FlutterDeepLinkingEnabled` in `Info.plist` + add associated domain in entitlements + host `apple-app-site-association`.
-- [ ] Test via ADB (Android) or `xcrun simctl openurl` (iOS).
+- [ ] Apply conditional configuration for Android (Manifest + Asset Links).
+- [ ] Apply conditional configuration for iOS (Plist + Entitlements + AASA).
+- [ ] Run validator -> review errors -> fix.
+
+### If configuring for Android:
+
+1. **Modify `AndroidManifest.xml`**: Add the intent filter inside the `<activity>` tag for `.MainActivity`.
+
+```xml
+<intent-filter android:autoVerify="true">
+    <action android:name="android.intent.action.VIEW" />
+    <category android:name="android.intent.category.DEFAULT" />
+    <category android:name="android.intent.category.BROWSABLE" />
+    <data android:scheme="http" android:host="yourdomain.com" />
+    <data android:scheme="https" />
+</intent-filter>
+```
+
+2. **Host `assetlinks.json`**: Serve the following JSON at `https://yourdomain.com/.well-known/assetlinks.json`.
+
+```json
+[
+  {
+    "relation": ["delegate_permission/common.handle_all_urls"],
+    "target": {
+      "namespace": "android_app",
+      "package_name": "com.yourcompany.yourapp",
+      "sha256_cert_fingerprints": ["YOUR_SHA256_FINGERPRINT"]
+    }
+  }
+]
+```
+
+### If configuring for iOS:
+
+1. **Modify `Info.plist`**: Opt-in to Flutter's default deep link handler.
+   _Note: If using a third-party deep linking plugin (e.g., `app_links`), set this to `NO` to prevent conflicts._
+
+```xml
+<key>FlutterDeepLinkingEnabled</key>
+<true/>
+```
+
+2. **Modify `Runner.entitlements`**: Add the associated domain.
+
+```xml
+<key>com.apple.developer.associated-domains</key>
+<array>
+  <string>applinks:yourdomain.com</string>
+</array>
+```
+
+3. **Host `apple-app-site-association`**: Serve the following JSON (without a `.json` extension) at `https://yourdomain.com/.well-known/apple-app-site-association`.
+
+```json
+{
+  "applinks": {
+    "apps": [],
+    "details": [
+      {
+        "appIDs": ["TEAM_ID.com.yourcompany.yourapp"],
+        "paths": ["*"],
+        "components": [{ "/": "/*" }]
+      }
+    ]
+  }
+}
+```
+
+### Validation Loop
+
+Run validator -> review errors -> fix.
+
+- **Android**: Test using ADB.
+  ```bash
+  adb shell 'am start -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "https://yourdomain.com/details/123"' com.yourcompany.yourapp
+  ```
+- **iOS**: Test using `xcrun` on a booted simulator.
+  ```bash
+  xcrun simctl openurl booted https://yourdomain.com/details/123
+  ```
 
 ## Workflow: Implementing Nested Navigation
 
-Use `StatefulShellRoute.indexedStack` to implement persistent shells with tab navigation.
+Use `StatefulShellRoute` to implement persistent UI shells (like a bottom navigation bar) that maintain the state of their child routes.
+
+### Task Progress
+
+- [ ] Define `StatefulShellRoute.indexedStack` in the `GoRouter` configuration.
+- [ ] Create `StatefulShellBranch` instances for each navigation tab.
+- [ ] Implement the shell widget using `StatefulNavigationShell`.
 
 ```dart
 final GoRouter _router = GoRouter(
@@ -90,12 +198,22 @@ final GoRouter _router = GoRouter(
         return ScaffoldWithNavBar(navigationShell: navigationShell);
       },
       branches: [
-        StatefulShellBranch(routes: [
-          GoRoute(path: '/home', builder: (context, state) => const HomeScreen()),
-        ]),
-        StatefulShellBranch(routes: [
-          GoRoute(path: '/settings', builder: (context, state) => const SettingsScreen()),
-        ]),
+        StatefulShellBranch(
+          routes: [
+            GoRoute(
+              path: '/home',
+              builder: (context, state) => const HomeScreen(),
+            ),
+          ],
+        ),
+        StatefulShellBranch(
+          routes: [
+            GoRoute(
+              path: '/settings',
+              builder: (context, state) => const SettingsScreen(),
+            ),
+          ],
+        ),
       ],
     ),
   ],
@@ -104,25 +222,25 @@ final GoRouter _router = GoRouter(
 
 ## Examples
 
-### Programmatic Navigation
-
-```dart
-context.go('/details/123');        // Replace current stack
-context.push('/details/123');      // Push onto stack
-context.goNamed('details', pathParameters: {'id': '123'});
-context.pop();
-```
+### High-Fidelity Shell Widget Implementation
 
-### Shell Widget Implementation
+Implement the UI shell that consumes the `StatefulNavigationShell` to handle branch switching.
 
 ```dart
 class ScaffoldWithNavBar extends StatelessWidget {
-  const ScaffoldWithNavBar({required this.navigationShell, super.key});
+  const ScaffoldWithNavBar({
+    required this.navigationShell,
+    super.key,
+  });
+
   final StatefulNavigationShell navigationShell;
 
   void _goBranch(int index) {
-    navigationShell.goBranch(index,
-      initialLocation: index == navigationShell.currentIndex);
+    navigationShell.goBranch(
+      index,
+      // Support navigating to the initial location when tapping the active tab.
+      initialLocation: index == navigationShell.currentIndex,
+    );
   }
 
   @override
@@ -142,6 +260,24 @@ class ScaffoldWithNavBar extends StatelessWidget {
 }
 ```
 
+### Programmatic Navigation
+
+Use the `context.go()` and `context.push()` extension methods provided by `go_router`.
+
+```dart
+// Replaces the current route stack with the target route (Declarative)
+context.go('/details/123');
+
+// Pushes the target route onto the existing stack (Imperative)
+context.push('/details/123');
+
+// Navigates using a named route and path parameters
+context.goNamed('details', pathParameters: {'id': '123'});
+
+// Pops the current route
+context.pop();
+```
+
 ## Flutter Ultra Integration
 
 After configuring routes, test navigation in the running app: