docs: fix code-standards violations across tutorials and guides

docs/src/content/docs/concepts/dependency-injection.md

@@ -19,11 +19,11 @@ namespace App\Blog\Service;
 use Marko\Cache\Contracts\CacheInterface;
 use Marko\Database\Connection\ConnectionInterface;
 
-class PostService
+readonly class PostService
 {
     public function __construct(
-        private readonly ConnectionInterface $connection,
-        private readonly CacheInterface $cache,
+        private ConnectionInterface $connection,
+        private CacheInterface $cache,
     ) {}
 
     public function getPost(int $id): ?array
@@ -106,10 +106,10 @@ If you request a concrete class with no special bindings, the container just bui
 
 ```php
 // No binding needed — container sees the constructor and resolves dependencies
-class PostController
+readonly class PostController
 {
     public function __construct(
-        private readonly PostService $postService,
+        private PostService $postService,
     ) {}
 }
 ```

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

@@ -19,10 +19,10 @@ namespace App\Blog\Services;
 use Marko\Core\Event\EventDispatcherInterface;
 use App\Blog\Events\Post\PostCreated;
 
-class PostService
+readonly class PostService
 {
     public function __construct(
-        private readonly EventDispatcherInterface $eventDispatcher,
+        private EventDispatcherInterface $eventDispatcher,
     ) {}
 
     public function createPost(string $title, string $body): Post
@@ -51,10 +51,10 @@ namespace App\Blog\Events\Post;
 use App\Blog\Entity\PostInterface;
 use Marko\Core\Event\Event;
 
-class PostCreated extends Event
+readonly class PostCreated extends Event
 {
     public function __construct(
-        private readonly PostInterface $post,
+        private PostInterface $post,
     ) {}
 
     public function getPost(): PostInterface

docs/src/content/docs/concepts/modularity.md

@@ -88,10 +88,10 @@ Your application code depends on the **interface package**:
 ```php
 use Marko\Cache\Contracts\CacheInterface;
 
-class ProductService
+readonly class ProductService
 {
     public function __construct(
-        private readonly CacheInterface $cache,
+        private CacheInterface $cache,
     ) {}
 }
 ```

docs/src/content/docs/getting-started/configuration.md

@@ -35,10 +35,10 @@ declare(strict_types=1);
 
 use Marko\Config\ConfigRepositoryInterface;
 
-class DatabaseService
+readonly class DatabaseService
 {
     public function __construct(
-        private readonly ConfigRepositoryInterface $configRepository,
+        private ConfigRepositoryInterface $configRepository,
     ) {}
 
     public function getHost(): string

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

@@ -58,10 +58,10 @@ use Marko\Routing\Attributes\Middleware;
 use Marko\Authentication\Middleware\AuthMiddleware;
 use Marko\Routing\Http\Response;
 
-class DashboardController
+readonly class DashboardController
 {
     public function __construct(
-        private readonly AuthManager $authManager,
+        private AuthManager $authManager,
     ) {}
 
     #[Get('/dashboard')]

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

@@ -26,10 +26,10 @@ namespace App\Blog\Service;
 
 use Marko\Cache\Contracts\CacheInterface;
 
-class PostService
+readonly class PostService
 {
     public function __construct(
-        private readonly CacheInterface $cache,
+        private CacheInterface $cache,
     ) {}
 
     public function getPopularPosts(): array

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

@@ -110,10 +110,10 @@ namespace App\Blog\Repository;
 use Marko\Database\Query\QueryBuilderInterface;
 use DateTimeImmutable;
 
-class PostRepository
+readonly class PostRepository
 {
     public function __construct(
-        private readonly QueryBuilderInterface $queryBuilder,
+        private QueryBuilderInterface $queryBuilder,
     ) {}
 
     public function findById(int $id): ?array
@@ -177,6 +177,8 @@ class PostRepository extends Repository
 }
 ```
 
+`query()` returns a `RepositoryQueryBuilder` pre-scoped to the repository's table. It exposes the full query builder (`where`, `whereIn`, `whereNotNull`, joins, `orderBy`, `limit`, etc.) and terminates with `getEntities()` for an `EntityCollection` or `firstEntity()` for a single hydrated entity. Fall back to `get()` / `first()` only when you want raw arrays (reports, aggregates).
+
 Use `with()` to eager-load relationships and avoid N+1 queries. Nested relationships use dot notation:
 
 ```php
@@ -213,10 +215,10 @@ use Marko\Database\Query\QueryBuilderInterface;
 use Marko\Database\Seed\SeederInterface;
 use DateTimeImmutable;
 
-class PostSeeder implements SeederInterface
+readonly class PostSeeder implements SeederInterface
 {
     public function __construct(
-        private readonly QueryBuilderInterface $queryBuilder,
+        private QueryBuilderInterface $queryBuilder,
     ) {}
 
     public function run(): void

docs/src/content/docs/guides/file-storage.md

@@ -58,10 +58,10 @@ namespace App\Blog\Service;
 
 use Marko\Filesystem\Contracts\FilesystemInterface;
 
-class DocumentService
+readonly class DocumentService
 {
     public function __construct(
-        private readonly FilesystemInterface $filesystem,
+        private FilesystemInterface $filesystem,
     ) {}
 
     public function save(string $name, string $contents): void
@@ -226,10 +226,10 @@ namespace App\Blog\Service;
 
 use Marko\Filesystem\Manager\FilesystemManager;
 
-class MediaService
+readonly class MediaService
 {
     public function __construct(
-        private readonly FilesystemManager $filesystemManager,
+        private FilesystemManager $filesystemManager,
     ) {}
 
     public function upload(string $path, string $contents): void

docs/src/content/docs/guides/mail.md

@@ -23,10 +23,10 @@ namespace App\Blog\Service;
 use Marko\Mail\Contracts\MailerInterface;
 use Marko\Mail\Message;
 
-class NotificationService
+readonly class NotificationService
 {
     public function __construct(
-        private readonly MailerInterface $mailer,
+        private MailerInterface $mailer,
     ) {}
 
     public function notifyAuthor(string $email, string $postTitle): void

docs/src/content/docs/guides/queues.md

@@ -26,11 +26,11 @@ namespace App\Blog\Job;
 
 use Marko\Queue\Job;
 
-class SendWelcomeEmail extends Job
+readonly class SendWelcomeEmail extends Job
 {
     public function __construct(
-        private readonly string $email,
-        private readonly string $name,
+        private string $email,
+        private string $name,
     ) {}
 
     public function handle(): void
@@ -50,10 +50,10 @@ declare(strict_types=1);
 use Marko\Queue\QueueInterface;
 use App\Blog\Job\SendWelcomeEmail;
 
-class RegistrationService
+readonly class RegistrationService
 {
     public function __construct(
-        private readonly QueueInterface $queue,
+        private QueueInterface $queue,
     ) {}
 
     public function register(string $email, string $name): void

docs/src/content/docs/guides/scheduling.md

@@ -79,10 +79,10 @@ You can programmatically check which tasks are due at a given time using `dueTas
 use Marko\Scheduler\Schedule;
 use DateTimeImmutable;
 
-class MaintenanceService
+readonly class MaintenanceService
 {
     public function __construct(
-        private readonly Schedule $schedule,
+        private Schedule $schedule,
     ) {}
 
     public function pendingTasks(): array

docs/src/content/docs/guides/validation.md

@@ -21,10 +21,10 @@ declare(strict_types=1);
 use Marko\Validation\Contracts\ValidatorInterface;
 use Marko\Validation\Validation\ValidationErrors;
 
-class PostController
+readonly class PostController
 {
     public function __construct(
-        private readonly ValidatorInterface $validator,
+        private ValidatorInterface $validator,
     ) {}
 
     public function store(array $data): void

docs/src/content/docs/packages/admin-auth.md

@@ -64,10 +64,10 @@ Modules register their permissions via `PermissionRegistryInterface`:
 ```php title="CatalogPermissions.php"
 use Marko\AdminAuth\Contracts\PermissionRegistryInterface;
 
-class CatalogPermissions
+readonly class CatalogPermissions
 {
     public function __construct(
-        private readonly PermissionRegistryInterface $permissionRegistry,
+        private PermissionRegistryInterface $permissionRegistry,
     ) {}
 
     public function register(): void
@@ -131,10 +131,10 @@ class OrderService
 use Marko\AdminAuth\Entity\AdminUserInterface;
 use Marko\Authentication\Contracts\GuardInterface;
 
-class DashboardController
+readonly class DashboardController
 {
     public function __construct(
-        private readonly GuardInterface $guard,
+        private GuardInterface $guard,
     ) {}
 
     public function index(): Response

docs/src/content/docs/packages/admin-panel.md

@@ -34,10 +34,10 @@ The panel registers these routes automatically:
 use Marko\AdminPanel\Menu\AdminMenuBuilderInterface;
 use Marko\AdminAuth\Entity\AdminUserInterface;
 
-class LayoutHelper
+readonly class LayoutHelper
 {
     public function __construct(
-        private readonly AdminMenuBuilderInterface $adminMenuBuilder,
+        private AdminMenuBuilderInterface $adminMenuBuilder,
     ) {}
 
     public function getSidebar(

docs/src/content/docs/packages/admin.md

@@ -104,10 +104,10 @@ Inject `AdminSectionRegistryInterface` to access all registered sections:
 use Marko\Admin\Contracts\AdminSectionInterface;
 use Marko\Admin\Contracts\AdminSectionRegistryInterface;
 
-class NavigationBuilder
+readonly class NavigationBuilder
 {
     public function __construct(
-        private readonly AdminSectionRegistryInterface $adminSectionRegistry,
+        private AdminSectionRegistryInterface $adminSectionRegistry,
     ) {}
 
     public function buildMenu(): array
@@ -170,10 +170,10 @@ return [
 ```php
 use Marko\Admin\Config\AdminConfigInterface;
 
-class AdminRouter
+readonly class AdminRouter
 {
     public function __construct(
-        private readonly AdminConfigInterface $adminConfig,
+        private AdminConfigInterface $adminConfig,
     ) {}
 
     public function getBaseUrl(): string

docs/src/content/docs/packages/authorization.md

@@ -21,10 +21,10 @@ Register abilities as closures on the Gate:
 use Marko\Authorization\AuthorizableInterface;
 use Marko\Authorization\Contracts\GateInterface;
 
-class AuthorizationBootstrap
+readonly class AuthorizationBootstrap
 {
     public function __construct(
-        private readonly GateInterface $gate,
+        private GateInterface $gate,
     ) {}
 
     public function boot(): void
@@ -42,10 +42,10 @@ class AuthorizationBootstrap
 ```php
 use Marko\Authorization\Contracts\GateInterface;
 
-class SettingsController
+readonly class SettingsController
 {
     public function __construct(
-        private readonly GateInterface $gate,
+        private GateInterface $gate,
     ) {}
 
     public function update(): void