@event4u/agent-config 1.9.1

package/.agent-src/skills/laravel-middleware/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: laravel-middleware
+description: "Use when creating or modifying Laravel middleware — request/response filtering, groups, priority, terminable middleware, or route-level assignment."
+source: package
+---
+
+# laravel-middleware
+
+## When to use
+
+Use this skill when working with HTTP middleware:
+- Creating custom middleware for authentication, logging, headers, etc.
+- Configuring middleware groups and priority
+- Terminable middleware (post-response processing)
+- Route-level and global middleware assignment
+
+## Procedure: Create middleware
+
+1. **Generate class** — `php artisan make:middleware EnsureCustomerIsActive`.
+2. **Implement logic** — Handle request in `handle()`, return response or pass to next.
+3. **Register** — Add to route group or global middleware stack.
+4. **Verify** — Run tests covering both allowed and blocked request scenarios.
+
+### Example
+
+```bash
+php artisan make:middleware EnsureCustomerIsActive
+```
+
+```php
+declare(strict_types=1);
+
+namespace App\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+class EnsureCustomerIsActive
+{
+    public function handle(Request $request, Closure $next): Response
+    {
+        if (!$request->user()?->getCustomer()?->isActive()) {
+            abort(403, 'Customer account is inactive.');
+        }
+
+        return $next($request);
+    }
+}
+```
+
+## Before vs. After middleware
+
+```php
+// Before middleware — runs BEFORE the request hits the controller
+public function handle(Request $request, Closure $next): Response
+{
+    // Check something before the request
+    return $next($request);
+}
+
+// After middleware — runs AFTER the controller returns a response
+public function handle(Request $request, Closure $next): Response
+{
+    $response = $next($request);
+
+    // Modify the response
+    $response->headers->set('X-Custom-Header', 'value');
+
+    return $response;
+}
+```
+
+## Terminable middleware
+
+Runs **after the response has been sent** to the browser:
+
+```php
+class LogRequestDuration
+{
+    private float $startTime;
+
+    public function handle(Request $request, Closure $next): Response
+    {
+        $this->startTime = microtime(true);
+
+        return $next($request);
+    }
+
+    public function terminate(Request $request, Response $response): void
+    {
+        $duration = microtime(true) - $this->startTime;
+        Log::info('Request duration', [
+            'url' => $request->fullUrl(),
+            'duration_ms' => round($duration * 1000, 2),
+        ]);
+    }
+}
+```
+
+## Middleware with parameters
+
+```php
+class CheckRole
+{
+    public function handle(Request $request, Closure $next, string $role): Response
+    {
+        if (!$request->user()?->hasRole($role)) {
+            abort(403);
+        }
+
+        return $next($request);
+    }
+}
+
+// Usage in routes
+Route::get('/admin', AdminController::class)->middleware('role:admin');
+```
+
+## Assigning middleware
+
+```php
+// Route-level
+Route::get('/dashboard', DashboardController::class)
+    ->middleware([EnsureCustomerIsActive::class]);
+
+// Group-level
+Route::middleware(['auth', EnsureCustomerIsActive::class])->group(function () {
+    // ...
+});
+
+// Global middleware (bootstrap/app.php)
+->withMiddleware(function (Middleware $middleware) {
+    $middleware->append(LogRequestDuration::class);
+    $middleware->prepend(SetLocale::class);
+})
+```
+
+## Middleware priority
+
+```php
+// bootstrap/app.php — control execution order
+->withMiddleware(function (Middleware $middleware) {
+    $middleware->priority([
+        AuthenticateMiddleware::class,
+        EnsureCustomerIsActive::class,
+        CheckRole::class,
+    ]);
+})
+```
+
+## Core rules
+
+- **Single responsibility** — one middleware, one concern.
+- **Early return** — abort or redirect as early as possible.
+- **Use terminable** for logging/metrics — don't block the response.
+- **Type-hint dependencies** — use constructor injection.
+- **Keep middleware thin** — delegate complex logic to services.
+
+## Output format
+
+1. Middleware class with handle method and typed request/response
+2. Registration in bootstrap or route group
+
+## Auto-trigger keywords
+
+- middleware
+- request filter
+- before middleware
+- after middleware
+- terminable
+- middleware group
+
+## Gotcha
+
+- Middleware execution order matters — registered order in the kernel defines the pipeline sequence.
+- Don't modify the response in `handle()` if the next middleware might also modify it — use `terminate()` for cleanup.
+- The model tends to forget that middleware runs on EVERY request in its group — keep it lightweight.
+
+## Do NOT
+
+- Do NOT put business logic in middleware — delegate to services.
+- Do NOT create catch-all middleware that does too many things.
+- Do NOT forget to register middleware — it won't run if not assigned.
+- Do NOT modify the request in after-middleware — use before-middleware for that.

package/.agent-src/skills/laravel-notifications/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: laravel-notifications
+description: "Use when sending notifications via mail, Slack, database, or custom channels — with queuing, on-demand recipients, and notification preferences."
+source: package
+---
+
+# laravel-notifications
+
+## When to use
+
+Use this skill when sending notifications to users or external systems:
+- Email, Slack, SMS, or database notifications
+- Custom notification channels
+- On-demand notifications (to non-user recipients)
+- Notification preferences and opt-out logic
+
+For **Mailables** (complex email templates, attachments), see [laravel-mail](../laravel-mail/SKILL.md).
+
+## Procedure: Create a notification
+
+1. **Generate class** — `php artisan make:notification InvoiceCreated`.
+2. **Choose channels** — Mail, database, Slack, or custom. Implement `via()`.
+3. **Build content** — Implement `toMail()`, `toArray()`, etc. for each channel.
+4. **Queue it** — Add `ShouldQueue` interface for non-blocking delivery.
+5. **Verify** — Send test notification, confirm delivery on all channels.
+
+### Example
+
+```bash
+php artisan make:notification InvoiceCreated
+```
+
+```php
+class InvoiceCreated extends Notification implements ShouldQueue
+{
+    use Queueable;
+
+    public function __construct(
+        private readonly Invoice $invoice,
+    ) {}
+
+    /** @return array<int, string> */
+    public function via(object $notifiable): array
+    {
+        return ['mail', 'database'];
+    }
+
+    public function toMail(object $notifiable): MailMessage
+    {
+        return (new MailMessage())
+            ->subject('New Invoice #' . $this->invoice->getNumber())
+            ->greeting('Hello ' . $notifiable->getName())
+            ->line('A new invoice has been created.')
+            ->action('View Invoice', url('/invoices/' . $this->invoice->getId()))
+            ->line('Thank you for your business.');
+    }
+
+    /** @return array<string, mixed> */
+    public function toArray(object $notifiable): array
+    {
+        return [
+            'invoice_id' => $this->invoice->getId(),
+            'amount' => $this->invoice->getAmount(),
+        ];
+    }
+}
+```
+
+## Sending notifications
+
+```php
+// Via the Notifiable trait on the model
+$user->notify(new InvoiceCreated($invoice));
+
+// Via the Notification facade (multiple recipients)
+Notification::send($users, new InvoiceCreated($invoice));
+
+// On-demand (no user model needed)
+Notification::route('mail', 'admin@example.com')
+    ->route('slack', '#billing')
+    ->notify(new InvoiceCreated($invoice));
+```
+
+## Database notifications
+
+Requires the notifications table migration:
+
+```bash
+php artisan notifications:table
+php artisan migrate
+```
+
+```php
+// Read notifications
+$user->notifications;           // all
+$user->unreadNotifications;     // unread only
+
+// Mark as read
+$notification->markAsRead();
+$user->unreadNotifications->markAsRead();
+```
+
+## Slack notifications
+
+```php
+public function toSlack(object $notifiable): SlackMessage
+{
+    return (new SlackMessage())
+        ->text('Invoice #' . $this->invoice->getNumber() . ' created')
+        ->headerBlock('New Invoice')
+        ->sectionBlock(function (SectionBlock $block) {
+            $block->text('Amount: ' . $this->invoice->getAmount());
+        });
+}
+```
+
+## Notification preferences
+
+```php
+public function via(object $notifiable): array
+{
+    // Respect user preferences
+    $channels = ['database'];
+
+    if ($notifiable->wantsEmailNotifications()) {
+        $channels[] = 'mail';
+    }
+
+    if ($notifiable->wantsSlackNotifications()) {
+        $channels[] = 'slack';
+    }
+
+    return $channels;
+}
+```
+
+## Core rules
+
+- **Always queue notifications** — implement `ShouldQueue` to avoid blocking requests.
+- **Keep payloads small** in `toArray()` — store IDs, not full objects.
+- **Use `via()` for channel logic** — don't hardcode channels, respect user preferences.
+- **On-demand for external recipients** — use `Notification::route()` for non-user targets.
+- **Database notifications for in-app** — use the notifications table for in-app notification centers.
+
+## Output format
+
+1. Notification class with via() and channel-specific methods
+2. Queued dispatch with proper serialization
+
+## Auto-trigger keywords
+
+- notification
+- notify
+- Notifiable
+- MailMessage
+- SlackMessage
+- database notification
+
+## Gotcha
+
+- Don't send notifications synchronously in request lifecycle — always queue them.
+- The model forgets to implement `toArray()` for database notifications — it throws silently.
+- `via()` method must return an array even for a single channel — `return ['mail']`, not `return 'mail'`.
+
+## Do NOT
+
+- Do NOT store large objects in database notification `data` — use IDs and fetch on read.
+- Do NOT use notifications for complex emails — use [Mailables](../laravel-mail/SKILL.md) instead.

package/.agent-src/skills/laravel-pennant/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: laravel-pennant
+description: "Use when working with feature flags — Laravel Pennant, gradual rollouts, A/B testing, scope-based flags — even when the user just says 'hide this behind a flag' without naming Pennant."
+source: package
+---
+
+# laravel-pennant
+
+## When to use
+
+Use this skill when working with feature flags:
+- Gradual feature rollouts (percentage-based)
+- Per-user or per-tenant feature toggling
+- A/B testing with feature variants
+- Environment-based feature gating
+
+## Procedure: Set up feature flags
+
+1. **Install** — `composer require laravel/pennant`, publish config, run migrations.
+2. **Define feature** — Create feature class or use closure-based definition.
+3. **Check feature** — Use `Feature::active('feature-name')` in code.
+4. **Verify** — Confirm feature is active/inactive for correct scopes. Run tests.
+
+### Installation
+
+```bash
+composer require laravel/pennant
+php artisan vendor:publish --provider="Laravel\Pennant\PennantServiceProvider"
+php artisan migrate
+```
+
+## Defining features
+
+### Class-based features (recommended)
+
+```bash
+php artisan pennant:feature NewDashboard
+```
+
+```php
+declare(strict_types=1);
+
+namespace App\Features;
+
+use App\Models\User;
+use Illuminate\Support\Lottery;
+
+class NewDashboard
+{
+    /** Resolve the feature's initial value. */
+    public function resolve(User $user): bool
+    {
+        // Percentage rollout
+        return Lottery::odds(1, 10)->choose();  // 10% of users
+    }
+}
+```
+
+### Closure-based features
+
+```php
+// In a service provider
+use Laravel\Pennant\Feature;
+
+Feature::define('new-dashboard', function (User $user): bool {
+    return $user->getCustomer()?->isEarlyAdopter() ?? false;
+});
+
+// Rich values (A/B testing)
+Feature::define('checkout-button', function (User $user): string {
+    return Arr::random(['blue', 'green', 'red']);
+});
+```
+
+## Checking features
+
+```php
+// Boolean check
+if (Feature::active('new-dashboard')) {
+    // Show new dashboard
+}
+
+// Via the user model (HasFeatures trait)
+if ($user->features()->active('new-dashboard')) {
+    // ...
+}
+
+// Rich value
+$color = Feature::value('checkout-button');  // 'blue', 'green', or 'red'
+
+// Blade directive
+@feature('new-dashboard')
+    <x-new-dashboard />
+@else
+    <x-legacy-dashboard />
+@endfeature
+```
+
+## Managing features
+
+```php
+// Activate for a specific user
+Feature::for($user)->activate('new-dashboard');
+
+// Deactivate
+Feature::for($user)->deactivate('new-dashboard');
+
+// Activate for everyone
+Feature::activateForEveryone('new-dashboard');
+
+// Deactivate for everyone
+Feature::deactivateForEveryone('new-dashboard');
+
+// Purge stored values (re-resolve on next check)
+Feature::purge('new-dashboard');
+```
+
+## Scopes
+
+Features can be scoped to any model, not just users:
+
+```php
+// Per-tenant feature
+Feature::for($customer)->active('advanced-reporting');
+
+// Define with tenant scope
+Feature::define('advanced-reporting', function (Customer $customer): bool {
+    return $customer->getPlan() === 'enterprise';
+});
+```
+
+## Drivers
+
+| Driver | Storage | Use case |
+|---|---|---|
+| `database` | DB table | Production — persistent, shared across servers |
+| `array` | In-memory | Testing — no persistence |
+
+```php
+// config/pennant.php
+'default' => env('PENNANT_STORE', 'database'),
+```
+
+## Eager loading
+
+```php
+// Prevent N+1 when checking features for multiple users
+Feature::for($users)->loadAll();
+
+// Load specific features
+Feature::for($users)->load(['new-dashboard', 'advanced-reporting']);
+```
+
+## Core rules
+
+- **Use class-based features** for anything non-trivial — they're testable and discoverable.
+- **Scope to the right model** — user, customer, or team depending on the feature.
+- **Eager load** when checking features for collections of users.
+- **Purge after full rollout** — remove the flag once 100% of users have the feature.
+- **Use `array` driver in tests** — prevents test pollution.
+- **Clean up old flags** — feature flags are temporary, not permanent config.
+
+## Output format
+
+1. Feature flag definition with scope and resolve logic
+2. Integration in controllers/services using Feature::active()
+
+## Auto-trigger keywords
+
+- feature flag
+- feature toggle
+- Pennant
+- gradual rollout
+- A/B test
+- feature gate
+
+## Gotcha
+
+- Feature flags in database driver require migration — don't forget `php artisan pennant:purge` for cleanup.
+- The model tends to check flags without a scope — always pass the authenticated user or a default scope.
+- Don't nest feature flag checks — it makes the logic impossible to reason about.
+
+## Do NOT
+
+- Do NOT leave feature flags forever — remove them after full rollout.
+- Do NOT use feature flags for permanent configuration — use config files.
+- Do NOT check features in tight loops without eager loading.
+- Do NOT forget to purge stored values when changing the resolve logic.

package/.agent-src/skills/laravel-pulse/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: laravel-pulse
+description: "Use when setting up Laravel Pulse — real-time dashboard, built-in cards, custom recorders, performance insights — even when the user just says 'I need app monitoring' without naming Pulse."
+source: package
+---
+
+# laravel-pulse
+
+## When to use
+
+Use this skill when working with Laravel Pulse:
+- Setting up the Pulse monitoring dashboard
+- Configuring built-in recorders (slow queries, exceptions, queues, etc.)
+- Creating custom Pulse cards and recorders
+- Performance monitoring and alerting
+
+## Procedure: Set up Pulse
+
+1. **Install** — `composer require laravel/pulse`, publish config, run migrations.
+2. **Configure** — Set up recorders in `config/pulse.php`.
+3. **Add dashboard** — Register route and authorize access.
+4. **Verify** — Visit `/pulse` dashboard, confirm data is being recorded.
+
+### Installation
+
+```bash
+composer require laravel/pulse
+php artisan vendor:publish --provider="Laravel\Pulse\PulseServiceProvider"
+php artisan migrate
+```
+
+## Dashboard
+
+### Access control
+
+```php
+// PulseServiceProvider or Gate
+Gate::define('viewPulse', function (User $user): bool {
+    return $user->isSuperuser();
+});
+```
+
+### Dashboard route
+
+Pulse registers `/pulse` automatically. Customize in `config/pulse.php`:
+
+```php
+'path' => 'pulse',
+'middleware' => ['web', 'auth'],
+```
+
+## Built-in cards
+
+| Card | What it shows |
+|---|---|
+| `<livewire:pulse.servers />` | CPU, memory, storage per server |
+| `<livewire:pulse.usage />` | Top users by request count |
+| `<livewire:pulse.queues />` | Queue throughput and wait times |
+| `<livewire:pulse.slow-queries />` | Slowest database queries |
+| `<livewire:pulse.slow-requests />` | Slowest HTTP requests |
+| `<livewire:pulse.slow-jobs />` | Slowest queued jobs |
+| `<livewire:pulse.slow-outgoing-requests />` | Slowest external HTTP calls |
+| `<livewire:pulse.exceptions />` | Most frequent exceptions |
+| `<livewire:pulse.cache />` | Cache hit/miss ratio |
+
+### Dashboard view
+
+```blade
+{{-- resources/views/vendor/pulse/dashboard.blade.php --}}
+<x-pulse>
+    <livewire:pulse.servers cols="full" />
+
+    <livewire:pulse.usage cols="4" rows="2" />
+    <livewire:pulse.queues cols="4" />
+    <livewire:pulse.cache cols="4" />
+
+    <livewire:pulse.slow-queries cols="8" />
+    <livewire:pulse.exceptions cols="4" />
+
+    <livewire:pulse.slow-requests cols="6" />
+    <livewire:pulse.slow-jobs cols="6" />
+</x-pulse>
+```
+
+## Configuration
+
+### config/pulse.php
+
+```php
+'recorders' => [
+    \Laravel\Pulse\Recorders\SlowQueries::class => [
+        'enabled' => true,
+        'threshold' => 1000,  // ms
+        'sample_rate' => 1.0,
+    ],
+    \Laravel\Pulse\Recorders\SlowRequests::class => [
+        'enabled' => true,
+        'threshold' => 1000,  // ms
+        'sample_rate' => 1.0,
+    ],
+    \Laravel\Pulse\Recorders\Exceptions::class => [
+        'enabled' => true,
+        'sample_rate' => 1.0,
+    ],
+],
+
+// Data retention
+'ingest' => [
+    'trim' => [
+        'lottery' => [1, 1000],
+        'keep' => '7 days',
+    ],
+],
+```
+
+## Custom recorders
+
+```php
+use Laravel\Pulse\Facades\Pulse;
+
+// Record a custom entry
+Pulse::record('api_call', 'stripe', 250)  // type, key, value
+    ->avg()
+    ->count();
+```
+
+## Core rules
+
+- **Trim old data** — configure retention to prevent database bloat.
+- **Use sample rates** in production — not every request needs recording.
+- **Separate database** — consider a dedicated DB connection for Pulse data.
+- **Restrict access** — always gate the dashboard behind authentication.
+- **Monitor what matters** — don't enable all recorders if you don't need them.
+
+## Output format
+
+1. Pulse configuration with recorders and dashboard cards
+2. Custom recorder class if needed
+
+## Auto-trigger keywords
+
+- Pulse
+- monitoring dashboard
+- slow queries
+- slow requests
+- application monitoring
+- performance dashboard
+
+## Gotcha
+
+- Pulse stores data in the same database by default — configure a separate connection for production.
+- The model forgets that Pulse data is sampled, not exact — don't use it for billing or exact counts.
+- Custom recorders must be registered in a service provider — they don't auto-discover.
+
+## Do NOT
+
+- Do NOT expose the Pulse dashboard without authentication.
+- Do NOT set sample rate to 1.0 on high-traffic production — use 0.1 or lower.
+- Do NOT forget to run `pulse:check` for server metrics.
+- Do NOT store Pulse data in the main application database on large apps.