@currentjs/gen 0.5.1 → 0.5.2

package/dist/generators/templates/data/cursorRulesTemplate

@@ -1,765 +1,21 @@
-# CurrentJS Framework Rules
+0. This is fullstack application, generated by CurrentJS code generator. Instructions are in REFERENCE.md.
 
-## Architecture Overview
-This is a CurrentJS framework application using clean architecture principles with the following layers:
-- **Controllers**: Handle HTTP requests/responses and route handling
-- **UseCases**: Orchestrate handler calls in sequence
-- **Services**: Contain business logic and orchestrate operations
-- **Stores**: Provide data access layer and database operations
-- **Domain Entities**: Core business models
-- **Views**: HTML templates for server-side rendering
+1. Yaml-first: edit yaml, `current generate`, `current commit` — in that order. `current generate` overwrites TypeScript files. Any hand-edits to generated files must be preserved with current commit before the next generation, or they are lost. This is the single most critical process rule.
 
-All layers (except Domain and Views) are auto-wired via **dependency injection** — the generator scans `@Injectable` and `@Controller` decorators, resolves constructor dependencies, and generates wiring code in `src/app.ts`.
+2. Never edit the DI wiring block in src/app.ts. The block between // currentjs:controllers:start and // currentjs:controllers:end is fully auto-regenerated. Changes there will silently vanish. Don't touch app.yaml either.
 
-## Commands
+3. Custom logic belongs exclusively in Models and Service methods. Controllers, UseCases, and DTOs are fully generated. When CRUD isn't enough, add a method to the *Service.ts class, then reference it in the yaml as a handler — never implement business logic in controllers.
 
-```bash
-current create module Modulename # Creates "Modulename" with default structure and yaml file
-```
-```bash
-current generate Modulename # Generates all TypeScript files based on the module's yaml, and runs "npm run build"
-current generate # Does the same as above, but for all modules
-```
-```bash
-current commit [files...] # Commits all changes in the code, so they won't be overwritten after regeneration
-current diff [module] # Show differences between generated and current code
-```
+4. Custom handlers must be declared in the yaml before (re)generating. After writing a service method, add it to useCases.Model.action.handlers in the yaml. If you skip this step, the use case won't call your method and the wiring won't be regenerated correctly.
 
-## The flow
-1. Create an empty app (`current create app`) – this step is already done.
-2. Create a new module: `current create module Name`
-3. In the module's yaml file, define module's:
- - domain (aggregates and value objects)
- - useCases (with input/output and handlers)
- - api endpoints (with auth)
- - web pages (with auth and onSuccess/onError)
-4. Generate TypeScript files: `current generate Name`
-5. If required, make changes in the:
- - model (i.e. some specific business rules or validations)
- - views
-6. Commit those changes: `current commit`
+5. Never include auto-managed fields in the domain definition. id, owner_id, created_at, updated_at, deleted_at are added automatically. Defining them manually causes schema conflicts and duplicate columns.
 
---- If needed more than CRUD: ---
+6. Model relationships use the model name as the field type, not a raw foreign key. owner: { type: Owner, required: true } — not ownerId: { type: id }. The generator derives the FK column, DTO field, and store JOIN automatically from the model-name type.
 
-7. Define action in the service by creating a method
-8. Describe this action in the module's yaml under useCases. Additionally, you may define api/web endpoints.
-9. `current generate Modulename`
-10. commit changes: `current commit`
+7. Business rule validation belongs in domain entities, not in services. Services orchestrate; entities own domain invariants. A rule like "a published post cannot be archived" is an entity concern. Type/presence validations are handled by DTOs.
 
-## Configuration Files
+8. Auth and permissions are yaml configuration, not code. auth: [owner, admin] on an endpoint is enough. Do not write auth guards or role checks manually in controllers — it's redundant and won't survive regeneration.
 
-### Application Configuration (app.yaml)
+9. The template engine is custom: x-for/x-if attributes and {{ }} syntax. It is not Alpine, Vue, or Jinja. Loops use <tbody x-for="items" x-row="item">, conditionals use x-if="value", interpolation uses {{ item.name }}. Don't import or use other templating conventions.
 
-**Do not modify this file**
-
-### Module Configuration (modulename.yaml)
-
-**The most work must be done in these files**
-
-**Complete Module Example:**
-```yaml
-domain:
-  aggregates:
-    Post:
-      root: true                          # Marks as aggregate root
-      fields:
-        title: { type: string, required: true }
-        content: { type: string, required: true }
-        authorId: { type: id, required: true }
-        publishedAt: { type: datetime }
-        status: { type: string, required: true }
-
-useCases:
-  Post:
-    list:
-      input:
-        pagination: { type: offset, defaults: { limit: 20, maxLimit: 100 } }
-      output: { from: Post, pagination: true }
-      handlers: [default:list]            # Built-in list handler
-    get:
-      input: { identifier: id }
-      output: { from: Post }
-      handlers: [default:get]             # Built-in get handler
-    create:
-      input: { from: Post }
-      output: { from: Post }
-      handlers: [default:create]          # Built-in create
-    update:
-      input: { identifier: id, from: Post, partial: true }
-      output: { from: Post }
-      handlers: [default:update]
-    delete:
-      input: { identifier: id }
-      output: void
-      handlers: [                         # Chain multiple handlers
-        checkCanDelete,                   # Custom → PostService.checkCanDelete(result, input)
-        default:delete                    # Built-in delete
-      ]
-    publish:                              # Custom action
-      input: { identifier: id }
-      output: { from: Post }
-      handlers: [
-        default:get,                      # Fetch entity
-        validateForPublish,               # Custom → PostService.validateForPublish(result, input)
-        updatePublishStatus               # Custom → PostService.updatePublishStatus(result, input)
-      ]
-
-api:                                      # REST API configuration
-  Post:                                   # Keyed by model name
-    prefix: /api/posts                    # Base URL for API endpoints
-    endpoints:
-      - method: GET                       # HTTP method
-        path: /                           # Relative path (becomes /api/posts/)
-        useCase: Post:list                # References useCases.Post.list
-        auth: all                         # Public access
-      - method: GET
-        path: /:id                        # Path parameter
-        useCase: Post:get
-        auth: all
-      - method: POST
-        path: /
-        useCase: Post:create
-        auth: authenticated               # Must be logged in
-      - method: PUT
-        path: /:id
-        useCase: Post:update
-        auth: [owner, admin]              # Owner OR admin (OR logic)
-      - method: DELETE
-        path: /:id
-        useCase: Post:delete
-        auth: [owner, admin]
-      - method: POST                      # Custom endpoint
-        path: /:id/publish
-        useCase: Post:publish
-        auth: [owner, editor, admin]
-
-web:                                      # Web interface configuration
-  Post:                                   # Keyed by model name
-    prefix: /posts                        # Base URL for web pages
-    layout: main_view                     # Layout template name
-    pages:
-      - path: /                           # List page
-        useCase: Post:list
-        view: postList                    # Template name
-        auth: all
-      - path: /:id                        # Detail page
-        useCase: Post:get
-        view: postDetail
-        auth: all
-      - path: /create                     # Create form (GET = show form)
-        method: GET
-        view: postCreate
-        auth: authenticated
-      - path: /create                     # Create form (POST = submit)
-        method: POST
-        useCase: Post:create
-        auth: authenticated
-        onSuccess:                        # What happens after successful submission
-          redirect: /posts/:id
-          toast: "Post created successfully"
-        onError:
-          stay: true
-          toast: error
-      - path: /:id/edit                   # Edit form (GET = show form)
-        method: GET
-        useCase: Post:get                 # Load existing data
-        view: postUpdate
-        auth: [owner, admin]
-      - path: /:id/edit                   # Edit form (POST = submit)
-        method: POST
-        useCase: Post:update
-        auth: [owner, admin]
-        onSuccess:
-          back: true
-          toast: "Post updated successfully"
-```
-
-**Make sure no `id`/`owner_id`/`created_at`/`updated_at`/`deleted_at` fields are present in the domain definition, since they are added automatically**
-
-**Use case option: withChild (aggregate root with child entities)**
-
-Per use case you can set `withChild: true` (default `false`) to show child entities on the root's pages. Only applies when the entity has child entities (e.g. Invoice with InvoiceItem). Ignored if there are no child entities.
-- **list** + `withChild: true`: adds a link column on the list page to the child entity list (no extra loading).
-- **get** + `withChild: true`: on the detail page, renders a table of child entities below the main card, with View/Edit/Add links.
-
-Example:
-```yaml
-useCases:
-  Invoice:
-    get:
-      withChild: true
-      input: { identifier: id }
-      output: { from: Invoice }
-      handlers: [default:get]
-```
-
-**Field Types:**
-- `string` - Text data (VARCHAR in database)
-- `number` - Numeric data (INT/DECIMAL in database)
-- `integer` - Integer data (INT in database)
-- `decimal` - Decimal data (DECIMAL in database)
-- `boolean` - True/false values (BOOLEAN in database)
-- `datetime` - Date and time values (DATETIME in database)
-- `date` - Date values (DATE in database)
-- `id` - Foreign key reference (INT in database)
-- `json` - JSON data
-- `enum` - Enumerated values (use with `values: [...]`)
-- `ModelName` - Relationship to another model (e.g., `Owner`, `User`, `Post`)
-
-**Multi-Model Configuration:**
-
-When working with multiple models in a single module, each model is a separate key in `api` and `web`:
-
-```yaml
-domain:
-  aggregates:
-    Cat:
-      root: true
-      fields:
-        name: { type: string, required: true }
-    Person:
-      root: true
-      fields:
-        name: { type: string, required: true }
-        email: { type: string, required: true }
-
-api:
-  Cat:
-    prefix: /api/cat
-    endpoints:
-      - method: GET
-        path: /
-        useCase: Cat:list
-        auth: all
-  Person:
-    prefix: /api/person
-    endpoints:
-      - method: GET
-        path: /
-        useCase: Person:list
-        auth: all
-
-web:
-  Cat:
-    prefix: /cat
-    layout: main_view
-    pages:
-      - path: /
-        useCase: Cat:list
-        view: catList
-        auth: all
-  Person:
-    prefix: /person
-    layout: main_view
-    pages:
-      - path: /
-        useCase: Person:list
-        view: personList
-        auth: all
-```
-
-**Model Relationships:**
-
-Define relationships by using another model's name as the field type in `domain.aggregates`:
-
-```yaml
-domain:
-  aggregates:
-    Owner:
-      root: true
-      fields:
-        name: { type: string, required: true }
-
-    Cat:
-      root: true
-      fields:
-        name: { type: string, required: true }
-        owner: { type: Owner, required: true }   # Creates relationship with Owner model
-```
-
-**Generated Behavior:**
-- **Domain Model**: Rich object with `owner: Owner` (full object, not just ID)
-- **DTOs**: Use `ownerId: number` for API requests
-- **Database**: Stores `ownerId` foreign key column (references `Owner.id`)
-- **Store**: Automatically loads the related Owner object when fetching a Cat
-- **HTML Forms**: Auto-generates select dropdown with "Create New" button
-- **TypeScript**: Full type safety with proper imports
-
-**Naming Convention:**
-Foreign keys are auto-generated following the pattern `fieldName + 'Id'`:
-- `owner` → `ownerId`
-- `author` → `authorId`
-- `parentComment` → `parentCommentId`
-
-The foreign key always references the `id` field of the related model.
-
-**🔄 Handler vs Use Case Architecture:**
-- **Handler**: Creates a separate service method (one handler = one service method)
-- **Use Case**: Defined under `useCases.ModelName.actionName`, calls handler methods step-by-step
-- **UseCase reference**: Used in `api`/`web` endpoints as `ModelName:actionName` (e.g., `Post:list`)
-
-**Built-in Handlers (used in `useCases.*.*.handlers`):**
-- `default:list` - Creates service method with pagination parameters
-- `default:get` - Creates service method named `get` with ID parameter
-- `default:create` - Creates service method with DTO parameter
-- `default:update` - Creates service method with ID and DTO parameters
-- `default:delete` - Creates service method with ID parameter
-
-Note: Handlers within `useCases` do NOT need a model prefix because the model is already the key.
-
-**Custom Handlers:**
-- `customMethodName` - Creates service method that accepts `(result, input)` parameters
-- `result`: Result from previous handler (or `null` if it's the first handler)
-- `input`: The parsed input DTO
-- Each handler generates a separate method in the service
-- User can customize the implementation after generation
-
-**🔗 Multiple Handlers per Use Case:**
-When a use case has multiple handlers, each handler generates a separate service method, and the use case orchestrator calls them sequentially. The use case returns the result from the last handler.
-
-**Parameter Passing Rules:**
-- **Default handlers** (`default:*`): Receive standard parameters (id, pagination, DTO, etc.)
-- **Custom handlers**: Receive `(result, input)` where:
-  - `result`: Result from previous handler, or `null` if it's the first handler
-  - `input`: Parsed input DTO
-
-**Handler Format Examples (inside `useCases`):**
-- `default:list` - Creates service method `list(page, limit)`
-- `default:get` - Creates service method `get(id)`
-- `validateContent` - Creates service method `validateContent(result, input)`
-- `notifySubscribers` - Creates service method `notifySubscribers(result, input)`
-
-**Form Success/Error Handling (in `web` pages):**
-
-Instead of a separate `strategy` field, use `onSuccess` and `onError` on web page endpoints:
-```yaml
-onSuccess:
-  redirect: /posts/:id   # Redirect to URL
-  toast: "Saved!"        # Show toast notification
-  back: true             # Navigate back in browser history
-  stay: true             # Stay on current page
-onError:
-  stay: true             # Stay on current page
-  toast: error           # Show error toast
-```
-
-The template generator converts `onSuccess` options into `data-strategy` attributes on HTML forms.
-
-**Auth Configuration (per endpoint in `api` and `web`):**
-- `all` - Anyone (including anonymous users)
-- `authenticated` - Any logged-in user
-- `owner` - User who created the entity (checks `ownerId` field)
-- `admin`, `editor`, `user` - Custom roles from JWT token
-- `[owner, admin]` - Array syntax: user must match ANY (OR logic). Privileged roles bypass ownership check.
-
-**Generated Files from Configuration:**
-- Domain entity class (one per model)
-- Use case orchestrator (one per model)
-- Service class with handler methods (one per model)
-- Input/Output DTOs (one per use case)
-- API controller with REST endpoints (one per model)
-- Web controller with page rendering (one per model)
-- Store class with database operations (one per model)
-- HTML templates for all views
-
-**Multi-Model Support:**
-- Each model gets its own Service, UseCase, Controller, and Store classes
-- In `api`/`web`, each model is a separate key (e.g., `api.Cat`, `api.Person`)
-- UseCase references use `ModelName:actionName` format (e.g., `Post:list`, `Person:create`)
-- Handlers within `useCases` do not need model prefix (model is already the key)
-- Controllers and services are generated per model, not per module
-
-## Dependency Injection & Wiring
-
-The application uses a decorator-driven DI system. All wiring is auto-generated in `src/app.ts` between `// currentjs:controllers:start` and `// currentjs:controllers:end` markers. **Never edit this block manually** — it is regenerated on each `current generate`.
-
-### `@Injectable` Decorator
-
-Lives in `src/system.ts`. Marks a class for automatic DI discovery:
-
-```typescript
-import { Injectable } from '../../../../system';
-
-@Injectable()
-export class MyService {
-  constructor(private myStore: MyStore) {}
-}
-```
-
-Generated Stores, Services, and UseCases already have `@Injectable()`. Controllers use `@Controller()` from `@currentjs/router` instead.
-
-### Adding Custom Classes to DI
-
-If you create a new class that should be auto-wired:
-1. Add `@Injectable()` decorator (import from `src/system.ts`)
-2. Declare dependencies as constructor parameters with their types
-3. Run `current generate` — the class will be auto-imported and instantiated in `app.ts`
-4. Run `current commit` to preserve your changes
-
-### How Wiring Works
-
-The generator:
-1. Scans all module `.ts` files for `@Injectable` and `@Controller` decorators
-2. Parses constructor parameters to build a dependency graph
-3. Topologically sorts classes (stores → services → use cases → controllers)
-4. Generates imports, instantiations, and the `controllers` array in `app.ts`
-
-Database provider instances are injected into stores based on `app.yaml` configuration (global, with optional per-module overrides). Both npm packages and local file paths are supported as providers.
-
-## Module Structure
-```
-src/modules/ModuleName/
-├── domain/
-│   ├── entities/
-│   │   └── Entity.ts                  # Domain model (aggregate root)
-│   └── valueObjects/
-│       └── ValueObject.ts             # Value objects (if any)
-├── application/
-│   ├── useCases/
-│   │   └── EntityUseCase.ts           # Use case orchestrator
-│   ├── services/
-│   │   └── EntityService.ts           # Business logic handlers
-│   └── dto/
-│       └── EntityAction.ts            # Input/Output DTOs per action
-├── infrastructure/
-│   ├── controllers/
-│   │   ├── EntityApiController.ts     # REST API endpoints
-│   │   └── EntityWebController.ts     # Web page controllers
-│   └── stores/
-│       └── EntityStore.ts             # Data access implementation
-├── views/
-│   ├── entityList.html                # List view template
-│   ├── entityDetail.html              # Detail view template
-│   ├── entityCreate.html              # Create form template
-│   └── entityEdit.html               # Edit form template
-└── modulename.yaml                    # Module configuration
-```
-
-## Best Practices
-
-- Use Domain Driven Design and Clean Architecture (kind of).
-- Prefer declarative configuration over imperative programming: when possible, change yamls instead of writing the code. Write the code only when it's really neccessary.
-- CRUD operation are autogenerated (first in module's yaml, then in the generated code).
-- If some custom action is needed, then it has to be defined in the **Service** then just put this action to the module's yaml. You may also define new methods in the *Store* and its interface (if needed).
-- Business rules must be defined only in models. That also applies to business rules validations (in contrast to *just* validations: e.g. if field exists and is of needed type – then validators are in use)
-
-## Core Package APIs (For Generated Code)
-
-### @currentjs/router - Controller Decorators & Context
-
-**Decorators (in controllers):**
-```typescript
-@Controller('/api/posts')  // Base path for controller
-@Get('/')                  // GET endpoint
-@Get('/:id')              // GET with path parameter
-@Post('/')                // POST endpoint
-@Put('/:id')              // PUT endpoint
-@Delete('/:id')           // DELETE endpoint
-@Render('template', 'layout')  // For web controllers
-```
-
-**Context Object (in route handlers):**
-```typescript
-interface IContext {
-  request: {
-    url: string;
-    path: string;
-    method: string;
-    parameters: Record<string, string | number>; // Path params + query params
-    body: any; // Parsed JSON or raw string
-    headers: Record<string, string | string[]>;
-    user?: AuthenticatedUser; // Parsed JWT user if authenticated
-  };
-  response: Record<string, any>;
-}
-
-// Usage examples
-const id = parseInt(ctx.request.parameters.id as string);
-const page = parseInt(ctx.request.parameters.page as string) || 1;
-const payload = ctx.request.body;
-const user = ctx.request.user; // If authenticated
-```
-
-**Authentication Support:**
-- JWT tokens parsed automatically from `Authorization: Bearer <token>` header
-- User object available at `ctx.request.user` with `id`, `email`, `role` fields
-- No manual setup required in generated code
-
-### @currentjs/templating - Template Syntax
-
-**Variables & Data Access:**
-```html
-{{ variableName }}
-{{ object.property }}
-{{ $root.arrayData }}     <!-- Access root data -->
-{{ $index }}              <!-- Loop index -->
-```
-
-**Control Structures:**
-```html
-<!-- Loops -->
-<tbody x-for="$root" x-row="item">
-  <tr>
-    <td>{{ item.name }}</td>
-    <td>{{ $index }}</td>
-  </tr>
-</tbody>
-
-<!-- Conditionals -->
-<div x-if="user.isAdmin">Admin content</div>
-<span x-if="errors.name">{{ errors.name }}</span>
-
-<!-- Template includes -->
-<userCard name="{{ user.name }}" role="admin" />
-```
-
-**Layout Integration:**
-- Templates use `<!-- @template name="templateName" -->` header
-- Main layout gets `{{ content }}` variable
-- Forms use `{{ formData.field || '' }}` for default values
-
-### @currentjs/provider-mysql - Database Operations
-
-**Query Execution (in stores):**
-```typescript
-// Named parameters (preferred)
-const result = await this.db.query(
-  'SELECT * FROM users WHERE status = :status AND age > :minAge',
-  { status: 'active', minAge: 18 }
-);
-
-// Result handling
-if (result.success && result.data.length > 0) {
-  return result.data.map(row => this.rowToModel(row));
-}
-```
-
-**Common Query Patterns:**
-```typescript
-// Insert with auto-generated fields
-const row = { ...data, created_at: new Date(), updated_at: new Date() };
-const result = await this.db.query(
-  `INSERT INTO table_name (\${fields.join(', ')}) VALUES (\${placeholders})`,
-  row
-);
-const newId = result.insertId;
-
-// Update with validation
-const query = `UPDATE table_name SET \${updateFields.join(', ')}, updated_at = :updated_at WHERE id = :id`;
-await this.db.query(query, { ...updateData, updated_at: new Date(), id });
-
-// Soft delete
-await this.db.query(
-  'UPDATE table_name SET deleted_at = :deleted_at WHERE id = :id',
-  { deleted_at: new Date(), id }
-);
-```
-
-**Error Handling:**
-```typescript
-try {
-  const result = await this.db.query(query, params);
-} catch (error) {
-  if (error instanceof MySQLConnectionError) {
-    throw new Error(`Database connection error: \${error.message}`);
-  } else if (error instanceof MySQLQueryError) {
-    throw new Error(`Query error: \${error.message}`);
-  }
-  throw error;
-}
-```
-
-## Frontend System (web/app.js)
-
-### Translation System
-
-**Basic Usage:**
-```javascript
-// Translate strings
-App.lang.t('Hello World')  // Returns translated version or original
-App.lang.t('Save changes')
-
-// Set language
-App.lang.set('pl')     // Switch to Polish
-App.lang.set('en')     // Switch to English
-App.lang.get()         // Get current language code
-```
-
-**Translation File (web/translations.json):**
-```json
-{
-  "pl": {
-    "Hello World": "Witaj Świecie",
-    "Save changes": "Zapisz zmiany",
-    "Delete": "Usuń"
-  },
-  "ru": {
-    "Hello World": "Привет мир",
-    "Save changes": "Сохранить изменения"
-  }
-}
-```
-
-### UI Feedback & Notifications
-
-**Toast Notifications:**
-```javascript
-App.ui.showToast('Success message', 'success')  // Green toast
-App.ui.showToast('Error occurred', 'error')     // Red toast  
-App.ui.showToast('Information', 'info')         // Blue toast
-App.ui.showToast('Warning', 'warning')          // Yellow toast
-```
-
-**Inline Messages:**
-```javascript
-App.ui.showMessage('messageId', 'Success!', 'success')
-App.ui.showMessage('errorContainer', 'Validation failed', 'error')
-```
-
-**Modal Dialogs:**
-```javascript
-App.ui.showModal('confirmModal', 'Item saved successfully', 'success')
-App.ui.showModal('errorModal', 'Operation failed', 'error')
-```
-
-### Navigation & Page Actions
-
-**Navigation Functions:**
-```javascript
-// SPA-style navigation
-App.nav.go('/posts/123')  // Loads via AJAX, updates #main
-
-// Or use native browser APIs directly
-window.history.back()      // Go back in history
-window.location.href = '/posts'  // Full page redirect
-window.location.reload()   // Reload page
-```
-
-### Form Handling & Strategy System
-
-**Form Strategy Configuration:**
-```html
-<!-- Form with strategy attributes -->
-<form data-strategy='["toast", "back"]' 
-      data-entity-name="Post"
-      data-field-types='{"age": "number", "active": "boolean"}'>
-  <input name="title" type="text" required>
-  <input name="age" type="number">
-  <input name="active" type="checkbox">
-  <button type="submit">Save</button>
-</form>
-```
-
-**Available Strategies:**
-- `toast` - Show success toast notification
-- `back` - Navigate back using browser history
-- `message` - Show inline message in specific element
-- `modal` - Show modal dialog
-- `redirect` - Redirect to specific URL
-- `refresh` - Reload the page
-- `remove` - Remove form element
-
-**Manual Form Submission:**
-```javascript
-const form = document.querySelector('#myForm');
-App.nav.submit(form, ['toast', 'back'], {
-  entityName: 'Post',
-  basePath: '/posts',
-  messageId: 'form-message'
-});
-```
-
-### Loading States & Utilities
-
-**Loading Indicators:**
-```javascript
-App.ui.showLoading('#form')      // Show spinner on form
-App.ui.hideLoading('#form')      // Hide spinner
-App.ui.showLoading('#main')      // Show spinner on main content
-```
-
-**Utility Functions:**
-```javascript
-App.utils.debounce(searchFunction, 300)  // Debounce for search inputs
-App.utils.$('#selector')                  // Safe element selection
-```
-
-### Event Handling & SPA Integration
-
-**Automatic Link Handling:**
-- Internal links automatically use AJAX navigation
-- External links work normally
-- Links with `data-external` skip AJAX handling
-
-**Automatic Form Handling:**
-- Forms with `data-strategy` use AJAX submission
-- Regular forms work normally
-- Automatic JSON conversion from FormData
-
-**Custom Event Listeners:**
-```javascript
-// Re-initialize after dynamic content loading
-App.utils.initializeEventListeners();
-
-// Handle specific link navigation
-document.querySelector('#myLink').addEventListener('click', (e) => {
-  e.preventDefault();
-  App.nav.go('/custom/path');
-});
-```
-
-### Global App Object
-
-**Accessing Functions:**
-```javascript
-// All functions available under window.App
-// Organized by category for better discoverability
-
-// UI Functions
-App.ui.showToast('Message', 'success');
-App.ui.showMessage('elementId', 'Success!', 'success');
-App.ui.showModal('modalId', 'Done!', 'success');
-App.ui.showLoading('#form');
-App.ui.hideLoading('#form');
-
-// Navigation Functions
-App.nav.go('/posts/123');  // SPA-style navigation with AJAX
-App.nav.submit(formElement, ['toast', 'back'], options);  // Submit form via AJAX
-
-// Translation Functions
-App.lang.t('Translate this');  // Translate string
-App.lang.set('pl');  // Set language
-App.lang.get();  // Get current language
-
-// Utility Functions
-App.utils.$('#selector');  // Safe element selection
-App.utils.debounce(fn, 300);  // Debounce function
-App.utils.initializeEventListeners();  // Re-initialize after dynamic content
-
-// Authentication Functions (JWT)
-App.auth.setAuthToken(token);  // Store JWT token
-App.auth.clearAuthToken();  // Remove JWT token
-App.auth.buildAuthHeaders(additionalHeaders);  // Build headers with auth token
-```
-
-### Template Data Binding
-```html
-<!-- List with pagination -->
-<tbody x-for="modules" x-row="module">
-  <tr>
-    <td>{{ module.name }}</td>
-    <td><a href="/module/{{ module.id }}">View</a></td>
-  </tr>
-</tbody>
-
-<!-- Form with validation errors -->
-<div x-if="errors.name" class="text-danger">{{ errors.name }}</div>
-<input type="text" name="name" value="{{ formData.name || '' }}" class="form-control">
-
-<!-- Form with strategy attributes -->
-<form data-strategy='["toast", "back"]' 
-      data-entity-name="Module"
-      data-field-types='{"count": "number", "active": "boolean"}'>
-  <!-- form fields -->
-</form>
-```
+10. Run current diff before modifying any generated file. It shows exactly what's been committed (safe to keep) vs. what's purely generated (will be overwritten). Use it as orientation before every non-yaml change.