docs: add repository agent guide

AGENTS.md

@@ -0,0 +1,67 @@
+# AGENTS.md
+
+## Projekt
+
+`wtr.` to mobilna PWA pogodowa dla Polski. Pokazuje bieżące pomiary synoptyczne, dane hydrologiczne i ostrzeżenia z publicznego API IMGW oraz oddzielnie oznaczoną prognozę modelową Open-Meteo. Open-Meteo Geocoding służy także do wyszukiwania miejscowości.
+
+Stack: Next.js App Router, React, TypeScript, Tailwind CSS, TanStack Query, Zustand, Framer Motion, Recharts i Lucide React. PWA korzysta z manifestu oraz własnego service workera.
+
+Najważniejsze katalogi:
+
+- `app/` - routing, layout, globalne style i route handlery proxy.
+- `components/` - komponenty pogody, prognozy, hydro, ostrzeżeń, layoutu, UI i stanów ekranu.
+- `hooks/` - hooki TanStack Query.
+- `lib/` - fetchery, normalizacja danych, tłumaczenia, helpery i store Zustand.
+- `types/` - typy danych IMGW, prognozy oraz lokalizacji.
+- `public/` - manifest, service worker i ikony PWA.
+
+## Komendy
+
+Wymagany jest Node.js 20.9 lub nowszy.
+
+```bash
+npm install
+npm run dev
+npm run lint
+npm run build
+npm run start
+```
+
+Repozytorium nie ma obecnie skryptu testów, osobnego skryptu type-check ani formattera. `npm run build` uruchamia kontrolę TypeScript wykonywaną przez Next.js. Nie opisuj ani nie uruchamiaj nieistniejących komend jako standardowego workflow.
+
+## Konwencje kodu
+
+- Używaj TypeScript konsekwentnie i importów absolutnych `@/...`.
+- Komponenty i typy nazywaj `PascalCase`, funkcje oraz hooki `camelCase`; hooki zaczynają się od `use`.
+- Trzymaj routing w `app/`, komponenty funkcjonalne w odpowiednim podkatalogu `components/`, zapytania Query w `hooks/`, fetchery i normalizację w `lib/`, a typy danych w `types/`.
+- Dodawaj `"use client"` tylko tam, gdzie komponent lub moduł korzysta z hooków, stanu przeglądarki albo interakcji.
+- Dane zewnętrzne pobieraj przez route handlery Next.js. Nie omijaj allowlisty w `app/api/imgw/[...path]/route.ts`.
+- Traktuj IMGW jako źródło bieżących pomiarów, hydro i ostrzeżeń. Prognozę Open-Meteo pokazuj oddzielnie jako prognozę modelową. Nie generuj fikcyjnych danych ani nie przedstawiaj prognozy jako pomiaru IMGW.
+- Normalizuj zewnętrzne odpowiedzi i obsługuj `null`, puste pola oraz błędne wartości. Brak danych pokazuj jawnie zamiast uzupełniać estymacją.
+- Dla pobierania danych używaj TanStack Query z sensownym `queryKey`, cache i retry. W UI zachowuj loading, error, retry oraz empty states.
+- Teksty interfejsu dodawaj równolegle po polsku i angielsku w `lib/i18n.tsx`. Nazw stacji i treści IMGW nie tłumacz automatycznie.
+- Trwałe preferencje użytkownika zapisuj przez istniejący store Zustand w `lib/store.ts` lub istniejące klucze `localStorage`.
+- Zachowuj mobile-first UI, dostępność klawiatury, `aria-label`, focus states oraz spokojny styl glassmorphism.
+- Nie edytuj ręcznie `next-env.d.ts`; plik jest generowany przez Next.js.
+
+Obsługa błędów:
+
+- Route handlery zwracają kontrolowane odpowiedzi JSON z kodem HTTP.
+- Fetchery w `lib/` rzucają `Error`, a komponenty prezentują czytelny stan błędu i retry.
+- Projekt nie ma warstwy logowania aplikacyjnego. Nie dodawaj przypadkowych `console.log`.
+
+## Instrukcje dla agenta
+
+- Przed zmianą przeczytaj pliki w obszarze funkcji i sprawdź `git status`.
+- Utrzymuj mały zakres zmian. Nie refaktoruj niezwiązanych modułów i nie cofaj cudzych zmian.
+- Nie dodawaj mocków jako źródła danych pogodowych. Przy zmianie źródeł API zaktualizuj route handler, typy, normalizację, UI i README.
+- Przy zmianach PWA sprawdź spójność `public/manifest.json`, `public/sw.js` i rejestracji service workera.
+- Przed zakończeniem uruchom co najmniej `npm run lint` i `npm run build`. Jeśli dodano testy, uruchom także ich skrypt.
+- Sprawdź `git diff --check` oraz `git status`. Nie commituj wygenerowanego churnu w `next-env.d.ts`.
+- Ważne decyzje o źródłach danych, ograniczeniach API, uruchamianiu i wdrożeniu dokumentuj krótko w `README.md`.
+
+## Utrzymywanie pliku
+
+Aktualizuj `AGENTS.md` w tej samej zmianie, gdy zmieniają się: struktura projektu, komendy, konwencje, zależności, sposób uruchamiania, testowania lub istotne decyzje architektoniczne.
+
+Jeśli ten plik jest nieaktualny, niepełny albo sprzeczny z kodem, popraw go zamiast ślepo go przestrzegać. Zachowuj go krótkim i praktycznym: bez historii czatu, dziennika zmian i ogólnych porad niezwiązanych z repozytorium.