coregen-cli 3.1.6__py3-none-any.whl

generators/static/cursor/docs/architecture/MOCK_AND_REMOTE_DATA.md.jinja

@@ -0,0 +1,87 @@
+# Mock and remote data sources — [[project_name]]
+
+## Why mock by default
+
+New entities use **mock** data so the app runs immediately without `Constants.apiUrl` or a live backend. Switch individual entities to **remote** when their API is ready.
+
+## Registry — `DataSourceConfig`
+
+File: `lib/apis/common/data_source_config.dart`
+
+```dart
+static const Map<String, DataSource> entities = {
+  'auth': DataSource.mock,   // when login enabled
+  'task': DataSource.mock,
+  'user': DataSource.remote, // example after API is ready
+};
+```
+
+- Keys: **snake_case** entity folder name; `'auth'` for authentication.
+- Change one line: `DataSource.mock` → `DataSource.remote`.
+- New entities from `add-domain` are added as `mock` automatically (existing `remote` entries are preserved).
+
+Startup calls `DataSourceConfig.validateRemoteRequiresApiUrl()` in `main.dart`. Any **non-auth** entity set to `remote` without a configured `Constants.apiUrl` throws a clear `StateError`. Placeholder strings like `INSERT YOUR LOCAL URL HERE` do **not** count as configured.
+
+`Constants.apiUrl` defaults to **empty** in `main.dart` for mock-only development. Dio uses `Constants.dioBaseUrl` (`http://127.0.0.1` when unset) so DI starts without network calls.
+
+## Infrastructure layout (per domain entity)
+
+| File | Role |
+|------|------|
+| `i_<entity>_service.dart` | Service interface |
+| `<entity>_remote_service.dart` | Retrofit REST client |
+| `mock_<entity>_service.dart` | Loads `assets/mock/<entity>.json`, in-memory CRUD |
+| `<entity>_service_module.dart` | DI: picks mock or remote via `DataSourceConfig` |
+| `<entity>_repository.dart` | Single repository; injects `I<Entity>Service` |
+
+Auth (`--login`):
+
+| File | Role |
+|------|------|
+| `auth_facade.dart` | Remote skeleton (Firebase/API — developer implements) |
+| `mock_auth_facade.dart` | Mock sign-in from `assets/mock/auth_user.json` |
+| `auth_facade_module.dart` | DI for `IAuthFacade` |
+
+## Mock JSON format
+
+Path: `assets/mock/<entity_snake_case>.json`
+
+```json
+{
+  "items": [
+    { "id": "1", "title": "Sample task", "done": false }
+  ]
+}
+```
+
+- Field names and types must match `<entity>_dto.dart` JSON serialization.
+- Include **at least 2–3 realistic records**.
+- `coregen add-domain` generates a starter file; **agents must update it** when adding entities manually or extending fields.
+
+Auth seed: `assets/mock/auth_user.json`
+
+```json
+{
+  "id": "mock-user-1",
+  "name": "Demo User",
+  "emailAddress": "demo@example.com"
+}
+```
+
+## Developer checklist — API ready
+
+1. Implement / verify `<entity>_remote_service.dart` endpoints.
+2. Set `'entity_key': DataSource.remote` in `DataSourceConfig.entities`.
+3. Set `Constants.apiUrl` in `initEnvironment()` in `main.dart`.
+4. Run `dart run build_runner build --delete-conflicting-outputs`.
+
+## AI obligation
+
+When implementing a **new domain entity** (epic or manual):
+
+1. Create `i_<entity>_service.dart`, `mock_<entity>_service.dart`, `<entity>_remote_service.dart`, `<entity>_service_module.dart`.
+2. **Create or update** `assets/mock/<entity>.json` with 2–3 coherent sample rows.
+3. Register the entity in `DataSourceConfig.entities` as `DataSource.mock` unless remote is explicitly required.
+4. Repository injects `I<Entity>Service` only — never Retrofit directly.
+
+See also: `docs/architecture/APIS_AND_INTEGRATION.md`.

generators/static/cursor/docs/architecture/REFERENCE_IMPLEMENTATIONS.md.jinja

@@ -0,0 +1,48 @@
+# Reference implementations — [[project_name]]
+
+Use these generated files as canonical examples when implementing new code.
+
+## Shell
+
+| Area | Path |
+|------|------|
+| Entry | `lib/main.dart` |
+| DI | `lib/injection.dart` |
+| Routing | `lib/router.dart` |
+| App widget | `lib/core/presentation/app_widget.dart` |
+| Error messages | `lib/core/errors/error_localizer.dart` |
+
+## Features (generated at create)
+
+| Feature | Application | Presentation |
+|---------|-------------|--------------|
+| Splash | — | `lib/features/splash/splash_page.dart` — `CustomScaffold`, `showBackButton: false` |
+| Home | — | `lib/features/home/home_page.dart` — `CustomScaffold`, `showBackButton: false` |
+
+{% if login %}
+## Auth (login enabled)
+
+| Layer | Path |
+|-------|------|
+| Domain | `lib/domain/auth/model/`, `lib/domain/auth/infrastructure/` |
+| Feature | `lib/features/auth/application/`, `lib/features/auth/presentation/` |
+| Sign-in form | `lib/features/auth/sign_in_form/application/`, `.../presentation/` |
+| Login page | `lib/features/auth/presentation/login_page.dart` — `CustomScaffold`, `showBackButton: false` |
+{% endif %}
+
+## Shared widgets
+
+- `lib/widgets/common/custom_scaffold.dart` — page shell (wraps `CScaffold`)
+- `lib/widgets/common/loading_widget.dart` — `CLoader.bouncing()`
+- `lib/widgets/common/error_widget.dart` — `CText.body`
+- `lib/widgets/common/unknown_state_widget.dart` — fallback BLoC state
+
+## APIs and data sources
+
+- `lib/apis/common/data_source_config.dart` — per-entity mock vs remote
+- `lib/apis/common/constants.dart` — `apiUrl`
+- `assets/mock/` — JSON seed data per entity
+
+See `docs/architecture/MOCK_AND_REMOTE_DATA.md`.
+
+When adding new code, match naming, imports, and patterns from the closest reference above. For UI components see `docs/architecture/CARAVAGGIO_COMPONENTS.md`.

generators/static/cursor/docs/architecture/WIDGETS_AND_CARAVAGGIO.md.jinja

@@ -0,0 +1,76 @@
+# Widgets and CaravaggioUI — [[project_name]]
+
+## CaravaggioUI (required)
+
+This project uses `caravaggio_ui` **1.0.6**. Initialize in `main.dart` via `CaravaggioUI.initialize(...)`.
+
+```dart
+import 'package:caravaggio_ui/caravaggio_ui.dart';
+```
+
+**Component catalog:** read `docs/architecture/CARAVAGGIO_COMPONENTS.md` before creating or editing presentation UI.
+
+Prefer CaravaggioUI components over raw Material widgets when equivalents exist (see catalog mapping table).
+
+## Pages — CustomScaffold (required)
+
+All routed pages **must** use `CustomScaffold` from `lib/widgets/common/custom_scaffold.dart`.
+
+- Do **not** use Material `Scaffold` + `AppBar` on pages.
+- `showBackButton: false` on root routes: Home, Splash, Login.
+- `showBackButton: true` on all other pages (add-page, feature pages, nested routes).
+- Use `bodyBuilder` with `topPadding` for scrollable content.
+- Move toolbar actions (add, refresh) to the `action` slot — no `FloatingActionButton`.
+
+```dart
+import 'package:caravaggio_ui/caravaggio_ui.dart';
+import 'package:[[project_name]]/widgets/common/custom_scaffold.dart';
+
+CustomScaffold(
+  title: CText.title('Title', size: TextSize.small),
+  showBackButton: true,
+  body: ...,
+);
+```
+
+Reusable BLoC **components** (`*_component.dart`) do **not** include a scaffold — the parent page provides `CustomScaffold` and `BlocProvider`.
+
+## Widget locations
+
+| Type | Path | Use when |
+|------|------|----------|
+| App-wide shared | `lib/widgets/common/` | Scaffold, loading, error, empty states — **reuse first** |
+| Cross-feature component | `lib/features/components/<name>/` | Reusable UI with its own BLoC (list/single/form) |
+| Feature-local | `lib/features/<feature>/presentation/widgets/` | Widget used only in one feature |
+| Pages | `lib/features/<feature>/presentation/*_page.dart` or `lib/features/<name>/<name>_page.dart` | Routed screens |
+
+## Existing shared widgets
+
+| Widget | Path | Implementation |
+|--------|------|----------------|
+| `CustomScaffold` | `lib/widgets/common/custom_scaffold.dart` | Wraps `CScaffold` |
+| `LoadingWidget` | `lib/widgets/common/loading_widget.dart` | `CLoader.bouncing()` |
+| `ErrorWidget` | `lib/widgets/common/error_widget.dart` | `CText.body` |
+| `UnknownStateWidget` | `lib/widgets/common/unknown_state_widget.dart` | `CText.body` |
+
+Import with `package:[[project_name]]/widgets/common/...`.
+
+## Reuse policy
+
+1. Check `lib/widgets/common/` before creating loading/error UI or page shells.
+2. Check `lib/features/components/` before building similar list/form UIs.
+3. Extract to `features/components/` when a second feature needs the same UI.
+4. Keep feature-specific layout in `presentation/widgets/`.
+5. Consult `CARAVAGGIO_COMPONENTS.md` before introducing new Material widgets.
+
+## Presentation patterns
+
+- `BlocBuilder` with typed `switch` on Freezed states.
+- Use `ErrorLocalizer` for failure messages.
+- `MultiBlocProvider` with explicit `List<SingleChildWidget>` typing.
+- Lists: `CTile.simple` instead of `ListTile`.
+- Loading: `LoadingWidget` or `CLoader` instead of `CircularProgressIndicator`.
+
+## Cursor skill
+
+For UI implementation patterns use skill **`/caravaggio-ui`** (page, form, list).

generators/static/cursor/docs/epics/README.md

@@ -0,0 +1,17 @@
+# Epics
+
+Track feature delivery as epics under `EPIC-NNN-<slug>.md`.
+
+## Workflow
+
+1. Invoke skill `/epic-delivery` with a high-level product description.
+2. Skill creates epic files from `.cursor/skills/epic-delivery/templates/epic.md`.
+3. Each epic is implemented via `epic-orchestrator` subagent.
+4. Status updated on completion; `layer-guardian` audits DDD boundaries.
+
+## Complexity
+
+- **small** — 1 entity + 1 UI use case → `feature-implementer`
+- **large** — multiple entities/screens/API → layer pipeline
+
+See root `AGENTS.md` and `docs/architecture/`.

generators/static/cursor/lib/domain/AGENTS.md

@@ -0,0 +1,23 @@
+# Domain layer
+
+## Structure
+
+- `model/` — entity, failure, repository interface, value objects
+- `infrastructure/` — DTO, `I*Service`, mock/remote services, service module, mapper, repository
+
+## Mock vs remote
+
+Per-entity switch in `lib/apis/common/data_source_config.dart`. Default: **mock**.
+
+When adding entities manually:
+
+1. Create full infrastructure including `mock_<entity>_service.dart` and `<entity>_service_module.dart`.
+2. Add `assets/mock/<entity>.json` with 2–3 sample items.
+3. Register in `DataSourceConfig.entities`.
+
+See `docs/architecture/MOCK_AND_REMOTE_DATA.md`.
+
+## Rules
+
+- No UI or BLoC in domain.
+- Repository interface in `model/`; implementation uses `I*Service`.

generators/static/cursor/lib/features/AGENTS.md

@@ -0,0 +1,23 @@
+# Features layer
+
+Vertical use cases under `lib/features/<name>/`.
+
+## Structure
+
+- `application/` — BLoC, events, states (Freezed)
+- `presentation/` — pages, components, feature-local widgets
+
+## Reusable components
+
+Cross-feature UI with its own BLoC: `lib/features/components/<name>/` (same application + presentation layout).
+
+## Rules
+
+- Application depends on domain interfaces, not infrastructure implementations.
+- **Pages** use `CustomScaffold` from `lib/widgets/common/custom_scaffold.dart` (never Material `Scaffold`).
+- **Components** (`*_component.dart`) have no scaffold — parent page provides it.
+- Presentation uses CaravaggioUI — see `docs/architecture/CARAVAGGIO_COMPONENTS.md`.
+- Reuse `lib/widgets/common/` shared widgets.
+- Routes go in `lib/router.dart` via integration-wiring.
+
+See `docs/architecture/WIDGETS_AND_CARAVAGGIO.md`.

generators/static/cursor/lib/widgets/AGENTS.md

@@ -0,0 +1,21 @@
+# Widgets
+
+## App-wide (`lib/widgets/common/`)
+
+Shared across the app:
+
+- `custom_scaffold.dart` — **required** for all routed pages (wraps `CScaffold`)
+- `loading_widget.dart` — `CLoader.bouncing()`
+- `error_widget.dart` — localized error display
+- `unknown_state_widget.dart` — unhandled BLoC states
+
+Always check here before creating new page shells or loading/error UI.
+
+## Feature components
+
+Reusable UI with BLoC: `lib/features/components/` — not under `widgets/`.
+
+## Policy
+
+- `docs/architecture/WIDGETS_AND_CARAVAGGIO.md` — locations, CustomScaffold rules
+- `docs/architecture/CARAVAGGIO_COMPONENTS.md` — full CaravaggioUI catalog

generators/static/cursor/rules/apis-layer.mdc.jinja

@@ -0,0 +1,21 @@
+---
+globs: lib/apis/**
+alwaysApply: false
+---
+
+# APIs layer
+
+- `lib/apis/common/constants.dart` — `apiUrl`, headers
+- `lib/apis/common/data_source_config.dart` — per-entity `DataSource.mock` / `DataSource.remote`
+- `lib/apis/interceptors/` — Dio interceptors (auth token, logging)
+- `lib/apis/core/` — Dio injectable module
+
+Read `docs/architecture/MOCK_AND_REMOTE_DATA.md` before adding or switching data sources.
+
+## Rules
+
+- No UI in `lib/apis/`.
+- Register services via `@injectable` modules; run `build_runner` after changes.
+- Non-auth entities set to `remote` require non-empty `Constants.apiUrl` (validated in `main.dart`).
+- New entities: add `assets/mock/<entity>.json` and register in `DataSourceConfig`.
+- Coordinate router/DI/mock JSON with `integration-wiring` subagent when adding endpoints for a new epic.

generators/static/cursor/rules/application-layer.mdc.jinja

@@ -0,0 +1,12 @@
+---
+globs: lib/features/**/application/**
+alwaysApply: false
+---
+
+# Application layer (BLoC)
+
+- Location: `lib/features/<feature>/application/`
+- Files: `<name>_bloc.dart`, `<name>_event.dart`, `<name>_state.dart` (Freezed).
+- BLoC depends on `I*Repository` from domain — never on infrastructure implementations directly.
+- No Flutter widgets or `BuildContext` in application layer.
+- Use explicit types in `BlocBuilder` and state `switch` expressions.

generators/static/cursor/rules/architecture-core.mdc.jinja

@@ -0,0 +1,43 @@
+---
+alwaysApply: true
+---
+
+# [[project_name]] — CoreGen DDD architecture
+
+## lib/ layout
+
+| Path | Role |
+|------|------|
+| `lib/core/` | Shared kernel: model (failures, VOs), infrastructure mixins, `app_widget`, `error_localizer` |
+| `lib/domain/<entity>/` | Shared domain: `model/` + `infrastructure/` only — no UI, no BLoC |
+| `lib/domain/enums/` | Domain enums |
+| `lib/features/<feature>/` | Vertical features: `application/` (BLoC) + `presentation/` (UI) |
+| `lib/features/components/` | Reusable UI components with their own BLoC |
+| `lib/apis/` | HTTP, Dio, `DataSourceConfig`, interceptors |
+| `lib/logging/`, `lib/storage/` | Cross-cutting infrastructure |
+| `lib/widgets/common/` | App-wide widgets (CustomScaffold, Loading, Error, UnknownState) |
+
+Mock seed data: `assets/mock/<entity>.json` (per-entity mock services). See `docs/architecture/MOCK_AND_REMOTE_DATA.md`.
+
+Entry points: `lib/main.dart`, `lib/injection.dart`, `lib/router.dart`.
+
+{% if login %}
+With login enabled: `lib/domain/auth/`, `lib/features/auth/`, `lib/features/auth/sign_in_form/`.
+{% endif %}
+
+## Layer boundaries
+
+- `domain/` must not import from `features/` or Flutter widgets.
+- `features/*/application/` must not import presentation widgets.
+- `presentation/` uses repositories via interfaces in `domain/*/model/i_*_repository.dart`.
+- Use `@injectable` / `get_it` — do not instantiate repositories in widgets.
+
+## How to add code
+
+Write Dart files manually following `docs/architecture/FILE_TEMPLATES.md` and `docs/architecture/REFERENCE_IMPLEMENTATIONS.md`.
+
+**Never run `coregen` CLI commands** (`coregen create`, `coregen add-*`). Agents implement code directly.
+
+## Epic workflow
+
+Use skill `/epic-delivery` for high-level features. See `docs/epics/README.md`.

generators/static/cursor/rules/dart-conventions.mdc.jinja

@@ -0,0 +1,14 @@
+---
+globs: lib/**/*.dart
+alwaysApply: false
+---
+
+# Dart conventions
+
+- File names: `snake_case.dart`. Classes: `PascalCase`.
+- Suffixes: `*_page.dart`, `*_bloc.dart`, `*_event.dart`, `*_state.dart`, `*_failure.dart`, `*_repository.dart`, `*_dto.dart`, `*_mapper.dart`, `*_service.dart`.
+- Use `package:[[project_name]]/...` imports (`always_use_package_imports`).
+- Specify types explicitly in `fold`, `catch`, `BlocBuilder`, and `switch` on Freezed states.
+- Freezed + json_serializable + injectable: after editing annotated files run:
+  `dart run build_runner build --delete-conflicting-outputs`
+- Respect `analysis_options.yaml` in project root.

generators/static/cursor/rules/domain-layer.mdc.jinja

@@ -0,0 +1,24 @@
+---
+globs: lib/domain/**
+alwaysApply: false
+---
+
+# Domain layer
+
+Domain entities live under `lib/domain/<entity>/`:
+
+**model/** — `<entity>.dart`, `<entity>_failure.dart`, `i_<entity>_repository.dart`, `value_objects.dart`, `value_validators.dart`
+
+**infrastructure/** — `<entity>_dto.dart`, `i_<entity>_service.dart`, `<entity>_remote_service.dart`, `mock_<entity>_service.dart`, `<entity>_service_module.dart`, `<entity>_mapper.dart`, `<entity>_repository.dart`
+
+Enums: `lib/domain/enums/<enum_snake>.dart`
+
+Mock JSON: `assets/mock/<entity>.json` — see `docs/architecture/MOCK_AND_REMOTE_DATA.md`.
+
+## Rules
+
+- No widgets, no BLoC, no `BuildContext` in domain.
+- Repository interface in `model/`; implementation in `infrastructure/`.
+- Repository injects `I*Service`; service module selects mock vs remote via `DataSourceConfig`.
+- When adding an entity, create/update `assets/mock/<entity>.json` with 2–3 sample rows.
+- After adding a new `*_failure.dart`, update `lib/core/errors/error_localizer.dart` with a `localize*Failure` method (or delegate to `integration-wiring` subagent).

generators/static/cursor/rules/login-context.mdc.jinja

@@ -0,0 +1,16 @@
+---
+globs: lib/domain/auth/**,lib/features/auth/**
+alwaysApply: false
+---
+
+# Login / auth context
+
+This project was created with `--login`. Auth-related paths:
+
+- Domain: `lib/domain/auth/model/`, `lib/domain/auth/infrastructure/`
+- Feature: `lib/features/auth/application/`, `lib/features/auth/presentation/`
+- Sign-in form: `lib/features/auth/sign_in_form/application/`, `.../presentation/`
+- API interceptor: `lib/apis/interceptors/`
+- `ErrorLocalizer.localizeAuthFailure` in `lib/core/errors/error_localizer.dart`
+
+Follow existing auth patterns when extending authentication flows.

generators/static/cursor/rules/presentation-layer.mdc.jinja

@@ -0,0 +1,15 @@
+---
+globs: lib/features/**/presentation/**
+alwaysApply: false
+---
+
+# Presentation layer
+
+- Location: `lib/features/<feature>/presentation/` or `lib/features/components/<name>/presentation/`
+- Pages: `<name>_page.dart`. Components: `<name>_component.dart`.
+- Pages use `CustomScaffold` — see `docs/architecture/WIDGETS_AND_CARAVAGGIO.md`.
+- UI components: see `docs/architecture/CARAVAGGIO_COMPONENTS.md`.
+- Use `MultiBlocProvider` with typed `providers` list.
+- Import shared states from `lib/widgets/common/` (LoadingWidget, ErrorWidget, UnknownStateWidget).
+- Map failures via `ErrorLocalizer` from `lib/core/errors/error_localizer.dart`.
+- New routes: update `lib/router.dart` (prefer `integration-wiring` subagent).

generators/static/cursor/rules/quality-gate.mdc.jinja

@@ -0,0 +1,14 @@
+---
+description: After substantial Dart changes, run quality checks — flutter analyze, build_runner when codegen files changed, dart format.
+alwaysApply: false
+---
+
+# Quality gate
+
+Before marking work complete:
+
+1. Run `flutter analyze` (or `dart analyze`) in project root and fix relevant issues.
+2. If Freezed, Injectable, Retrofit, or json_serializable files changed, run:
+   `dart run build_runner build --delete-conflicting-outputs`
+3. Optionally run `dart format .`
+4. Do not leave analyzer errors in files you modified.

generators/static/cursor/rules/ui-caravaggio.mdc.jinja

@@ -0,0 +1,22 @@
+---
+globs: lib/**/presentation/**,lib/widgets/**
+alwaysApply: false
+---
+
+# UI — CaravaggioUI and widget reuse
+
+Read before creating or editing UI:
+
+1. `docs/architecture/WIDGETS_AND_CARAVAGGIO.md` — app policy, widget locations, CustomScaffold rules
+2. `docs/architecture/CARAVAGGIO_COMPONENTS.md` — full component catalog (caravaggio_ui 1.0.6)
+
+## Hard rules
+
+- **Pages:** use `CustomScaffold` from `lib/widgets/common/custom_scaffold.dart`. Never Material `Scaffold` + `AppBar` on pages.
+- **Root pages** (Home, Splash, Login): `showBackButton: false`.
+- **Components** (`*_component.dart`): no scaffold — parent page provides shell.
+- Prefer cataloged CaravaggioUI components over Material equivalents (`CTile`, `CLoader`, `CButton`, `CText`, etc.).
+- Reuse `LoadingWidget`, `ErrorWidget`, `UnknownStateWidget` from `lib/widgets/common/` before creating new states.
+- Cross-feature reusable components: `lib/features/components/<name>/` with `application/` + `presentation/`.
+- Feature-local widgets: `lib/features/<feature>/presentation/widgets/`.
+- Do not duplicate widget policy in comments — follow the architecture docs.

generators/static/cursor/skills/caravaggio-ui/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: caravaggio-ui
+description: Implement Flutter presentation UI with CaravaggioUI components and CustomScaffold. Use when creating pages, forms, lists, dialogs, or any presentation layer UI in this project.
+---
+
+# CaravaggioUI — presentation patterns
+
+Implement UI using `caravaggio_ui` **1.0.6** and project wrappers.
+
+## Prerequisites
+
+Read `docs/architecture/CARAVAGGIO_COMPONENTS.md` (full component catalog).
+
+Policy and locations: `docs/architecture/WIDGETS_AND_CARAVAGGIO.md`.
+
+```dart
+import 'package:caravaggio_ui/caravaggio_ui.dart';
+import 'package:<project>/widgets/common/custom_scaffold.dart';
+```
+
+---
+
+## Pattern 1 — Page with scrollable content
+
+Use `CustomScaffold` + `bodyBuilder` for lists and scroll views.
+
+```dart
+class ItemsPage extends StatelessWidget {
+  static const String routeName = '/items';
+
+  const ItemsPage({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return CustomScaffold(
+      title: CText.title('Items', size: TextSize.small),
+      showBackButton: true,
+      action: IconButton(
+        icon: const Icon(Icons.add),
+        onPressed: () { /* navigate to create */ },
+      ),
+      bodyBuilder: (context, topPadding) {
+        return BlocBuilder<ItemsBloc, ItemsState>(
+          builder: (context, state) => switch (state) {
+            Loading() => Padding(
+              padding: EdgeInsets.only(top: topPadding),
+              child: const LoadingWidget(),
+            ),
+            Loaded(:final items) => ListView.builder(
+              padding: EdgeInsets.only(top: topPadding, left: 16, right: 16),
+              itemCount: items.length,
+              itemBuilder: (context, index) => CTile.simple(
+                title: items[index].name,
+                onTap: () { /* detail */ },
+              ),
+            ),
+            _ => const SizedBox.shrink(),
+          },
+        );
+      },
+    );
+  }
+}
+```
+
+**Root pages** (Home, Splash, Login): `showBackButton: false`, no title if not needed.
+
+---
+
+## Pattern 2 — Form
+
+Forms live inside a page shell or component — no scaffold in reusable form components.
+
+```dart
+CTextField.bordered(
+  decoration: CFieldDecoration(label: 'Email'),
+  onChanged: (value) => bloc.add(EmailChanged(value)),
+),
+const SizedBox(height: 16),
+CButton.elevated(
+  radius: AppRadius.s,
+  onPressed: isSubmitting ? null : onSubmit,
+  child: isSubmitting
+      ? SizedBox(
+          width: 20,
+          height: 20,
+          child: CCircularProgressIndicator.primary(),
+        )
+      : CText.label('Submit'),
+),
+```
+
+Use `CDatePicker`, `CDropdown`, `CCheckbox`, `CRadioGroup` as needed — see catalog.
+
+---
+
+## Pattern 3 — List component (no scaffold)
+
+Reusable BLoC components omit scaffold; parent page wraps with `CustomScaffold`.
+
+```dart
+class TaskListComponent extends StatelessWidget {
+  const TaskListComponent({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return BlocBuilder<TaskListBloc, TaskListState>(
+      builder: (context, state) => switch (state) {
+        Loading() => const LoadingWidget(),
+        Loaded(:final items) => ListView.builder(
+          itemCount: items.length,
+          itemBuilder: (context, index) => CTile.simple(
+            title: items[index].title,
+            trailing: IconButton(
+              icon: const Icon(Icons.delete),
+              onPressed: () => context.read<TaskListBloc>().add(
+                TaskListEvent.deleteRequested(items[index].id),
+              ),
+            ),
+          ),
+        ),
+        Error(:final message) => ErrorWidget(message: message),
+        _ => const UnknownStateWidget(),
+      },
+    );
+  }
+}
+```
+
+---
+
+## Checklist
+
+- [ ] Page uses `CustomScaffold`, not Material `Scaffold`
+- [ ] Caravaggio components from catalog, not raw Material equivalents
+- [ ] Shared widgets reused from `lib/widgets/common/`
+- [ ] Failures via `ErrorLocalizer`
+- [ ] `flutter analyze` passes