1.0.18

docs/PLAYBOOK.md

@@ -4,12 +4,13 @@ Sztywna procedura dla pracownika albo AI (Antigravity). Mówi CO robić, W JAKIE
 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: [publishing.md](./publishing.md) (cykl publikacji), [getting-started.md](./getting-started.md)
+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
+## 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
@@ -18,6 +19,8 @@ Powiązane: [publishing.md](./publishing.md) (cykl publikacji), [getting-started
 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ę.
 
 ---
 
@@ -39,6 +42,11 @@ 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
@@ -83,6 +91,9 @@ pokazał 0. Naprawa: dodać eksport, przejść łańcuch od nowa.
   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.
 
 ---
 
@@ -236,4 +247,8 @@ Nie mów „działa", dopóki:
 - [ ] 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
+- [ ] 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/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

@@ -172,6 +172,9 @@ export const blockRegistry: BlockComponentMap = {
 }
 ```
 
+> **Jak budować treść, żeby klient mógł wszystko edytować** (filozofia
+> CMS, kolejność komponent→blok→strona): [architektura-tresci.md](./architektura-tresci.md).
+
 **Puste `blocks: []` crashuje** (traverseFields) — zawsze co najmniej jeden blok.
 
 ### enhanceProps — wstrzykiwanie danych server-side do bloków

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intecion/ipal-kit",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "description": "Intecion Payload Advanced Library — a Payload CMS 3 plugin: i18n, SEO, forms, consent, analytics, blog/archives.",
   "license": "MIT",
   "repository": {