Kai Personalize Laravel Package

Getting Started

• Install the package with Composer, publish its config and migrations, then run php artisan migrate. Start by reading config/kai.php (or the package's published config) and the service provider to see what is registered, scheduled, and exposed.
• The fastest first use case is maintenance hygiene: run php artisan kai:cleanup --days=30 --force and php artisan kai:cleanup-fingerprints --apply manually once, inspect the output, then move them into the scheduler.
• If you do not have shell access, look for Settings → Tools. v1.3.1 adds a browser runner for exactly three commands:
  • kai:cleanup-fingerprints --apply
  • kai:refresh-cache --all
  • kai:cleanup --days=30 (invoked with --force)
• Before exposing the Tools tab, confirm which role or policy grants Manage Settings. Test it with both an admin and a non-admin account.

Implementation Patterns

• Schedule the routine work, use the UI for exceptions. Put cleanup and cache refresh in routes/console.php or the console kernel:

  $schedule->command('kai:cleanup --days=30 --force')->daily();
  $schedule->command('kai:cleanup-fingerprints --apply')->weekly();
  

  Reserve the Settings → Tools tab for one-off runs or environments where shell access is unavailable.
• Always pass --force in non-interactive contexts. The new UI does this for kai:cleanup; any Artisan::call(), queued job, or scheduler entry you write must do the same or the command will wait for a confirmation that cannot arrive.
• Refresh caches after deploys and bulk imports, not on a timer. kai:refresh-cache --all is a good post-deploy hook or manual step after data migrations; avoid putting it on a high-frequency schedule.
• Wrap commands in your own service or job when you need multi-tenant or per-account cleanup. Loop tenants and call the command with explicit arguments rather than trying to parameterise the Tools tab.
• Capture output and exit codes when invoking from application code:

  $exit = Artisan::call('kai:cleanup', ['--days' => 30, '--force' => true]);
  $output = Artisan::output();
  

  Log both so scheduled runs are debuggable.
• Treat the Tools tab as an operator console. Keep destructive actions behind confirmation (already done) and behind your strongest settings-level permission. For repeatable operations, document the equivalent Artisan command alongside the button.

Gotchas and Tips

• --apply vs dry run. kai:cleanup-fingerprints is invoked with --apply in the UI; without it the command likely reports what it would delete. Do not assume a bare run has cleaned anything.
• --force is mandatory outside a terminal. The Tools tab handles this for kai:cleanup, but scheduler entries and Artisan::call() do not. A missing --force in a queued job is a classic silent hang.
• --all is dangerous on kai:cleanup. The UI deliberately fixes the argument to --days=30; if you add your own tooling, never expose a free-form argument or command string. The release's slug-plus-server-side-definition design is the pattern to copy.
• The Tools tab is intentionally not extensible from the browser. It runs three fixed server-side definitions. If you need a fourth maintenance action, add it in code with the same allow-list approach rather than introducing a generic command runner.
• Permission drift. The tab depends on Manage Settings. If you use a custom guard, policy, or a settings package with its own permission name, verify the mapping; a misconfigured gate either hides the tab or, worse, exposes destructive cleanup to the wrong role.
• Output is rendered verbatim. Command output may include file paths, record counts, or internal identifiers. Review what these commands print before giving the tab to a broad admin group.
• Web request time limits. Long cleanups can exceed max_execution_time or proxy timeouts. For large datasets, run via the scheduler or CLI; the browser runner is best for modest, interactive cleanups.
• Confirmation dialogs do not make an action idempotent. Deleting fingerprints or old records cannot be undone. Take a database snapshot before the first production run, and dry-run the underlying Artisan command first where supported.
• Debugging order: run the equivalent Artisan command with -v in staging, check the application log for the captured output, then test the Tools tab with a low-privilege account. If the tab is missing, check package discovery, the settings panel registration, and the permission gate before assuming a bug.