fix(docs): correct observer and plugin examples across all docs

- Observer: use #[Observer(event: Class::class)] attribute instead of
  string event names or non-existent module.php 'observers' registration
- Plugins: use #[Plugin(target:)], #[Before], #[After] attributes
  instead of non-existent module.php 'plugins' registration
- Fix plugin method signatures: no $subject param, before returns null,
  after receives $result as first arg
- All examples now match the actual core implementation

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: markshust

README.md

@@ -143,7 +143,7 @@ class OrderPlugin
 **Observers** — React to system events:
 
 ```php
-#[Observer('order.placed')]
+#[Observer(event: OrderPlaced::class)]
 class SendOrderNotification
 {
     public function handle(OrderPlaced $event): void

docs/src/content/docs/concepts/events.md

@@ -58,7 +58,7 @@ class PostCreatedEvent
 
 ## Creating Observers
 
-An observer is a class that handles a specific event:
+An observer is a class with the `#[Observer]` attribute that handles a specific event. The `event` parameter specifies which event class to listen for:
 
 ```php title="TrackPostCreation.php"
 <?php
@@ -68,7 +68,9 @@ declare(strict_types=1);
 namespace App\Analytics\Observer;
 
 use Marko\Blog\Event\PostCreatedEvent;
+use Marko\Core\Attributes\Observer;
 
+#[Observer(event: PostCreatedEvent::class)]
 class TrackPostCreation
 {
     public function handle(PostCreatedEvent $event): void
@@ -80,31 +82,26 @@ class TrackPostCreation
 }
 ```
 
-## Registering Observers
+Observers are discovered automatically from module `src/` directories — no manual registration needed.
 
-Observers are registered in `module.php`:
-
-```php title="module.php"
-<?php
+## Observer Priority
 
-declare(strict_types=1);
+When multiple observers listen to the same event, they run by priority (higher values first). Use the `priority` parameter to control order:
 
-use App\Analytics\Observer\TrackPostCreation;
-use Marko\Blog\Event\PostCreatedEvent;
+```php
+#[Observer(event: PostCreatedEvent::class, priority: 10)]
+class HighPriorityObserver
+{
+    public function handle(PostCreatedEvent $event): void { /* ... */ }
+}
 
-return [
-    'observers' => [
-        PostCreatedEvent::class => [
-            TrackPostCreation::class,
-        ],
-    ],
-];
+#[Observer(event: PostCreatedEvent::class, priority: 0)]
+class DefaultPriorityObserver
+{
+    public function handle(PostCreatedEvent $event): void { /* ... */ }
+}
 ```
 
-## Observer Priority
-
-When multiple observers listen to the same event, they run in module priority order (`app/` → `modules/` → `vendor/`). Within the same module, observers run in the order they're listed.
-
 ## Built-in Events
 
 Marko packages dispatch events at meaningful points:

docs/src/content/docs/concepts/plugins.md

@@ -20,7 +20,7 @@ Marko intentionally does **not** support Around plugins. Around plugins (which w
 
 ## Creating a Plugin
 
-A plugin is a plain PHP class with methods that follow a naming convention:
+A plugin is a class with the `#[Plugin]` attribute targeting the class you want to intercept. Methods use `#[Before]` and `#[After]` attributes and follow a naming convention:
 
 ```php title="PostRepositoryPlugin.php"
 <?php
@@ -30,68 +30,64 @@ declare(strict_types=1);
 namespace App\MyApp\Plugin;
 
 use Marko\Blog\Repository\PostRepository;
+use Marko\Core\Attributes\After;
+use Marko\Core\Attributes\Before;
+use Marko\Core\Attributes\Plugin;
 
+#[Plugin(target: PostRepository::class)]
 class PostRepositoryPlugin
 {
     /**
-     * Modify arguments before getPost() is called.
+     * Runs before getPost() — return null to continue, or non-null to short-circuit.
      */
-    public function beforeGetPost(PostRepository $subject, int $id): array
+    #[Before]
+    public function beforeGetPost(int $id): null
     {
-        // Log or transform the input
-        return [$id]; // Return modified arguments as array
+        // Log or validate the input
+        return null;
     }
 
     /**
-     * Modify the return value after getPost() completes.
+     * Runs after getPost() — receives the result, then the original arguments.
      */
-    public function afterGetPost(PostRepository $subject, array $result): array
+    #[After]
+    public function afterGetPost(array $result, int $id): array
     {
-        // Add extra data to the result
+        // Enrich the result
         $result['retrieved_at'] = time();
 
         return $result;
     }
 }
 ```
 
+Plugins are discovered automatically from module `src/` directories — no manual registration needed.
+
 ### Method Naming
 
 - `beforeMethodName` — runs before `methodName`
 - `afterMethodName` — runs after `methodName`
 
-The first parameter is always `$subject` (the original object). For `before` plugins, remaining parameters match the original method's signature. Return an array of the (possibly modified) arguments.
-
-For `after` plugins, the second parameter is the result from the original method. Return the (possibly modified) result.
+For `before` plugins, parameters match the original method's signature. Return `null` to continue to the original method, or return a non-null value to short-circuit and use that as the result.
 
-## Registering Plugins
+For `after` plugins, the first parameter is the result from the original method, followed by the original arguments. Return the (possibly modified) result.
 
-Plugins are registered in `module.php`:
-
-```php title="module.php"
-<?php
+### Sort Order
 
-declare(strict_types=1);
-
-use App\MyApp\Plugin\PostRepositoryPlugin;
-use Marko\Blog\Repository\PostRepository;
+Use the `sortOrder` parameter to control the order when multiple plugins target the same method:
 
-return [
-    'plugins' => [
-        PostRepository::class => [
-            PostRepositoryPlugin::class,
-        ],
-    ],
-];
+```php
+#[Before(sortOrder: 10)]
+public function beforeGetPost(int $id): null { /* runs first */ }
 ```
 
 ## Plugin Execution Order
 
 When multiple plugins target the same method:
 
-1. All `before` plugins run (in module priority order)
-2. The original method runs
-3. All `after` plugins run (in module priority order)
+1. All `before` plugins run (in sort order)
+2. The original method runs (unless a before plugin short-circuited)
+3. All `after` plugins run (in sort order)
 
 ## When to Use Plugins
 

docs/src/content/docs/guides/authentication.md

@@ -214,17 +214,18 @@ The authentication system dispatches events you can observe:
 | `FailedLoginEvent` | Login attempt fails |
 | `PasswordResetEvent` | Password is reset |
 
-```php title="module.php"
+```php title="app/security/src/Observer/LockoutAfterFailures.php"
 use Marko\Authentication\Event\FailedLoginEvent;
-use App\Security\Observer\LockoutAfterFailures;
+use Marko\Core\Attributes\Observer;
 
-return [
-    'observers' => [
-        FailedLoginEvent::class => [
-            LockoutAfterFailures::class,
-        ],
-    ],
-];
+#[Observer(event: FailedLoginEvent::class)]
+class LockoutAfterFailures
+{
+    public function handle(FailedLoginEvent $event): void
+    {
+        // Lock the account after repeated failures...
+    }
+}
 ```
 
 ## Next Steps

docs/src/content/docs/packages/core.md

@@ -73,13 +73,13 @@ Decouple "something happened" from "react to it":
 use Marko\Core\Attributes\Observer;
 use Marko\Core\Event\Event;
 
-#[Observer(event: 'user.created')]
+#[Observer(event: UserCreatedEvent::class)]
 class SendWelcomeEmail
 {
     public function handle(
-        Event $event,
+        UserCreatedEvent $event,
     ): void {
-        $user = $event->data['user'];
+        $user = $event->user;
         // Send email...
     }
 }
@@ -185,7 +185,7 @@ throw new MarkoException(
 #[Plugin(target: ClassName::class)]            // Mark class as plugin
 #[Before]                                       // Run before target method
 #[After]                                        // Run after target method
-#[Observer(event: 'event.name')]               // React to events
+#[Observer(event: EventClass::class)]           // React to events
 #[Command(name: 'cmd:name', description: '')] // Register CLI command
 ```
 

docs/src/content/docs/tutorials/build-a-blog.md

@@ -167,23 +167,26 @@ Protect the comment form so only logged-in users can comment:
 composer require marko/authentication
 ```
 
-The blog package dispatches events you can observe:
+The blog package dispatches events you can observe. Create an observer class with the `#[Observer]` attribute:
 
-```php title="app/blog/module.php"
+```php title="app/blog/src/Observer/NotifyAuthorOfComment.php"
 <?php
 
 declare(strict_types=1);
 
+namespace App\Blog\Observer;
+
 use Marko\Blog\Events\Comment\CommentCreated;
-use App\Blog\Observer\NotifyAuthorOfComment;
-
-return [
-    'observers' => [
-        CommentCreated::class => [
-            NotifyAuthorOfComment::class,
-        ],
-    ],
-];
+use Marko\Core\Attributes\Observer;
+
+#[Observer(event: CommentCreated::class)]
+class NotifyAuthorOfComment
+{
+    public function handle(CommentCreated $event): void
+    {
+        // Send notification to the post author...
+    }
+}
 ```
 
 ## Step 7: Extend with Plugins
@@ -199,10 +202,14 @@ namespace App\Blog\Plugin;
 
 use Marko\Blog\Entity\Post;
 use Marko\Blog\Repositories\PostRepositoryInterface;
+use Marko\Core\Attributes\After;
+use Marko\Core\Attributes\Plugin;
 
+#[Plugin(target: PostRepositoryInterface::class)]
 class AddReadingTimePlugin
 {
-    public function afterFindBySlug(PostRepositoryInterface $subject, ?Post $result): ?Post
+    #[After]
+    public function afterFindBySlug(?Post $result): ?Post
     {
         if ($result === null) {
             return null;
@@ -216,25 +223,6 @@ class AddReadingTimePlugin
 }
 ```
 
-Register it:
-
-```php title="app/blog/module.php"
-<?php
-
-declare(strict_types=1);
-
-use Marko\Blog\Repositories\PostRepositoryInterface;
-use App\Blog\Plugin\AddReadingTimePlugin;
-
-return [
-    'plugins' => [
-        PostRepositoryInterface::class => [
-            AddReadingTimePlugin::class,
-        ],
-    ],
-];
-```
-
 ## What You've Learned
 
 - How to scaffold a Marko project and install packages

packages/blog/README.md

@@ -104,7 +104,7 @@ Use `#[Observer]` to react to blog lifecycle events without modifying core class
 use Marko\Core\Attributes\Observer;
 use Marko\Blog\Events\Post\PostCreated;
 
-#[Observer]
+#[Observer(event: PostCreated::class)]
 class PostCreatedObserver
 {
     public function handle(PostCreated $event): void