@event4u/agent-config 1.9.1

package/.agent-src/guidelines/php/artisan-commands.md

@@ -0,0 +1,81 @@
+# Artisan Command Guidelines
+
+> Console command conventions — naming, structure, input/output, safety, scheduling.
+
+**Related Skills:** `artisan-commands`
+**Related Guidelines:** [patterns/service-layer.md](patterns/service-layer.md)
+
+## Naming
+
+- Clear, intention-revealing names: `users:cleanup`, `orders:sync`, `reports:generate`
+- Follow Laravel naming style: `{domain}:{action}`
+
+## Structure
+
+- Commands **orchestrate** — they accept input, validate conditions, call services, report results.
+- Heavy business logic belongs in services/actions, not in `handle()`.
+- Keep `handle()` readable and linear.
+
+## Input
+
+- **Arguments** for required primary input.
+- **Options** for toggles, filters, execution modes.
+- Validate critical inputs before expensive/destructive work.
+- Provide safe defaults where appropriate.
+- Use `--force` flag for destructive commands — always check it.
+
+## Output
+
+- Use `$this->info()`, `$this->warn()`, `$this->error()`, `$this->table()`, progress bars.
+- Keep output readable for both humans and logs.
+- Don't flood the console — use verbose mode for noisy output.
+- `$this->info()` is suppressed in quiet mode — use `$this->line()` for critical info.
+
+## Interactive vs Automated
+
+- Use confirmations for destructive operations in manual commands.
+- **Never** add interactive prompts to scheduler/CI commands.
+- Support non-interactive execution (`--no-interaction`).
+
+## Batch and Long-Running
+
+- Use chunking, cursors, or batching for large datasets.
+- Report progress for long-running tasks.
+- Handle partial failures intentionally.
+- Avoid loading large datasets into memory at once.
+
+## Safety
+
+- Treat cleanup, repair, sync, and deletion as high-risk.
+- Add safeguards for destructive operations.
+- Be explicit about dry-run behavior if supported.
+- Never perform irreversible work silently.
+- Add environment checks for production commands.
+
+## Scheduling
+
+Commands for the scheduler must:
+- Run non-interactively
+- Be idempotent where possible
+- Log/report useful status
+- Fail loudly enough for monitoring
+
+## Error Handling
+
+- Fail with meaningful messages.
+- Don't swallow exceptions silently.
+- Return appropriate exit codes.
+- Surface enough context to diagnose without exposing sensitive data.
+
+## Testing
+
+- Test behavior, not just class existence.
+- Assert: exit codes, console output, side effects, option/argument behavior.
+
+## Do NOT
+
+- Put business logic in commands — delegate to services.
+- Use `dd()` or `var_dump()` — use `$this->info()` / `$this->error()`.
+- Skip input validation in command signatures.
+- Make scheduled commands interactive.
+- Run destructive operations without safeguards.

package/.agent-src/guidelines/php/blade-ui.md

@@ -0,0 +1,78 @@
+# Blade UI Guidelines
+
+> Blade template conventions — views, components, partials, forms, escaping, styling.
+
+**Related Skills:** `blade-ui`, `livewire`, `flux`
+**Related Guidelines:** [controllers.md](controllers.md)
+
+## View Structure
+
+- Use the project's existing layout system.
+- Organize templates into clear sections.
+- Extract repeated sections into partials or components.
+- Prefer semantic HTML.
+- Avoid deeply nested conditionals — use a partial/component instead.
+
+## Blade Logic
+
+- Use Blade directives for **simple presentation logic** only.
+- Keep conditionals small and view-focused.
+- No business calculations or database access in templates.
+- No heavy data transformations in Blade.
+- Move non-trivial formatting to controllers, view models, presenters, or components.
+
+## Components
+
+- Use Blade components for reusable UI pieces (when project already uses them).
+- Keep component APIs clean and explicit — clear prop/slot names.
+- Don't create a component for something used only once (unless it significantly improves clarity).
+
+## Partials
+
+- Use partials for repeated markup fragments when a full component is unnecessary.
+- Name partials clearly per project conventions.
+- Avoid deep partial hierarchies that make UI hard to trace.
+
+## Forms
+
+- Follow the project's form style for labels, inputs, validation messages, old values, session feedback.
+- Use CSRF protection correctly.
+- Render validation errors consistently.
+- Preserve user input using project conventions.
+- Reuse existing field components/partials — don't duplicate.
+
+## Validation and Feedback
+
+- Display validation errors clearly and consistently.
+- Show success/error flash messages per project conventions.
+- Keep feedback near the relevant UI.
+- Don't invent a second feedback pattern if one already exists.
+
+## Escaping and Output Safety
+
+- Escape output by default — use `{{ }}`.
+- Use `{!! !!}` only when intentionally safe and already sanitized.
+- Be careful with rich content, HTML snippets, and user-generated content.
+
+## Styling
+
+- Reuse existing CSS/Tailwind conventions.
+- Don't introduce a new styling approach in one template.
+- Match class usage with neighboring templates.
+- If the project uses design-system components, follow them.
+- Always use utility classes — not inline styles.
+
+## Accessibility
+
+- Use labels for form fields.
+- Prefer semantic elements.
+- Add ARIA only where it meaningfully improves accessibility.
+
+## Do NOT
+
+- Place business logic in Blade templates.
+- Query the database from views.
+- Echo unescaped user data without explicit sanitization.
+- Inline large blocks of CSS or JS — use asset files.
+- Duplicate repeated markup when a component/partial exists.
+- `@include` shares parent scope — components don't. Know the difference.

package/.agent-src/guidelines/php/controllers.md

@@ -0,0 +1,90 @@
+# Controller Guidelines
+
+> Project-specific controller conventions. Thin controllers, single-action pattern, OpenAPI annotations.
+
+**Related Skills:** `api-endpoint`, `laravel`, `openapi`
+**Related Guidelines:** [validations.md](validations.md), [resources.md](resources.md)
+
+## Core Rules
+
+- **Single Action Controllers** only (`__invoke()`) — no Resource Controllers
+- Each controller must have: FormRequest, OpenAPI schema attributes
+- Use Resource responses where applicable (not all controllers return JSON — e.g. Delete returns an empty response, file downloads return a file stream)
+- Thin controllers — business logic in Services/Actions
+
+## Naming Schema
+
+| Action  | Controller                  | FormRequest                | Resource             |
+|---------|-----------------------------|----------------------------|----------------------|
+| Create  | `Create{Entity}Controller`  | `Create{Entity}Request`    | `{Entity}Resource`   |
+| List    | `List{Entities}Controller`  | `List{Entities}Request`    | `{Entity}Resource`   |
+| Show    | `Show{Entity}Controller`    | `Show{Entity}Request`      | `{Entity}Resource`   |
+| Update  | `Update{Entity}Controller`  | `Update{Entity}Request`    | `{Entity}Resource`   |
+| Delete  | `Delete{Entity}Controller`  | `Delete{Entity}Request`    | empty `Response`     |
+| Restore | `Restore{Entity}Controller` | `Restore{Entity}Request`   | `{Entity}Resource`   |
+
+> List uses **plural** entity name. All others use **singular**.
+
+## HTTP Actions
+
+| Action  | Method | Path                 | Notes                                     |
+|---------|--------|----------------------|-------------------------------------------|
+| Create  | POST   | `/api/{entities}`    | JSON body                                 |
+| List    | GET    | `/api/{entities}`    | Filters, Pagination                       |
+| Show    | GET    | `/api/{entities}/{id}` |                                         |
+| Update  | PATCH  | `/api/{entities}/{id}` | JSON body                               |
+| Delete  | DELETE | `/api/{entities}/{id}` | `?force=true` for hard delete            |
+| Restore | GET    | `/api/{entities}/{id}/restore` |                                |
+
+## Controller Pattern
+
+```php
+class CreateLinkController extends Controller
+{
+    #[CreateLinkRequestSchema(path: '/links', version: '1', resource: LinkResource::class)]
+    #[CreateResourceResponseSchema(LinkResource::class)]
+    #[ValidationErrorResponse]
+    public function __invoke(CreateLinkRequest $request): LinkResource
+    {
+        $link = Link::create($request->validated());
+        return LinkResource::make($link);
+    }
+}
+```
+
+**Key points:**
+- Use `$request->validated()` — never `$request->all()`
+- Use `Resource::make()` instead of `new Resource()` (easier to test)
+- Simple CRUD can live directly in the controller
+- Complex logic → Service class / Repository
+
+## Filters & Ordering
+
+Use the `pipeline` / `paginatedPipeline` macros with filter classes:
+
+```php
+$links = Link::query()
+    ->paginatedPipeline([
+        StringFilter::on('text')->isLike()->some(),
+        DateFilter::on('created_at')->all(),
+        OrderFilter::on(['id', 'name'])->default(['id' => 'asc']),
+    ]);
+```
+
+## OpenAPI Documentation
+
+- Always extend `{Action}ResourceRequestSchema` for Create/Update/List (keeps controllers clean)
+- Show/Delete/Restore use the base schema classes directly
+- No per-endpoint auth/permission error schemas (documented globally)
+- **`ValidationErrorResponse`** must be added to **every** controller that accepts input (Create, Update, etc.)
+- **`ResourceNotFoundResponse`** must be added to every controller that queries a single entity (Show, Update, Delete, Restore)
+
+| Action  | Request Schema           | Response Schema            | Error Responses                                    |
+|---------|--------------------------|----------------------------|----------------------------------------------------|
+| Create  | Extended (custom class)  | `CreateResourceResponseSchema` | `ValidationErrorResponse`                      |
+| List    | Extended (custom class)  | `ListResourceResponseSchema`  |                                                 |
+| Show    | `ShowResourceRequestSchema` | `ShowResourceResponseSchema` | `ResourceNotFoundResponse`                     |
+| Update  | Extended (custom class)  | `UpdateResourceResponseSchema` | `ValidationErrorResponse`, `ResourceNotFoundResponse` |
+| Delete  | `DeleteResourceRequestSchema` | `DeleteResourceResponseSchema` | `ResourceNotFoundResponse`                  |
+| Restore | `RestoreResourceRequestSchema` | `RestoreResourceResponseSchema` | `ResourceNotFoundResponse`               |
+

package/.agent-src/guidelines/php/database.md

@@ -0,0 +1,111 @@
+# Database Guidelines
+
+> Database conventions — indexing, query optimization, migrations, transactions, multi-connection patterns.
+
+**Related Skills:** `database`, `eloquent`, `multi-tenancy`
+**Related Guidelines:** [eloquent.md](eloquent.md)
+
+## Indexing
+
+### When to add indexes
+
+- Columns in `WHERE` clauses
+- Columns in `JOIN` conditions
+- Columns in `ORDER BY` (especially with pagination)
+- Foreign key columns (Laravel adds with `foreignId()`)
+
+### When NOT to add indexes
+
+- Boolean columns with low selectivity (99% same value)
+- Small tables (< 1000 rows)
+- Frequently updated columns (indexes slow writes)
+
+### Composite indexes
+
+Order matters — most selective column first:
+
+```php
+$table->index(['customer_id', 'created_at']);
+```
+
+## Query Optimization
+
+### EXPLAIN analysis
+
+| Column | Bad value | Meaning |
+|---|---|---|
+| `type` | `ALL` | Full table scan — needs index |
+| `rows` | High number | Too many rows examined |
+| `Extra` | `Using filesort` | Sorting without index |
+| `Extra` | `Using temporary` | Temp table — optimize GROUP BY/DISTINCT |
+| `key` | `NULL` | No index used |
+
+Good values: `type` = `ref`, `eq_ref`, `const`; `Extra` = `Using index`.
+
+### Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `SELECT *` in production | Select only needed columns |
+| `LIKE '%search%'` | Fulltext search or `LIKE 'search%'` |
+| `OFFSET` on large tables | Cursor pagination |
+| Subquery in WHERE | Rewrite as JOIN |
+| `ORDER BY RAND()` | Application-level randomization |
+
+### Pagination
+
+Always paginate list endpoints — never `get()` on unbounded queries:
+
+```php
+// Standard
+$users = User::query()->paginate(15);
+
+// Cursor pagination for large tables
+$users = User::query()->orderBy('id')->cursorPaginate(15);
+```
+
+## Migrations
+
+- Use `php artisan make:migration` to generate.
+- Use `decimal` for money — never `float`.
+- Add foreign keys with `constrained()` + proper `onDelete()`.
+- Always add indexes for searchable/filterable columns.
+- One logical change per migration.
+- Make reversible when possible (`down()` method).
+
+### Multi-connection migrations
+
+```php
+Schema::connection('tenant_database')->create('projects', function (Blueprint $table) {
+    // ...
+});
+```
+
+## Transactions
+
+```php
+// Single connection
+DB::transaction(function () use ($order, $items): void {
+    $order->save();
+    $order->items()->createMany($items);
+});
+
+// Explicit connection
+DB::connection('tenant_database')->transaction(function () {
+    // Tenant-specific operations
+});
+```
+
+## Multi-Connection Architecture
+
+- Always specify `$connection` on models.
+- Use explicit connection in migrations targeting specific databases.
+- Transactions are per-connection — cross-connection requires manual begin/commit/rollback.
+
+## Do NOT
+
+- Use raw SQL with user input — always parameterize.
+- Use `float` for money — use `decimal`.
+- Use `get()` or `all()` on large tables without pagination.
+- Run migrations without specifying connection in multi-DB project.
+- Add indexes without checking existing ones — duplicates waste write performance.

package/.agent-src/guidelines/php/eloquent.md

@@ -0,0 +1,208 @@
+# Eloquent Model Guidelines
+
+> Project-specific Eloquent conventions. Getter/setter pattern, casts, fillable, defaults.
+
+**Related Skills:** `eloquent`, `database`, `migration-creator`
+**Related Guidelines:** [patterns/repositories.md](patterns/repositories.md)
+
+## Core Rules
+
+- Add `$attributes` array for all columns with database defaults
+- Use `$casts` for type casting (encrypted, arrays, enums, dates, booleans)
+- Every model attribute MUST have a **getter** and a **fluent setter**
+- Fluent setters: prefer `static` as return type (preserves subclass types). Use `self` when the class is `final` or when `self` is intentionally more precise.
+
+## Getter/Setter Architecture
+
+There are **two layers** — inside the model vs. outside the model. Never mix them up.
+
+### Inside the model (implementing getters/setters)
+
+**ALWAYS** use `getAttribute()` / `setAttribute()` — these are the Eloquent internals
+that respect `$casts`, accessors, and mutators. **NEVER** use `$this->column_name`
+magic property access inside the model — not for attributes, not for relationships.
+
+**Cast the return value** when the attribute is NOT in `$casts`:
+
+```php
+// ✅ Good — getAttribute() with explicit cast (attribute NOT in $casts)
+public function isActive(): bool
+{
+    return (bool) $this->getAttribute('active');
+}
+
+// user_id is not in $casts, so cast explicitly
+public function getUserId(): ?int
+{
+    $value = $this->getAttribute('user_id');
+
+    return null === $value ? null : (int) $value;
+}
+
+// ✅ Good — NO manual cast needed (attribute IS in $casts)
+// protected $casts = ['is_paused' => 'boolean'];
+public function isPaused(): bool
+{
+    return $this->getAttribute('is_paused');
+}
+
+// ❌ Bad — magic property access
+public function isActive(): bool
+{
+    return (bool) $this->active;
+}
+```
+
+Fluent setter pattern:
+```php
+public function setUserId(?int $userId): static
+{
+    $this->setAttribute('user_id', $userId);
+    return $this;
+}
+```
+
+### Outside the model (calling code: services, controllers, jobs, tests, etc.)
+
+**Always use getters and setters. Never use `getAttribute()` / `setAttribute()` directly.**
+
+```php
+// ✅ Good — use getters/setters
+$config->isPaused();
+$config->setIsPaused(true)->save();
+$name = $customer->getName();
+
+// ❌ Bad — calling getAttribute/setAttribute from outside the model
+$config->getAttribute('is_paused');
+$config->setAttribute('is_paused', true)->save();
+
+// ❌ Bad — direct property access
+$config->is_paused;
+$config->is_paused = true;
+```
+
+**Why:** Getters/setters provide type safety, IDE autocompletion, and a stable API.
+If the underlying column changes, only the model internals need updating.
+
+## Relationship Getters
+
+Every relationship MUST have a **typed getter method** placed directly **above** the relationship method.
+Outside the model, always use the getter — never access the magic property.
+
+```php
+// ✅ Good — getter uses getAttribute(), placed above the relationship method
+public function getEquipment(): ?Equipment
+{
+    return $this->getAttribute('equipment');
+}
+
+public function equipment(): BelongsTo
+{
+    return $this->belongsTo(Equipment::class, 'item_id', 'item_id');
+}
+
+// ✅ Good — calling code uses getter
+$equipment = $repair->getEquipment();
+
+// ❌ Bad — magic property inside getter
+public function getEquipment(): ?Equipment
+{
+    return $this->equipment;  // NEVER do this
+}
+
+// ❌ Bad — accessing magic property from outside the model
+$equipment = $repair->equipment;
+```
+
+When checking if a relationship result exists, use `instanceof` instead of `null ===`:
+
+```php
+// ✅ Good — type-safe check
+if (!$equipment instanceof Equipment) {
+    return;
+}
+
+// ❌ Bad — less type-safe
+if (null === $equipment) {
+    return;
+}
+```
+
+## Observers over `booted()`
+
+Do NOT use `booted()` / `boot()` for model lifecycle hooks (`saving`, `saved`, `deleted`, etc.).
+Use a dedicated **Observer** class registered via the `#[ObservedBy]` attribute.
+
+```php
+// ✅ Good — Observer registered via attribute
+#[ObservedBy([RepairObserver::class])]
+class Repair extends Model { /* ... */ }
+
+// ❌ Bad — lifecycle logic in booted()
+class Repair extends Model
+{
+    protected static function booted(): void
+    {
+        static::saving(static function (Repair $repair): void { /* ... */ });
+    }
+}
+```
+
+**Why:** Observers keep models slim, make lifecycle logic testable and discoverable,
+and follow the established project pattern (all other models use `#[ObservedBy]`).
+
+## Default Attributes
+
+```php
+protected $attributes = [
+    'options' => [],
+    'default_role' => 'staff',
+    'verified' => false,
+];
+```
+
+### Expressive Setters
+
+Prefer expressive method names over generic setters when they improve readability:
+
+```php
+// ✅ Better — intent is clear
+$model->activate();
+
+// 🆗 OK but less expressive
+$model->setActive(true);
+```
+
+## Model Updates
+
+Always use validated data — never `$request->all()`:
+
+```php
+// ✅ Good
+$model->update($request->validated());
+
+// ❌ Bad — passes unvalidated data
+$model->update($request->all());
+```
+
+## Prefer Model Casts — No Redundant Manual Casting
+
+When an attribute is defined in `$casts` (or `casts()` method), do **not** manually cast it again
+in getters. The model already handles the conversion.
+
+```php
+// ✅ Good — no manual cast needed, model handles it
+public function isPaused(): bool
+{
+    return $this->getAttribute('is_paused');
+}
+
+// ❌ Bad — redundant (bool) cast when already in $casts
+public function isPaused(): bool
+{
+    return (bool) $this->getAttribute('is_paused');
+}
+```
+
+This applies to all cast types: `boolean`, `integer`, `float`, `array`, `datetime`, enums, etc.
+If the attribute is cast, trust the cast — do not re-cast in PHP.

package/.agent-src/guidelines/php/flux.md

@@ -0,0 +1,80 @@
+# Flux UI Guidelines
+
+> Flux component conventions — usage, variants, forms, icons, Livewire integration.
+
+**Related Skills:** `flux`, `livewire`, `blade-ui`
+
+## Component Usage
+
+- Use Flux components (`<flux:*>`) instead of raw HTML where a Flux equivalent exists.
+- Follow the project's existing Flux usage patterns.
+- Check Flux docs at https://fluxui.dev/docs for latest API.
+
+## Common Components
+
+```blade
+{{-- Button --}}
+<flux:button variant="primary">Save</flux:button>
+<flux:button variant="danger" wire:click="delete">Delete</flux:button>
+
+{{-- Input --}}
+<flux:input wire:model="name" label="Name" placeholder="Enter name" />
+
+{{-- Select --}}
+<flux:select wire:model="status" label="Status">
+    <flux:option value="active">Active</flux:option>
+    <flux:option value="inactive">Inactive</flux:option>
+</flux:select>
+
+{{-- Modal --}}
+<flux:modal name="confirm-delete">
+    <flux:heading>Delete item?</flux:heading>
+    <flux:text>This action cannot be undone.</flux:text>
+    <flux:button variant="danger" wire:click="delete">Confirm</flux:button>
+</flux:modal>
+
+{{-- Table --}}
+<flux:table>
+    <flux:columns>
+        <flux:column>Name</flux:column>
+    </flux:columns>
+    <flux:rows>
+        @foreach($items as $item)
+            <flux:row :key="$item->id">
+                <flux:cell>{{ $item->name }}</flux:cell>
+            </flux:row>
+        @endforeach
+    </flux:rows>
+</flux:table>
+```
+
+## Variants and Styling
+
+- Use `variant` prop: `primary`, `danger`, `ghost`, `subtle`, `outline`.
+- Use `size` prop: `sm`, `base`, `lg`.
+- Add custom Tailwind via `class` only when Flux doesn't cover the need.
+- Don't override Flux's built-in styling with conflicting classes.
+
+## Forms
+
+- Use `<flux:input>`, `<flux:textarea>`, `<flux:select>`, `<flux:checkbox>`.
+- Use `label` prop — Flux handles the `<label>` element.
+- Use `wire:model` for Livewire binding.
+- Flux components automatically display validation errors.
+
+## Icons
+
+- `<flux:icon name="heroicon-name" />` — Heroicons naming convention.
+
+## Livewire Integration
+
+- `wire:click`, `wire:submit`, `wire:model` work directly on Flux components.
+- Modals: `$this->modal('name')->show()`.
+
+## Do NOT
+
+- Use raw `<button>`, `<input>`, `<select>` when Flux equivalent exists.
+- Override Flux component styles globally — use variants or slots.
+- Mix Flux with a different UI library in the same view.
+- Skip `label` prop on form fields — accessibility matters.
+- Add manual error rendering alongside Flux (it's built-in).