Save this content to: .claude/skills/kinetix-pdf-templates/SKILL.md

# Kinetix PDF Templates Development

## When to Apply

Activate this skill when:
- Declaring a document format (`PdfTemplate` subclass, `PdfField` knobs) or registering it (`KinetixPdf::register`).
- Mounting `<KinetixPdfTemplate template="…" />` (configurator + live preview + download).
- Generating real documents (`KinetixPdf::render/pdf`) or choosing a driver (`kinetix.pdf.driver`).

## Documentation

For full details, reference `docs/pdf-templates.md` (published at https://happones.github.io/kinetix/pdf-templates).

## Essentials

```php
class QuotePdf extends PdfTemplate
{
    public static string $key = 'quote';
    public function sampleData(): array { /* preview data */ }
}

KinetixPdf::register(QuotePdf::class);          // provider boot()
$pdf = KinetixPdf::pdf('quote', $quote);        // binary, stored settings applied
```

- Models implement `Pdf\Contracts\ProvidesPdfData` (`toPdfData(): array` mapping the record onto the data shape) and are passed directly to `render()/pdf()`; the interface is optional (hybrid detection — any object with the method works), plain arrays are always accepted, other objects throw.

- Default `fields()` = standard knobs (accent/text color, font, title, logo, status, SKU, striped, footer, signature); override with `PdfField::color/text/select/toggle/number`.
- Default layout = built-in generic document (`DocumentBuilder`, dompdf-safe inline CSS). Custom: override `html()` (PHP) or `view()` (Blade, receives settings/data/template).
- Settings persist in `kinetix_pdf_templates` (publish `--tag=kinetix-pdf-migrations`), per team when team scoping applies. Endpoints gated by `viewKinetixPdf` (local-only default).
- Drivers auto-detected: spatie/laravel-pdf → barryvdh/laravel-dompdf → dompdf/dompdf. Only DECLARED fields are read from requests (undeclared keys never reach the store/renderer).

## UUID / ULID Host Models

This feature's migration builds `team_id` with
`Happones\Kinetix\Support\HostKeys`, which types each column after YOUR model
at migrate time from its primary key (`HasUlids` -> ulid, `HasUuids` -> uuid, string `$keyType` ->
string, else bigint). Pin `kinetix.key_types.user|team` when detection cannot
see the setup; morph ids follow `kinetix.key_types.morph` (default bigint) —
set it when the referenced models use UUIDs/ULIDs. Apps migrated on an older
Kinetix have bigint columns on disk and need their own ALTER migration. Full
recipe: the `kinetix-boost` skill, section "UUID / ULID Host Models".