sdd-full 4.8.0 → 4.8.2

package/skills/flutter-skills/skills/flutter-build-responsive-layout/SKILL.md

@@ -1,139 +0,0 @@
----
-name: flutter-build-responsive-layout
-description: Use `LayoutBuilder`, `MediaQuery`, or `Expanded/Flexible` to create a layout that adapts to different screen sizes. Use when you need the UI to look good on both mobile and tablet/desktop form factors.
-metadata:
-  model: models/gemini-3.1-pro-preview
-  last_modified: Tue, 21 Apr 2026 20:17:40 GMT
----
-# Implementing Adaptive Layouts
-
-## Contents
-- [Space Measurement Guidelines](#space-measurement-guidelines)
-- [Widget Sizing and Constraints](#widget-sizing-and-constraints)
-- [Device and Orientation Behaviors](#device-and-orientation-behaviors)
-- [Workflow: Constructing an Adaptive Layout](#workflow-constructing-an-adaptive-layout)
-- [Workflow: Optimizing for Large Screens](#workflow-optimizing-for-large-screens)
-- [Examples](#examples)
-
-## Space Measurement Guidelines
-Determine the available space accurately to ensure layouts adapt to the app window, not just the physical device.
-
-*   **Use `MediaQuery.sizeOf(context)`** to get the size of the entire app window.
-*   **Use `LayoutBuilder`** to make layout decisions based on the parent widget's allocated space. Evaluate `constraints.maxWidth` to determine the appropriate widget tree to return.
-*   **Do not use `MediaQuery.orientationOf` or `OrientationBuilder`** near the top of the widget tree to switch layouts. Device orientation does not accurately reflect the available app window space.
-*   **Do not check for hardware types** (e.g., "phone" vs. "tablet"). Flutter apps run in resizable windows, multi-window modes, and picture-in-picture. Base all layout decisions strictly on available window space.
-
-## Widget Sizing and Constraints
-Understand and apply Flutter's core layout rule: **Constraints go down. Sizes go up. Parent sets position.**
-
-*   **Distribute Space:** Use `Expanded` and `Flexible` within `Row`, `Column`, or `Flex` widgets.
-    *   Use `Expanded` to force a child to fill all remaining available space (equivalent to `Flexible` with `fit: FlexFit.tight` and a `flex` factor of 1.0).
-    *   Use `Flexible` to allow a child to size itself up to a specific limit while still expanding/contracting. Use the `flex` factor to define the ratio of space consumption among siblings.
-*   **Constrain Width:** Prevent widgets from consuming all horizontal space on large screens. Wrap widgets like `GridView` or `ListView` in a `ConstrainedBox` or `Container` and define a `maxWidth` in the `BoxConstraints`.
-*   **Lazy Rendering:** Always use `ListView.builder` or `GridView.builder` when rendering lists with an unknown or large number of items.
-
-## Device and Orientation Behaviors
-Ensure the app behaves correctly across all device form factors and input methods.
-
-*   **Do not lock screen orientation.** Locking orientation causes severe layout issues on foldable devices, often resulting in letterboxing (the app centered with black borders). Android large format tiers require both portrait and landscape support.
-*   **Fallback for Locked Orientation:** If business requirements strictly mandate a locked orientation, use the `Display API` to retrieve physical screen dimensions instead of `MediaQuery`. `MediaQuery` fails to receive the larger window size in compatibility modes.
-*   **Support Multiple Inputs:** Implement support for basic mice, trackpads, and keyboard shortcuts. Ensure touch targets are appropriately sized and keyboard navigation is accessible.
-
-## Workflow: Constructing an Adaptive Layout
-
-Follow this workflow to implement a layout that adapts to the available `BoxConstraints`.
-
-**Task Progress:**
-- [ ] Identify the target widget that requires adaptive behavior.
-- [ ] Wrap the widget tree in a `LayoutBuilder`.
-- [ ] Extract the `constraints.maxWidth` from the builder callback.
-- [ ] Define an adaptive breakpoint (e.g., `largeScreenMinWidth = 600`).
-- [ ] **If `maxWidth > largeScreenMinWidth`:** Return a large-screen layout (e.g., a `Row` placing a navigation sidebar and content area side-by-side).
-- [ ] **If `maxWidth <= largeScreenMinWidth`:** Return a small-screen layout (e.g., a `Column` or standard navigation-style approach).
-- [ ] Run validator -> resize the application window -> review layout transitions -> fix overflow errors.
-
-## Workflow: Optimizing for Large Screens
-
-Follow this workflow to prevent UI elements from stretching unnaturally on large displays.
-
-**Task Progress:**
-- [ ] Identify full-width components (e.g., `ListView`, text blocks, forms).
-- [ ] **If optimizing a list:** Convert `ListView.builder` to `GridView.builder` using `SliverGridDelegateWithMaxCrossAxisExtent` to automatically adjust column counts based on window size.
-- [ ] **If optimizing a form or text block:** Wrap the component in a `ConstrainedBox`.
-- [ ] Apply `BoxConstraints(maxWidth: [optimal_width])` to the `ConstrainedBox`.
-- [ ] Wrap the `ConstrainedBox` in a `Center` widget to keep the constrained content centered on large screens.
-- [ ] Run validator -> test on desktop/tablet target -> review horizontal stretching -> adjust `maxWidth` or grid extents.
-
-## Examples
-
-### Adaptive Layout using LayoutBuilder
-Demonstrates switching between a mobile and desktop layout based on available width.
-
-```dart
-import 'package:flutter/material.dart';
-
-const double largeScreenMinWidth = 600.0;
-
-class AdaptiveLayout extends StatelessWidget {
-  const AdaptiveLayout({super.key});
-
-  @override
-  Widget build(BuildContext context) {
-    return LayoutBuilder(
-      builder: (context, constraints) {
-        if (constraints.maxWidth > largeScreenMinWidth) {
-          return _buildLargeScreenLayout();
-        } else {
-          return _buildSmallScreenLayout();
-        }
-      },
-    );
-  }
-
-  Widget _buildLargeScreenLayout() {
-    return Row(
-      children: [
-        const SizedBox(width: 250, child: Placeholder(color: Colors.blue)),
-        const VerticalDivider(width: 1),
-        Expanded(child: const Placeholder(color: Colors.green)),
-      ],
-    );
-  }
-
-  Widget _buildSmallScreenLayout() {
-    return const Placeholder(color: Colors.green);
-  }
-}
-```
-
-### Constraining Width on Large Screens
-Demonstrates preventing a widget from consuming all horizontal space.
-
-```dart
-import 'package:flutter/material.dart';
-
-class ConstrainedContent extends StatelessWidget {
-  const ConstrainedContent({super.key});
-
-  @override
-  Widget build(BuildContext context) {
-    return Scaffold(
-      body: Center(
-        child: ConstrainedBox(
-          constraints: const BoxConstraints(
-            maxWidth: 800.0, // Maximum width for readability
-          ),
-          child: ListView.builder(
-            itemCount: 50,
-            itemBuilder: (context, index) {
-              return ListTile(
-                title: Text('Item $index'),
-              );
-            },
-          ),
-        ),
-      ),
-    );
-  }
-}
-```

package/skills/flutter-skills/skills/flutter-fix-layout-issues/SKILL.md

@@ -1,130 +0,0 @@
----
-name: flutter-fix-layout-issues
-description: Fixes Flutter layout errors (overflows, unbounded constraints) using Dart and Flutter MCP tools. Use when addressing "RenderFlex overflowed", "Vertical viewport was given unbounded height", or similar layout issues.
-metadata:
-  model: models/gemini-3.1-pro-preview
-  last_modified: Tue, 21 Apr 2026 19:45:59 GMT
----
-# Resolving Flutter Layout Errors
-
-## Contents
-- [Constraint Violation Diagnostics](#constraint-violation-diagnostics)
-- [Layout Error Resolution Workflow](#layout-error-resolution-workflow)
-- [Examples](#examples)
-
-## Constraint Violation Diagnostics
-
-Flutter layout operates on a strict rule: **Constraints go down. Sizes go up. Parent sets position.** Layout errors occur when this negotiation fails, typically due to unbounded constraints or unconstrained children. 
-
-Diagnose layout failures using the following error signatures:
-
-*   **"Vertical viewport was given unbounded height"**: Triggered when a scrollable widget (`ListView`, `GridView`) is placed inside an unconstrained vertical parent (`Column`). The parent provides infinite height, and the child attempts to expand infinitely.
-*   **"An InputDecorator...cannot have an unbounded width"**: Triggered when a `TextField` or `TextFormField` is placed inside an unconstrained horizontal parent (`Row`). The text field attempts to determine its width based on infinite available space.
-*   **"RenderFlex overflowed"**: Triggered when a child of a `Row` or `Column` requests a size larger than the parent's allocated constraints. Visually indicated by yellow and black warning stripes.
-*   **"Incorrect use of ParentData widget"**: Triggered when a `ParentDataWidget` is not a direct descendant of its required ancestor. (e.g., `Expanded` outside a `Flex`, `Positioned` outside a `Stack`).
-*   **"RenderBox was not laid out"**: A cascading side-effect error. Ignore this and look further up the stack trace for the primary constraint violation (usually an unbounded height/width error).
-
-## Layout Error Resolution Workflow
-
-Copy and use this checklist to systematically resolve layout constraint violations.
-
-### Task Progress
-- [ ] Run the application in debug mode to capture the exact layout exception in the console.
-- [ ] Identify the primary error message (ignore cascading "RenderBox was not laid out" errors).
-- [ ] Apply the conditional fix based on the specific error type:
-  - **If "Vertical viewport was given unbounded height"**: Wrap the scrollable child (`ListView`, `GridView`) in an `Expanded` widget to consume remaining space, or wrap it in a `SizedBox` to provide an absolute height constraint.
-  - **If "An InputDecorator...cannot have an unbounded width"**: Wrap the `TextField` or `TextFormField` in an `Expanded` or `Flexible` widget.
-  - **If "RenderFlex overflowed"**: Constrain the overflowing child by wrapping it in an `Expanded` widget (to force it to fit) or a `Flexible` widget (to allow it to be smaller than the allocated space).
-  - **If "Incorrect use of ParentData widget"**: Move the `ParentDataWidget` to be a direct child of its required parent. Ensure `Expanded`/`Flexible` are direct children of `Row`/`Column`/`Flex`. Ensure `Positioned` is a direct child of `Stack`.
-- [ ] Execute Flutter hot reload.
-- [ ] Run validator -> review errors -> fix: Inspect the UI to verify the red/grey error screen or yellow/black overflow stripes are resolved. If new layout errors appear, repeat the workflow.
-
-## Examples
-
-### Fixing Unbounded Height (ListView in Column)
-
-**Input (Error State):**
-```dart
-// Throws "Vertical viewport was given unbounded height"
-Column(
-  children: <Widget>[
-    const Text('Header'),
-    ListView(
-      children: const <Widget>[
-        ListTile(title: Text('Item 1')),
-        ListTile(title: Text('Item 2')),
-      ],
-    ),
-  ],
-)
-```
-
-**Output (Resolved State):**
-```dart
-// Wrap ListView in Expanded to constrain its height to the remaining Column space
-Column(
-  children: <Widget>[
-    const Text('Header'),
-    Expanded(
-      child: ListView(
-        children: const <Widget>[
-          ListTile(title: Text('Item 1')),
-          ListTile(title: Text('Item 2')),
-        ],
-      ),
-    ),
-  ],
-)
-```
-
-### Fixing Unbounded Width (TextField in Row)
-
-**Input (Error State):**
-```dart
-// Throws "An InputDecorator...cannot have an unbounded width"
-Row(
-  children: [
-    const Icon(Icons.search),
-    TextField(), 
-  ],
-)
-```
-
-**Output (Resolved State):**
-```dart
-// Wrap TextField in Expanded to constrain its width to the remaining Row space
-Row(
-  children: [
-    const Icon(Icons.search),
-    Expanded(
-      child: TextField(),
-    ),
-  ],
-)
-```
-
-### Fixing RenderFlex Overflow
-
-**Input (Error State):**
-```dart
-// Throws "A RenderFlex overflowed by X pixels on the right"
-Row(
-  children: [
-    const Icon(Icons.info),
-    const Text('This is a very long text string that will definitely overflow the available screen width and cause a RenderFlex error.'),
-  ],
-)
-```
-
-**Output (Resolved State):**
-```dart
-// Wrap the Text widget in Expanded to force it to wrap within the available constraints
-Row(
-  children: [
-    const Icon(Icons.info),
-    Expanded(
-      child: const Text('This is a very long text string that will definitely overflow the available screen width and cause a RenderFlex error.'),
-    ),
-  ],
-)
-```

package/skills/flutter-skills/skills/flutter-implement-json-serialization/SKILL.md

@@ -1,153 +0,0 @@
----
-name: flutter-implement-json-serialization
-description: Create model classes with `fromJson` and `toJson` methods using `dart:convert`. Use when manually mapping JSON keys to class properties for simple data structures.
-metadata:
-  model: models/gemini-3.1-pro-preview
-  last_modified: Tue, 21 Apr 2026 21:44:50 GMT
----
-# Serializing JSON Manually in Flutter
-
-## Contents
-- [Core Guidelines](#core-guidelines)
-- [Workflow: Implementing a Serializable Model](#workflow-implementing-a-serializable-model)
-- [Workflow: Fetching and Parsing JSON](#workflow-fetching-and-parsing-json)
-- [Examples](#examples)
-
-## Core Guidelines
-
-- **Import `dart:convert`**: Utilize Flutter's built-in `dart:convert` library for manual JSON encoding (`jsonEncode`) and decoding (`jsonDecode`).
-- **Enforce Type Safety**: Always cast the `dynamic` result of `jsonDecode()` to the expected type, typically `Map<String, dynamic>` for objects or `List<dynamic>` for arrays.
-- **Encapsulate Serialization Logic**: Define plain model classes containing properties corresponding to the JSON structure. Implement a `fromJson` factory constructor and a `toJson` method within the model.
-- **Handle Background Parsing**: If parsing large JSON documents (execution time > 16ms), offload the parsing logic to a separate isolate using Flutter's `compute()` function to prevent UI jank.
-- **Throw Exceptions on Failure**: When handling HTTP responses, throw an exception if the status code is not successful (e.g., not 200 OK or 201 Created). Do not return `null`.
-
-## Workflow: Implementing a Serializable Model
-
-Use this checklist to implement manual JSON serialization for a data model.
-
-**Task Progress:**
-- [ ] Define the plain model class with `final` properties.
-- [ ] Implement the `factory Model.fromJson(Map<String, dynamic> json)` constructor.
-- [ ] Implement the `Map<String, dynamic> toJson()` method.
-- [ ] Write unit tests for both serialization methods.
-- [ ] Run validator -> review type mismatch errors -> fix casting logic.
-
-1. **Define the Model**: Create a class with properties matching the JSON keys.
-2. **Implement `fromJson`**: Extract values from the `Map` and cast them to the appropriate Dart types. Use pattern matching or explicit casting.
-3. **Implement `toJson`**: Return a `Map<String, dynamic>` mapping the class properties back to their JSON string keys.
-4. **Validate**: Execute unit tests to ensure type safety, autocompletion, and compile-time exception handling function correctly.
-
-## Workflow: Fetching and Parsing JSON
-
-Use this conditional workflow when retrieving and parsing JSON from a network request.
-
-**Task Progress:**
-- [ ] Execute the HTTP request.
-- [ ] Validate the response status code.
-- [ ] Determine parsing strategy (Synchronous vs. Isolate).
-- [ ] Decode and map the JSON to the model.
-
-1. **Execute Request**: Use the `http` package to perform the network call.
-2. **Validate Response**: 
-   - If `response.statusCode == 200` (or 201 for POST), proceed to parsing.
-   - If the status code indicates failure, throw an `Exception`.
-3. **Determine Parsing Strategy**:
-   - If parsing a **small payload** (e.g., a single object), parse synchronously on the main thread.
-   - If parsing a **large payload** (e.g., an array of thousands of objects), use `compute(parseFunction, response.body)` to parse in a background isolate.
-4. **Decode and Map**: Pass the decoded JSON to your model's `fromJson` constructor.
-
-## Examples
-
-### High-Fidelity Model Implementation
-
-```dart
-import 'dart:convert';
-
-class User {
-  final int id;
-  final String name;
-  final String email;
-
-  const User({
-    required this.id,
-    required this.name,
-    required this.email,
-  });
-
-  // Factory constructor for deserialization
-  factory User.fromJson(Map<String, dynamic> json) {
-    return switch (json) {
-      {
-        'id': int id,
-        'name': String name,
-        'email': String email,
-      } => 
-        User(
-          id: id,
-          name: name,
-          email: email,
-        ),
-      _ => throw const FormatException('Failed to load User.'),
-    };
-  }
-
-  // Method for serialization
-  Map<String, dynamic> toJson() {
-    return {
-      'id': id,
-      'name': name,
-      'email': email,
-    };
-  }
-}
-```
-
-### Synchronous Parsing (Small Payload)
-
-```dart
-import 'dart:convert';
-import 'package:http/http.dart' as http;
-
-Future<User> fetchUser(http.Client client, int userId) async {
-  final response = await client.get(
-    Uri.parse('https://api.example.com/users/$userId'),
-    headers: {'Accept': 'application/json'},
-  );
-
-  if (response.statusCode == 200) {
-    // Decode returns dynamic, cast to Map<String, dynamic>
-    final Map<String, dynamic> jsonMap = jsonDecode(response.body) as Map<String, dynamic>;
-    return User.fromJson(jsonMap);
-  } else {
-    throw Exception('Failed to load user');
-  }
-}
-```
-
-### Background Parsing (Large Payload)
-
-```dart
-import 'dart:convert';
-import 'package:flutter/foundation.dart';
-import 'package:http/http.dart' as http;
-
-// Top-level function required for compute()
-List<User> parseUsers(String responseBody) {
-  final parsed = (jsonDecode(responseBody) as List<dynamic>).cast<Map<String, dynamic>>();
-  return parsed.map<User>((json) => User.fromJson(json)).toList();
-}
-
-Future<List<User>> fetchUsers(http.Client client) async {
-  final response = await client.get(
-    Uri.parse('https://api.example.com/users'),
-    headers: {'Accept': 'application/json'},
-  );
-
-  if (response.statusCode == 200) {
-    // Offload expensive parsing to a background isolate
-    return compute(parseUsers, response.body);
-  } else {
-    throw Exception('Failed to load users');
-  }
-}
-```

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

@@ -1,255 +0,0 @@
----
-name: flutter-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.
-metadata:
-  model: models/gemini-3.1-pro-preview
-  last_modified: Tue, 21 Apr 2026 21:08:03 GMT
----
-# Implementing Routing and Deep Linking
-
-## Contents
-- [Core Concepts](#core-concepts)
-- [Workflow: Initializing the Application and Router](#workflow-initializing-the-application-and-router)
-- [Workflow: Configuring Platform Deep Linking](#workflow-configuring-platform-deep-linking)
-- [Workflow: Implementing Nested Navigation](#workflow-implementing-nested-navigation)
-- [Examples](#examples)
-
-## Core Concepts
-
-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**: 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 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());
-}
-
-final GoRouter _router = GoRouter(
-  initialLocation: '/',
-  routes: [
-    GoRoute(
-      path: '/',
-      builder: (context, state) => const HomeScreen(),
-      routes: [
-        GoRoute(
-          path: 'details/:id',
-          builder: (context, state) => DetailsScreen(id: state.pathParameters['id']!),
-        ),
-      ],
-    ),
-  ],
-  errorBuilder: (context, state) => ErrorScreen(error: state.error),
-);
-
-class MyApp extends StatelessWidget {
-  const MyApp({super.key});
-
-  @override
-  Widget build(BuildContext context) {
-    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).
-- [ ] 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` 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(
-  initialLocation: '/home',
-  routes: [
-    StatefulShellRoute.indexedStack(
-      builder: (context, state, navigationShell) {
-        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(),
-            ),
-          ],
-        ),
-      ],
-    ),
-  ],
-);
-```
-
-## Examples
-
-### High-Fidelity 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,
-  });
-
-  final StatefulNavigationShell navigationShell;
-
-  void _goBranch(int index) {
-    navigationShell.goBranch(
-      index,
-      // Support navigating to the initial location when tapping the active tab.
-      initialLocation: index == navigationShell.currentIndex,
-    );
-  }
-
-  @override
-  Widget build(BuildContext context) {
-    return Scaffold(
-      body: navigationShell,
-      bottomNavigationBar: NavigationBar(
-        selectedIndex: navigationShell.currentIndex,
-        onDestinationSelected: _goBranch,
-        destinations: const [
-          NavigationDestination(icon: Icon(Icons.home), label: 'Home'),
-          NavigationDestination(icon: Icon(Icons.settings), label: 'Settings'),
-        ],
-      ),
-    );
-  }
-}
-```
-
-### 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();
-```