Save this content to: AGENTS.md

# Agent guide: `banulakwin/laravel-metadata`

Config-driven key/value metadata per **group**.

## Install

- `composer require banulakwin/laravel-metadata`
- Publish: `php artisan vendor:publish --tag=meta-config` → `config/meta.php` (field definitions + defaults).
- Migrations: package loads automatically when `metadata.register_migrations` is true, or publish `metadata-migrations`.

## Definitions source

- **`config('meta')`** — primary group/field definitions (publish `meta-config`).
- **`config('metadata.definitions')`** — optional extra inline groups/fields merged on top of `meta`.
- **`MetadataRegistry::all()`** — merges the above with PHP files under `config('metadata.definitions_path')` or default `app/Cms/Metadata/{group}.php` (each file returns `['fields' => [...]]`). Optional cache: `metadata.definitions_cache_ttl` / `definitions_cache_key`.
- **`php artisan meta:sync`** — clears definitions cache (when TTL > 0), then seeds missing DB rows from **`MetadataRegistry::all()`** (never overwrites existing values).

## PHP

- `meta_group('site')` — associative array of string values for one group.
- `app(\Banulakwin\Metadata\Services\MetadataService::class)->get('site', 'phone', null)` — typed decode when `meta.site.fields.phone.type` is set.

## Do not

- Commit generated files (`vendor/`, `composer.lock`, `coverage/`).

## Testing & Quality

```bash
composer test          # PHPUnit
composer pint          # Laravel Pint code style fix
composer pint:check    # Pint check only (no fix)
composer phpstan       # PHPStan level max on src/
composer quality       # All: pint + phpstan + test
```

## CI

GitHub Actions runs tests, Pint, and PHPStan on push/PR (`.github/workflows/tests.yml`).