1.0.19

dist/globals/SiteIntegrations/index.d.ts

@@ -14,6 +14,10 @@ type BuildSiteIntegrationsArgs = {
  * impossible to enter.)
  *
  * Unnamed tabs keep data flat (siteIntegrations.ga4MeasurementId).
+ *
+ * Note: R2 storage credentials are NOT here — storage is infrastructure and
+ * binds at boot, so its config lives in .env (R2_BUCKET, R2_ENDPOINT, ...),
+ * consumed by buildR2Storage. See docs/storage.md.
  */
 export declare function buildSiteIntegrations({ additionalFields, }?: BuildSiteIntegrationsArgs): GlobalConfig;
 export {};

dist/index.d.ts

@@ -20,6 +20,9 @@ export type { I18nConfig, LocaleDefinition, LocalizedSlugs } from './modules/i18
 export { buildLocalizedPath, getDefaultLocale, getLocaleCodes, getLocaleDefinition, getLocalizedSlugs, isValidLocale, LOCALE_COOKIE_NAME, matchAcceptLanguage, negotiateLocale, switchLocalePath, } from './modules/i18n/index.js';
 export type { LocaleMiddlewareResult } from './modules/i18n/index.js';
 export { createLocaleMiddleware, DEFAULT_MIDDLEWARE_MATCHER } from './modules/i18n/index.js';
+export { normalizeFilename, normalizeFilenameHook } from './modules/media/index.js';
+export { getNotificationTexts, NOTIFICATION_FALLBACK, resolveFormMessage, } from './modules/notifications/index.js';
+export type { FormNotificationTexts, NotificationsData, NotificationTexts, } from './modules/notifications/index.js';
 export type { PagesOption, SystemPageRole } from './modules/pages/index.js';
 export { ALL_SYSTEM_PAGE_ROLES, getSystemPagePath } from './modules/pages/index.js';
 export type { GlobalQueryOptions } from './modules/payload/index.js';
@@ -31,7 +34,6 @@ export { buildHreflangAlternates, buildMetadata, composeTitle } from './modules/
 export type { AutoFillMapping, RobotsRules, SitemapEntry } from './modules/seo/index.js';
 export { buildAutoFillMetaHook, buildRobots, buildSitemapEntries, createMetadataGenerator, createPageMetadata, injectAutoFillMeta, } from './modules/seo/index.js';
 export { buildSlugField, toSlug } from './modules/slug/index.js';
-export { NOTIFICATION_FALLBACK, getNotificationTexts, resolveFormMessage, } from './modules/notifications/index.js';
-export type { FormNotificationTexts, NotificationsData, NotificationTexts, } from './modules/notifications/index.js';
+export { buildR2Storage } from './modules/storage/index.js';
 export { ipalKit } from './plugin.js';
 export type { IpalOptions } from './types.js';

dist/modules/email/graphAdapter.js

@@ -89,18 +89,19 @@ import { getSiteIntegrations } from '../payload/index.js';
                         sent: false
                     };
                 }
-                // The panel's from-address is used as Reply-To, NOT as the message From.
+                // Display name on the From, WITHOUT triggering Send-As.
                 //
-                // Why: app-only Graph sends from GRAPH_SENDER's mailbox. If we also set a
-                // `from` that differs from that mailbox, Exchange demands "Send As"
-                // permission on it and rejects with ErrorSendAsDenied otherwise. So we
-                // never override `from` — Graph stamps the mail as GRAPH_SENDER (the
-                // mailbox we legitimately own) — and route replies to the panel address
-                // via Reply-To. Recipients see the mail from forms@… but replying reaches
-                // the real destination. No Send-As needed.
+                // The trick: we may set a `from` as long as its ADDRESS stays the sender
+                // mailbox (GRAPH_SENDER) — only the display NAME changes. Exchange only
+                // demands Send-As when the from ADDRESS differs from the mailbox, so a
+                // same-address / custom-name From is allowed and gives each project its
+                // own sender label (e.g. "Kancelaria Kędzierski") over the shared mailbox.
+                //
+                // The panel's from-address becomes Reply-To (so replies reach the client),
+                // and the panel's from-name becomes the sender display name.
                 const panel = await getSiteIntegrations(payload);
                 const replyToAddress = panel.smtpFromAddress || undefined;
-                const replyToName = panel.smtpFromName || undefined;
+                const senderName = panel.smtpFromName || undefined;
                 const to = toRecipients(message.to);
                 if (to.length === 0) {
                     payload.logger.error('[ipal] Email not sent: no valid recipient.');
@@ -116,10 +117,7 @@ import { getSiteIntegrations } from '../payload/index.js';
                 const replyTo = message.replyTo ? toRecipients(message.replyTo) : replyToAddress ? [
                     {
                         emailAddress: {
-                            address: replyToAddress,
-                            ...replyToName ? {
-                                name: replyToName
-                            } : {}
+                            address: replyToAddress
                         }
                     }
                 ] : [];
@@ -136,7 +134,17 @@ import { getSiteIntegrations } from '../payload/index.js';
                     ...message.bcc ? {
                         bccRecipients: toRecipients(message.bcc)
                     } : {},
-                    // NO `from` — Graph uses GRAPH_SENDER's own mailbox, so no Send-As.
+                    // From with the sender's OWN address (no Send-As) plus an optional
+                    // display name from the panel. Omit entirely when no name is set —
+                    // Graph then uses the mailbox's default name.
+                    ...senderName ? {
+                        from: {
+                            emailAddress: {
+                                name: senderName,
+                                address: env.sender
+                            }
+                        }
+                    } : {},
                     ...replyTo.length > 0 ? {
                         replyTo
                     } : {}

dist/modules/i18n/negotiateLocale.d.ts

@@ -1,6 +1,13 @@
 import type { I18nConfig } from './types.js';
 /** Cookie name the template uses to persist a visitor's locale choice. */
-export declare const LOCALE_COOKIE_NAME = "ipal-locale";
+/**
+ * Cookie name for the persisted locale choice. Uses NEXT_LOCALE — the convention
+ * Next.js and its i18n ecosystem expect — so the cookie is interoperable with
+ * other libraries that read the active locale (instead of a plugin-specific
+ * name). Written only under functional consent; cleared when that consent is
+ * withdrawn (see consent cookieMap).
+ */
+export declare const LOCALE_COOKIE_NAME = "NEXT_LOCALE";
 type NegotiateLocaleArgs = {
     /** Raw Accept-Language header value */
     acceptLanguage?: null | string;

dist/modules/i18n/negotiateLocale.js

@@ -1,5 +1,11 @@
 import { getLocaleCodes, isValidLocale } from './helpers.js';
-/** Cookie name the template uses to persist a visitor's locale choice. */ export const LOCALE_COOKIE_NAME = 'ipal-locale';
+/** Cookie name the template uses to persist a visitor's locale choice. */ /**
+ * Cookie name for the persisted locale choice. Uses NEXT_LOCALE — the convention
+ * Next.js and its i18n ecosystem expect — so the cookie is interoperable with
+ * other libraries that read the active locale (instead of a plugin-specific
+ * name). Written only under functional consent; cleared when that consent is
+ * withdrawn (see consent cookieMap).
+ */ export const LOCALE_COOKIE_NAME = 'NEXT_LOCALE';
 /**
  * Resolves which locale to serve, in priority order:
  *   1. Cookie (explicit prior choice)

dist/modules/media/index.d.ts

@@ -0,0 +1 @@
+export { normalizeFilename, normalizeFilenameHook } from './normalizeFilename.js';

dist/modules/media/normalizeFilename.d.ts

@@ -0,0 +1,25 @@
+import type { CollectionBeforeOperationHook } from 'payload';
+/**
+ * Normalizes a filename: slugifies the NAME part (diacritics, spaces, case)
+ * while preserving the extension. Keeps uploaded media URLs clean and portable.
+ *
+ *   "Zdjęcie jeden nad morzem.jpg"  → "zdjecie-jeden-nad-morzem.jpg"
+ *   "Faktura #12 (2024).PDF"        → "faktura-12-2024.pdf"
+ *   "already-clean.webp"            → "already-clean.webp"
+ *
+ * Why not toSlug(): toSlug uses strict:true, which would strip the dot and
+ * merge name+extension. Here we split on the LAST dot, slug the stem, lowercase
+ * the extension, and rejoin.
+ */
+export declare function normalizeFilename(filename: string): string;
+/**
+ * beforeOperation hook for an upload collection (e.g. Media). Rewrites the
+ * incoming file's name to its normalized form before Payload stores it, so both
+ * the stored file and its DB filename are clean. Works with local disk and with
+ * cloud storage adapters (R2/S3) — it runs before the storage layer.
+ *
+ * Wire into your Media collection:
+ *   import { normalizeFilenameHook } from '@intecion/ipal-kit'
+ *   hooks: { beforeOperation: [normalizeFilenameHook] }
+ */
+export declare const normalizeFilenameHook: CollectionBeforeOperationHook;

dist/modules/storage/buildR2Storage.d.ts

@@ -0,0 +1,18 @@
+import type { Plugin } from 'payload';
+/**
+ * Cloudflare R2 media storage — configured from environment variables (agency
+ * infrastructure, not per-project panel data). R2 is S3-compatible, so we use
+ * @payloadcms/storage-s3 pointed at the R2 endpoint.
+ *
+ * Storage is infrastructure (like the database or PAYLOAD_SECRET): it binds at
+ * boot, and its credentials are agency-owned — so it lives in .env, not the
+ * panel. See docs/storage.md for the required variables.
+ *
+ * Returns the storage plugin when all R2 vars are present; otherwise returns a
+ * no-op passthrough so the project falls back to Payload's default local disk
+ * storage (useful in dev without R2). This mirrors how mailAdapter degrades
+ * gracefully when a transport isn't configured.
+ *
+ * @param collections - slugs of upload collections to offload to R2 (e.g. ['media'])
+ */
+export declare const buildR2Storage: (collections?: string[]) => Plugin;

dist/modules/storage/index.d.ts

@@ -0,0 +1 @@
+export { buildR2Storage } from './buildR2Storage.js';

docs/PLAYBOOK.md

@@ -0,0 +1,254 @@
+# Playbook wdrożenia — ipal-kit
+
+Sztywna procedura dla pracownika albo AI (Antigravity). Mówi CO robić, W JAKIEJ
+KOLEJNOŚCI, i CZYM SIĘ KIEROWAĆ. Zasady są twarde, przykłady realne — wzięte z
+faktycznych błędów, które się zdarzyły. Odstępstwa tylko za świadomą decyzją.
+
+Powiązane: [standardy-kodu.md](./standardy-kodu.md) (dobre praktyki senior),
+[publishing.md](./publishing.md) (cykl publikacji), [getting-started.md](./getting-started.md)
+(nowy projekt), ../ANTIGRAVITY-ZASADY-AGENT.md (zasady dla AI).
+
+---
+
+## ZŁOTE ZASADY (łam tylko świadomie)
+
+1. **Nic na sztywno.** Tekst, obraz, link, dane firmy → panel/baza, nie kod.
+2. **Logika w pluginie, projekt podłącza.** Jeśli piszesz w projekcie coś, co
+   robi już plugin — zatrzymaj się, użyj pluginu.
+3. **Next 16 = proxy.ts.** NIGDY middleware.ts. Jeśli istnieje — usuń.
+4. **Weryfikuj każdy etap grepem.** Nie zakładaj, że zadziałało. Sprawdź.
+5. **Napraw u źródła, nie łataj.** Bez `as any`, `@ts-ignore`, kopii logiki.
+6. **Zmiana w pluginie nie działa, dopóki nie: build → publish → wciągnięcie.**
+7. **Zmieniłeś API → zaktualizuj docs w tym samym commicie.** Docs jadą w
+   pakiecie; rozjazd kod↔docs = agent dostaje złą mapę.
+
+---
+
+## CZĘŚĆ A — ŁAŃCUCH ZMIANY W PLUGINIE (najważniejsze)
+
+Najczęstsze źródło frustracji tej sesji: „zmieniłem kod, a nie działa". Prawie
+zawsze przyczyna: **przerwany łańcuch**. Zmiana w pluginie przechodzi przez
+PIĘĆ etapów. Pominięcie któregokolwiek = stara wersja w projekcie.
+
+```
+źródła (src) → build (dist) → publish (rejestr) → wciągnięcie (node_modules) → restart
+```
+
+### Sztywna procedura zmiany w pluginie
+
+```bash
+cd ~/payload-cms/ipal-kit
+
+# 1. ŹRÓDŁA — nanieś zmianę, ZWERYFIKUJ że jest
+grep -c "<symbol-zmiany>" src/<ścieżka>            # MUSI być >0
+
+# 1b. DOCS — jeśli zmiana dotyka API/zachowania, ZAKTUALIZUJ docs/
+#     (nowa funkcja, zmiana sygnatury, nowe pole panelu, nowy adapter...).
+#     Docs jadą w pakiecie (files: dist, docs) — nieaktualne docs = agent
+#     dostaje złą mapę. Kod i docs publikuj RAZEM.
+
+# 2. BUILD — zbuduj, ZWERYFIKUJ że dist ma zmianę
+pnpm build
+grep -c "<symbol-zmiany>" dist/<ścieżka>           # MUSI być >0
+
+# 3. COMMIT (PRZED version — inaczej "working directory not clean")
+git add -A && git commit -m "opis"
+
+# 4. VERSION + PUBLISH
+npm version patch                                   # czyste repo wymagane
+npm publish
+
+# 5. PUSH
+git push && git push --tags
+
+# 6. PROJEKT — wciągnij, ZWERYFIKUJ że node_modules ma zmianę
+cd ~/<projekt>
+pnpm add @intecion/ipal-kit@<nowa-wersja>
+grep -c "<symbol-zmiany>" node_modules/@intecion/ipal-kit/dist/<ścieżka>   # MUSI być >0
+
+# 7. RESTART dev (Payload buduje adaptery/config przy starcie!)
+pnpm dev
+```
+
+### TRZY punkty kontrolne grep (nie pomijaj żadnego)
+
+| Etap | Grep | Jeśli 0 |
+|---|---|---|
+| po edycji | `src/...` | zmiana nie zapisana / zły plik |
+| po build | `dist/...` | build nie złapał / błąd typów |
+| po pnpm add | `node_modules/...` | projekt ma starą wersję |
+
+**Realny przykład (z tej sesji):** `buildSecurityHeaders is not a function`.
+Przyczyna: moduł istniał w `src`, ale NIE był wyeksportowany w `src/index.ts`
+→ `dist` go nie miał → import w projekcie = undefined. Grep `dist/index.js`
+pokazał 0. Naprawa: dodać eksport, przejść łańcuch od nowa.
+
+### Pułapki kolejności (realne błędy sesji)
+
+- **`npm version` przed commitem** → "Git working directory not clean". ZAWSZE
+  commit przed version.
+- **`npm publish` bez `pnpm build`** → publikujesz STARY dist. ZAWSZE build przed
+  publish, grep dist po buildzie.
+- **`pnpm add` przy działającym dev** → proces ma stary adapter w pamięci.
+  Payload czyta email/config przy starcie. ZAWSZE restart po wciągnięciu.
+- **Publikacja bez aktualizacji docs** → agent (Antigravity) po `pnpm add`
+  czyta `node_modules/@intecion/ipal-kit/docs/` z NIEAKTUALNĄ mapą. Jeśli
+  zmieniłeś API — docs w tym samym commicie.
+
+---
+
+## CZĘŚĆ B — GREP JAKO NARZĘDZIE (jak weryfikować dobrze)
+
+Grep był w tej sesji głównym narzędziem diagnozy. Ale trzeba go używać mądrze.
+
+### Reguła: grepuj TOKENY, nie całe frazy z kolejnością
+
+**Realny błąd:** grep `"env.sender, name: senderName"` dał 0, choć kod był OK —
+bo plik miał odwróconą kolejność kluczy (`name: senderName, address: env.sender`).
+Obiekt JS ignoruje kolejność, ale grep nie.
+
+```bash
+# ŹLE — zależny od kolejności/formatowania:
+grep -c "env.sender, name: senderName" plik.ts        # 0 mimo poprawnego kodu
+
+# DOBRZE — pojedynczy token, odporny:
+grep -c "senderName" plik.ts                          # 3 ✓
+```
+
+Grepuj **nazwę symbolu** (funkcja, zmienna, eksport), nie całą linię z interpunkcją.
+
+---
+
+## CZĘŚĆ C — DIAGNOSTYKA „KOD DOBRY, ZACHOWANIE ZŁE"
+
+Gdy grep potwierdza kod, wersja nowa, a zachowanie stare — przejdź listę:
+
+1. **Dev nie zrestartowany?** Payload buduje adaptery/config przy starcie.
+   Ctrl+C + `pnpm dev`. (Najczęstsza przyczyna.)
+2. **Zmiana zapisana w panelu?** Endpointy czytają z BAZY, nie z pola na ekranie.
+   Kliknij Save.
+3. **Zdublowana zależność?** `@payloadcms/ui` w node_modules pluginu = dwie
+   instancje = hooki bez kontekstu. Sprawdź:
+   `ls node_modules/@intecion/ipal-kit/node_modules/@payloadcms/ui`
+   Jest? → peerDependency problem (patrz Część D).
+4. **Cache klienta?** Np. klient pocztowy pokazuje zapamiętaną nazwę nadawcy
+   mimo poprawnych nagłówków. Sprawdź surowe źródło (View Source), wyślij na
+   inny adres.
+5. **Import map nieaktualny?** Custom komponenty Payload:
+   `npx payload generate:importmap`.
+
+**Realny przykład:** MaskedField rzucał "Cannot destructure property 'config'".
+Kod OK. Przyczyna: dublet `@payloadcms/ui` (plugin miał własną kopię) →
+`useField` z jednej instancji nie widział kontekstu z drugiej. Naprawa w Część D.
+
+---
+
+## CZĘŚĆ D — peerDependencies (dublety zależności)
+
+**Zasada:** wszystko, co dostarcza PROJEKT, jest `peerDependency` w pluginie,
+NIE `dependency`. Inaczej menedżer instaluje własną kopię dla pluginu → dublet
+→ React/Payload context się rozjeżdża (dwie instancje nie widzą się nawzajem).
+
+Peer (projekt dostarcza): `payload`, `@payloadcms/ui`, `@payloadcms/next`,
+`@payloadcms/plugin-*`, `react`, `react-dom`, `next`.
+
+**Realny błąd:** `@payloadcms/ui` był tylko w devDependencies (brak w peer) →
+pnpm dołożył kopię pluginowi → MaskedField/TestEmailButton/CookieBanner
+wszystkie się psuły (hooki bez kontekstu). Naprawa: dodać do peerDependencies,
+opublikować, w projekcie `rm -rf node_modules/@intecion/ipal-kit && pnpm add`.
+
+Weryfikacja braku dubletu:
+```bash
+ls node_modules/@intecion/ipal-kit/node_modules/@payloadcms/ui 2>/dev/null \
+  && echo "DUBLET ✗" || echo "OK ✓"
+```
+
+---
+
+## CZĘŚĆ E — NOWY PROJEKT KLIENCKI (kolejność)
+
+Pełne szczegóły: [getting-started.md](./getting-started.md). Tu skrót kolejności.
+
+1. **Szkielet** Payload 3 + Next 16, pnpm, Node 22
+2. **`.npmrc`** — `legacy-peer-deps=true` + rejestr `@intecion`
+3. **`pnpm add @intecion/ipal-kit`** + zależności peer
+4. **build script z `--webpack`** (Next 16 + Payload; Turbopack konfliktuje)
+5. **i18n.config.ts** — jedno źródło locale
+6. **payload.config.ts** — ipalKit({...}), `email: mailAdapter()`
+7. **Kolekcje/globale** — wszystko localized/upload (nic na sztywno)
+8. **lib/content.ts + lib/payload.ts** — helpery, jedno źródło getCachedPayload
+9. **proxy.ts** (NIE middleware.ts) — routing locale, obsługa roota
+10. **Bloki** — dane przez enhanceProps, nie import lib (cykl)
+11. **buildSlugField** zamiast ręcznego slug
+12. **getLocalizedSlugs** zamiast zaszytej mapy ścieżek
+13. **buildSecurityHeaders** w next.config
+14. **Test:** root `/` przekierowuje, formularz wysyła, panel działa
+
+---
+
+## CZĘŚĆ F — EMAIL (SMTP vs Graph)
+
+Pełne szczegóły: [email.md](./email.md). Decyzja transportu:
+
+- **Klient na M365/Exchange** → Graph (SMTP AUTH na M365 często wyłączony)
+- **Klient z własnym SMTP / Gmail** → SMTP
+- **Przełącznik:** panel → Site Integrations → SMTP → Email Transport
+- **Dyspozytor:** `email: mailAdapter()` czyta wybór przy każdej wysyłce
+
+### Graph — checklist wdrożenia (Wasza strona, jednorazowo)
+
+1. Azure: App registration → tenantId, clientId, clientSecret
+2. Azure: Mail.Send APPLICATION permission + **Grant admin consent**
+3. `.env` projektu: GRAPH_TENANT_ID, GRAPH_CLIENT_ID, GRAPH_CLIENT_SECRET, GRAPH_SENDER
+4. Panel: From Name (nazwa nadawcy), From Address (→ reply-to)
+
+### Realne pułapki Graph (wszystkie zdarzyły się w sesji)
+
+| Błąd | Przyczyna | Naprawa |
+|---|---|---|
+| `ErrorSendAsDenied` | `from` ≠ sender | from.address = GRAPH_SENDER, klient w replyTo |
+| nazwa „Noreply" mimo panelu | Exchange nadpisuje / cache klienta | display name skrzynki / sprawdź nagłówki |
+| `Insufficient privileges` | brak admin consent | Grant admin consent w Azure |
+| `AADSTS1002012` | zły scope | scope = `.../.default`, nie Mail.Send |
+
+**Zasada from/replyTo:** `from.address` ZAWSZE = GRAPH_SENDER (wspólna skrzynka,
+zero Send-As). Nazwa (`from.name`) z panelu — różna per projekt. Adres klienta
+→ replyTo (odpowiedzi trafiają do klienta).
+
+---
+
+## CZĘŚĆ G — CO NALEŻY DO PLUGINU, A CO DO PROJEKTU
+
+Powtarzalne pytanie. Reguła: **jeśli zależy od danych/domen konkretnego projektu
+→ projekt. Jeśli identyczne wszędzie → plugin.**
+
+| Rzecz | Gdzie | Dlaczego |
+|---|---|---|
+| i18n, SEO meta, forms, consent, blog | plugin | uniwersalne |
+| Powiadomienia (teksty wyników) | plugin | uniwersalne, per język z panelu |
+| Zgoda RODO (enforcement) | plugin | uniwersalne, server-side |
+| Nagłówki bezpieczeństwa (HSTS...) | plugin | identyczne wszędzie |
+| Email (SMTP + Graph) | plugin | uniwersalne, konfiguracja z panelu/env |
+| **CSP** | **projekt** | zależy od domen projektu |
+| **schema.org / JSON-LD** | **projekt** | zależy od danych firmy |
+| **Breadcrumbs** | **projekt** | render z danych routingu projektu |
+| **Dane rejestrowe firmy** | **projekt** | różne per typ firmy |
+
+---
+
+## CZĘŚĆ H — CHECKLIST PRZED „GOTOWE"
+
+Nie mów „działa", dopóki:
+
+- [ ] `pnpm build --webpack` przechodzi lokalnie (nie tylko dev)
+- [ ] root `/` przekierowuje na locale (bez middleware.ts)
+- [ ] formularz wysyła (test przez panel: Send test)
+- [ ] panel: wszystkie teksty/obrazy edytowalne (nic na sztywno)
+- [ ] brak dubletu @payloadcms/ui (Część D)
+- [ ] grep potwierdza wersję pluginu w node_modules
+- [ ] sekrety w .env (nie w repo), maskowane w panelu
+- [ ] brak plików middleware.ts, brak zaszytej mapy slugów
+- [ ] strona 404 (not-found.tsx) — edytowalna, per język, link powrotu
+- [ ] formularze z buildera w panelu (NIE własne hardkodowane)
+- [ ] compliance: polityki, baner cookies, zgoda RODO w formularzach
+  (patrz [wymagania-prawne.md](./wymagania-prawne.md))

docs/README.md

@@ -1,5 +1,7 @@
 # IPAL — Dokumentacja modułów
 
+> **Zaczynasz wdrożenie?** Przeczytaj najpierw [WDROZENIE-PLAYBOOK.md](./WDROZENIE-PLAYBOOK.md) — sztywna procedura, kolejność, realne przykłady błędów.
+
 **Instalacja pakietu** (token Gitea, rejestr vs repozytorium) → główny
 [README](../README.md).
 **Nowy projekt krok po kroku** → [getting-started.md](./getting-started.md).
@@ -106,6 +108,7 @@ export default buildConfig({
 | access | Role admin > editor > user, kontrola dostępu | [access.md](./access.md) |
 | payload-helpers | getSiteSettings / getSiteIntegrations | [payload-helpers.md](./payload-helpers.md) |
 | seo | Metadata, hreflang, auto-fill, plugin-seo | [seo.md](./seo.md) |
+| architektura-tresci | **Jak budować, żeby klient wszystko edytował** (filozofia CMS) | [architektura-tresci.md](./architektura-tresci.md) |
 | blocks | RenderBlocks — silnik renderowania bloków | [blocks.md](./blocks.md) |
 | consent | Banner cookies GDPR, Google Consent Mode | [consent.md](./consent.md) |
 | turnstile | Cloudflare Turnstile (widget + verify) | [turnstile.md](./turnstile.md) |
@@ -118,7 +121,7 @@ export default buildConfig({
 | content | Blog/archiwa: kolekcje pod stroną-archiwum, listing, paginacja | [content.md](./content.md) |
 
 Nowy projekt krok po kroku: [getting-started.md](./getting-started.md)
-Referencja wdrożenia frontu: [frontend-setup.md](./frontend-setup.md)
+Referencja wdrożenia frontu: [getting-started.md](./getting-started.md)
 Wydawanie nowych wersji wtyczki: [publishing.md](./publishing.md)
 Jak komendy łączą się z Gitea (dla instalujących): [gitea-commands.md](./gitea-commands.md)
 Working with a project repo on Gitea (clone/pull/push): [gitea-workflow.md](./gitea-workflow.md) · [🇵🇱 PL](./gitea-workflow.pl.md)

docs/consent.md

@@ -109,7 +109,7 @@ Dostępne tokeny (każdy ma odpowiednik `-dark` używany pod `dark:`):
 | `--ipal-hover` | `#f5f5f5` | hover przycisków drugorzędnych |
 | `--ipal-radius` | `0.375rem` | zaokrąglenie przycisków |
 
-Wymaga `@source` skanującego pakiet (patrz frontend-setup.md) — inaczej Tailwind
+Wymaga `@source` skanującego pakiet (patrz getting-started.md) — inaczej Tailwind
 nie wygeneruje tych klas.
 
 ### Gdy tokeny nie wystarczą
@@ -131,4 +131,39 @@ Sloty: `root`, `primaryButton`, `secondaryButton`. Podany className zastępuje
 domyślny (nie dokleja się).
 
 Elementy mają też `data-ipal="banner"` i `data-ipal="cookie-button"` — stabilne
-uchwyty do CSS albo testów e2e.
+uchwyty do CSS albo testów e2e.
+
+## Locale jako cookie functional (wbudowane)
+
+Plugin sam zarządza jedną cookie functional: **`NEXT_LOCALE`** (wybór języka).
+Nie musisz nic konfigurować — działa out of the box:
+
+- **Zapis za zgodą.** Middleware zapisuje `NEXT_LOCALE` tylko, gdy użytkownik
+  zaakceptował kategorię **functional**. Bez zgody język działa (negocjacja per
+  żądanie), ale nie jest utrwalany w cookie.
+- **Sprzątanie po cofnięciu.** Gdy użytkownik cofnie zgodę na functional, hook
+  consent usuwa `NEXT_LOCALE` automatycznie. Odpowiada za to `DEFAULT_COOKIE_MAP`:
+
+```ts
+const DEFAULT_COOKIE_MAP = {
+  functional: [LOCALE_COOKIE_NAME],   // 'NEXT_LOCALE' — plugin zna własną cookie
+}
+```
+
+### Twoje własne cookie functional/analytics
+
+Jeśli ustawiasz własne cookie podlegające zgodzie, rozszerz mapę — hook wtedy
+sprzątnie też Twoje po cofnięciu zgody:
+
+```ts
+useConsent({
+  functional: ['NEXT_LOCALE', 'moje-ustawienie'],
+  analytics: ['_ga', '_gid'],
+})
+```
+
+Przekazana mapa zastępuje domyślną — pamiętaj dołączyć `NEXT_LOCALE`, jeśli
+chcesz zachować sprzątanie locale (albo zaimportuj `LOCALE_COOKIE_NAME` i dodaj).
+
+> Mechanizm zgody dla locale jest opisany też od strony i18n:
+> [i18n.md](./i18n.md#cookie-locale-a-zgoda-rodo).

docs/email.md

@@ -149,4 +149,31 @@ Jeśli `from` w panelu = cudza domena (np. `[email protected]`), a sender =
 `[email protected]` — Exchange zablokuje, chyba że aplikacja ma Send-As na tę
 domenę. Najbezpieczniej: `from` = `GRAPH_SENDER` (Wasza skrzynka), a adres
 klienta w `replyTo` (odpowiedzi trafią do klienta). Wtedy Send-As na cudze
-domeny nie jest potrzebny.
+domeny nie jest potrzebny.
+
+## Przełącznik transportu — mailAdapter
+
+`mailAdapter()` to dyspozytor: jeden adapter wpięty w config, wybiera transport
+(SMTP/Graph) przy KAŻDEJ wysyłce, czytając ustawienie z panelu. Dzięki temu
+przełącznik działa w panelu (Payload buduje adapter raz przy starcie, więc nie
+da się podmieniać osobnych adapterów w runtime — dyspozytor deleguje wewnątrz).
+
+```ts
+// payload.config.ts — JEDEN adapter, wybór wewnątrz
+import { mailAdapter } from '@intecion/ipal-kit'
+email: mailAdapter()
+```
+
+Panel → Site Integrations → SMTP → **Email Transport** (SMTP / Microsoft Graph).
+Dyspozytor czyta ten wybór per wysyłka. Guard: jeśli wybrano Graph, ale brak
+sekretów w .env → log + fallback na SMTP (nie cicha awaria).
+
+## Test wysyłki — przycisk w panelu
+
+W tabie SMTP jest przycisk **Send test**: podaj adres, kliknij, wyślij testowy
+mail przez AKTUALNY transport. Pokazuje wynik (✓/✗ z błędem). Endpoint
+`POST /api/ipal/test-email` (admin-only). Zapisz zmiany przed testem — endpoint
+czyta z bazy, nie z pola na ekranie.
+
+> Bezcenne przy diagnozie Graph — od razu widzisz `ErrorSendAsDenied`,
+> `Insufficient privileges` itp. zamiast zgadywać.

docs/forms.md

@@ -4,6 +4,31 @@ Wpina `@payloadcms/plugin-form-builder` (kolekcje forms + form-submissions) i
 dostarcza `submitForm` — wywoływalną z frontu funkcję, która spina: weryfikację
 Turnstile → zapis zgłoszenia → wysyłkę maili (naszym senderem).
 
+## ⚠️ ZASADA: formularz POCHODZI z buildera w panelu (obowiązkowe)
+
+**Formularze buduje redaktor w panelu** (kolekcja Forms), NIE deweloper w kodzie.
+To jest CMS — klient sam definiuje pola, etykiety, komunikaty, odbiorcę. Front
+tylko RENDERUJE formularz z panelu i wysyła przez `submitForm`.
+
+**NIGDY nie twórz własnego, hardkodowanego formularza** — z ręcznie wpisanymi
+polami, etykietami w JSX, własną walidacją. To łamie „nic na sztywno" (klient nie
+zmieni pól ani tekstów) i omija cały mechanizm pluginu (Turnstile, rate-limit,
+consent RODO, powiadomienia).
+
+| ŹLE (własny formularz) | DOBRZE (builder pluginu) |
+|---|---|
+| `<input name="email" placeholder="Email" />` w JSX | pola z kolekcji Forms (panel) |
+| etykiety/komunikaty w kodzie | etykiety per język w panelu |
+| własna walidacja/wysyłka | `submitForm` (Turnstile+consent+mail) |
+| klient nie zmieni formularza | klient edytuje pola w panelu |
+
+**Jak poprawnie:** redaktor tworzy formularz w kolekcji Forms → front pobiera
+jego definicję → renderuje pola dynamicznie → wysyła przez `submitForm`. Pola,
+etykiety, komunikaty, odbiorca — wszystko z panelu.
+
+Jeśli formularz wymaga pola, którego builder nie ma — dodaj je przez konfigurację
+`fields` (patrz niżej) albo rozbuduj plugin. NIE hardkoduj własnego formularza.
+
 ## Zależność
 
 ```json

docs/getting-started.md

@@ -1,14 +1,18 @@
-# Nowy projekt — krok po kroku
+# Setup projektu — od zera do wdrożenia
 
-> **Instalacja pluginu** (token Gitea, rejestr vs git) jest opisana w głównym
+Pełny przewodnik: od pustego katalogu do działającej, wielojęzycznej strony z
+blokami, consentem, formularzem i SEO. Łączy szkielet projektu (kolejność
+kroków) z wymaganiami frontendu (Tailwind, trasy, bloki, metadata).
+
+> **Instalacja pluginu** (token Gitea, rejestr vs git) jest w głównym
 > [README](../README.md). Ten przewodnik zakłada, że `@intecion/ipal-kit` jest
-> już zainstalowany, i przeprowadza przez **konfigurację** projektu.
+> zainstalowany, i przeprowadza przez konfigurację.
+>
+> **Zaczynasz wdrożenie produkcyjne?** Najpierw [WDROZENIE-PLAYBOOK.md](./WDROZENIE-PLAYBOOK.md)
+> — zasady, procedura, pułapki.
 
-Od pustego katalogu do działającej, wielojęzycznej strony z blokami, consentem i
-formularzem. Kolejność jest istotna: kilka kroków zależy od poprzednich (schemat
-bazy, importMap, kolejność wpięcia).
-
-Zakłada: pnpm, Node 20+, SQLite (dla Postgres zmienia się tylko adapter).
+Kolejność jest istotna — kilka kroków zależy od poprzednich (schemat bazy,
+importMap, kolejność wpięcia). Zakłada: pnpm, Node 22, Next 16.
 
 ---
 
@@ -16,21 +20,22 @@ Zakłada: pnpm, Node 20+, SQLite (dla Postgres zmienia się tylko adapter).
 
 ```bash
 npx create-payload-app@latest moj-projekt
-# → Blank, SQLite
+# → Blank, SQLite (dev) / Postgres (prod)
 cd moj-projekt
 ```
 
 ## 2. Plugin i zależności
 
-Zainstaluj `@intecion/ipal-kit` zgodnie z [README](../README.md) (rejestr Gitea
-albo bezpośrednio z repozytorium — wymaga tokenu). Następnie dodaj zależności
-współdzielone z Payloadem, których plugin nie zaciąga sam:
+Zainstaluj `@intecion/ipal-kit` zgodnie z [README](../README.md). Dodaj
+zależności współdzielone z Payloadem, których plugin nie zaciąga sam:
 
 ```bash
-pnpm add @payloadcms/plugin-seo@3.84.1 @payloadcms/plugin-form-builder@3.84.1 \
+pnpm add @payloadcms/plugin-seo @payloadcms/plugin-form-builder \
          nodemailer lucide-react slugify server-only
 ```
 
+### Spójność wersji @payloadcms/* (KRYTYCZNE)
+
 Wersje `@payloadcms/*` **muszą** zgadzać się z wersją `payload` — inaczej
 zagnieżdżone pluginy się nie wpinają (pusty tab SEO, brak kolekcji Forms) albo
 projekt się wywala. Wymuś w `package.json`:
@@ -38,13 +43,13 @@ projekt się wywala. Wymuś w `package.json`:
 ```json
 "pnpm": {
   "overrides": {
-    "payload": "3.84.1",
-    "@payloadcms/ui": "3.84.1",
-    "@payloadcms/next": "3.84.1",
-    "@payloadcms/db-sqlite": "3.84.1",
-    "@payloadcms/richtext-lexical": "3.84.1",
-    "@payloadcms/plugin-seo": "3.84.1",
-    "@payloadcms/plugin-form-builder": "3.84.1"
+    "payload": "3.88.0",
+    "@payloadcms/ui": "3.88.0",
+    "@payloadcms/next": "3.88.0",
+    "@payloadcms/db-postgres": "3.88.0",
+    "@payloadcms/richtext-lexical": "3.88.0",
+    "@payloadcms/plugin-seo": "3.88.0",
+    "@payloadcms/plugin-form-builder": "3.88.0"
   }
 }
 ```
@@ -53,11 +58,17 @@ projekt się wywala. Wymuś w `package.json`:
 rm -rf node_modules pnpm-lock.yaml && pnpm install
 ```
 
+### Build script z --webpack (Next 16)
+
+Next 16 domyślnie Turbopack, który konfliktuje z withPayload. W `package.json`:
+```json
+"build": "cross-env NODE_OPTIONS=\"--max-old-space-size=3072\" next build --webpack"
+```
+
 ## 3. Konfiguracja locale — jedno źródło
 
-Middleware działa przed Payloadem i potrzebuje listy locale synchronicznie, więc
-nie może jej czytać z gotowego configu. Wydziel osobny plik i importuj w obu
-miejscach:
+Proxy działa przed Payloadem i potrzebuje listy locale synchronicznie, więc nie
+może jej czytać z gotowego configu. Wydziel osobny plik, importuj wszędzie:
 
 ```ts
 // src/i18n.config.ts
@@ -67,25 +78,24 @@ export const i18nConfig = {
     { code: 'pl', label: 'Polski' },
     { code: 'en', label: 'English' },
   ],
-} as const
+} as const   // as const — inaczej TS nie uzna locales za niepustą tuple
 ```
 
-`as const` jest konieczne — bez niego TS nie uzna `locales` za niepustą listę.
+Importuj w: `payload.config` (ipalKit({ i18n: i18nConfig })) i `proxy.ts`.
 
 ## 4. payload.config.ts
 
 ```ts
-import { ipalKit, panelSmtpAdapter } from '@intecion/ipal-kit'
+import { ipalKit, mailAdapter } from '@intecion/ipal-kit'
 import { i18nConfig } from '@/i18n.config'
 import { Pages } from '@/collections/Pages'
 
 export default buildConfig({
-  // …reszta z template'u
   collections: [Users, Media, Pages],
 
-  // SMTP z panelu zamiast env — czyta Site Integrations przy każdym wysłaniu.
+  // Dyspozytor email: czyta transport (SMTP/Graph) z panelu przy każdej wysyłce.
   // Bez tego maile form-buildera nie wyjdą (Payload podstawia mocka).
-  email: panelSmtpAdapter(),
+  email: mailAdapter(),
 
   plugins: [
     ipalKit({
@@ -113,11 +123,11 @@ export const Pages: CollectionConfig = {
   access: { read: () => true },
   fields: [
     { name: 'title', type: 'text', required: true, localized: true },
-    buildSlugField({ from: 'title' }),
+    buildSlugField({ from: 'title' }),        // NIGDY ręczny slug — plugin to ma
     {
       name: 'layout',
       type: 'blocks',
-      blocks: [ContentBlock],   // NIGDY pusta lista — Payload się wywala
+      blocks: [ContentBlock],                  // NIGDY pusta lista — Payload crashuje
     },
   ],
 }
@@ -158,15 +168,31 @@ import type { BlockComponentMap } from '@intecion/ipal-kit/rsc'
 import { ContentBlockComponent } from '@/blocks/Content/Component'
 
 export const blockRegistry: BlockComponentMap = {
-  content: ContentBlockComponent,
+  content: ContentBlockComponent,           // klucz = slug bloku
 }
 ```
 
-Klucz w rejestrze = `slug` bloku.
+> **Jak budować treść, żeby klient mógł wszystko edytować** (filozofia
+> CMS, kolejność komponent→blok→strona): [architektura-tresci.md](./architektura-tresci.md).
 
-## 7. Tailwind
+**Puste `blocks: []` crashuje** (traverseFields) — zawsze co najmniej jeden blok.
 
-Blank template go nie ma, a komponenty pluginu (banner cookies) są w Tailwindzie.
+### enhanceProps — wstrzykiwanie danych server-side do bloków
+
+Bloki NIE importują `lib/*` (cykl importów). Wartości server-side (turnstileSiteKey,
+odbiorca formularza) wstrzykuje się przez enhanceProps — bez wiedzy pluginu:
+
+```ts
+const enhanceProps = ({ block }) => {
+  if (block.blockType === 'formBlock') return { turnstileSiteKey, notificationTo }
+  return {}
+}
+```
+
+## 7. Tailwind (WYMÓG)
+
+Blank template go nie ma, a komponenty pluginu (banner cookies, Turnstile) są w
+czystym Tailwindzie.
 
 ```bash
 pnpm add tailwindcss @tailwindcss/postcss
@@ -183,16 +209,30 @@ export default { plugins: { '@tailwindcss/postcss': {} } }
 @source "../../../node_modules/@intecion/ipal-kit/dist/**/*.js";
 ```
 
-`@source` jest **konieczny** — Tailwind nie skanuje `node_modules`, więc bez
-niego klasy komponentów pluginu nie powstaną i banner wyrenderuje się goły.
-Ścieżka jest relatywna do pliku CSS.
+**`@source` jest KONIECZNY** — Tailwind nie skanuje `node_modules`, więc bez
+niego klasy komponentów pluginu nie powstaną (banner wyrenderuje się goły).
+Ścieżka relatywna do pliku CSS.
 
-## 8. Proxy (dawniej middleware)
+### Przestylowanie pod klienta
 
-> **Next 16:** konwencja `middleware.ts` jest przestarzała — nazwa pliku to teraz
-> `proxy.ts`, a funkcja `proxy` zamiast `middleware`. Logika pluginu bez zmian:
-> `createLocaleMiddleware` działa tak samo. Migracja jednej komendy:
-> `npx @next/codemod@canary middleware-to-proxy .`
+Komponenty pluginu mają domyślny wygląd. Kolory/zaokrąglenia przez CSS custom
+properties (fallbacki wbudowane):
+```css
+:root {
+  --ipal-primary: #16a34a;
+  --ipal-radius: 1rem;
+}
+```
+Pełna lista tokenów + opcja classNames: [consent.md](./consent.md).
+
+## 8. Proxy (routing locale) — NIGDY middleware.ts
+
+> **Next 16 używa `proxy.ts`, NIE `middleware.ts`.** Plik `proxy.ts`, funkcja
+> `proxy`. `middleware.ts` jest przestarzały — jeśli istnieje, USUŃ go. Nigdy
+> obu naraz. Migracja starego: `npx @next/codemod@canary middleware-to-proxy .`
+>
+> Import z pluginu zostaje `@intecion/ipal-kit/next/middleware` — to nazwa
+> subpath eksportu, NIE nazwa pliku. Nie myl ich.
 
 ```ts
 // src/proxy.ts
@@ -205,104 +245,89 @@ const localeMiddleware = createLocaleMiddleware({ config: i18nConfig })
 
 export function proxy(request: NextRequest) {
   const result = localeMiddleware(request)
-  if (result.type === 'next') return NextResponse.next()
 
-  const response = NextResponse.redirect(result.location)
-  // cookie tylko gdy jest zgoda na kategorię functional — inaczej undefined
-  if (result.cookie) response.cookies.set(result.cookie.name, result.cookie.value)
+  // Cookie zapisywany w OBU wynikach (redirect na '/' i next przy zmianie
+  // języka), TYLKO gdy jest zgoda na functional.
+  const response =
+    result.type === 'next'
+      ? NextResponse.next()
+      : NextResponse.redirect(result.location)
+
+  if (result.cookie) {
+    response.cookies.set(result.cookie.name, result.cookie.value)
+  }
   return response
 }
 
-// INLINE, nie import — Next analizuje ten obiekt statycznie i nie wykonuje
-// importów. Importowana stała zostanie zignorowana, proxy złapie /admin
-// i /_next, i wszystko zwróci 500.
+// Matcher INLINE (nie import) — Next analizuje statycznie, nie wykonuje importów.
+// Import stałej byłby zignorowany → proxy złapałby /admin /_next /api → 500.
+// Ten wzorzec łapie root '/' (negocjacja locale), pomija api/admin/_next/pliki.
 export const config = {
   matcher: ['/((?!api|admin|_next|.*\\..*).*)'],
 }
 ```
 
-> Import z pluginu zostaje `@intecion/ipal-kit/next/middleware` — to nazwa
-> subpath eksportu w pakiecie, niezależna od tego, czy plik projektu nazywa się
-> `middleware.ts` czy `proxy.ts`.
+### Zlokalizowane ścieżki — getLocalizedSlugs (NIGDY zaszyta mapa)
 
-## 9. Warstwa dostępu do danych
-
-Next uruchamia `generateMetadata` i komponent strony niezależnie — `cache()`
-sprawia, że nie pytają bazy dwa razy o to samo.
+Do przełącznika języka / budowania ścieżek NIE twórz zaszytej mapy slugów.
+Slugi są w bazie (pole `slug` localized):
 
 ```ts
-// src/lib/payload.ts
-import { cache } from 'react'
-import { getPayload } from 'payload'
-import config from '@/payload.config'
+import { getLocalizedSlugs, switchLocalePath } from '@intecion/ipal-kit'
 
-export const getCachedPayload = cache(async () => getPayload({ config: await config }))
-
-export const getSettings = cache(async (locale: string) =>
-  (await getCachedPayload()).findGlobal({
-    slug: 'site-settings',
-    locale: locale as 'pl' | 'en',
-    depth: 2,
-  }),
-)
+const doc = await payload.findByID({ collection: 'pages', id, locale: 'all' })
+const slugs = getLocalizedSlugs({ slugField: doc.slug, config: i18nConfig })
+switchLocalePath({ slugs, targetLocale: 'en', config: i18nConfig })  // → '/en/about'
 ```
 
-```ts
-// src/lib/locales.ts
-import { cache } from 'react'
-import config from '@/payload.config'
+## 9. Warstwa dostępu do danych — lib/ (jedno źródło)
 
-export const getConfiguredLocales = cache(async (): Promise<string[]> => {
-  const payloadConfig = await config
-  return payloadConfig.localization ? payloadConfig.localization.locales.map((l) => l.code) : []
+```ts
+// src/lib/content.ts — JEDYNE źródło helperów pluginu
+import { createContentHelpers } from '@intecion/ipal-kit'
+import payloadConfig from '@/payload.config'
+import { i18nConfig } from '@/i18n.config'
+
+export const {
+  getCachedPayload, getSettings, getConfiguredLocales, resolveRoute, getEntries, robots,
+} = createContentHelpers({
+  config: payloadConfig,          // PAYLOAD config (nie i18n!)
+  content: { collections: [] },
+  i18n: i18nConfig,               // i18n OSOBNO
 })
 ```
 
 ```ts
-// src/lib/pages.ts
+// src/lib/payload.ts — funkcje projektu, typowane
 import { cache } from 'react'
-import type { Page, SiteSetting } from '@/payload-types'
-import { getCachedPayload, getSettings } from './payload'
+import { getSiteSettings } from '@intecion/ipal-kit'
+import { getCachedPayload } from './content'      // z content, nie osobny getPayload
+import type { SiteSetting } from '@/payload-types'
 
-export const resolvePage = cache(
-  async (locale: string, slugPath: string | null): Promise<Page | null> => {
-    if (!slugPath) {
-      // Strona główna z System Pages — edytor może ją zmienić bez zmiany kodu.
-      const settings = (await getSettings(locale)) as SiteSetting
-      const homepage = settings.homepage
-      return homepage && typeof homepage === 'object' ? homepage : null
-    }
-
-    const payload = await getCachedPayload()
-    const result = await payload.find({
-      collection: 'pages',
-      where: { slug: { equals: slugPath } },
-      locale: locale as 'pl' | 'en',
-      depth: 2,
-      limit: 1,
-    })
-    return result.docs[0] ?? null
-  },
+export const getSettings = cache(async (locale: string) =>
+  getSiteSettings<SiteSetting>(await getCachedPayload(), { locale: locale as never, depth: 2 }),
 )
 ```
 
+> NIE twórz `lib/pages.ts` (resolvePage) ani `lib/locales.ts` — plugin ma
+> `resolveRoute` i `getConfiguredLocales`. Duplikaty = rozjazd.
+
 ## 10. Trasy
 
 Usuń starter — `(frontend)/layout.tsx` i `(frontend)/page.tsx`. Rootem zostaje
-layout locale, bo `<html lang>` musi znać język, a `(frontend)` jest ponad
-segmentem `[locale]`. Każdy trafia na ścieżkę z locale — middleware przekierowuje.
+layout locale (bo `<html lang>` musi znać język).
 
 ```
 src/app/(frontend)/
   styles.css
   [locale]/
-    layout.tsx
+    layout.tsx                  # walidacja locale + ConsentProvider + Analytics
     [[...slug]]/
-      page.tsx
+      page.tsx                  # render bloków
 ```
 
-`[[...slug]]` — **podwójne** nawiasy. Pojedyncze `[slug]` dają string zamiast
-tablicy (`slug.join is not a function`) i nie łapią samego `/pl`.
+**`[[...slug]]` — PODWÓJNE nawiasy** (opcjonalny catch-all). Pojedyncze `[slug]`
+dają string (`slug.join is not a function`) i nie łapią samego `/pl`.
 
 ```tsx
 // src/app/(frontend)/[locale]/layout.tsx
@@ -310,8 +335,8 @@ import { notFound } from 'next/navigation'
 import { getConsentTexts, getAnalyticsConfig } from '@intecion/ipal-kit'
 import { ConsentProvider, CookieBanner, CookieButton, Analytics } from '@intecion/ipal-kit/client'
 import { i18nConfig } from '@/i18n.config'
-import { getCachedPayload, getSettings } from '@/lib/payload'
-import { getConfiguredLocales } from '@/lib/locales'
+import { getCachedPayload, getConfiguredLocales } from '@/lib/content'
+import { getSettings } from '@/lib/payload'
 import '../styles.css'
 
 export default async function LocaleLayout({ children, params }) {
@@ -325,13 +350,9 @@ export default async function LocaleLayout({ children, params }) {
 
   const [texts, analytics] = await Promise.all([
     getConsentTexts({
-      config: i18nConfig,
-      locale,
-      payload,
-      privacyPolicy:
-        privacyPage && typeof privacyPage === 'object'
-          ? { page: privacyPage, label: 'Polityka prywatności' }
-          : undefined,
+      config: i18nConfig, locale, payload,
+      privacyPolicy: privacyPage && typeof privacyPage === 'object'
+        ? { page: privacyPage, label: 'Polityka prywatności' } : undefined,
     }),
     getAnalyticsConfig(payload),
   ])
@@ -343,7 +364,7 @@ export default async function LocaleLayout({ children, params }) {
           <main>{children}</main>
           <CookieBanner />
           <CookieButton />
-          <Analytics {...analytics} />
+          <Analytics {...analytics} />        {/* WEWNĄTRZ ConsentProvider */}
         </ConsentProvider>
       </body>
     </html>
@@ -364,8 +385,7 @@ import { RenderBlocks } from '@intecion/ipal-kit/rsc'
 import { createPageMetadata } from '@intecion/ipal-kit'
 import { i18nConfig } from '@/i18n.config'
 import { blockRegistry } from '@/blocks/registry'
-import { getCachedPayload } from '@/lib/payload'
-import { resolvePage } from '@/lib/pages'
+import { getCachedPayload, resolveRoute } from '@/lib/content'
 
 const pageMetadata = createPageMetadata({
   config: i18nConfig,
@@ -377,104 +397,92 @@ export async function generateMetadata({ params }): Promise<Metadata> {
   return pageMetadata({ payload: await getCachedPayload(), locale, slug })
 }
 
-export default async function Page({ params }) {
+export default async function Page({ params, searchParams }) {
   const { locale, slug } = await params
-  const page = await resolvePage(locale, slug?.length ? slug.join('/') : null)
-  if (!page) notFound()
-
-  return <RenderBlocks blocks={page.layout as never} components={blockRegistry} />
+  const { page } = await searchParams
+  const route = await resolveRoute(locale, slug ?? [], page)   // 3 args
+  if (!route) notFound()
+  return <RenderBlocks blocks={route.doc.layout as never} components={blockRegistry} />
 }
 ```
 
-## 11. Środowisko
+- brak slug (`/pl`) → home przez System Pages (nie hardkod slug)
+- slug (`/pl/o-nas`) → resolveRoute po slug w danym locale
+- `depth: 2` → relacje w blokach (form) się populują
 
-```bash
-# .env
-DATABASE_URL=file:./moj-projekt.db
-PAYLOAD_SECRET=<losowy-ciąg>
-NEXT_PUBLIC_SERVER_URL=http://localhost:3000
-```
+## 11. Metadata / SEO (szczegóły)
+
+`createPageMetadata` obsługuje hreflang. Kluczowe: resolveDocument pobiera
+dokument z **`locale: 'all'`** — wtedy `slug` jest mapą locale→wartość, z której
+budują się hreflang alternates. Zwykły fetch (jeden locale) → tylko string,
+hreflang nie powstanie.
 
 Bez `NEXT_PUBLIC_SERVER_URL` canonical i hreflang wyjdą względne.
 
-## 12. Generowanie i start
+## 12. Nagłówki bezpieczeństwa
+
+```ts
+// next.config.ts
+import { buildSecurityHeaders } from '@intecion/ipal-kit'
+const securityHeaders = buildSecurityHeaders({
+  hsts: process.env.NODE_ENV === 'production',    // off w dev (http)
+  additional: [ /* CSP projektu — zna swoje domeny */ ],
+})
+// async headers() { return [{ source: '/:path*', headers: securityHeaders }] }
+```
+Szczegóły: [security.md](./security.md).
+
+## 13. Środowisko
+
+```bash
+# .env
+DATABASE_URI=<postgres albo file:./dev.db>
+PAYLOAD_SECRET=<losowy-ciąg>
+NEXT_PUBLIC_SERVER_URL=http://localhost:3000
+# Email przez Graph (opcjonalnie — sekrety agencyjne):
+# GRAPH_TENANT_ID=... GRAPH_CLIENT_ID=... GRAPH_CLIENT_SECRET=... GRAPH_SENDER=...
+```
+
+## 14. Generowanie i start
 
 ```bash
 pnpm generate:types
-pnpm payload generate:importmap   # pola SEO to komponenty admina
+pnpm payload generate:importmap   # pola SEO + custom komponenty (MaskedField...)
 pnpm dev
 ```
 
-`generate:importmap` powtarzaj po każdej zmianie, która dokłada komponenty
-admina.
+`generate:importmap` powtarzaj po każdej zmianie dokładającej komponenty admina.
 
-## 13. Konfiguracja w panelu
+## 15. Konfiguracja w panelu
 
 `http://localhost:3000/admin`
 
-1. **Utwórz pierwszego użytkownika** (dostanie rolę admin).
-2. **Site Settings → General** — nazwa witryny, kolejność i separator tytułu.
-3. **Pages** — utwórz stronę główną. Wypełnij tytuł **w każdym locale**
-   (przełącznik u góry) — slug generuje się per język, a pusty slug w EN oznacza
-   404 na `/en/…`.
-4. **Site Settings → System Pages** — wskaż Homepage. Bez tego `/pl` da 404.
-5. **Cookie Settings** — treść bannera (bez tego lecą angielskie domyślne).
+1. **Utwórz pierwszego użytkownika** (rola admin).
+2. **Site Settings → General** — nazwa witryny, tytuł.
+3. **Pages** — strona główna. Tytuł **w każdym locale** (slug per język; pusty
+   slug EN = 404 na `/en/…`).
+4. **Site Settings → System Pages** — wskaż Homepage (bez tego `/pl` → 404).
+5. **Cookie Settings** — treść bannera per język.
+6. **Notifications** — teksty wyników formularza per język (opcjonalne, ma fallback).
+7. **Site Integrations → SMTP** — transport (SMTP/Graph), From Name, From Address.
 
-Wejdź na `/` — powinno przekierować na `/pl` i pokazać stronę.
+Wejdź na `/` — powinno przekierować na `/pl`.
 
 ---
 
-## Rzeczy opcjonalne
+## Opcjonalne
 
 ### Formularz z Turnstile
+Wymaga bloku formularza (patrz [forms.md](./forms.md)) + Site Integrations →
+Turnstile (klucze testowe Cloudflare: site `1x00000000000000000000AA`, secret
+`1x0000000000000000000000000000000AA`). Maile wysyła form-builder przez
+mailAdapter — nie pisze się ich w kodzie. Zgoda RODO: checkbox o nazwie `consent`.
 
-Wymaga bloku formularza w projekcie (patrz forms.md) oraz:
-
-- **Site Integrations → Turnstile** — site key i secret. Klucze testowe
-  Cloudflare (zawsze przechodzą): site `1x00000000000000000000AA`, secret
-  `1x0000000000000000000000000000000AA`.
-- **Site Integrations → SMTP** — host, port, user, hasło, adres nadawcy.
-- **Forms → dany formularz → Emails** — odbiorca, temat, treść (`{{*:table}}`
-  wypisze wszystkie pola tabelką). Maile wysyła form-builder przez
-  `panelSmtpAdapter` — nie pisze się ich w kodzie.
-
-
-### Blog / archiwum (kolekcja pod stroną-archiwum)
-
-Pełny opis: content.md. W skrócie:
-
-1. **Kolekcja** `src/collections/Posts.ts` — tytuł (localized), `buildSlugField`,
-   pola, bloki. Dodaj ją do `collections` w payload.config.
-
-2. **content.config.ts** obok i18n.config.ts:
-```ts
-import type { ContentOption } from '@intecion/ipal-kit'
-export const contentConfig: ContentOption = {
-  collections: [{ slug: 'posts', label: 'Artykuły', perPage: 10 }],
-}
-```
-
-3. **payload.config** — `content: contentConfig`, plus `posts` w `seo.collections`.
-
-4. **Front** — `createContentHelpers` w `src/lib/content.ts`, `resolveRoute`
-   w page.tsx (obsługa typów page/archive/entry), blok listy (EntriesList).
-
-5. **Baza + typy** — nowa kolekcja to nowy schemat:
-```bash
-rm -f *.db *.db-shm *.db-wal && pnpm generate:types && pnpm dev
-```
-
-6. **W panelu** — utwórz stronę „Artykuły" (w każdym locale!), dodaj do niej blok
-   listy, w System Pages przypisz ją jako archiwum kolekcji posts. Dodaj wpisy.
-
-Adres wpisów = slug strony-archiwum. Zmiana tytułu strony przenosi sekcję. Kolejny
-typ treści (realizacje) = kolejna kolekcja + kolejna pozycja w content.config.
-
-### Sitemapa i robots.txt
-
-`createContentHelpers` oddaje gotowe handlery — dodaj `i18n` i `baseUrl` do jego
-argumentów (patrz seo.md), potem dwa pliki po jednej linii:
+### Blog / archiwum
+Pełny opis: [content.md](./content.md). Kolekcja + content.config.ts +
+przypisanie strony-archiwum w System Pages.
 
+### Sitemapa i robots
 ```ts
 // app/sitemap.ts
 export { sitemap as default } from '@/lib/content'
@@ -482,44 +490,22 @@ export { sitemap as default } from '@/lib/content'
 export { robots as default } from '@/lib/content'
 ```
 
-Sitemapa z hreflangiem per URL, lastmod, wpisami bloga; pomija drafty i noindex.
-
-### Analytics
-
-**Site Integrations** → GA4 Measurement ID albo GTM Container ID. Tagi ładują
-się z Consent Mode: nic nie zapisze ciasteczek, dopóki odwiedzający nie
-zaakceptuje kategorii Analytics.
-
-### Przestylowanie pod klienta
-
-```css
-/* styles.css */
-:root {
-  --ipal-primary: #16a34a;
-  --ipal-radius: 1rem;
-}
-```
-
-Pełna lista tokenów: consent.md.
-
 ---
 
 ## Kiedy coś nie działa
 
 | Objaw | Przyczyna |
 |---|---|
-| Pusty tab SEO / brak kolekcji Forms | rozjazd wersji `@payloadcms/*` — sprawdź `pnpm.overrides` |
+| Pusty tab SEO / brak Forms | rozjazd wersji `@payloadcms/*` — sprawdź `pnpm.overrides` |
 | `PayloadComponent not found in importMap` | `pnpm payload generate:importmap` |
-| Banner bez stylów | brak `@source` na `node_modules/@intecion/ipal-kit` albo brak Tailwinda |
-| `/admin` i `/_next` zwracają 500 | matcher w middleware nie jest inline |
-| `slug.join is not a function` | katalog `[slug]` zamiast `[[...slug]]` |
+| `Cannot destructure property 'config'` (custom pole) | dublet `@payloadcms/ui` — peerDependency (playbook D) |
+| Banner bez stylów | brak `@source` na node_modules albo brak Tailwinda |
+| `/admin` i `/_next` → 500 | matcher w proxy nie jest inline |
+| `slug.join is not a function` | `[slug]` zamiast `[[...slug]]` |
 | `/pl` → 404 | Homepage nieustawiony w System Pages |
-| `/en/cokolwiek` → 404, `/pl/cokolwiek` działa | pusty tytuł (a więc i slug) w locale EN |
+| `/en/*` → 404, `/pl/*` działa | pusty tytuł/slug w locale EN |
 | `Missing <html> and <body>` | root layout usunięty, a `[locale]/layout.tsx` ich nie ma |
-| `SQLITE_ERROR: index … already exists` | zmiana schematu — usuń `*.db *.db-shm *.db-wal` |
-| Zmiany w pluginie nie widać | Turbopack cache — `rm -rf .next` |
-| Maile nie wychodzą | brak `email: panelSmtpAdapter()` w configu albo pusty SMTP w panelu |
-| GTM ładuje się, brak `_ga` | pusty kontener — GTM sam nie ustawia ciasteczek, potrzebny opublikowany tag GA4 |
-| `/pl/artykuly` → 404 | strona nieprzypisana jako archiwum w System Pages |
-| brak pola „archive page" w panelu | brak `content` w configu albo `generate:importmap` po dodaniu |
-| wpis 404 mimo że istnieje | slug pusty w tym locale — wypełnij tytuł w danym języku |
+| Zmiany w pluginie nie widać | `rm -rf .next`; sprawdź czy wciągnięto wersję (grep node_modules) |
+| Maile nie wychodzą | brak `email: mailAdapter()` albo pusty SMTP/Graph |
+| istnieje `middleware.ts` | USUŃ — Next 16 to `proxy.ts` |
+| zaszyta mapa `localizedRoutes` | antywzorzec — `getLocalizedSlugs` z bazy |

docs/i18n.md

@@ -107,4 +107,36 @@ Zachowanie:
   locale z: cookie → Accept-Language → default
 - wybrany locale zapisany w cookie (`LOCALE_COOKIE_NAME`)
 
-`DEFAULT_MIDDLEWARE_MATCHER` wyklucza `api`, `admin`, `_next`, pliki statyczne.
+`DEFAULT_MIDDLEWARE_MATCHER` wyklucza `api`, `admin`, `_next`, pliki statyczne.
+
+## Cookie locale a zgoda (RODO)
+
+Wybór języka zapisywany jest w cookie **`NEXT_LOCALE`** (konwencja Next.js —
+kompatybilna z innymi bibliotekami i18n, które czytają aktywny locale). Ale
+zapis podlega zgodzie: to cookie kategorii **functional**, więc:
+
+- **Zapis TYLKO za zgodą.** Middleware zapisuje `NEXT_LOCALE` jedynie, gdy
+  użytkownik zgodził się na kategorię functional (`mayPersistLocale` sprawdza
+  zgodę). Bez zgody język działa per żądanie (negocjacja z Accept-Language),
+  ale nie jest utrwalany.
+- **Sprzątanie po cofnięciu zgody.** Gdy użytkownik cofnie zgodę na functional,
+  cookie `NEXT_LOCALE` jest usuwane automatycznie (consent zna tę cookie przez
+  `DEFAULT_COOKIE_MAP` — patrz [consent.md](./consent.md)).
+
+Nazwa cookie to jedna stała `LOCALE_COOKIE_NAME` (`modules/i18n/negotiateLocale`),
+propagująca do middleware i sprzątania consent. Można nadpisać w
+`createLocaleMiddleware({ cookieName })`, ale domyślnie `NEXT_LOCALE` jest
+zalecane (interop).
+
+### Kolejność negocjacji locale
+
+1. Cookie `NEXT_LOCALE` (jeśli jest — czyli był wybór za zgodą)
+2. Nagłówek `Accept-Language` (preferencje przeglądarki)
+3. `defaultLocale` z konfiguracji
+
+Wejście na `/` → negocjacja → redirect na `/pl` (albo wynik negocjacji).
+Zmiana języka (URL `/en` różny od cookie) → zapis nowego wyboru (za zgodą).
+
+> **Migracja ze starej nazwy:** wcześniej cookie nazywało się `ipal-locale`.
+> Po zmianie na `NEXT_LOCALE` użytkownicy ze starą cookie przejdą raz ponowną
+> negocjację (stara cookie ignorowana). Jednorazowe, bez wpływu na nowe projekty.

docs/storage.md

@@ -0,0 +1,131 @@
+# storage — media na Cloudflare R2
+
+Offload mediów (obrazy, pliki) do Cloudflare R2 zamiast lokalnego dysku. R2 jest
+S3-kompatybilny; plugin dostarcza `buildR2Storage`, który czyta dane z `.env`
+i konfiguruje adapter.
+
+> **Storage to infrastruktura, nie treść.** Dane R2 (klucze, bucket) idą do
+> `.env` — jak DATABASE_URI, PAYLOAD_SECRET, GRAPH_*. NIE do panelu (to sekrety
+> agencyjne, wiążą się przy starcie, nie zmienia ich redaktor).
+
+## Zależność
+
+```bash
+pnpm add @payloadcms/storage-s3
+```
+
+## Zmienne .env
+
+Patrz [R2-ENV-przyklad](../R2-ENV-przyklad.md) po pełną instrukcję skąd wziąć wartości.
+
+```bash
+R2_BUCKET=nazwa-bucketa
+R2_ENDPOINT=https://<ACCOUNT_ID>.r2.cloudflarestorage.com
+R2_ACCESS_KEY_ID=<access-key-id>
+R2_SECRET_ACCESS_KEY=<secret-access-key>
+```
+
+## Wpięcie (payload.config.ts)
+
+```ts
+import { buildR2Storage } from '@intecion/ipal-kit'
+
+export default buildConfig({
+  // ...
+  plugins: [
+    ipalKit({ /* ... */ }),
+    buildR2Storage(['media']),   // slugi kolekcji upload do offloadu
+  ],
+})
+```
+
+`buildR2Storage` przyjmuje listę kolekcji upload (domyślnie `['media']`). Jeśli
+masz więcej kolekcji plików: `buildR2Storage(['media', 'documents'])`.
+
+## Zachowanie (fallback)
+
+- **Wszystkie 4 zmienne** → media w R2.
+- **Brak zmiennych** → fallback na lokalny dysk (dev działa bez R2, zero konfiguracji).
+- **Część zmiennych** → ostrzeżenie w logu + fallback (częściowa konfiguracja =
+  pewnie pomyłka).
+
+To wzorzec „degrade gracefully" — jak mailAdapter, który wraca do SMTP, gdy brak
+Graph. Projekt działa niezależnie od tego, czy R2 jest skonfigurowany.
+
+## Publiczny dostęp (WAŻNE)
+
+R2 domyślnie prywatny. Upload zadziała, ale obrazy się NIE wyświetlą (403), dopóki
+nie skonfigurujesz publicznego odczytu:
+
+1. Cloudflare → R2 → bucket → Settings → **Public access** → podłącz custom domain
+2. Albo serwuj przez Cloudflare CDN / własną domenę
+
+Bez tego media wgrają się do R2, ale front nie pokaże obrazów. Konfiguracja domeny
+jest po stronie Cloudflare, nie kodu.
+
+## Migracja istniejących mediów
+
+Jeśli projekt miał media lokalnie i przełączasz na R2 — nowe uploady idą do R2,
+ale STARE zostają na dysku (i znikną przy redeployu bez wolumenu). Przed
+przełączeniem na produkcji przenieś istniejące pliki do bucketa (np. `rclone`
+albo ręcznie przez R2 dashboard), inaczej stare obrazy znikną.
+
+## Weryfikacja
+
+```bash
+# po wpięciu i ustawieniu .env:
+pnpm dev
+# wgraj obraz w panelu (Media) → sprawdź w Cloudflare R2, czy plik się pojawił
+```
+
+## Dev na lokalnym I na R2 (seedowanie podczas developmentu)
+
+Fallback (brak zmiennych → lokalny dysk) oznacza, że **dev działa w obu trybach**:
+
+- **Dev bez R2 w .env** → media na lokalnym dysku. Szybki start, zero konfiguracji.
+- **Dev z R2 w .env** → media w R2 już podczas developmentu. Przydatne, gdy
+  seedujesz treść w devie i chcesz, żeby od razu lądowała w buckecie (np. wspólny
+  bucket dev, albo test realnego flow przed produkcją).
+
+Przełączasz trybem po prostu obecnością zmiennych R2 w `.env`. Ten sam kod,
+`buildR2Storage` sam wykrywa. Nie musisz nic zmieniać w configu między trybami.
+
+> Jeśli seedujesz w devie do R2 — pamiętaj, że to realny bucket. Używaj osobnego
+> bucketa dev (nie produkcyjnego), żeby nie mieszać danych testowych z realnymi.
+
+## Normalizacja nazw plików (automatyczna)
+
+Plik `normalizeFilenameHook` czyści nazwy wgrywanych plików — slugifikuje nazwę,
+zachowuje rozszerzenie:
+
+```
+"Zdjęcie jeden nad morzem.jpg"  → "zdjecie-jeden-nad-morzem.jpg"
+"Faktura #12 (2024).PDF"        → "faktura-12-2024.pdf"
+```
+
+Wpięcie w kolekcję Media (projekt):
+
+```ts
+import { normalizeFilenameHook } from '@intecion/ipal-kit'
+
+export const Media: CollectionConfig = {
+  slug: 'media',
+  upload: { staticDir: 'media' /* ... */ },
+  hooks: {
+    beforeOperation: [normalizeFilenameHook],   // czyści nazwę przed zapisem
+  },
+  fields: [ /* alt itd. */ ],
+}
+```
+
+Działa z lokalnym dyskiem i z R2/S3 (hook biegnie PRZED warstwą storage, więc
+czysta nazwa trafia i do bazy, i do bucketa). Dlaczego to ważne:
+
+- **URL-e mediów są czyste** — `/media/zdjecie-nad-morzem.jpg`, nie
+  `/media/Zdjęcie%20jeden%20nad%20morzem.jpg` (spacje/diakrytyki w URL = problemy).
+- **Przenośność** — nazwa bez polskich znaków/spacji działa wszędzie (CDN, S3, systemy plików).
+- **Bez kolizji kodowania** — spacje i `#`, `()` w nazwach plików potrafią psuć
+  ścieżki i cache.
+
+Sama funkcja `normalizeFilename(name)` też jest wyeksportowana, gdybyś potrzebował
+jej poza hookiem.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intecion/ipal-kit",
-  "version": "1.0.14",
+  "version": "1.0.19",
   "description": "Intecion Payload Advanced Library — a Payload CMS 3 plugin: i18n, SEO, forms, consent, analytics, blog/archives.",
   "license": "MIT",
   "repository": {
@@ -38,7 +38,8 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "scripts": {
     "build": "pnpm copyfiles && pnpm build:types && pnpm build:swc",
@@ -59,6 +60,7 @@
     "test:int": "vitest"
   },
   "dependencies": {
+    "@payloadcms/storage-s3": "^3.88.0",
     "lucide-react": "^0.400.0",
     "nodemailer": "^8.0.1",
     "server-only": "^0.0.1",

pnpm-lock.yaml

@@ -8,6 +8,9 @@ importers:
 
   .:
     dependencies:
+      '@payloadcms/storage-s3':
+        specifier: ^3.88.0
+        version: 3.88.0(@types/[email protected])([email protected])([email protected](@babel/[email protected])(@playwright/[email protected])([email protected]([email protected]))([email protected])([email protected]))([email protected]([email protected])([email protected]))([email protected]([email protected]))([email protected])([email protected])
       lucide-react:
         specifier: ^0.400.0
         version: 0.400.0([email protected])
@@ -133,6 +136,88 @@ packages:
     resolution: {integrity: sha512-60vepv88RwcJtSHrD6MjIL6Ta3SOYbgfnkHb+ppAVK+o9mXprRtulx7VlRl3lN3bbvysAfCS7WMVfhUYemB0IQ==}
     engines: {node: '>= 16'}
 
+  '@aws-sdk/[email protected]':
+    resolution: {integrity: sha512-Dtu0gr4dnATZAPwEYbpCsG+MpLM7OAliy2gTepEFQwl1vZ6DL3QMH2FveMa3HLvPsOdhJsPRB3KtxVhph9T75A==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/[email protected]':
+    resolution: {integrity: sha512-8+UH1uBWwjbRu0ugTBhJ/cu3rL/vzf1tm9/3+xZGf1uybIO3HTF2xLJJaTKkRPvzxz8/n/w+YrwoHGZ2Q/a2Zg==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/[email protected]':
+    resolution: {integrity: sha512-reqPFEQrZxDZpeGj4PFMepBeR5LGYHRqq/L0motTzgFkCRBA4rFdaVXDSLYyGHhxVz7sT2PDnPN9CluGSfgyJA==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/[email protected]':
+    resolution: {integrity: sha512-H404B7dJl2mCrBqahDEYsanB0xhdDp6tXnXcTUnXmmpy2Q3J0Ho0bUajZ2jr/RdwzCyS59Gi8xXIFwPLGBl6Uw==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/[email protected]':
+    resolution: {integrity: sha512-X98zYOrVOeuosCX+6ktf29FC2N2GHPLia7qv6mzPzTc+RPAuHWCDS++Z6JK7eGYqb/v6uaW7bAXaOvDBfol+0w==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/[email protected]':
+    resolution: {integrity: sha512-Rykg6s5ceBuynMOGWgoowO4N+27JfnqXAnVaSunZl0hOO1XodSrxGNz6sCEbnmS0lAfQZDKyb3fbr46gSuv6Sg==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/[email protected]':
+    resolution: {integrity: sha512-Jb59xfEISoN5mmbnA+HYqdtrSX3CgCtJoof+V5D8/TgUI56W63GEEd5Y58WijU3Ou6+WEgaLD1feVzaRXV5IDQ==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/[email protected]':
+    resolution: {integrity: sha512-Rml+WitoFvXmv6JZ18U/xGdGDGGvB/mOin0ya0lTnTrdC0Z1lrVxTYh7iNklZBcvcRMrs4DoEf6xy1KWyrLQQw==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/[email protected]':
+    resolution: {integrity: sha512-2ry03fGRJr4sV3jI+ocjj5JqALnFD6ymM5KiNCDZMvq8bX2GSbE0vji4aM43TVCl2nXqqLRZaUxdq/KeWRAY4Q==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/[email protected]':
+    resolution: {integrity: sha512-jkhg/8ocAAoc0RFyLMhCw+/zZh7gystQgd4F4hznNa8P4Cc501PQmxd+jGLiMHodPJ+7Zv/3znM62gZojyasmA==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/[email protected]':
+    resolution: {integrity: sha512-d3AGyVu759PGr35mEB2s22xxlNEA5rpdxtSPJthfPFJvoQ8dt357iVPECqWfUxXp1toJAvKmbtcIYVGigaGsCA==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/[email protected]':
+    resolution: {integrity: sha512-4dxJX2pueKHtFyxdtT/IH385NpAWjbNjpbbIN6L9YK58dbae6ldyiLSom1EV5nPoOxKtWLXiqch+yo3NjXfleQ==}
+    engines: {node: '>=20.0.0'}
+    peerDependencies:
+      '@aws-sdk/client-s3': ^3.1119.0
+
+  '@aws-sdk/[email protected]':
+    resolution: {integrity: sha512-wMIsNumRVKaNMKhvU/s9VrdEwE8S6gSzXp4RygFG5BEMnGkkXf8cjh8zf7cKJBpUDpqTWqwbz5isEgp9rH6Lng==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/[email protected]':
+    resolution: {integrity: sha512-NhEgryjlBF9w38ZXqGymQV28IhkYa1mKhlbYnqIis57AYwWGVYfUPgg/qC2rLRqOUfblxx++irvju10kVTa8Vw==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/[email protected]':
+    resolution: {integrity: sha512-yEqb0ispm9uXZ7nk5stErMB7yn43j3XCAaHM15MsdWaCk7RvEmGjYdbyHZcH86JpUg7mk1v1m2xwzLj2o+3uCg==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/[email protected]':
+    resolution: {integrity: sha512-L+2xZTye/2T96f3lwCws0Zw6GG2JHZW9e8FpVgGBeeExSKyeoZ6CWRpBml/7DNiK/O26jrgPM9F+Ay8VkgzUWQ==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/[email protected]':
+    resolution: {integrity: sha512-ygIivKqh8aHzNkucOCXHyIBgBpLPfrSI0mCqXF+vLBsPTUKqj0VSqAY0GFPe7lQl4HntjOcQ+KSyS7oUV2C54Q==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/[email protected]':
+    resolution: {integrity: sha512-LkwLL2BLbC6wNNm4JaH9mbEqBMdOZCct6VAYqhdN4U1xrWM+fUJQEfbHwQgDypapOWTRtlk25akb5afM0P8CIQ==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/[email protected]':
+    resolution: {integrity: sha512-wlFmCIGUlwF4zx/kncw+bmxTQh1HeSJq4mYV/V5cZUSJadDP3kXvGW8Rn21cimj/7y9ju+47oYWXi97vF7czaA==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws/[email protected]':
+    resolution: {integrity: sha512-sl4Bm6yiMNYrZKkqqDFWN0UfnWhlS8ivKxrYl+6t0gCLrqr8y3B2IqZZbFRkfaVVp7C/baApyh71P+LeE1A2sQ==}
+    engines: {node: '>=18.0.0'}
+
   '@babel/[email protected]':
     resolution: {integrity: sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw==}
     engines: {node: '>=6.9.0'}
@@ -1646,6 +1731,13 @@ packages:
       next: '>=15.2.9 <15.3.0 || >=15.3.9 <15.4.0 || >=15.4.11 <15.5.0 || >=16.2.6 <17.0.0'
       payload: 3.88.0
 
+  '@payloadcms/[email protected]':
+    resolution: {integrity: sha512-wIcRVedtBZIQMu7dpSE1TOJKJd0HuVSUNPrV2KxIbtqQFm+ly34NCJYY0m1+K0YS6my8BKdcB4jj2exg8454Ig==}
+    peerDependencies:
+      payload: 3.88.0
+      react: ^19.0.1 || ^19.1.2 || ^19.2.1
+      react-dom: ^19.0.1 || ^19.1.2 || ^19.2.1
+
   '@payloadcms/[email protected]':
     resolution: {integrity: sha512-C915jEHADVN9xW7fSq/bYIZig1zjfQo+t4wrgiqjOCmB81oMgyqLRB3RlL2e6y4PzBUtgss2VS40vn/tVD/61Q==}
     peerDependencies:
@@ -1671,6 +1763,12 @@ packages:
       react: ^19.0.1 || ^19.1.2 || ^19.2.1
       react-dom: ^19.0.1 || ^19.1.2 || ^19.2.1
 
+  '@payloadcms/[email protected]':
+    resolution: {integrity: sha512-+35JRD4y7ImnIJuPSBhECHGGml0A+xju9BT/zW+lRUycDvvA0cqZNP+t95OVoZrxIB6V75Vg8GKPvAaRAmgOEw==}
+    engines: {node: ^18.20.2 || >=20.9.0}
+    peerDependencies:
+      payload: 3.88.0
+
   '@payloadcms/[email protected]':
     resolution: {integrity: sha512-AZVQjjW5pKxO+K9ODeh6yw6/EfXK1hxGPw55KzzDC5srO3hjNskgyWtkauKvbz+S0+xFspANbRc4OD/Rg/74WA==}
 
@@ -1839,6 +1937,30 @@ packages:
     resolution: {integrity: sha512-TV7t8GKYaJWsn00tFDqBw8+Uqmr8A0fRU1tvTQhyZzGv0sJCGRQL3JGMI3ucuKo3XIZdUP+Lx7/gh2t3lewy7g==}
     engines: {node: '>=14.16'}
 
+  '@smithy/[email protected]':
+    resolution: {integrity: sha512-CsOeKq/9kA3y6VJHt+/+VTCtBaxJ4OTFpgrjIUhPpDIKxBci1k2bJaQASF2h/ELWrulGp+t97DZ0mevfAD8idg==}
+    engines: {node: '>=18.0.0'}
+
+  '@smithy/[email protected]':
+    resolution: {integrity: sha512-A9uSdn72ozbRUSit0eib0TW7nXuNPlaeM0zcGkJ+nE6tFcSDbnmtwoxbTCFBukVQcszDAyvsd7+rTduPTXpygg==}
+    engines: {node: '>=18.0.0'}
+
+  '@smithy/[email protected]':
+    resolution: {integrity: sha512-nZyWTmSpJEXl6VtWVMBJve/7x12DZu6sIX1z1a+ZMaHlQQRs9Zpu6NbTe/gmxYXVRpkjxyDYpZ5gx2IM6f/Wkw==}
+    engines: {node: '>=18.0.0'}
+
+  '@smithy/[email protected]':
+    resolution: {integrity: sha512-2jY1tSpERfPfWqyBV2pH+iGFaghVsIJszJNsT7hxtQYhVJpWDyc0LqOWI+nXOxOAHaEfZ4PXXtp1wW1TGpHhkA==}
+    engines: {node: '>=18.0.0'}
+
+  '@smithy/[email protected]':
+    resolution: {integrity: sha512-7ImGm+FkHRLcBaRttIAMZ6bzJZWb2cJGoYjq46F2UjycujWzrL9GEN9h4w7eQyXJYnltrUhxbbieBAIRrdqpow==}
+    engines: {node: '>=18.0.0'}
+
+  '@smithy/[email protected]':
+    resolution: {integrity: sha512-FOKpVZob9MPTn2znRzGrnsMHv7BOsKVw3XiP/cOyYLDVZ9qKp4nifIiSCuUU/fIj5Vu0UOAxCFr+qRAtG0NUkA==}
+    engines: {node: '>=18.0.0'}
+
   '@standard-schema/[email protected]':
     resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
 
@@ -2563,6 +2685,9 @@ packages:
   [email protected]:
     resolution: {integrity: sha512-a7tP5+0Mw3YlUJcGAKUqIBkYYGlYxk2fnCasq/FUph1hadxlTRjF+gAcZksxANnaMnALjxEddmSi/H3OR8ugcQ==}
 
+  [email protected]:
+    resolution: {integrity: sha512-tzPjzCxygAKWFOJP011oxFHs57HzIhOEracIgAePE4pqB3LikALKnSzUyU4MGs9/iCEUuHlAJTjTc5M+u7YEGg==}
+
   [email protected]:
     resolution: {integrity: sha512-EwOCDEex4quD37XhqM3omwtMoJjr//isUZz1JopUNWms+4Z2ViyM/k1YIRePpoVNnQhENnxtFjLaxNHrT7xIUg==}
 
@@ -2596,6 +2721,9 @@ packages:
     resolution: {integrity: sha512-nEh+kZOPY1w+gcCMobZ6ETUp9WfibndnosbpwB1iJk/8Gt5ZF2bhS6+B6bPYz424KtwsR6Rflc3tCz1/ghX2dQ==}
     engines: {node: '>=4.0'}
 
+  [email protected]:
+    resolution: {integrity: sha512-/gDYp/UtU0eA1ys8bOs9J6a+E/KWIY+DZ+Q2WESNUA0jFRsJOc0SNUO6xJ5SGA1xueg3NL65W6s+NY5l9cunuw==}
+
   [email protected]:
     resolution: {integrity: sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ==}
 
@@ -2866,6 +2994,10 @@ packages:
     resolution: {integrity: sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==}
     engines: {node: '>=6'}
 
+  [email protected]:
+    resolution: {integrity: sha512-DtCOLG98P007x7wiiOmfI0fi3eIKyWiLTGJ2MDnVi/E04lWGbf+JzrRHMm0rgIIZJGtHpKpbVgLWHrv8xXpc3Q==}
+    engines: {node: '>=0.10.0'}
+
   [email protected]:
     resolution: {integrity: sha512-y+8xyqdGLL+6sh0tVeHcfP/QDd8gUgbasolJJpY7NgeQGSZ739bDtSiaiDgtoicy+mtYB81dKLxO9xRhCyIB3A==}
     engines: {node: '>=12.20'}
@@ -3363,10 +3495,18 @@ packages:
   [email protected]:
     resolution: {integrity: sha512-LUd5euvbMLpwOF8m6ivPCbhQeSiYVNb8Vs0fQ8QjXo0JTkEHpz8pxdQf0gStltaPpw0Cca8b39KxvK9cfKRiAw==}
 
+  [email protected]:
+    resolution: {integrity: sha512-mQw+2fkQbALzQ7V0MY0IqdnXNOeTtP4r0lN9z7AAawCXgqea7bDii20AYrIBrFd/Hx0M2Ocz6S111CaFkUcb0Q==}
+    engines: {node: '>=0.8.x'}
+
   [email protected]:
     resolution: {integrity: sha512-8uSpZZocAZRBAPIEINJj3Lo9HyGitllczc27Eh5YYojjMFMn8yHMDMaUHE2Jqfq05D/wucwI4JGURyXt1vchyg==}
     engines: {node: '>=10'}
 
+  [email protected]:
+    resolution: {integrity: sha512-A5EmesHW6rfnZ9ysHQjPdJRni0SRar0tjtG5MNtm9n5TUvsYU8oozprtRD4AqHxcZWWlVuAmQo2nWKfN9oyjTw==}
+    engines: {node: '>=0.10.0'}
+
   [email protected]:
     resolution: {integrity: sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==}
     engines: {node: '>=12.0.0'}
@@ -3455,6 +3595,9 @@ packages:
     resolution: {integrity: sha512-wXZV5emFEjrridIgED11OoUKLxiYjAcqot/NJdAkOhlJ+vGzwhOAfcG5OX1jP+S0PcjEn8bdMJv+g2jwQ3Onig==}
     engines: {node: '>=8'}
 
+  [email protected]:
+    resolution: {integrity: sha512-UC2I2+nx1ZuOBclWVNdcnbDR5dlrOdVb7xNjmT/lHE+LsgztWks3dG7boJ37yTS/venXw84B/mAW9uHVoC5QRg==}
+
   [email protected]:
     resolution: {integrity: sha512-NKfW6bec6GfKc0SGx1e07QZY9PE99u0Bft/0rzSD5k3sO/vwkVUpDUKVm5Gpp5Ue3YfShPFTX2070tDs5kB9Ng==}
 
@@ -3470,6 +3613,10 @@ packages:
     resolution: {integrity: sha512-+iwzCJ7C5v5KgcBuueqVoNiHVoQpwiUK5XFLjf0affFTep+Wcw93tPvmb8tqujDNmzhBDPddnWV/qgWSXgq+Hg==}
     engines: {node: '>=12'}
 
+  [email protected]:
+    resolution: {integrity: sha512-6jvvn/12IC4quLBL1KNokxC7wWTvYncaVUYSoxWw7YykPLuRrnv4qdHcSOywOI5RpkOVGeQRtWM8/q+G6W6qfQ==}
+    engines: {node: '>= 8'}
+
   [email protected]:
     resolution: {integrity: sha512-f7ccFPK3SXFHpx15UIGyRJ/FJQctuKZ0zVuN3frBo4HnK3cay9VEW0R6yPYFHC0AgqhukPzKjq22t5DmAyqGyw==}
     engines: {node: '>=16'}
@@ -3577,6 +3724,14 @@ packages:
     resolution: {integrity: sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==}
     deprecated: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting [email protected]
 
+  [email protected]:
+    resolution: {integrity: sha512-sKzpEkf11GpOFuw0Zzjzmt4B4UZwjOcG757PPvrfhxcLFbq0wpsgpOqxpxtxFiCG4DtG93M6XRVbF2oGdev7bg==}
+    engines: {node: '>=0.10.0'}
+
+  [email protected]:
+    resolution: {integrity: sha512-5lsx1NUDHtSjfg0eHlmYvZKv8/nVqX4ckFbM+FrGcQ+04KWcWFo9P5MxPZYSzUvyzmdTbI7Eix8Q4IbELDqzKg==}
+    engines: {node: '>=0.10.0'}
+
   [email protected]:
     resolution: {integrity: sha512-oahGvuMGQlPw/ivIYBjVSrWAfWLBeku5tpPE2fOPLi+WHffIWbuh2tCjhyQhTBPMf5E9jDEH4FOmTYgYwbKwtQ==}
     engines: {node: '>=18'}
@@ -3672,6 +3827,10 @@ packages:
   [email protected]:
     resolution: {integrity: sha512-/gGivxi8JPKWNm/W0jSmzcMPpfpPLc3dY/6GxhX2hQ9iGj3aDfklV4ET7NjKpSinLpJ5vafa9iiGIEZg10SfBw==}
 
+  [email protected]:
+    resolution: {integrity: sha512-eSmmWE5bZTK2Nou4g0AI3zZ9rswp7GRKoKXS1BLUkvPviOqs4YTN1djQIqrXy9k5gEtdLPy86JjRwsNM9tnDcA==}
+    engines: {node: '>=0.10.0'}
+
   [email protected]:
     resolution: {integrity: sha512-dTxcvPXqPvXBQpq5dUr6mEMJX4oIEFv6bwom3FDwKRDsuIjjJGANqhBuoAn9c1RQJIdAKav33ED65E2ys+87QQ==}
 
@@ -3725,6 +3884,9 @@ packages:
   [email protected]:
     resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==}
 
+  [email protected]:
+    resolution: {integrity: sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==}
+
   [email protected]:
     resolution: {integrity: sha512-MAQUJuIo7Xqk8EVNP+6d3CKq9c80hi4tjIbIAT6lmGW9W6WzlHiu9PS8uSuUYU+Do+j1baiFp3H25XEVxDIG2g==}
 
@@ -3894,6 +4056,10 @@ packages:
     resolution: {integrity: sha512-mfcwb6IzQyOKTs84CQMrOwW4gQcaTOAWJ0zzJCl2WSPDrWk/OzDaImWFH3djXhb24g4eudZfLRozAvPGw4d9hQ==}
     engines: {node: '>= 0.4'}
 
+  [email protected]:
+    resolution: {integrity: sha512-eXK1UInq2bPmjyX6e3VHIzMLobc4J94i4AWn+Hpq3OU5KkrRC96OAcR3PRJ/pGu6m8TRnBHP9dkXQVsT/COVIA==}
+    engines: {node: '>=0.10.0'}
+
   [email protected]:
     resolution: {integrity: sha512-e6rvdUCiQCAuumZslxRJWR/Doq4VpPR82kqclvcS0efgt430SlGIk05vdCN58+VrzgtIcfNODjozVielycD4Sw==}
     engines: {node: '>=16'}
@@ -4098,6 +4264,9 @@ packages:
     resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==}
     engines: {node: '>= 8'}
 
+  [email protected]:
+    resolution: {integrity: sha512-jz+Cfrg9GWOZbQAnDQ4hlVnQky+341Yk5ru8bZSe6sIDTCIg8n9i/u7hSQGSVOF3C7lH6mGtqjkiT9G4wFLL0w==}
+
   [email protected]:
     resolution: {integrity: sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==}
 
@@ -4430,6 +4599,10 @@ packages:
     resolution: {integrity: sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg==}
     engines: {node: '>=8'}
 
+  [email protected]:
+    resolution: {integrity: sha512-1Y1A//QUXEZK7YKz+rD9WydcE1+EuPr6ZBgKecAB8tmoW6UFv0NREVJe1p+jRxtThkcbbKkfwIbWJe/IeE6m2Q==}
+    engines: {node: '>=0.10.0'}
+
   [email protected]:
     resolution: {integrity: sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==}
     engines: {node: '>=8'}
@@ -4682,6 +4855,10 @@ packages:
   [email protected]:
     resolution: {integrity: sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==}
 
+  [email protected]:
+    resolution: {integrity: sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==}
+    engines: {node: '>= 6'}
+
   [email protected]:
     resolution: {integrity: sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA==}
     engines: {node: '>=8.10.0'}
@@ -4721,6 +4898,10 @@ packages:
   [email protected]:
     resolution: {integrity: sha512-0a1F4l73/ZFZOakJnQ3FvkJ2+gSTQWz/r2KE5OdDY0TxPm5h4GkqkWWfM47T7HsbnOtcJVEF4epCVy6u7Q3K+g==}
 
+  [email protected]:
+    resolution: {integrity: sha512-R7uiTjECzvOsWSfdM0QKFNBVFcK27aHOUwdvK53BcW8zqnGdYp0Fbj82cy54+2A4P2tFM22J5kRfe1R+lM/1yg==}
+    engines: {node: '>=0.10.0'}
+
   [email protected]:
     resolution: {integrity: sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g==}
     engines: {node: '>=4'}
@@ -4966,6 +5147,9 @@ packages:
     resolution: {integrity: sha512-eLoXW/DHyl62zxY4SCaIgnRhuMr6ri4juEYARS8E6sCEqzKpOiE521Ucofdx+KnDZl5xmvGYaaKCk5FEOxJCoQ==}
     engines: {node: '>= 0.4'}
 
+  [email protected]:
+    resolution: {integrity: sha512-H73RAHsVBapbim0tU2JwwOiXUj+fikfiaoYAKHF3VJfA0pe2BCzkhAHBlLG6REzE+2WNZcxOXjK7lkso+9euLA==}
+
   [email protected]:
     resolution: {integrity: sha512-Mcc5wHehp9aXz1ax6bZUyY5afg9u2rv5cqQI3mRrYkGC8rW2hM02jWuwjtL++LS5qinSyhj2QfLyNsuc+VsExg==}
     engines: {node: '>=10.0.0'}
@@ -5393,6 +5577,10 @@ packages:
     resolution: {integrity: sha512-fvO4ExWMFsqyhG3AiPAObMuY1lxaqgYcxbc49CNdWDDECOJNgQyvsOWVwbZc+qf3rzRtxojBK+CMEv0Ld5CYpw==}
     engines: {node: '>= 0.4'}
 
+  [email protected]:
+    resolution: {integrity: sha512-HxJdYWq1MTIQbJ3nw0cqssHoTNU267KlrDuGZ1WYlxDStUtKUhOaJmh112/TZmHxxUfuJqPXSOm7tDyas0OSIQ==}
+    hasBin: true
+
   [email protected]:
     resolution: {integrity: sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==}
     engines: {node: '>= 8'}
@@ -5490,6 +5678,190 @@ snapshots:
       '@types/json-schema': 7.0.15
       js-yaml: 4.3.0
 
+  '@aws-sdk/[email protected]':
+    dependencies:
+      '@aws-sdk/core': 3.977.9
+      '@aws-sdk/types': 3.974.5
+      '@smithy/core': 3.33.3
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@aws-sdk/[email protected]':
+    dependencies:
+      '@aws-sdk/checksums': 3.1000.29
+      '@aws-sdk/core': 3.977.9
+      '@aws-sdk/credential-provider-node': 3.972.81
+      '@aws-sdk/middleware-sdk-s3': 3.972.75
+      '@aws-sdk/signature-v4-multi-region': 3.996.46
+      '@aws-sdk/types': 3.974.5
+      '@smithy/core': 3.33.3
+      '@smithy/fetch-http-handler': 5.7.2
+      '@smithy/node-http-handler': 4.11.3
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@aws-sdk/[email protected]':
+    dependencies:
+      '@aws-sdk/types': 3.974.5
+      '@aws-sdk/xml-builder': 3.972.40
+      '@aws/lambda-invoke-store': 0.3.0
+      '@smithy/core': 3.33.3
+      '@smithy/signature-v4': 5.7.3
+      '@smithy/types': 4.17.2
+      bowser: 2.14.1
+      tslib: 2.8.1
+
+  '@aws-sdk/[email protected]':
+    dependencies:
+      '@aws-sdk/core': 3.977.9
+      '@aws-sdk/types': 3.974.5
+      '@smithy/core': 3.33.3
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@aws-sdk/[email protected]':
+    dependencies:
+      '@aws-sdk/core': 3.977.9
+      '@aws-sdk/types': 3.974.5
+      '@smithy/core': 3.33.3
+      '@smithy/fetch-http-handler': 5.7.2
+      '@smithy/node-http-handler': 4.11.3
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@aws-sdk/[email protected]':
+    dependencies:
+      '@aws-sdk/core': 3.977.9
+      '@aws-sdk/credential-provider-env': 3.972.70
+      '@aws-sdk/credential-provider-http': 3.972.72
+      '@aws-sdk/credential-provider-login': 3.972.77
+      '@aws-sdk/credential-provider-process': 3.972.70
+      '@aws-sdk/credential-provider-sso': 3.973.14
+      '@aws-sdk/credential-provider-web-identity': 3.972.76
+      '@aws-sdk/nested-clients': 3.997.44
+      '@aws-sdk/types': 3.974.5
+      '@smithy/core': 3.33.3
+      '@smithy/credential-provider-imds': 4.5.2
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@aws-sdk/[email protected]':
+    dependencies:
+      '@aws-sdk/core': 3.977.9
+      '@aws-sdk/nested-clients': 3.997.44
+      '@aws-sdk/types': 3.974.5
+      '@smithy/core': 3.33.3
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@aws-sdk/[email protected]':
+    dependencies:
+      '@aws-sdk/credential-provider-env': 3.972.70
+      '@aws-sdk/credential-provider-http': 3.972.72
+      '@aws-sdk/credential-provider-ini': 3.973.15
+      '@aws-sdk/credential-provider-process': 3.972.70
+      '@aws-sdk/credential-provider-sso': 3.973.14
+      '@aws-sdk/credential-provider-web-identity': 3.972.76
+      '@aws-sdk/types': 3.974.5
+      '@smithy/core': 3.33.3
+      '@smithy/credential-provider-imds': 4.5.2
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@aws-sdk/[email protected]':
+    dependencies:
+      '@aws-sdk/core': 3.977.9
+      '@aws-sdk/types': 3.974.5
+      '@smithy/core': 3.33.3
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@aws-sdk/[email protected]':
+    dependencies:
+      '@aws-sdk/core': 3.977.9
+      '@aws-sdk/nested-clients': 3.997.44
+      '@aws-sdk/token-providers': 3.1116.0
+      '@aws-sdk/types': 3.974.5
+      '@smithy/core': 3.33.3
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@aws-sdk/[email protected]':
+    dependencies:
+      '@aws-sdk/core': 3.977.9
+      '@aws-sdk/nested-clients': 3.997.44
+      '@aws-sdk/types': 3.974.5
+      '@smithy/core': 3.33.3
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@aws-sdk/[email protected](@aws-sdk/[email protected])':
+    dependencies:
+      '@aws-sdk/client-s3': 3.1119.0
+      '@smithy/core': 3.33.3
+      '@smithy/types': 4.17.2
+      buffer: 5.6.0
+      events: 3.3.0
+      stream-browserify: 3.0.0
+      tslib: 2.8.1
+
+  '@aws-sdk/[email protected]':
+    dependencies:
+      '@aws-sdk/core': 3.977.9
+      '@aws-sdk/signature-v4-multi-region': 3.996.46
+      '@aws-sdk/types': 3.974.5
+      '@smithy/core': 3.33.3
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@aws-sdk/[email protected]':
+    dependencies:
+      '@aws-sdk/core': 3.977.9
+      '@aws-sdk/signature-v4-multi-region': 3.996.46
+      '@aws-sdk/types': 3.974.5
+      '@smithy/core': 3.33.3
+      '@smithy/fetch-http-handler': 5.7.2
+      '@smithy/node-http-handler': 4.11.3
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@aws-sdk/[email protected]':
+    dependencies:
+      '@aws-sdk/core': 3.977.9
+      '@aws-sdk/signature-v4-multi-region': 3.996.46
+      '@aws-sdk/types': 3.974.5
+      '@smithy/core': 3.33.3
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@aws-sdk/[email protected]':
+    dependencies:
+      '@aws-sdk/types': 3.974.5
+      '@smithy/signature-v4': 5.7.3
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@aws-sdk/[email protected]':
+    dependencies:
+      '@aws-sdk/core': 3.977.9
+      '@aws-sdk/nested-clients': 3.997.44
+      '@aws-sdk/types': 3.974.5
+      '@smithy/core': 3.33.3
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@aws-sdk/[email protected]':
+    dependencies:
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@aws-sdk/[email protected]':
+    dependencies:
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@aws/[email protected]': {}
+
   '@babel/[email protected]':
     dependencies:
       '@babel/helper-validator-identifier': 7.29.7
@@ -7020,6 +7392,21 @@ snapshots:
       - supports-color
       - typescript
 
+  '@payloadcms/[email protected](@types/[email protected])([email protected])([email protected](@babel/[email protected])(@playwright/[email protected])([email protected]([email protected]))([email protected])([email protected]))([email protected]([email protected])([email protected]))([email protected]([email protected]))([email protected])([email protected])':
+    dependencies:
+      '@payloadcms/ui': 3.88.0(@types/[email protected])([email protected])([email protected](@babel/[email protected])(@playwright/[email protected])([email protected]([email protected]))([email protected])([email protected]))([email protected]([email protected])([email protected]))([email protected]([email protected]))([email protected])([email protected])
+      find-node-modules: 2.1.3
+      payload: 3.88.0([email protected])([email protected])
+      range-parser: 1.2.1
+      react: 19.2.6
+      react-dom: 19.2.6([email protected])
+    transitivePeerDependencies:
+      - '@types/react'
+      - monaco-editor
+      - next
+      - supports-color
+      - typescript
+
   '@payloadcms/[email protected](@types/[email protected])([email protected])([email protected](@babel/[email protected])(@playwright/[email protected])([email protected]([email protected]))([email protected])([email protected]))([email protected]([email protected])([email protected]))([email protected]([email protected]))([email protected])([email protected])':
     dependencies:
       '@payloadcms/translations': 3.88.0
@@ -7094,6 +7481,22 @@ snapshots:
       - utf-8-validate
       - yjs
 
+  '@payloadcms/[email protected](@types/[email protected])([email protected])([email protected](@babel/[email protected])(@playwright/[email protected])([email protected]([email protected]))([email protected])([email protected]))([email protected]([email protected])([email protected]))([email protected]([email protected]))([email protected])([email protected])':
+    dependencies:
+      '@aws-sdk/client-s3': 3.1119.0
+      '@aws-sdk/lib-storage': 3.1119.0(@aws-sdk/[email protected])
+      '@aws-sdk/s3-request-presigner': 3.1119.0
+      '@payloadcms/plugin-cloud-storage': 3.88.0(@types/[email protected])([email protected])([email protected](@babel/[email protected])(@playwright/[email protected])([email protected]([email protected]))([email protected])([email protected]))([email protected]([email protected])([email protected]))([email protected]([email protected]))([email protected])([email protected])
+      payload: 3.88.0([email protected])([email protected])
+    transitivePeerDependencies:
+      - '@types/react'
+      - monaco-editor
+      - next
+      - react
+      - react-dom
+      - supports-color
+      - typescript
+
   '@payloadcms/[email protected]':
     dependencies:
       date-fns: 4.1.0
@@ -7220,6 +7623,39 @@ snapshots:
 
   '@sindresorhus/[email protected]': {}
 
+  '@smithy/[email protected]':
+    dependencies:
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@smithy/[email protected]':
+    dependencies:
+      '@smithy/core': 3.33.3
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@smithy/[email protected]':
+    dependencies:
+      '@smithy/core': 3.33.3
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@smithy/[email protected]':
+    dependencies:
+      '@smithy/core': 3.33.3
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@smithy/[email protected]':
+    dependencies:
+      '@smithy/core': 3.33.3
+      '@smithy/types': 4.17.2
+      tslib: 2.8.1
+
+  '@smithy/[email protected]':
+    dependencies:
+      tslib: 2.8.1
+
   '@standard-schema/[email protected]': {}
 
   '@swc-node/[email protected](@swc/[email protected])(@swc/[email protected])':
@@ -8043,6 +8479,8 @@ snapshots:
 
   [email protected]: {}
 
+  [email protected]: {}
+
   [email protected]:
     dependencies:
       balanced-match: 1.0.2
@@ -8078,6 +8516,11 @@ snapshots:
     dependencies:
       '@types/node': 22.19.9
 
+  [email protected]:
+    dependencies:
+      base64-js: 1.5.1
+      ieee754: 1.2.1
+
   [email protected]:
     dependencies:
       base64-js: 1.5.1
@@ -8330,6 +8773,8 @@ snapshots:
 
   [email protected]: {}
 
+  [email protected]: {}
+
   [email protected]: {}
 
   [email protected]: {}
@@ -9098,6 +9543,8 @@ snapshots:
     transitivePeerDependencies:
       - bare-abort-controller
 
+  [email protected]: {}
+
   [email protected]:
     dependencies:
       cross-spawn: 7.0.6
@@ -9110,6 +9557,10 @@ snapshots:
       signal-exit: 3.0.7
       strip-final-newline: 2.0.0
 
+  [email protected]:
+    dependencies:
+      homedir-polyfill: 1.0.3
+
   [email protected]: {}
 
   [email protected]:
@@ -9204,6 +9655,11 @@ snapshots:
       make-dir: 3.1.0
       pkg-dir: 4.2.0
 
+  [email protected]:
+    dependencies:
+      findup-sync: 4.0.0
+      merge: 2.1.1
+
   [email protected]: {}
 
   [email protected]:
@@ -9220,6 +9676,13 @@ snapshots:
     dependencies:
       semver-regex: 4.0.5
 
+  [email protected]:
+    dependencies:
+      detect-file: 1.0.0
+      is-glob: 4.0.3
+      micromatch: 4.0.8
+      resolve-dir: 1.0.1
+
   [email protected]:
     dependencies:
       flatted: 3.4.2
@@ -9330,6 +9793,20 @@ snapshots:
       once: 1.4.0
       path-is-absolute: 1.0.1
 
+  [email protected]:
+    dependencies:
+      global-prefix: 1.0.2
+      is-windows: 1.0.2
+      resolve-dir: 1.0.1
+
+  [email protected]:
+    dependencies:
+      expand-tilde: 2.0.2
+      homedir-polyfill: 1.0.3
+      ini: 1.3.8
+      is-windows: 1.0.2
+      which: 1.3.1
+
   [email protected]: {}
 
   [email protected]: {}
@@ -9425,6 +9902,10 @@ snapshots:
     dependencies:
       react-is: 16.13.1
 
+  [email protected]:
+    dependencies:
+      parse-passwd: 1.0.0
+
   [email protected]: {}
 
   [email protected]: {}
@@ -9467,6 +9948,8 @@ snapshots:
 
   [email protected]: {}
 
+  [email protected]: {}
+
   [email protected]:
     dependencies:
       kind-of: 6.0.3
@@ -9630,6 +10113,8 @@ snapshots:
       call-bound: 1.0.4
       get-intrinsic: 1.3.0
 
+  [email protected]: {}
+
   [email protected]:
     dependencies:
       is-inside-container: 1.0.0
@@ -9855,6 +10340,8 @@ snapshots:
 
   [email protected]: {}
 
+  [email protected]: {}
+
   [email protected]:
     dependencies:
       decode-named-character-reference: 1.3.0
@@ -10320,6 +10807,8 @@ snapshots:
       json-parse-even-better-errors: 2.3.1
       lines-and-columns: 1.2.4
 
+  [email protected]: {}
+
   [email protected]: {}
 
   [email protected]: {}
@@ -10610,6 +11099,12 @@ snapshots:
       string_decoder: 1.1.1
       util-deprecate: 1.0.2
 
+  [email protected]:
+    dependencies:
+      inherits: 2.0.4
+      string_decoder: 1.1.1
+      util-deprecate: 1.0.2
+
   [email protected]:
     dependencies:
       picomatch: 2.3.2
@@ -10653,6 +11148,11 @@ snapshots:
 
   [email protected]: {}
 
+  [email protected]:
+    dependencies:
+      expand-tilde: 2.0.2
+      global-modules: 1.0.0
+
   [email protected]: {}
 
   [email protected]: {}
@@ -10979,6 +11479,11 @@ snapshots:
       es-errors: 1.3.0
       internal-slot: 1.1.0
 
+  [email protected]:
+    dependencies:
+      inherits: 2.0.4
+      readable-stream: 3.6.2
+
   [email protected]: {}
 
   [email protected]:
@@ -11479,6 +11984,10 @@ snapshots:
       gopd: 1.2.0
       has-tostringtag: 1.0.2
 
+  [email protected]:
+    dependencies:
+      isexe: 2.0.0
+
   [email protected]:
     dependencies:
       isexe: 2.0.0

src/globals/SiteIntegrations/fields/storage.ts

@@ -1,44 +0,0 @@
-import type { Field } from 'payload'
-
-/**
- * Cloudflare R2 storage credentials.
- * Reserved for future use — media offloading to R2.
- *
- * Protected at the global level (SiteIntegrations requires an authenticated
- * user), so the access keys stay editable in the admin panel while remaining
- * inaccessible to anonymous API requests.
- */
-export const storageFields: Field[] = [
-  {
-    name: 'r2Bucket',
-    type: 'text',
-    admin: {
-      description: 'R2 bucket name.',
-    },
-  },
-  {
-    name: 'r2Endpoint',
-    type: 'text',
-    admin: {
-      description: 'R2 S3-compatible endpoint URL.',
-    },
-  },
-  {
-    name: 'r2AccessKeyId',
-    type: 'text',
-    admin: {
-      description: 'R2 access key ID.',
-    },
-  },
-  {
-    name: 'r2SecretAccessKey',
-    type: 'text',
-    admin: {
-      description: 'R2 secret access key.',
-      // Masked in the UI (••••) — stored plaintext, readable for R2 auth.
-      components: {
-        Field: '@intecion/ipal-kit/client#MaskedField',
-      },
-    },
-  },
-]

src/globals/SiteIntegrations/index.ts

@@ -3,7 +3,6 @@ import type { Field, GlobalConfig } from 'payload'
 import { isAdmin } from '../../modules/access/index.js'
 import { analyticsFields } from './fields/analytics.js'
 import { smtpFields } from './fields/smtp.js'
-import { storageFields } from './fields/storage.js'
 import { turnstileFields } from './fields/turnstile.js'
 
 type BuildSiteIntegrationsArgs = {
@@ -22,6 +21,10 @@ type BuildSiteIntegrationsArgs = {
  * impossible to enter.)
  *
  * Unnamed tabs keep data flat (siteIntegrations.ga4MeasurementId).
+ *
+ * Note: R2 storage credentials are NOT here — storage is infrastructure and
+ * binds at boot, so its config lives in .env (R2_BUCKET, R2_ENDPOINT, ...),
+ * consumed by buildR2Storage. See docs/storage.md.
  */
 export function buildSiteIntegrations({
   additionalFields,
@@ -44,7 +47,6 @@ export function buildSiteIntegrations({
           { fields: analyticsFields, label: 'Analytics' },
           { fields: turnstileFields, label: 'Turnstile' },
           { fields: smtpFields, label: 'SMTP' },
-          { fields: storageFields, label: 'Storage' },
           ...(additionalFields?.length ? [{ fields: additionalFields, label: 'Custom' }] : []),
         ],
       },

src/index.ts

@@ -75,6 +75,18 @@ export {
 } from './modules/i18n/index.js'
 export type { LocaleMiddlewareResult } from './modules/i18n/index.js'
 export { createLocaleMiddleware, DEFAULT_MIDDLEWARE_MATCHER } from './modules/i18n/index.js'
+// Media — filename normalization hook for upload collections (Media).
+export { normalizeFilename, normalizeFilenameHook } from './modules/media/index.js'
+export {
+  getNotificationTexts,
+  NOTIFICATION_FALLBACK,
+  resolveFormMessage,
+} from './modules/notifications/index.js'
+export type {
+  FormNotificationTexts,
+  NotificationsData,
+  NotificationTexts,
+} from './modules/notifications/index.js'
 export type { PagesOption, SystemPageRole } from './modules/pages/index.js'
 export { ALL_SYSTEM_PAGE_ROLES, getSystemPagePath } from './modules/pages/index.js'
 export type { GlobalQueryOptions } from './modules/payload/index.js'
@@ -99,18 +111,8 @@ export {
   injectAutoFillMeta,
 } from './modules/seo/index.js'
 export { buildSlugField, toSlug } from './modules/slug/index.js'
-export {
-  NOTIFICATION_FALLBACK,
-  getNotificationTexts,
-  resolveFormMessage,
-} from './modules/notifications/index.js'
-export type {
-  FormNotificationTexts,
-  NotificationsData,
-  NotificationTexts,
-} from './modules/notifications/index.js'
+// Storage — Cloudflare R2 media offload, configured from .env.
+export { buildR2Storage } from './modules/storage/index.js'
 
 export { ipalKit } from './plugin.js'
 export type { IpalOptions } from './types.js'
-
-

src/modules/i18n/negotiateLocale.ts

@@ -3,7 +3,14 @@ import type { I18nConfig } from './types.js'
 import { getLocaleCodes, isValidLocale } from './helpers.js'
 
 /** Cookie name the template uses to persist a visitor's locale choice. */
-export const LOCALE_COOKIE_NAME = 'ipal-locale'
+/**
+ * Cookie name for the persisted locale choice. Uses NEXT_LOCALE — the convention
+ * Next.js and its i18n ecosystem expect — so the cookie is interoperable with
+ * other libraries that read the active locale (instead of a plugin-specific
+ * name). Written only under functional consent; cleared when that consent is
+ * withdrawn (see consent cookieMap).
+ */
+export const LOCALE_COOKIE_NAME = 'NEXT_LOCALE'
 
 type NegotiateLocaleArgs = {
   /** Raw Accept-Language header value */

src/modules/media/index.ts

@@ -0,0 +1 @@
+export { normalizeFilename, normalizeFilenameHook } from './normalizeFilename.js'

src/modules/media/normalizeFilename.ts

@@ -0,0 +1,53 @@
+import type { CollectionBeforeOperationHook } from 'payload'
+import slugify from 'slugify'
+
+/**
+ * Normalizes a filename: slugifies the NAME part (diacritics, spaces, case)
+ * while preserving the extension. Keeps uploaded media URLs clean and portable.
+ *
+ *   "Zdjęcie jeden nad morzem.jpg"  → "zdjecie-jeden-nad-morzem.jpg"
+ *   "Faktura #12 (2024).PDF"        → "faktura-12-2024.pdf"
+ *   "already-clean.webp"            → "already-clean.webp"
+ *
+ * Why not toSlug(): toSlug uses strict:true, which would strip the dot and
+ * merge name+extension. Here we split on the LAST dot, slug the stem, lowercase
+ * the extension, and rejoin.
+ */
+export function normalizeFilename(filename: string): string {
+  const lastDot = filename.lastIndexOf('.')
+
+  // No extension (or leading-dot dotfile) → slug the whole thing.
+  if (lastDot <= 0) {
+    return slugify(filename, { lower: true, strict: true, trim: true })
+  }
+
+  const stem = filename.slice(0, lastDot)
+  const ext = filename.slice(lastDot + 1).toLowerCase()
+
+  const cleanStem = slugify(stem, { lower: true, strict: true, trim: true })
+  const cleanExt = slugify(ext, { lower: true, strict: true, trim: true })
+
+  // Stem could slug to empty (e.g. filename was all symbols) — fall back so we
+  // never produce a nameless file.
+  const safeStem = cleanStem || 'plik'
+
+  return cleanExt ? `${safeStem}.${cleanExt}` : safeStem
+}
+
+/**
+ * beforeOperation hook for an upload collection (e.g. Media). Rewrites the
+ * incoming file's name to its normalized form before Payload stores it, so both
+ * the stored file and its DB filename are clean. Works with local disk and with
+ * cloud storage adapters (R2/S3) — it runs before the storage layer.
+ *
+ * Wire into your Media collection:
+ *   import { normalizeFilenameHook } from '@intecion/ipal-kit'
+ *   hooks: { beforeOperation: [normalizeFilenameHook] }
+ */
+export const normalizeFilenameHook: CollectionBeforeOperationHook = ({ req, operation }) => {
+  if (operation !== 'create' && operation !== 'update') return
+  const file = req.file
+  if (file?.name) {
+    file.name = normalizeFilename(file.name)
+  }
+}

src/modules/storage/buildR2Storage.ts

@@ -0,0 +1,53 @@
+import type { Plugin } from 'payload'
+import { s3Storage } from '@payloadcms/storage-s3'
+
+/**
+ * Cloudflare R2 media storage — configured from environment variables (agency
+ * infrastructure, not per-project panel data). R2 is S3-compatible, so we use
+ * @payloadcms/storage-s3 pointed at the R2 endpoint.
+ *
+ * Storage is infrastructure (like the database or PAYLOAD_SECRET): it binds at
+ * boot, and its credentials are agency-owned — so it lives in .env, not the
+ * panel. See docs/storage.md for the required variables.
+ *
+ * Returns the storage plugin when all R2 vars are present; otherwise returns a
+ * no-op passthrough so the project falls back to Payload's default local disk
+ * storage (useful in dev without R2). This mirrors how mailAdapter degrades
+ * gracefully when a transport isn't configured.
+ *
+ * @param collections - slugs of upload collections to offload to R2 (e.g. ['media'])
+ */
+export const buildR2Storage = (collections: string[] = ['media']): Plugin => {
+  const bucket = process.env.R2_BUCKET
+  const endpoint = process.env.R2_ENDPOINT
+  const accessKeyId = process.env.R2_ACCESS_KEY_ID
+  const secretAccessKey = process.env.R2_SECRET_ACCESS_KEY
+
+  // Any missing → skip R2, fall back to local disk. Warn so it's not silent.
+  if (!bucket || !endpoint || !accessKeyId || !secretAccessKey) {
+    return (config) => {
+      // Only warn when SOME vars are set (partial config = likely a mistake).
+      if (bucket || endpoint || accessKeyId || secretAccessKey) {
+        console.warn(
+          '[ipal] R2 storage: incomplete env (need R2_BUCKET, R2_ENDPOINT, ' +
+            'R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY). Falling back to local disk.',
+        )
+      }
+      return config
+    }
+  }
+
+  const collectionsConfig = Object.fromEntries(collections.map((slug) => [slug, true]))
+
+  return s3Storage({
+    collections: collectionsConfig,
+    bucket,
+    config: {
+      endpoint,
+      region: 'auto', // R2 uses 'auto'
+      credentials: { accessKeyId, secretAccessKey },
+      // R2 requires path-style addressing for S3 compatibility.
+      forcePathStyle: true,
+    },
+  })
+}

src/modules/storage/index.ts

@@ -0,0 +1 @@
+export { buildR2Storage } from './buildR2Storage.js'