Improve troubleshooting docs and format package names consistently

- Fix troubleshooting.md: remove incorrect sections, add correct examples
- Extract all inline code examples to separate .dart files for compilation
- Format package names (watch_it, get_it, command_it) as code in markdown
- Use <code> tags for package names inside HTML elements
- Add Bloc/Cubit to Quick Navigation in without_watch_it.md
- Add notifyOnlyWhenValueChanges and includeLastResultInCommandResults docs

Author: escamoteur

code_samples/lib/command_it/_shared/stubs.dart

@@ -55,8 +55,8 @@ class UnauthorizedException implements Exception {
   String toString() => 'UnauthorizedException: $message';
 }
 
-// Toast/Snackbar service for error examples
-class ToastService {
+// Toast/Snackbar manager for error examples
+class ToastManager {
   void showError(String message) {
     debugPrint('Toast: $message');
   }
@@ -70,8 +70,8 @@ class ToastService {
   }
 }
 
-// Analytics service for error tracking examples
-class AnalyticsService {
+// Analytics manager for error tracking examples
+class AnalyticsManager {
   void logError(Object error, StackTrace? stackTrace) {
     debugPrint('Analytics: Error logged - $error');
   }
@@ -81,6 +81,55 @@ class AnalyticsService {
   }
 }
 
+// Database stub
+class Database {
+  Future<void> initialize() async {}
+}
+
+// User class for auth examples
+class User {
+  final String id;
+  final String name;
+
+  User(this.id, this.name);
+
+  static User empty() => User('', '');
+}
+
+// Profile class for examples
+class Profile {
+  final String name;
+
+  Profile(this.name);
+
+  static Profile empty() => Profile('');
+}
+
+// Generic Data class for examples
+class Data {
+  final String? id;
+  final String? value;
+
+  Data([this.id, this.value]);
+
+  static Data empty() => Data();
+}
+
+// Form data for examples
+class FormData {
+  final Map<String, dynamic> fields;
+
+  FormData([this.fields = const {}]);
+}
+
+// Search result
+class Result {
+  final String id;
+  final String title;
+
+  Result(this.id, this.title);
+}
+
 // Additional models for command examples
 class Todo {
   final String id;
@@ -134,6 +183,38 @@ Future<void> simulateDelay([int milliseconds = 500]) {
 
 // Extension on ApiClient for command_it examples
 extension ApiClientCommandExtensions on ApiClient {
+  Future<List<Data>> fetchData() async {
+    await simulateDelay();
+    return [Data('1', 'value1'), Data('2', 'value2')];
+  }
+
+  Future<void> save(Data data) async {
+    await simulateDelay();
+  }
+
+  Future<void> submit(FormData data) async {
+    await simulateDelay();
+  }
+
+  Future<List<Result>> search(String query) async {
+    await simulateDelay();
+    return [Result('1', 'Result for $query')];
+  }
+
+  Future<User> login(String username, String password) async {
+    await simulateDelay();
+    return User('1', username);
+  }
+
+  Future<void> logout() async {
+    await simulateDelay();
+  }
+
+  Future<Profile> loadProfile() async {
+    await simulateDelay();
+    return Profile('John Doe');
+  }
+
   Future<List<Todo>> fetchTodos() async {
     await simulateDelay();
     return fakeTodos;
@@ -173,3 +254,31 @@ extension ApiClientCommandExtensions on ApiClient {
 void showSnackBar(String message) {
   debugPrint('SnackBar: $message');
 }
+
+// Progress Control stubs
+class Item {
+  final String? id;
+  final String? name;
+
+  Item([this.id, this.name]);
+}
+
+Future<void> uploadChunk(dynamic file, int chunkIndex) async {
+  await simulateDelay(50);
+}
+
+Future<void> downloadData() async {
+  await simulateDelay(300);
+}
+
+Future<void> processData() async {
+  await simulateDelay(300);
+}
+
+Future<void> saveResults() async {
+  await simulateDelay(300);
+}
+
+Future<void> processItem(Item item) async {
+  await simulateDelay(100);
+}

code_samples/lib/command_it/best_practices_antipatterns.dart

@@ -0,0 +1,132 @@
+// ignore_for_file: unused_local_variable, unused_field
+import 'package:command_it/command_it.dart';
+import 'package:flutter/material.dart';
+import '_shared/stubs.dart';
+
+final api = ApiClient();
+
+// #region not_listening_errors
+// ❌ BAD: Errors go nowhere
+late final commandNoListener = Command.createAsyncNoParam<Data>(
+  () => api.fetchData().then((list) => list.first),
+  initialValue: Data.empty(),
+  errorFilter: const LocalErrorFilter(),
+);
+// No error listener! Assertions in debug mode
+
+// ✅ GOOD: Always listen to errors when using localHandler
+void setupGoodErrorListener() {
+  commandNoListener.errors.listen((error, _) {
+    if (error != null) showError(error.error);
+  });
+}
+
+void showError(Object error) {
+  debugPrint('Error: $error');
+}
+// #endregion not_listening_errors
+
+// #region try_catch_inside
+// ❌ BAD: try/catch inside command function
+class DataManagerBad {
+  late final loadCommand = Command.createAsyncNoParam<Data>(
+    () async {
+      try {
+        final list = await api.fetchData();
+        return list.first;
+      } catch (e) {
+        // Manual error handling defeats command_it's error system
+        debugPrint('Error: $e');
+        rethrow;
+      }
+    },
+    initialValue: Data.empty(),
+  );
+}
+
+// ✅ GOOD: Let command handle errors, use ..errors.listen()
+class DataManagerGood {
+  late final loadCommand = Command.createAsyncNoParam<Data>(
+    () async {
+      final list = await api.fetchData();
+      return list.first;
+    },
+    initialValue: Data.empty(),
+  )..errors.listen((error, _) {
+      if (error != null) {
+        debugPrint('Error: ${error.error}');
+      }
+    });
+}
+// #endregion try_catch_inside
+
+// #region excessive_results
+class ExcessiveResultsExample extends StatelessWidget {
+  final Command<void, String> command;
+
+  const ExcessiveResultsExample({super.key, required this.command});
+
+  @override
+  Widget build(BuildContext context) {
+    return Column(
+      children: [
+        // ❌ BAD: Always using .results when not needed
+        ValueListenableBuilder(
+          valueListenable: command.results,
+          builder: (context, result, _) {
+            return Text(result.data?.toString() ?? '');
+          },
+        ),
+        // Rebuilds on running, error, success
+
+        // ✅ GOOD: Use .value for data-only updates
+        ValueListenableBuilder(
+          valueListenable: command,
+          builder: (context, data, _) {
+            return Text(data.toString());
+          },
+        ),
+        // Only rebuilds on successful completion
+      ],
+    );
+  }
+}
+// #endregion excessive_results
+
+// #region forgetting_initial
+// ❌ WRONG: Missing initialValue would be compile error
+// late final commandMissing = Command.createAsyncNoParam<String>(
+//   () => api.load(),
+//   // Missing initialValue!
+// );
+
+// ✅ CORRECT: Always provide initialValue
+late final commandWithInitial = Command.createAsyncNoParam<String>(
+  () async => 'loaded',
+  initialValue: '', // Required for non-void results
+);
+// #endregion forgetting_initial
+
+// #region sync_isrunning
+// ❌ WRONG: Sync commands don't have meaningful isRunning
+final syncCommand = Command.createSyncNoParam<String>(
+  () => 'result',
+  initialValue: '',
+);
+
+// Accessing isRunning on sync command - always false
+// ValueListenableBuilder(
+//   valueListenable: syncCommand.isRunning, // Not useful!
+//   builder: ...,
+// );
+
+// ✅ CORRECT: Use async command if you need isRunning
+final asyncCommand = Command.createAsyncNoParam<String>(
+  () async => 'result',
+  initialValue: '',
+);
+// #endregion sync_isrunning
+
+void main() {
+  setupGoodErrorListener();
+}