Save this content to: AGENTS.md

# Agent guide: `banulakwin/filament-page-builder`

Filament admin panel for CMS content managed by `banulakwin/laravel-page-builder`.

## Mental model

- Runtime content source is `page_contents` (not PHP definition files).
- Definitions from `PageRegistry::all()` are schema/default metadata, not live content.
- `__common` page key represents `config('pages.common_sections')` content.
- Never overwrite editor-managed content during sync-style flows.
- Repeater/group values are stored as JSON strings in `page_contents.value`.

## Current package surface

- Plugin: `Banulakwin\FilamentPageBuilder\FilamentPageBuilderPlugin`
- Resource: `Banulakwin\FilamentPageBuilder\Resources\PageBuilderContents\PageBuilderContentResource`
- Pages:
  - `ListPageBuilderContents`
  - `EditPageBuilderContent`
  - `ViewPageBuilderContent`

### Current list-page UX

- Page selector is Filament-native (`SelectFilter`) with toolbar dropdown trigger.
- `deferFilters(false)` is enabled for immediate filter application.
- Records are grouped by `section`.
- Grouping settings UI is hidden; groups are collapsed by default.
- Labels are prettified (`common-footer` => `Common Footer`).

### Current edit-page UX

- Field type is resolved from `PageRegistry` config for the current row.
- Field configs may include optional **`label`**, **`rules`** (Laravel string rules), **`meta`** (e.g. `aspect_ratio`, `crop`, `image_editor`, `width`/`height` hints), **`disk`**, and **`path`** (storage directory on that disk). `Banulakwin\PageBuilder\Support\CmsFieldRules` maps `rules` to Filament validation and file limits; images use `CommonImageUpload` with disk/path and meta-driven aspect ratio and cropping.
- Scalar fields are type-aware: `text`, `textarea`, `url`, `color`, `image`, `richtext`.
- `group` fields render schema-driven nested fields from config (supports nested `group` / `repeater`).
- `repeater` fields render schema-driven item rows from config (supports nested `group` / `repeater`).
- Repeater row keys are fixed to configured field names; only values are editable.
- New repeater rows auto-seed configured subfields with defaults.

## Do

- Keep resource operations non-destructive for existing values.
- Prefer deriving selectable page keys from `PageRegistry::all()`.
- Keep navigation in `Content Management`.
- Keep list query constrained to definition-backed keys only.
- Preserve nested JSON shape when reading/saving repeater/group values.
- Build input components from configured field type recursively for nested structures.

## Do not

- Do not read CMS PHP files on web requests for runtime rendering.
- Do not add `updateOrCreate`-style sync behavior that can overwrite edited values.
- Do not couple this package to app-specific resources or models.
- Do not allow arbitrary extra nested keys in repeater items when schema is fixed in config.
- 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`).