docs: add comprehensive Riverpod 3.0 migration documentation and Priority 1 implementation

Priority 1 (COMPLETE):
- Add riverpod_lint and custom_lint packages
- Update analysis_options.yaml with custom_lint plugin
- Update AGENTS.md with Riverpod 3.0 best practices
- Fix unsafe ref usage in modern_chat_input.dart
- All tests passing, zero breaking changes

Priority 2 (PLANNED):
- Complete migration plan for 39 providers (RIVERPOD_PRIORITY2_PLAN.md)
- Quick reference guide (RIVERPOD_PRIORITY2_QUICKREF.md)
- Progress tracker (RIVERPOD_PRIORITY2_TRACKER.md)
- Master documentation index (RIVERPOD_MIGRATION_INDEX.md)
- Analysis and summary documents

Documentation includes:
- Step-by-step migration examples
- 6-phase implementation plan (23-33 hours)
- Testing strategies and rollback procedures
- Risk assessment and mitigation
- Timeline and resource estimates

RIVERPOD_QUICKSTART.md

@@ -0,0 +1,279 @@
+# Riverpod 3.0 Quick Start Guide
+
+## Immediate Actions (30 minutes)
+
+### Step 1: Add riverpod_lint (5 minutes)
+
+1. **Update `pubspec.yaml`:**
+
+```bash
+cd /Users/cogwheel/Documents/conduit
+```
+
+Add to `dev_dependencies` section:
+
+```yaml
+dev_dependencies:
+  # ... existing dependencies ...
+  riverpod_lint: ^3.0.0
+  custom_lint: ^0.8.0
+```
+
+2. **Install packages:**
+
+```bash
+flutter pub get
+```
+
+3. **Update `analysis_options.yaml`:**
+
+Add this at the top level (same level as `linter:`):
+
+```yaml
+analyzer:
+  plugins:
+    - custom_lint
+```
+
+Full file should look like:
+
+```yaml
+include: package:flutter_lints/flutter.yaml
+
+analyzer:
+  plugins:
+    - custom_lint
+
+linter:
+  rules:
+    avoid_print: true
+```
+
+4. **Run the linter:**
+
+```bash
+dart run custom_lint
+```
+
+This will show Riverpod-specific issues if any exist.
+
+---
+
+### Step 2: Fix Any Linter Issues (10 minutes)
+
+The linter will identify issues like:
+
+- ❌ Using `ref` outside of widgets/providers
+- ❌ Missing `ref.mounted` checks
+- ❌ Incorrect provider usage patterns
+
+**Example Fix:**
+
+If you see: `"ref should not be used outside of a widget/provider"`
+
+```dart
+// ❌ Bad
+class MyService {
+  void doSomething(WidgetRef ref) {  // ref as parameter
+    ref.read(someProvider);
+  }
+}
+
+// ✅ Good
+@riverpod
+class MyService extends _$MyService {
+  @override
+  void build() {}
+  
+  void doSomething() {
+    ref.read(someProvider);  // ref is available in Notifier
+  }
+}
+```
+
+---
+
+### Step 3: Update AGENTS.md (5 minutes)
+
+Replace the state management section in `AGENTS.md`:
+
+**Find (around line 166):**
+
+```markdown
+### State Management
+* **Built-in Solutions:** Prefer Flutter's built-in state management solutions.
+  Do not use a third-party package unless explicitly requested.
+```
+
+**Replace with:**
+
+```markdown
+### State Management
+* **Riverpod 3.0:** This project uses Riverpod 3.0 for state management.
+* **Code Generation:** Always use `@riverpod` annotation with code generation 
+  for new providers. See existing examples in `lib/core/providers/`.
+* **Notifier Classes:** Use `Notifier` and `AsyncNotifier` for mutable state:
+  ```dart
+  @riverpod
+  class Counter extends _$Counter {
+    @override
+    int build() => 0;
+    
+    void increment() => state++;
+  }
+  ```
+* **Provider Functions:** Use `@riverpod` functions for computed/derived state:
+  ```dart
+  @riverpod
+  int doubled(DoubledRef ref) {
+    final count = ref.watch(counterProvider);
+    return count * 2;
+  }
+  ```
+* **Keep Alive:** Use `@Riverpod(keepAlive: true)` for singletons:
+  ```dart
+  @Riverpod(keepAlive: true)
+  class AuthManager extends _$AuthManager { ... }
+  ```
+* **Async Safety:** Always check `ref.mounted` before state updates in async ops:
+  ```dart
+  Future<void> loadData() async {
+    final data = await fetchData();
+    if (!ref.mounted) return;  // ✅ Prevent updates after disposal
+    state = data;
+  }
+  ```
+* **Automatic Retry:** Providers automatically retry on failure with exponential
+  backoff. Customize if needed:
+  ```dart
+  @riverpod
+  Future<Data> myData(MyDataRef ref) async {
+    ref.onDispose(() {
+      // Cleanup
+    });
+    return await fetchData();
+  }
+  ```
+* **Lint Rules:** Use `custom_lint` with `riverpod_lint` to catch common mistakes.
+  Run `dart run custom_lint` before committing.
+```
+
+---
+
+## Validation (10 minutes)
+
+### 1. Run All Checks
+
+```bash
+# Code generation (if needed)
+dart run build_runner build --delete-conflicting-outputs
+
+# Custom lint
+dart run custom_lint
+
+# Standard analysis
+flutter analyze
+
+# Tests
+flutter test
+```
+
+### 2. Expected Results
+
+All should pass ✅ without new errors. You may see some warnings from `riverpod_lint` which are informational.
+
+### 3. Common Warnings and Fixes
+
+#### Warning: "Provider could use autoDispose"
+
+```dart
+// Current
+@riverpod
+Future<Data> myData(MyDataRef ref) async {
+  return await fetch();
+}
+
+// Suggested (if data is short-lived)
+@riverpod
+Future<Data> myData(MyDataRef ref) async {
+  ref.cacheFor(const Duration(minutes: 5));  // Auto-dispose after 5 min
+  return await fetch();
+}
+```
+
+#### Warning: "Missing ref.mounted check"
+
+```dart
+// Current
+Future<void> save() async {
+  await someAsyncOp();
+  state = newValue;  // ⚠️ Might be disposed
+}
+
+// Fixed
+Future<void> save() async {
+  await someAsyncOp();
+  if (!ref.mounted) return;  // ✅
+  state = newValue;
+}
+```
+
+---
+
+## Next Steps (Optional)
+
+After completing the quick start, you can:
+
+1. **Read the full analysis:** See `RIVERPOD_3_ANALYSIS.md`
+2. **Start migration:** Follow Phase 2 in the analysis document
+3. **Add provider docs:** Document provider purposes with dartdoc
+
+---
+
+## Troubleshooting
+
+### Issue: `custom_lint` not found
+
+```bash
+# Reinstall
+flutter pub get
+flutter pub global activate custom_lint
+```
+
+### Issue: Analysis takes too long
+
+```bash
+# Restart Dart analysis server
+# In VS Code: Cmd+Shift+P -> "Dart: Restart Analysis Server"
+# In Android Studio: File -> Invalidate Caches / Restart
+```
+
+### Issue: Generated files out of sync
+
+```bash
+# Clean and rebuild
+flutter clean
+flutter pub get
+dart run build_runner build --delete-conflicting-outputs
+```
+
+---
+
+## Benefits You'll See Immediately
+
+After adding `riverpod_lint`:
+
+✅ **Compile-time safety** - Catch errors before runtime  
+✅ **Better autocomplete** - IDE knows provider types  
+✅ **Quick fixes** - Automatic solutions for common issues  
+✅ **Consistency checks** - Enforced best practices  
+✅ **Refactoring confidence** - Compiler catches all usages  
+
+---
+
+## Questions?
+
+Refer to:
+- Full analysis: `RIVERPOD_3_ANALYSIS.md`
+- Official docs: https://riverpod.dev
+- Linter docs: https://riverpod.dev/docs/concepts/about_riverpod_lint