docs: document recommended state/controller registration pattern for consumer apps (#18)

* docs: document recommended state/controller registration pattern for consumer apps

Add architecture reference (doc/architecture/controllers.md) covering the
lazy singleton pattern, MagicController + MagicStateMixin usage, controller
lifecycle, view binding, and a decision tree for eager vs lazy vs per-view
registration. Add practical getting-started guide (doc/guides/state-management.md)
with end-to-end examples. Update scaffolded app_service_provider.stub with
state registration guidance comments. Add cross-references in service-provider.md.

Closes #17

* fix: address PR #18 review comments

- controllers.md: clarify MagicStateMixin<bool> is most common, not
  universal (Newsletter/OTP use untyped); qualify NavigatesRoutes usage;
  note NotificationsListView as MagicStatefulView exception; fix
  views-and-layouts Related URL (architecture → basics)
- state-management.md: fix "five-state" → "four-state"; fix
  _isSubmitting → _isLoading consistency; fix flutter/widgets.dart →
  flutter/material.dart for Icons.* usage; rename Pattern B section
  to "Manual Access" matching actual content
- README.md: use hosted doc URLs instead of repo-relative paths
- stub: replace local doc path with generic package docs reference

Author: anilcancakir

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+- Documentation for recommended state/controller registration pattern for consumer apps (`doc/architecture/controllers.md`, `doc/guides/state-management.md`)
+- State registration guidance in scaffolded `app_service_provider.stub`
+
 ## [0.0.1-alpha.8] - 2026-03-31
 
 ### 🐛 Bug Fixes

README.md

@@ -379,6 +379,8 @@ App launch → MagicStarterServiceProvider.boot()
 | [Manager](https://magic.fluttersdk.com/packages/starter/architecture/manager) | Singleton manager and customization hooks |
 | [Service Provider](https://magic.fluttersdk.com/packages/starter/architecture/service-provider) | Bootstrap lifecycle, Gate abilities, IoC bindings |
 | [View Registry](https://magic.fluttersdk.com/packages/starter/architecture/view-registry) | String-keyed builders and host app overrides |
+| [Controllers & State Registration](https://magic.fluttersdk.com/packages/starter/architecture/controllers) | Recommended state/controller registration pattern for consumer apps |
+| [State Management Guide](https://magic.fluttersdk.com/packages/starter/guides/state-management) | State management best practices and patterns |
 
 ---
 

assets/stubs/install/app_service_provider.stub

@@ -73,5 +73,25 @@ class AppServiceProvider extends ServiceProvider {
 {{ teams_block }}
 {{ social_login_block }}
 {{ notifications_block }}
+
+        // -------------------------------------------------------------------
+        // State Registration (optional — for eager initialization)
+        // -------------------------------------------------------------------
+        // Most state classes should use the lazy singleton pattern with a
+        // static accessor instead of registering here:
+        //
+        //   class ProjectState extends MagicController
+        //       with MagicStateMixin<List<Project>> {
+        //     static ProjectState get instance =>
+        //         Magic.findOrPut(ProjectState.new);
+        //   }
+        //
+        // Only register here if the state needs to be ready before any view
+        // renders (e.g., WebSocket connection, auth-dependent init):
+        //
+        //   Magic.findOrPut(DashboardState.new);
+        //
+        // See the Magic Starter package documentation/repository for the
+        // controller architecture guide.
     }
 }