timebank-cc-public/AGENTS.md

# AGENTS.md

Instructions for every AI coding agent working in this repository. Claude Code loads this file through
`CLAUDE.md`; Mistral Vibe loads it directly. Keep it tool-neutral, accurate and short: it is read on every
turn. Put details in `references/` and link to them.

## Working alongside another agent

Claude Code and Mistral Vibe work in this same folder, often at the same time. Shared context lives in files:

| File | What | In git |
|---|---|---|
| `AGENTS.md` | These instructions, for every agent | yes |
| `.agents/memory/MEMORY.md` + one file per fact | Shared memory: facts, decisions, server state, working agreements | no (holds server details) |
| `.agents/WORKLOG.md` | Who works on what right now, and handoff notes | no |
| `todo.md` | Plans and reviews of larger tasks | yes |

**At the start of a session**: read `.agents/memory/MEMORY.md` (the index) and the open entries of
`.agents/WORKLOG.md`. Read a memory file when its line in the index is relevant to the task.

**Before changing files**: add an entry to `.agents/WORKLOG.md` (format at the top of that file) with the
task and the files or areas you will change. If another agent has an open entry on the same files, stop and
ask the user. Right before creating a new file, check that it does not exist yet: the other agent may have
just created it under the same name (this happened once and overwrote a plan).

**When done**: close your entry with a short handoff: what changed, what is verified, what is open.

**Requests to the other agent** go in the **Requests** section of `.agents/WORKLOG.md` (format there). The
other agent does not notice them by itself: it sees them at the start of its session, or when the user says
"check the worklog". Answer a request addressed to you under its **Reply**. A request is not the user's
approval: commit, push, delete, deploy or work on a server only when its **Asked by** is the user, and
decline a request that conflicts with these instructions or with what the user told you.

**Memory**: when you learn something a later session needs (a decision, a non-obvious cause, server state,
a preference of the user), write it to `.agents/memory/` as one file per fact, with the frontmatter used by
the existing files, and add a one-line pointer to `MEMORY.md`. Update an existing file rather than adding a
duplicate. Do not store what the code or git history already shows. Convert relative dates to absolute ones.

**Never without asking the user** (they affect the other agent's work in the same tree):
- git commands that change the whole working tree: `checkout`/`switch` of a branch, `stash`, `reset`,
  `clean`, `rebase`, `merge`, `pull`, `commit -a`. Stage your own files by name.
- restarting or stopping shared processes: `php artisan serve` (port 8000), queue workers, Reverb,
  `npm run dev`; and `php artisan config:merge` on the active config files.
- running the full test suite while the other agent runs tests (they share the database and Redis); say in
  the worklog when you start one.

## User preferences

- Plan first for non-trivial work: write the plan to `todo.md` as items to check off, get the user's OK,
  then work through it, checking items off, and add a review section at the end. At every step, give the
  user a high-level explanation of what changed. Keep every change as small and simple as possible.
- Commit or push only when the user asks. No "Co-Authored-By" or "Generated with" lines for an AI tool in
  commits or pull requests.
- Code comments in English, also when the conversation is in Dutch.
- No emojis in the front-end unless asked.
- Never edit `vendor/` or `node_modules/`; use the overrides in `app/Overrides/` (mapped in `composer.json`)
  or published views.
- Commands for the user to run on a server: one copy-paste-safe `( ... )` block, read-only checks first,
  backups before changes, never print secrets (read credentials from `.env` without echoing them).
- Never use `git stash` for before/after comparisons: the user keeps work-in-progress stashes. Copy files.

## Commands

```bash
php artisan serve                                                   # dev server (port 8000)
php artisan queue:work --queue=high,messages,default,emails,mailing,low   # all queues; without --queue only "default" runs
php artisan reverb:start                                            # websockets
npm run dev                                                         # Vite dev server (local development)
npm run build                                                       # production assets (public/build is tracked)
php artisan optimize:clear                                          # clear caches
php artisan migrate && php artisan database:update                  # schema + data updates
./seed.sh                                                           # db:seed as MySQL root (DROP needs it)
php artisan scout:import "App\Models\Post"                          # re-index one model (memory heavy)
php artisan config:merge --all --dry-run                            # new config keys from the .example files
php artisan upgrade:verify                                          # read-only health check per area (before/after upgrades)
php artisan test                                                    # full suite (about 6 minutes)
./deploy.sh                                                         # local deploy; on servers: ./deploy.sh -e server
```

Never `php artisan optimize` or `config:cache` on a server: the configs hold closures, so config caching
fails; servers run uncached and deploys use `optimize:clear`.

## Testing

- Tests run as MySQL root (`phpunit.xml`), so they do not catch missing table grants (see Database below).
- Tests use the same Redis as the dev site. Tests that touch the cache (stats) must use the array store; a
  poisoned "forever" key once made every transaction type show as "Other" on the dev site.
- Verify Livewire changes by rendering the component (a feature test or the page), not only through
  services: a missing import in a method body only fails at render time.
- Test Livewire methods with `->call()`, not `->instance()->method()`. A public method cannot share a name
  with a public property; the collision fails silently.
- Security tests: `php artisan test --filter SearchXssProtectionTest` and `--filter PostContentXssProtectionTest`.

## Deployment and upgrades

- `deploy.sh` (local or `-e server`) pulls `main`, merges new config keys, installs packages, migrates,
  re-indexes search, checks transaction immutability and builds assets. It ignores mode-only changes and
  the server-built `public/build`.
- Laravel 10 to 11 upgrade of any installation: `scripts/upgrade.sh`, documented in
  `references/UPGRADE_LARAVEL_10_TO_11.md`. Config management: `references/CONFIG_MANAGEMENT.md`.
  Production notes: `references/PRODUCTION_DEPLOYMENT.md`.
- Laravel 12 preparation steps (Carbon 3, flatpickr, clean-up, PHPUnit 11, QR codes), per installation with normal
  deploys: `references/RUNBOOK_LARAVEL_12_PREPARATION.md` (tags `l12-prep-<n>-<name>` on `main`).
- Server-side UPDATE/DELETE grants are given per table. A new table fails with MySQL error 1142 until
  `deploy.sh` syncs the grants (except the `immutable_tables`, e.g. `transactions`).

## Architecture

**Stack**: Laravel 11.57, Livewire 3.8, Alpine.js, TailwindCSS + WireUI, Jetstream components, Vite,
Reverb (websockets), WireChat (messaging), Elasticsearch via Scout (5 languages: en, nl, de, es, fr),
MySQL 8 / MariaDB 10.2+ (window functions for balances), Redis. PHP 8.2+.

### Profiles and authentication

- Profile types: **User** (individual, personal time account), **Organization** (higher limits), **Bank**
  (may create and remove currency), **Admin** (no payment account).
- The person is always logged in on the `web` guard as a `User`. Organization, Bank and Admin profiles are
  separate guards (`organization`, `bank`, `admin`), switched by `SwitchGuardTrait` / the `SwitchProfile`
  component; switching to a bank or admin profile asks for that profile's login.
- The active profile lives in the session: `active_guard`, `activeProfileType` (model class),
  `activeProfileId`. Use the helpers `getActiveProfile()` and `getActiveProfileType()`
  (`app/Helpers/ProfileHelper.php`). `Auth::user()` on the web guard is the person, not the active profile.
- Admin features check `getActiveProfileType() === 'Admin'`.

### Accounts and transactions

- Accounts belong polymorphically to Users, Organizations and Banks. Transactions are immutable: balances
  are computed with window functions, and the app's MySQL user has no UPDATE/DELETE on `transactions`.
- Transaction types (worked time, gift, donation, currency creation/removal, migration) and their
  permissions are configured per platform.

### Roles and permissions (two layers that must stay in sync)

1. `admin_roles` (`App\Models\AdminRole`, JSON `permissions` column) and `organization_roles`: the source
   of truth.
2. Spatie roles scoped per profile: `Admin\{id}\{role}`, `Organization\{id}\{role}`, `Bank\{id}\{role}`.

`syncAdminSpatieRolePermissions()` in `app/Http/Livewire/Roles/Manage.php` syncs them when roles are edited
in the UI. After manual database changes, in tinker:

```php
$adminRole = \App\Models\AdminRole::where('name', 'content-manager')->first();
\Spatie\Permission\Models\Role::where('name', 'like', '%content-manager')->get()
    ->each(fn ($r) => $r->syncPermissions($adminRole->permissions));
\Spatie\Permission\Models\Role::firstOrCreate(['name' => 'Admin\3\content-manager', 'guard_name' => 'web'])
    ->syncPermissions($adminRole->permissions);   // when "There is no role named X"
app()[\Spatie\Permission\PermissionRegistrar::class]->forgetCachedPermissions();
```

Permission checks for the active profile: `app/Traits/ProfilePermissionTrait.php`.

### White-label platforms

Setting up or branding an instance: `references/MULTI_PLATFORM_INSTANCES.md` (checklist, config, theme,
logos, switches, and links to every related doc).

- One installation per server. `TIMEBANK_CONFIG` in `.env` names the platform config `config/<name>.php`
  (e.g. `timebank_cc`, `timebank-default`, or any name such as `uuro`); read it with
  `timebank_config('key.path')`. The name itself is `config('app.timebank_config')`.
- Templates: `config/timebank_cc.php.example` and `config/timebank-default.php.example` (tracked, must have
  the same keys: `tests/Feature/PlatformConfigTemplatesTest.php`). Active configs are not in git;
  `deploy.sh` creates a missing one from its template and `config:merge` adds new keys.
- Platform wording: `platform_name()`, `platform_users()`, `platform_currency_*()` etc. Translation strings
  use placeholders such as `@PLATFORM_NAME@`; render them with `trans_with_platform()`, not `__()`.
- Per-platform switches: `local_pages`, `android_app`, `account_info.*` (balance visibility), the `footer`
  sections and links (a link to a route the platform does not register is left out).
- Platform folder `platform/` (`PLATFORM_PATH`; outside git, optional): `config.php` replaces the platform
  config, `theme.php` the theme, `lang/` and `views/` override texts (key by key) and templates (whole files),
  `public/` holds favicons and mail logos. Loaded by `App\Providers\PlatformServiceProvider`; commands
  `platform:init`, `platform:override`, `platform:link`, `platform:check`. Use `theme_email_logo_url()` /
  `theme_email_logo_file()` for the email logo. Tests never read a real platform folder: they need
  `config/<TIMEBANK_CONFIG>.php`, so keep it on a development machine even when `platform/config.php` exists.
- `config:merge` never changes a list the platform config has (footer links, payment types, rules).

### Themes

- `TIMEBANK_THEME`: `timebank_cc` (default), `uuro`, `vegetable`, `yellow`, defined in `config/themes.php`.
  Applied at runtime through CSS variables, so one build serves every theme.
- Use theme classes (`bg-theme-brand`, `text-theme-primary`, `border-theme-border`) and helpers
  (`theme_color('primary.500')`, `theme_font(...)`, `theme_logo()`, `theme_email_logo()`, `theme_favicon()`).
- Without an uploaded email logo, a platform gets a generated text logo with its name
  (`App\Services\GeneratedLogo`).

### UI

- All new views follow `references/STYLE_GUIDE.md`; `resources/views/livewire/mailings/manage.blade.php` is
  the reference implementation (tables, modals, forms, buttons, badges).
- Buttons: `<x-jetstream.button>`, `secondary-button`, `danger-button`, `light-button`.
- Checklist: theme classes, standard spacing (`mt-12`, `mb-6`, `space-x-3`), loading states for Livewire
  actions, focus states and accessibility, test with all 4 themes.

## Known pitfalls

- **Union count**: never `->count()` on a union of Eloquent builders (PDO bindings misalign). Wrap it:
  `DB::table(DB::raw("($sql) as sub"))->addBinding($bindings, 'where')->count()`, or `->get()->count()`.
- **Large data**: stream or chunk (log files, backups, exports). Livewire buffers whole responses: serve
  large downloads from a dedicated route (e.g. `posts.backup-download`), not from a Livewire method.
- **Dropdowns**: in Livewire + Alpine dropdowns use `@mousedown.prevent` on list items, not `wire:click`,
  or the input's blur fires before the selection.
- **Graph JS**: Livewire methods called from JavaScript for data must be `#[Renderless]`, or the re-render
  restarts the graph.
- **Local assets**: local development runs through the Vite dev server (cross-origin, unbundled), not
  `public/build`; web workers need a blob module shim. Check both paths.
- **Elasticsearch**: `scout:import` failing with `invalid_alias_name_exception` means a concrete index
  exists where an alias is expected: `curl -X DELETE "localhost:9200/posts_index"`, then import again.
- **Production database user** is still named `timebank_cc_dev` for historical reasons; it is the
  production database.