From 195d4169f52019fd74da523a633ac68a25952a8a Mon Sep 17 00:00:00 2001
From: rasm-its <radoslaw.smolinski@intecion.com>
Date: Wed, 12 Aug 2026 17:54:40 +0200
Subject: [PATCH] updated docs

---
 README.md                  | 164 +++++++++++--------------------------
 docs/README.md             |   4 +-
 docs/dev/gitea-commands.md |  86 +++++++++++++++++++
 docs/dev/publishing.md     | 116 ++++++++++++++++++++++++++
 docs/frontend-setup.md     |  16 ++--
 docs/getting-started.md    |  20 +++--
 docs/i18n.md               |  15 ++--
 7 files changed, 287 insertions(+), 134 deletions(-)
 create mode 100644 docs/dev/gitea-commands.md
 create mode 100644 docs/dev/publishing.md

diff --git a/README.md b/README.md
index 60fda87..5ede2fc 100644
--- a/README.md
+++ b/README.md
@@ -11,99 +11,23 @@ blog/archive system (collections under an archive page, listing, pagination).
 
 ---
 
-## Before you start
-
-The `git.intecion.net` server is internal — you'll only see the code and the
-package once you're signed in to your Intecion account. Every installation method
-needs your personal access token. Without it you'll get a 404 or an
-"Unauthorized" error.
-
-You generate the token once. It's tied to your account — don't ask anyone for
-theirs, and don't put it in any file that ends up in a repository.
-
-### Generate a token
-
-1. Sign in to Gitea → click your avatar → **Settings**.
-2. **Applications → Generate New Token**.
-3. Name it (e.g. `ipal-kit-install`) and select the scope:
-   - `read:package` — if you only install the plugin in projects,
-   - `write:package` — additionally, if you'll publish new versions.
-4. Click **Generate**. Copy the token now — Gitea shows it only once.
-
-### Store the token in your environment
-
-Don't paste the token straight into project files. Keep it in an environment
-variable, so your install config carries no secret. How you set it depends on
-your system:
-
-**macOS** (default shell is zsh):
-```bash
-echo 'export GITEA_TOKEN=paste_your_token_here' >> ~/.zshrc
-source ~/.zshrc
-```
-
-**Linux / Ubuntu** (default shell is bash):
-```bash
-echo 'export GITEA_TOKEN=paste_your_token_here' >> ~/.bashrc
-source ~/.bashrc
-```
-
-**Windows (PowerShell)** — set it permanently for your user, then open a new
-terminal so it takes effect:
-```powershell
-setx GITEA_TOKEN "paste_your_token_here"
-```
-
-> On Windows, `setx` writes the variable but does **not** affect the current
-> window — close it and open a new PowerShell for the token to be visible.
-
----
-
 ## Installation
 
-There are two routes. Pick **Route A** if you just want to use the plugin in a
-project — it's faster and versioned. Choose **Route B** only when you need a
-specific, unreleased commit straight from the repository.
+The plugin is published to a **public package registry** on the company Gitea.
+Installing it needs no token — just point the `@intecion` scope at the registry.
 
-### Route A — from the registry (recommended)
-
-The plugin is published to the package registry in Gitea. You pull a ready-built
-package and build nothing locally.
-
-**1. Configure the registry.** Add these two lines to an `.npmrc` file:
+**1. Point the scope at the registry.** Add this line to an `.npmrc` file in your
+project (or to `~/.npmrc` to apply it everywhere):
 
 ```
 @intecion:registry=https://git.intecion.net/api/packages/IntecionSoftware/npm/
-//git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN}
 ```
 
-You can put this file **in the project directory** (applies to that project) or
-**globally** (applies everywhere). The global location differs by system:
-
-| System | Global `.npmrc` path |
-|---|---|
-| macOS | `~/.npmrc` (i.e. `/Users/you/.npmrc`) |
-| Linux / Ubuntu | `~/.npmrc` (i.e. `/home/you/.npmrc`) |
-| Windows | `%USERPROFILE%\.npmrc` (i.e. `C:\Users\you\.npmrc`) |
-
-Fastest way to create the global file:
-
-```bash
-# macOS / Linux
-npm config set @intecion:registry https://git.intecion.net/api/packages/IntecionSoftware/npm/
-```
-```powershell
-# Windows (PowerShell) — same command, npm handles the path
-npm config set @intecion:registry https://git.intecion.net/api/packages/IntecionSoftware/npm/
-```
-
-Then add the auth line manually (npm config doesn't set tokens with variables).
-Because the token lives in the `${GITEA_TOKEN}` variable, the file holds no
-secret — you can safely commit a project-level `.npmrc`.
-
-> **Windows note:** the `${GITEA_TOKEN}` syntax in `.npmrc` is expanded by npm/pnpm
-> itself, not by the shell — so it works the same on Windows as on macOS/Linux,
-> as long as you set the variable with `setx` (see above).
+Only packages starting with `@intecion/` go to Gitea. Everything else
+(`react`, `next`, `@payloadcms/*`, …) still comes from the public npm registry —
+this line is a scoped override, not a change of your default registry. The file
+holds no secret, so you can commit it (and you should — your deployment needs it
+too).
 
 **2. Install:**
 
@@ -111,28 +35,25 @@ secret — you can safely commit a project-level `.npmrc`.
 pnpm add @intecion/ipal-kit
 ```
 
-### Route B — straight from the repository
+That's it. No token, no login — the registry is public for reads.
 
-pnpm clones the repository and uses the pre-built output. There's no `gitea:`
-shorthand — give the full address.
+### Why the registry, not a git install
 
-Over HTTPS with your token:
+You *can* install straight from the repo
+(`pnpm add git+https://git.intecion.net/IntecionSoftware/ipal-kit.git`), and for a
+quick throwaway test it works. But prefer the registry for real projects:
 
-```bash
-pnpm add git+https://$GITEA_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git
-```
+- **Client components resolve correctly.** A git install unpacks into a
+  commit-hashed path (`.pnpm/@intecion+ipal-kit@git+https…#hash/…`) that breaks
+  Next.js's React Client Manifest — the consent banner, analytics, and Turnstile
+  components fail at runtime with "Could not find the module … in the React
+  Client Manifest". The registry unpacks to a clean `node_modules/@intecion/…`
+  path, so this doesn't happen.
+- **Versioning.** `pnpm` sees a real version number, so a version bump cleanly
+  replaces the old one — no cache-clearing dance.
 
-Or over SSH, if you have a key added in Gitea:
-
-```bash
-pnpm add git+ssh://git@git.intecion.net:IntecionSoftware/ipal-kit.git
-```
-
-Append a specific version after `#` to pin to a release:
-
-```bash
-pnpm add git+https://$GITEA_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git#v1.0.0
-```
+Keep the git install only for pulling a specific unreleased commit during
+plugin development.
 
 ---
 
@@ -146,6 +67,10 @@ pnpm add @payloadcms/plugin-seo@3.84.1 @payloadcms/plugin-form-builder@3.84.1 \
          nodemailer lucide-react slugify server-only
 ```
 
+> **Match `lucide-react` to the plugin.** The plugin uses `lucide-react@^0.400.0`.
+> If your project pulls a different major (e.g. `1.x`), you end up with two copies
+> and confusing type errors. Pin your project to the same range.
+
 From here, the guide takes over: **[docs/getting-started.md](./docs/getting-started.md)** —
 from an empty project to a working site.
 
@@ -153,16 +78,25 @@ from an empty project to a working site.
 
 ## Publishing a new version
 
-This section only applies if you develop the plugin itself and publish new
-versions. You'll need a token with the `write:package` scope.
+This section applies only if you develop the plugin itself. Publishing (unlike
+installing) **does** need a token, with the `write:package` scope.
 
-In `~/.npmrc`:
+In `~/.npmrc` (path differs per OS — see the table below):
 
 ```
 //git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN}
 ```
 
-Build, bump the version number, publish:
+Generate the token in Gitea → **Settings → Applications → Generate New Token**,
+scope `write:package`. Put it in the `GITEA_TOKEN` env var.
+
+| System | Global `.npmrc` path |
+|---|---|
+| macOS | `~/.npmrc` |
+| Linux / Ubuntu | `~/.npmrc` |
+| Windows | `%USERPROFILE%\.npmrc` |
+
+Then build and publish:
 
 ```bash
 pnpm clean && pnpm build
@@ -170,8 +104,7 @@ npm version patch          # 1.0.0 → 1.0.1
 npm publish
 ```
 
-Bump the version on every release — that way pnpm always sees the new package and
-nobody gets stuck on a stale one from the cache.
+Full checklist and troubleshooting: **[docs/publishing.md](./docs/publishing.md)**.
 
 ---
 
@@ -189,11 +122,10 @@ Everything lives in the **[docs/](./docs)** directory. To get started:
 
 | What you see | What's wrong |
 |---|---|
-| `404` or `Unauthorized` on `pnpm add @intecion/...` | no token in `.npmrc`, a wrong token, or you don't have access to the organization in Gitea |
-| `404` when installing from the `.git` address | you're not signed in, the token is missing from the address, or you lack access to the repository |
-| `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` | an attempt to build on install from git — report it to whoever publishes the plugin |
-| old code after reinstalling | cache: run `pnpm store prune`, then remove `.next` and `node_modules/@intecion` |
+| `404` on `pnpm add @intecion/...` | the `@intecion:registry` line is missing from `.npmrc` — the install went to public npm instead of Gitea |
+| `Could not find the module … in the React Client Manifest` | installed from git, not the registry — reinstall from the registry (clean path) |
+| two versions of `lucide-react` | your project pins a different major than the plugin's `^0.400.0` — align them |
+| `missing secret key … to secure Payload` | `PAYLOAD_SECRET` isn't set in the runtime environment (not a plugin issue) |
 
-If you get stuck, check the troubleshooting table above, see
-**[docs/publishing.md](./docs/publishing.md)** for distribution issues, or message
-the team that maintains the plugin.
\ No newline at end of file
+If you get stuck, see **[docs/publishing.md](./docs/publishing.md)** or message the
+team that maintains the plugin.
\ No newline at end of file
diff --git a/docs/README.md b/docs/README.md
index ad3b491..c7d9920 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -95,7 +95,7 @@ export default buildConfig({
 | `@intecion/ipal-kit/server` | runtime server-only (sendEmail, verifyTurnstile, submitForm) | Server Actions / route handlers |
 | `@intecion/ipal-kit/client` | komponenty client (consent, Turnstile, Analytics) | `'use client'` |
 | `@intecion/ipal-kit/rsc` | RenderBlocks (RSC) | server component |
-| `@intecion/ipal-kit/next/middleware` | locale middleware | middleware.ts / proxy.ts |
+| `@intecion/ipal-kit/next/middleware` | locale middleware (import bez zmian) | `proxy.ts` (Next 16; dawniej `middleware.ts`) |
 
 ## Moduły
 
@@ -118,6 +118,8 @@ export default buildConfig({
 Nowy projekt krok po kroku: [getting-started.md](./getting-started.md)
 Referencja wdrożenia frontu: [frontend-setup.md](./frontend-setup.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)
 
 ## Zasady dla wszystkich modułów
 
diff --git a/docs/dev/gitea-commands.md b/docs/dev/gitea-commands.md
new file mode 100644
index 0000000..97813b0
--- /dev/null
+++ b/docs/dev/gitea-commands.md
@@ -0,0 +1,86 @@
+# Jak komendy rozmawiają z git.intecion.net
+
+Ten plik tłumaczy, co robi każda komenda, gdy instalujesz `@intecion/ipal-kit`.
+Rejestr pakietów jest **publiczny do odczytu** — instalacja nie wymaga tokenu.
+Token jest potrzebny tylko przy publikowaniu nowych wersji (patrz
+[publishing.md](./publishing.md)).
+
+## Rejestr scoped — co to znaczy
+
+W `.npmrc` masz jedną linię:
+
+```
+@intecion:registry=https://git.intecion.net/api/packages/IntecionSoftware/npm/
+```
+
+To reguła: „pakiety zaczynające się od `@intecion/` pobieraj z tego adresu".
+**Nie zmienia** domyślnego rejestru — wszystko inne (`react`, `next`,
+`@payloadcms/*`) dalej idzie z publicznego npm. To override dla jednego scope,
+nie przełączenie całego źródła.
+
+Dlatego mieszana instalacja działa bez konfliktu:
+- `@intecion/ipal-kit` → Gitea
+- `react`, `payload`, `lucide-react` → npm
+
+## Komenda po komendzie
+
+### edycja `.npmrc` (linia z registry)
+
+**Co robi:** zapisuje regułę „scope `@intecion` → rejestr Gitea". Nic nie
+pobiera — to plik konfiguracyjny, czytany dopiero przy instalacji.
+
+**Rozmowa z serwerem:** żadna przy samym zapisie.
+
+Ponieważ rejestr jest publiczny, ta linia **nie zawiera tokenu** — plik jest
+bezpieczny do zacommitowania i musi trafić do repo, żeby serwer deploymentu też
+wiedział, skąd brać `@intecion/*`.
+
+### `pnpm add @intecion/ipal-kit`
+
+**Co robi:** to komenda, która faktycznie łączy się z rejestrem.
+
+Krok po kroku:
+1. pnpm widzi scope `@intecion` → sprawdza `.npmrc` → znajduje regułę „→ Gitea".
+2. Łączy się z rejestrem Gitea. Rejestr publiczny, więc **bez tokenu**.
+3. Rejestr odsyła metadane pakietu (wersje, adres `.tgz`).
+4. pnpm pobiera i rozpakowuje do `node_modules/@intecion/ipal-kit` — **czysta
+   ścieżka**, bez hasha commita.
+
+Ta czysta ścieżka jest ważna: komponenty klienta pluginu (baner zgód, analytics,
+Turnstile) rozwiązują się poprawnie tylko z niej. Instalacja z gita dawała
+pokręconą ścieżkę z hashem, która łamała React Client Manifest.
+
+**Gdy to zawiedzie:**
+- `404` — brakuje linii `@intecion:registry` w `.npmrc`, więc pnpm poszedł do
+  publicznego npm, gdzie pakietu nie ma. Sprawdź, czy `.npmrc` istnieje i ma tę
+  linię.
+
+### `pnpm install`
+
+**Co robi:** odtwarza wszystkie zależności z `package.json` / lockfile, w tym
+`@intecion/ipal-kit`. Ta sama rozmowa z Gitea dla części `@intecion`, reszta z
+npm. Różnica względem `add`: `install` odtwarza to, co już zapisane, `add`
+dopisuje nowe.
+
+## Sprawdzenie, czy rejestr odpowiada
+
+Bez tokenu, publiczny endpoint:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}\n" \
+  https://git.intecion.net/api/packages/IntecionSoftware/npm/@intecion%2Fipal-kit
+```
+
+`200` → rejestr działa, pakiet dostępny. `404` → zła ścieżka/nazwa.
+
+## Krótkie podsumowanie
+
+| Komenda | Rozmawia z serwerem? | Token? | Po co |
+|---|---|---|---|
+| edycja `.npmrc` (registry) | nie | nie | reguła scope na później |
+| `pnpm add @intecion/ipal-kit` | tak | nie (publiczny) | pobiera pakiet |
+| `pnpm install` | tak (dla @intecion) | nie | odtwarza zależności |
+| `curl .../npm/@intecion%2F...` | tak | nie | test dostępności |
+
+Publikowanie wersji (osobna rola, **wymaga** tokenu `write:package`):
+[publishing.md](./publishing.md).
\ No newline at end of file
diff --git a/docs/dev/publishing.md b/docs/dev/publishing.md
new file mode 100644
index 0000000..e98bb16
--- /dev/null
+++ b/docs/dev/publishing.md
@@ -0,0 +1,116 @@
+# Wydawanie nowej wersji
+
+
+> **Instalacja jest publiczna** — rejestr Gitea pozwala pobierać pakiety bez
+> tokenu. Ten plik dotyczy **publikowania** nowych wersji, co wymaga tokenu
+> `write:package`. Instrukcja instalacji: główny [README](../README.md).
+
+Dla osób rozwijających samą wtyczkę. Instalacja (dla użytkowników) jest w głównym
+[README](../README.md) — ten plik dotyczy publikowania kolejnych wersji do
+rejestru Gitea.
+
+## package.json — co musi się zgadzać
+
+Przed pierwszą publikacją sprawdź, że manifest jest poprawny — te pola były
+źródłem większości problemów przy dystrybucji:
+
+```json
+{
+  "name": "@intecion/ipal-kit",
+  "version": "1.0.0",
+  "files": ["dist"],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { "...": "wszystkie subpath na ./dist/*.js i ./dist/*.d.ts" },
+  "publishConfig": {
+    "registry": "https://git.intecion.net/api/packages/IntecionSoftware/npm/"
+  }
+}
+```
+
+Kontrola przed publikacją:
+
+```bash
+grep -c '"exports"' package.json          # 1 — jeden blok, nie dwa
+grep -c "git+https.*ipal-kit" package.json # 0 — brak self-reference
+grep '"import"' package.json | head -1     # ./dist/ — nie ./src/
+node -e "JSON.parse(require('fs').readFileSync('package.json','utf8'))" # bez błędu
+```
+
+- **`exports` na `dist`, nie `src`** — jeden blok, wszystkie ścieżki na `./dist/`.
+- **jeden blok `exports`** — nie zostawiaj drugiego (np. w starym
+  `publishConfig.exports`); dwa bloki rozjeżdżają rozwiązywanie modułów.
+- **brak self-reference** — pakiet nie może mieć siebie w `dependencies`.
+  Wchodzi, gdy odpalisz `pnpm add` w katalogu wtyczki — **nigdy tego nie rób**.
+- **peer, nie dependencies** — `payload`, `next`, `react`,
+  `@payloadcms/plugin-seo`, `@payloadcms/plugin-form-builder` w
+  `peerDependencies`. W `dependencies` inaczej zaciągną drugą kopię Payloada.
+
+## Rejestr — droga zalecana
+
+Rejestr npm w Gitea. Pracownicy pobierają gotowy `dist`, nie budują u siebie.
+
+**Token** z zakresem `write:package` (Gitea → Settings → Applications), w
+globalnym `.npmrc` (ścieżka zależna od systemu — patrz tabela w głównym
+[README](../README.md#route-a--from-the-registry-recommended); na Windows to
+`%USERPROFILE%\.npmrc`):
+
+```
+//git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN}
+```
+
+**Wydanie:**
+
+```bash
+pnpm clean && pnpm build
+npm version patch          # 1.0.0 → 1.0.1 (minor/major wg zmian)
+npm publish
+```
+
+Podnoś wersję przy każdym wydaniu — pnpm rozpoznaje pakiet po numerze, więc nowy
+numer znosi cały cykl czyszczenia pamięci podręcznej, który męczy przy
+zostawaniu na jednej wersji.
+
+## Alternatywa — dystrybucja z repozytorium (bez rejestru)
+
+Jeśli nie publikujesz do rejestru, a instalujesz bezpośrednio z Gitea
+(`git+https://...`), obowiązują dodatkowe reguły:
+
+- **`dist/` musi być zacommitowany** w repozytorium — instalacja z git nie
+  buduje pakietu. Buduj i commituj `dist` przed każdym wydaniem:
+  ```bash
+  pnpm build
+  git add -f dist/          # -f, jeśli .gitignore normalnie ignoruje dist
+  git commit -m "build dist"
+  git push
+  ```
+- **BRAK `prepare: pnpm build`** w package.json — inaczej pnpm próbuje budować
+  przy instalacji i żąda `onlyBuiltDependencies`.
+- **sprawdzaj repozytorium, nie plik lokalny** — pnpm z git bierze stan repo:
+  ```bash
+  git show origin/main:package.json | grep '"import"' | head -1   # ./dist/
+  ```
+  Commit z nazwą „fix" nie znaczy, że poprawka jest w commicie.
+
+## Weryfikacja po publikacji
+
+W czystym projekcie testowym:
+
+```bash
+pnpm store prune
+pnpm add @intecion/ipal-kit          # albo git+https://... dla drogi repo
+node -e "console.log(require.resolve('@intecion/ipal-kit/next/middleware'))"
+```
+
+Ostatnia komenda ma wypisać ścieżkę do `dist/exports/next-middleware.js` — nie
+błąd. Jeśli pokazuje `src/...ts`, główny `exports` wskazuje źródła zamiast builda.
+
+## Diagnostyka
+
+| Objaw | Przyczyna |
+|---|---|
+| `Cannot find module .../src/...ts` | główny `exports` na `src`; przy instalacji z git `publishConfig` jest ignorowane |
+| Turbopack „Module not found" mimo pliku na dysku | dwa bloki `exports`; Node bierze zły |
+| `ENOENT ...ipal-kit.tgz` | self-reference w `dependencies` |
+| `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` | `prepare` w package.json (droga repo) |
+| stary kod mimo reinstall | pamięć podręczna; podnieś wersję albo `pnpm store prune` + `rm -rf .next node_modules/@intecion` |
\ No newline at end of file
diff --git a/docs/frontend-setup.md b/docs/frontend-setup.md
index ae45bf7..4685769 100644
--- a/docs/frontend-setup.md
+++ b/docs/frontend-setup.md
@@ -91,20 +91,21 @@ export const i18nConfig = {
 } as const   // as const — inaczej TS: locales nie pasuje do niepustej tuple
 ```
 
-Importuj w: payload.config (ipalKit({ i18n: i18nConfig })), middleware.ts.
+Importuj w: payload.config (ipalKit({ i18n: i18nConfig })), proxy.ts.
 Layout może czytać locale z payload config (config.localization.locales) —
 też jedno źródło.
 
-## Middleware
+## Proxy (dawniej middleware)
 
 > **Next 16:** konwencja `middleware.ts` jest deprecated na rzecz `proxy.ts`
 > (plik `proxy.ts`, funkcja `export function proxy`). Logika pluginu bez zmian —
 > `createLocaleMiddleware` działa tak samo, zmienia się tylko nazwa pliku i
-> funkcji po stronie projektu. Na razie `middleware.ts` działa z ostrzeżeniem.
+> funkcji po stronie projektu. Migracja jedną komendą:
+> `npx @next/codemod@canary middleware-to-proxy .`
 
 
 ```ts
-// src/middleware.ts
+// src/proxy.ts
 import { NextResponse } from 'next/server'
 import type { NextRequest } from 'next/server'
 import { createLocaleMiddleware } from '@intecion/ipal-kit/next/middleware'
@@ -112,16 +113,17 @@ import { i18nConfig } from '@/i18n.config'
 
 const localeMiddleware = createLocaleMiddleware({ config: i18nConfig })
 
-export function middleware(request: NextRequest) {
+export function proxy(request: NextRequest) {
   const result = localeMiddleware(request)
   if (result.type === 'next') return NextResponse.next()
   const response = NextResponse.redirect(result.location)
-  response.cookies.set(result.cookie.name, result.cookie.value)
+  // cookie tylko gdy jest zgoda na kategorię functional — inaczej undefined
+  if (result.cookie) response.cookies.set(result.cookie.name, result.cookie.value)
   return response
 }
 
 // matcher MUSI być inline (Next analizuje statycznie, nie wykonuje importów —
-// import DEFAULT_MIDDLEWARE_MATCHER byłby zignorowany → middleware łapie
+// import DEFAULT_MIDDLEWARE_MATCHER byłby zignorowany → proxy łapie
 // /admin /_next /api → 500)
 export const config = {
   matcher: ['/((?!api|admin|_next|.*\\..*).*)'],
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 8865feb..3876d4c 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -187,10 +187,15 @@ export default { plugins: { '@tailwindcss/postcss': {} } }
 niego klasy komponentów pluginu nie powstaną i banner wyrenderuje się goły.
 Ścieżka jest relatywna do pliku CSS.
 
-## 8. Middleware
+## 8. Proxy (dawniej middleware)
+
+> **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 .`
 
 ```ts
-// src/middleware.ts
+// src/proxy.ts
 import { NextResponse } from 'next/server'
 import type { NextRequest } from 'next/server'
 import { createLocaleMiddleware } from '@intecion/ipal-kit/next/middleware'
@@ -198,23 +203,28 @@ import { i18nConfig } from '@/i18n.config'
 
 const localeMiddleware = createLocaleMiddleware({ config: i18nConfig })
 
-export function middleware(request: NextRequest) {
+export function proxy(request: NextRequest) {
   const result = localeMiddleware(request)
   if (result.type === 'next') return NextResponse.next()
 
   const response = NextResponse.redirect(result.location)
-  response.cookies.set(result.cookie.name, result.cookie.value)
+  // cookie tylko gdy jest zgoda na kategorię functional — inaczej undefined
+  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, middleware złapie /admin
+// importów. Importowana stała zostanie zignorowana, proxy złapie /admin
 // i /_next, i wszystko zwróci 500.
 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`.
+
 ## 9. Warstwa dostępu do danych
 
 Next uruchamia `generateMetadata` i komponent strony niezależnie — `cache()`
diff --git a/docs/i18n.md b/docs/i18n.md
index e358639..2794aef 100644
--- a/docs/i18n.md
+++ b/docs/i18n.md
@@ -69,13 +69,18 @@ fallback na `/{locale}` (root), zamiast dead-endu na 404.
 ## Middleware — patrz osobno
 
 Negocjacja locale + redirect na wejściu (`domena.com` → `/pl`) jest w
-`@intecion/ipal-kit/next/middleware`. Zobacz [middleware w tej sekcji](#middleware)
+`@intecion/ipal-kit/next/middleware`. Zobacz [proxy w tej sekcji](#proxy-dawniej-middleware)
 niżej.
 
-## Middleware
+## Proxy (dawniej middleware)
+
+> **Next 16:** plik nazywa się teraz `proxy.ts`, funkcja `proxy`. Import z
+> pluginu (`@intecion/ipal-kit/next/middleware`) bez zmian — to nazwa subpath
+> eksportu, niezależna od nazwy pliku projektu. Migracja:
+> `npx @next/codemod@canary middleware-to-proxy .`
 
 ```ts
-// middleware.ts (projekt klienta) — jedyna logika to podłączenie
+// proxy.ts (projekt klienta) — jedyna logika to podłączenie
 import { NextResponse } from 'next/server'
 import { createLocaleMiddleware, DEFAULT_MIDDLEWARE_MATCHER } from '@intecion/ipal-kit/next/middleware'
 
@@ -85,11 +90,11 @@ const i18nConfig = {
 }
 const localeMiddleware = createLocaleMiddleware({ config: i18nConfig })
 
-export function middleware(req) {
+export function proxy(req) {
   const r = localeMiddleware(req)
   if (r.type === 'next') return NextResponse.next()
   const res = NextResponse.redirect(r.location)
-  res.cookies.set(r.cookie.name, r.cookie.value)
+  if (r.cookie) res.cookies.set(r.cookie.name, r.cookie.value)
   return res
 }