docs: fix API inaccuracies across packages, guides, and tutorials

- pubsub-redis, pubsub-pgsql: use subscription param directly for SSE
- validation: validate() returns ValidationErrors, added validateOrFail()
- caching: CachePoolInterface → CacheInterface, fix method names
- database: ConnectionInterface → QueryBuilderInterface for fluent queries
- routing: DisableRoute takes no params, fix attribute namespaces
- authentication: AuthManagerInterface → AuthManager
- All tutorials: fix Response/Request namespaces, validator API, query
  builder usage, auth access patterns, event class names

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

Author: markshust

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

@@ -43,7 +43,7 @@ return [
 
 ## Using Authentication
 
-Inject the `AuthManagerInterface` to check authentication state:
+Inject `AuthManager` to check authentication state:
 
 ```php title="app/dashboard/Controller/DashboardController.php"
 <?php
@@ -52,17 +52,17 @@ declare(strict_types=1);
 
 namespace App\Dashboard\Controller;
 
-use Marko\Authentication\AuthManagerInterface;
-use Marko\Routing\Attribute\Get;
-use Marko\Routing\Attribute\Middleware;
+use Marko\Authentication\AuthManager;
+use Marko\Routing\Attributes\Get;
+use Marko\Routing\Attributes\Middleware;
 use Marko\Authentication\Middleware\AuthMiddleware;
 use Marko\Http\ResponseInterface;
 use Marko\Http\JsonResponse;
 
 class DashboardController
 {
     public function __construct(
-        private readonly AuthManagerInterface $authManager,
+        private readonly AuthManager $authManager,
     ) {}
 
     #[Get('/dashboard')]
@@ -138,37 +138,62 @@ declare(strict_types=1);
 
 namespace App\MyApp\Auth;
 
-use Marko\Authentication\GuardInterface;
+use Marko\Authentication\Contracts\GuardInterface;
 use Marko\Authentication\AuthenticatableInterface;
 
 class ApiKeyGuard implements GuardInterface
 {
+    public function check(): bool
+    {
+        return $this->user() !== null;
+    }
+
+    public function guest(): bool
+    {
+        return !$this->check();
+    }
+
     public function user(): ?AuthenticatableInterface
     {
         // Look up user by API key from request header
     }
 
-    public function check(): bool
+    public function id(): int|string|null
     {
-        return $this->user() !== null;
+        return $this->user()?->getAuthIdentifier();
     }
 
     public function attempt(array $credentials): bool
     {
         // Validate API key credentials
     }
 
+    public function login(AuthenticatableInterface $user): void
+    {
+        // Store the authenticated user
+    }
+
+    public function loginById(int|string $id): ?AuthenticatableInterface
+    {
+        // Find and log in a user by ID
+    }
+
     public function logout(): void
     {
         // Invalidate the API key
     }
+
+    public function getName(): string
+    {
+        return 'api-key';
+    }
 }
 ```
 
 Register it via Preference in your `module.php`:
 
 ```php title="module.php"
-use Marko\Authentication\GuardInterface;
+use Marko\Authentication\Contracts\GuardInterface;
 use App\MyApp\Auth\ApiKeyGuard;
 
 return [

docs/src/content/docs/guides/caching.md

@@ -3,7 +3,7 @@ title: Caching
 description: Cache data with pluggable backends — file, Redis, or array for testing.
 ---
 
-Marko's cache system follows the interface/implementation pattern. Code against `CachePoolInterface`, swap backends by changing a binding.
+Marko's cache system follows the interface/implementation pattern. Code against `CacheInterface`, swap backends by changing a binding.
 
 ## Setup
 
@@ -24,49 +24,58 @@ declare(strict_types=1);
 
 namespace App\Blog\Service;
 
-use Marko\Cache\CachePoolInterface;
+use Marko\Cache\Contracts\CacheInterface;
 
 class PostService
 {
     public function __construct(
-        private readonly CachePoolInterface $cachePool,
+        private readonly CacheInterface $cache,
     ) {}
 
     public function getPopularPosts(): array
     {
-        return $this->cachePool->remember('posts.popular', 3600, function () {
-            // This closure only runs on cache miss
-            return $this->fetchPopularPostsFromDb();
-        });
+        $posts = $this->cache->get('posts.popular');
+
+        if ($posts === null) {
+            $posts = $this->fetchPopularPostsFromDb();
+            $this->cache->set('posts.popular', $posts, ttl: 3600);
+        }
+
+        return $posts;
     }
 
     public function clearPostCache(): void
     {
-        $this->cachePool->forget('posts.popular');
+        $this->cache->delete('posts.popular');
     }
 }
 ```
 
 ## Cache Operations
 
 ```php
+use Marko\Cache\Contracts\CacheInterface;
+
 // Store a value (TTL in seconds)
-$this->cache->put('key', $value, ttl: 3600);
+$this->cache->set('key', $value, ttl: 3600);
 
-// Retrieve a value
-$value = $this->cache->get('key');
+// Retrieve a value (with optional default)
+$value = $this->cache->get('key', default: 'fallback');
 
 // Check if a key exists
 $this->cache->has('key'); // bool
 
 // Remove a key
-$this->cache->forget('key');
+$this->cache->delete('key');
+
+// Store multiple values
+$this->cache->setMultiple(['key1' => $val1, 'key2' => $val2], ttl: 3600);
 
-// Get or compute (cache-aside pattern)
-$value = $this->cache->remember('key', 3600, fn () => expensiveComputation());
+// Retrieve multiple values
+$values = $this->cache->getMultiple(['key1', 'key2']);
 
 // Clear all cache
-$this->cache->flush();
+$this->cache->clear();
 ```
 
 ## Switching Backends
@@ -78,12 +87,12 @@ Change from file cache to Redis by updating your `module.php`:
 
 declare(strict_types=1);
 
-use Marko\Cache\CachePoolInterface;
-use Marko\Cache\Redis\RedisCachePool;
+use Marko\Cache\Contracts\CacheInterface;
+use Marko\Cache\Redis\Driver\RedisCacheDriver;
 
 return [
     'bindings' => [
-        CachePoolInterface::class => RedisCachePool::class,
+        CacheInterface::class => RedisCacheDriver::class,
     ],
 ];
 ```

docs/src/content/docs/guides/database.md

@@ -96,7 +96,9 @@ marko db:status
 
 ## Querying
 
-Use the `ConnectionInterface` for database queries:
+### Query Builder
+
+Use `QueryBuilderInterface` for fluent query building:
 
 ```php title="app/blog/Repository/PostRepository.php"
 <?php
@@ -105,33 +107,33 @@ declare(strict_types=1);
 
 namespace App\Blog\Repository;
 
-use Marko\Database\ConnectionInterface;
+use Marko\Database\Query\QueryBuilderInterface;
 use DateTimeImmutable;
 
 class PostRepository
 {
     public function __construct(
-        private readonly ConnectionInterface $connection,
+        private readonly QueryBuilderInterface $queryBuilder,
     ) {}
 
     public function findById(int $id): ?array
     {
-        return $this->connection->table('posts')
-            ->where('id', $id)
+        return $this->queryBuilder->table('posts')
+            ->where('id', '=', $id)
             ->first();
     }
 
     public function findPublished(): array
     {
-        return $this->connection->table('posts')
-            ->where('published', true)
-            ->orderBy('created_at', 'desc')
+        return $this->queryBuilder->table('posts')
+            ->where('published', '=', true)
+            ->orderBy('created_at', 'DESC')
             ->get();
     }
 
     public function create(string $title, string $body): int
     {
-        return $this->connection->table('posts')->insert([
+        return $this->queryBuilder->table('posts')->insert([
             'title' => $title,
             'body' => $body,
             'published' => false,
@@ -152,19 +154,19 @@ declare(strict_types=1);
 
 namespace App\Blog\Database\Seeder;
 
-use Marko\Database\ConnectionInterface;
+use Marko\Database\Query\QueryBuilderInterface;
 use Marko\Database\SeederInterface;
 use DateTimeImmutable;
 
 class PostSeeder implements SeederInterface
 {
     public function __construct(
-        private readonly ConnectionInterface $connection,
+        private readonly QueryBuilderInterface $queryBuilder,
     ) {}
 
     public function run(): void
     {
-        $this->connection->table('posts')->insert([
+        $this->queryBuilder->table('posts')->insert([
             'title' => 'Hello World',
             'body' => 'Welcome to Marko.',
             'published' => true,

docs/src/content/docs/guides/routing.md

@@ -14,9 +14,9 @@ declare(strict_types=1);
 
 namespace App\Blog\Controller;
 
-use Marko\Routing\Attribute\Get;
-use Marko\Routing\Attribute\Post;
-use Marko\Routing\Attribute\Delete;
+use Marko\Routing\Attributes\Get;
+use Marko\Routing\Attributes\Post;
+use Marko\Routing\Attributes\Delete;
 use Marko\Http\ResponseInterface;
 use Marko\Http\JsonResponse;
 
@@ -75,8 +75,8 @@ public function show(int $userId, int $postId): ResponseInterface
 Apply middleware to routes using the `#[Middleware]` attribute:
 
 ```php
-use Marko\Routing\Attribute\Get;
-use Marko\Routing\Attribute\Middleware;
+use Marko\Routing\Attributes\Get;
+use Marko\Routing\Attributes\Middleware;
 use Marko\Authentication\Middleware\AuthMiddleware;
 
 class AdminController
@@ -112,14 +112,16 @@ Higher-priority modules can override routes from lower-priority modules. If `ven
 
 ## Disabling Routes
 
-To remove a vendor route without replacing it, use the `#[DisableRoute]` attribute:
+To remove a vendor route without replacing it, use the `#[DisableRoute]` attribute. Place it on a method that also has the route attribute you want to disable --- `#[DisableRoute]` takes no parameters and simply disables the route defined by the preceding routing attribute:
 
 ```php
-use Marko\Routing\Attribute\DisableRoute;
+use Marko\Routing\Attributes\Get;
+use Marko\Routing\Attributes\DisableRoute;
 
 class BlogRouteOverrides
 {
-    #[DisableRoute(method: 'GET', path: '/blog/rss')]
+    #[Get('/blog/rss')]
+    #[DisableRoute]
     public function disableRss(): void {}
 }
 ```
@@ -137,7 +139,7 @@ namespace App\MyApp\Middleware;
 
 use Marko\Http\RequestInterface;
 use Marko\Http\ResponseInterface;
-use Marko\Routing\MiddlewareInterface;
+use Marko\Routing\Middleware\MiddlewareInterface;
 
 class RateLimitMiddleware implements MiddlewareInterface
 {