This is the full developer documentation for Sportigio
# Baza wiedzy Sportigio
> Scenariusze krok po kroku dla klubu. Każdy opisany w panelu i przez API, sprawdzony na klubie demo.
## Wybierz obszar
[Dział zatytułowany „Wybierz obszar”](#wybierz-obszar)
[Strona WWWPublikacja, wygląd, strona główna z sekcji, menu i podstrony.6 scenariuszy](/website/publish/)[SponsorzyKategorie sponsorów, logotypy, kolejność i podstrona partnerów.1 scenariusz](/content/sponsors/)[SklepZamówienia, maile do kupujących, wiadomości do wielu kupujących i VAT.4 scenariusze](/earn/store-orders/)
Sprzedaż biletówWydarzenie, rodzaje biletów, plan miejsc, karnety i skanowanie.W przygotowaniu
AkademiaNabór, grupy treningowe, składki, zgody i portal rodzica.W przygotowaniu
Pakiety wsparciaPakiety członkowskie (subskrypcje), portal wspierającego i zbiórki.W przygotowaniu
## Zacznij tutaj
[Dział zatytułowany „Zacznij tutaj”](#zacznij-tutaj)
[Pierwsze kroki w panelu](/getting-started/first-steps/)Logowanie, nazwa klubu, logo, kolory, media społecznościowe.
[Jak korzystać z tej bazy](/getting-started/how-to-use/)Układ stron, oznaczenia planów, ścieżki w panelu, sekcja dla agentów AI.
[Dodaj pierwszą aktualność](/content/news/)Artykuł z okładką, przypięcie do slidera, galeria i wideo.
[Podłącz asystenta AI do klubu](/getting-started/connect-ai/)Claude Code, Codex i Cursor przez MCP oraz zakres integracji ChatGPT.
## Dla agentów AI
[Dział zatytułowany „Dla agentów AI”](#dla-agentów-ai)
Ta baza jest też źródłem dla agenta AI Sportigio i dla narzędzi MCP. Mapa “use case → narzędzie” i zasady pracy: [Dla agentów AI](/for-agents/overview/). Cały tekst bazy w jednym pliku dla modeli: [`/llms-full.txt`](/llms-full.txt).
# Dodaj mecze i wyniki
> Liga, sezon, rywale z herbami, terminarz, wpisywanie wyników, Centrum Meczowe i linki do biletów lub transmisji.
* Scenariusz
UC-008
* Plan
każdy; synchronizacja z API rozgrywek zależnie od dyscypliny i planu
* Czas
20 minut na pierwszy terminarz
## Cel
[Dział zatytułowany „Cel”](#cel)
Kibic widzi terminarz, ostatni wynik i odliczanie do najbliższego meczu na stronie, w profilu i w mailach, a klub wpisuje wynik w minutę po meczu.
## Zanim zaczniesz
[Dział zatytułowany „Zanim zaczniesz”](#zanim-zaczniesz)
* Dyscyplina ustawiona w [Pierwszych krokach](/getting-started/first-steps/).
* Lista rywali z herbami (PNG) i terminarz z datami, godzinami i miejscem.
* Nowy klub ma już jedną ligę, jeden własny klub i jeden sezon. Zmień ich nazwy zamiast tworzyć nowe.
## Krok po kroku w panelu
[Dział zatytułowany „Krok po kroku w panelu”](#krok-po-kroku-w-panelu)
1. Otwórz **Treści > Mecze** (`/app/games`). Zakładki: **Przegląd** (najbliższy i ostatni mecz, forma), **Terminarz**, **Wyniki**, **Ustawienia**.
2. W **Ustawienia > Ligi** wejdź w kartę ligi: nazwij ją (np. “IV liga, gr. mazowiecka”), ustaw sezon, opcjonalnie adres tabeli albo synchronizację z API rozgrywek.
3. W tej samej karcie sekcja **Rywale**: dodaj przeciwników i wgraj ich herby. To jedyne miejsce na rywali - nie ma osobnej zakładki “Kluby”.
4. Wróć do **Mecze** i kliknij **+ Dodaj Mecz**: gospodarz, gość, data i godzina, kolejka, miejsce, liga i sezon.
5. Po meczu na karcie w **Przegląd** kliknij **Popraw wynik** albo wejdź w **Centrum Meczowe**: wynik, status (zaplanowany, trwa, zakończony, przełożony, anulowany), opis, skład, wydarzenia meczowe.
6. **Linki** przy meczu: bilety, transmisja, relacja, galeria - pokazują się na karcie meczu na stronie. **Udostępnij** daje grafikę i link, **Zmień datę** przekłada spotkanie.
## Efekt
[Dział zatytułowany „Efekt”](#efekt)
* Sekcja **Mecze** na stronie głównej pokazuje ostatnie wyniki i nadchodzące spotkania z herbami rywali.
* Podstrony `/games` (terminarz), wyniki i tabela ligowa działają z menu.
* Kibic dodaje mecz do kalendarza Google, Apple albo pliku ICS z karty meczu.
* Najbliższy mecz pojawia się na Pulpicie panelu z odliczaniem.
## Przez API / MCP
[Dział zatytułowany „Przez API / MCP”](#przez-api--mcp)
| Krok | Narzędzie |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Własne drużyny i rywale | `list_clubs` (`is_my_team` oznacza własne) |
| Nowy rywal | `create_club {name, color?, logo_url?, league_id?}` |
| Herb rywala albo własnego klubu | `update_club {id, logo_url}` |
| Nowy mecz | `create_game {home_id, guest_id, date_time "Y-m-d H:i:s", league_id, season_id, round?, venue?}` |
| Wynik i status | `update_game {id, points_home, points_guest, status}` (`2` = zakończony, `91` = przełożony, `92` = anulowany) |
| Linki na karcie meczu | `save_game_link`, `list_game_links`, `delete_game_link` |
| Tabela ligowa | `get_standings` |
| Fakty przed napisaniem zapowiedzi | `get_game_context {id}` |
| Import terminarza z API rozgrywek | `search_games_api` → `configure_games_sync` |
Terminarz, o który pyta kibic (“najbliższy mecz”): `list_games {scope: "upcoming"}`. Nigdy nie podawaj nazwy własnego klubu w `search` - wynik będzie pusty.
## Pułapki
[Dział zatytułowany „Pułapki”](#pułapki)
* **Bez rywala nie dodasz meczu.** Rywal musi istnieć w lidze przed spotkaniem.
* **Rywal bez herbu dostaje kolorowy placeholder z inicjałami** - lepsze niż pusty kwadrat, ale herb warto dodać, bo pokazuje się na kartach, w sliderze i w grafikach do udostępnienia.
* **Status “zakończony” trzeba ustawić.** Sam wynik bez statusu zostawia mecz jako zaplanowany w części widoków.
* Data w API to zawsze `Y-m-d H:i:s` w strefie klubu.
* Synchronizacja z API rozgrywek działa dla wybranych dyscyplin i lig; ręczny terminarz działa zawsze.
## Zobacz też
[Dział zatytułowany „Zobacz też”](#zobacz-też)
* [Dodaj kadrę](/content/squad/)
* [Dodaj aktualność](/content/news/) (zapowiedzi i relacje z `game_id`)
* [Ułóż stronę główną z sekcji](/website/homepage-sections/)
# Dodaj aktualność
> Artykuł, galeria lub wideo z okładką, tagami, przypięciem do slidera i planowaną publikacją.
* Scenariusz
UC-007
* Plan
każdy; auto-tagowanie AI i filtry tagów od PRO
* Czas
10 minut
## Cel
[Dział zatytułowany „Cel”](#cel)
Klub publikuje wpis z okładką, który pojawia się w sekcji aktualności, w sliderze na górze strony i w profilu, bez zależności od algorytmu Facebooka.
## Zanim zaczniesz
[Dział zatytułowany „Zanim zaczniesz”](#zanim-zaczniesz)
* Tytuł i kilka akapitów treści. Jedna myśl na akapit.
* Okładka pozioma (16:9). Zdjęcie pionowe zostanie wpasowane z rozmytym tłem.
* Dla wideo: link do YouTube. Dla galerii: zdjęcia z dysku.
## Krok po kroku w panelu
[Dział zatytułowany „Krok po kroku w panelu”](#krok-po-kroku-w-panelu)
1. Otwórz **Treści > Aktualności** (`/app/posts`). Zakładki: **Wszystkie**, **Przypięte** (slider), **Zaplanowane**, **Analiza** (odsłony).
2. Kliknij **+ Dodaj post** albo kafel **Nowy Post**.
3. Wybierz typ: artykuł, galeria, wideo. Można je łączyć w jednym wpisie.
4. Wpisz tytuł, krótki opis (zajawka na kartach) i treść. **Redaktor AI** w prawej kolumnie pomaga napisać albo skrócić tekst.
5. Wgraj **okładkę**. Wpis o konkretnym meczu może dostać okładkę z herbami obu drużyn generowaną automatycznie.
6. Dodaj **tagi** (segmentacja i filtry na stronie od PRO).
7. Ustaw datę publikacji, jeśli wpis ma wyjść później - trafi do **Zaplanowane**.
8. Zapisz. Na karcie wpisu ikona **gwiazdki** przypina wpis do slidera na stronie głównej; kolejność przypiętych ustawiasz w zakładce **Przypięte**.
## Efekt
[Dział zatytułowany „Efekt”](#efekt)
* Wpis jest w sekcji **Aktualności** na stronie głównej i na liście `/posts`.
* Przypięty wpis pokazuje się w sliderze (jeśli slider jest włączony w [ustawieniach wyglądu](/website/appearance/)).
* Kibic może udostępnić wpis; licznik odsłon jest w **Analiza**.
## Przez API / MCP
[Dział zatytułowany „Przez API / MCP”](#przez-api--mcp)
| Krok | Narzędzie |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Lista wpisów | `list_posts` |
| Nowy wpis | `create_post {title, content (HTML), photo_url?, video_url?, gallery_image_urls?, tag_ids?, pinned?, hero_order?, created_at?, visibility?}` |
| Okładka z herbami dla wpisu o meczu | `create_post {..., game_id}` (zamiast `photo_url`) |
| Edycja, przypięcie, zmiana okładki | `update_post {id, ...}` |
| Kolejność slidera | `reorder_pinned_posts {ids}` |
| Fakty do zapowiedzi lub relacji z meczu | `get_game_context {id}` |
| Post z Facebooka jako materiał | `list_facebook_posts` → `get_facebook_post {id}` |
| Tagi klubu | `list_tags` |
Wpis bez `photo_url` i `game_id` dostaje domyślną okładkę w barwach klubu. `created_at` w przyszłości = wpis zaplanowany.
## Pułapki
[Dział zatytułowany „Pułapki”](#pułapki)
* **Slider to przypięte wpisy, nie najnowsze.** Bez gwiazdki slider jest pusty.
* **Okładka z adresu URL musi być publiczna (https).** Adres prywatny albo lokalny jest odrzucany po cichu i wpis dostaje okładkę domyślną.
* Pełnowymiarowe zdjęcia z Facebooka bywają za duże do importu; wybierz mniejszy wariant.
* **Aktualności** i **Lista postów** na jednej stronie głównej dublują wpis.
* Widoczność “członkowie” bez aktywnych pakietów pokazuje wszystkim zajawkę.
## Zobacz też
[Dział zatytułowany „Zobacz też”](#zobacz-też)
* [Ułóż stronę główną z sekcji](/website/homepage-sections/)
* [Dodaj mecze i wyniki](/content/matches/)
# Dodaj sponsora
> Kategorie sponsorów, logotypy, kolejność, sekcja Sponsorzy na stronie, podstrona partnerów i logotypy w nagłówku.
* Scenariusz
UC-010
* Plan
każdy; logotypy w nagłówku strony od PRO
* Czas
15 minut
## Cel
[Dział zatytułowany „Cel”](#cel)
Sponsorzy widzą swoje logo na stronie klubu w kolejności, którą ustala klub, a sponsor główny jest wyraźnie większy.
## Zanim zaczniesz
[Dział zatytułowany „Zanim zaczniesz”](#zanim-zaczniesz)
* Logotypy w PNG z przezroczystym tłem, w poziomym formacie (szerokość większa od wysokości). Loga w JPG z białym tłem będą białymi prostokątami na kolorowym tle.
* Podział na kategorie, np. Sponsor główny, Partnerzy, Partnerzy medialni.
## Krok po kroku w panelu
[Dział zatytułowany „Krok po kroku w panelu”](#krok-po-kroku-w-panelu)
1. Otwórz **Treści > Sponsorzy** (`/app/sponsors`). Zakładki: **Sponsorzy** i **Kategorie**.
2. W **Kategorie** dodaj kategorie w kolejności, w jakiej mają się wyświetlać. Każda ma **wysokość wiersza logotypów** (sponsor główny wyższy) i przełącznik **pokazuj na stronie**.
3. Wróć do **Sponsorzy** i kliknij **+ Nowy Sponsor** albo kafel **DODAJ** w kategorii: nazwa, kategoria, logo, adres strony sponsora, krótki opis (widoczny w układzie z listą i w Klubie Biznesu).
4. Zapisz. **Edytuj kolejność** przy nazwie kategorii układa loga w jej obrębie.
5. Dodaj sekcję **Sponsorzy** na stronie głównej ([sekcje](/website/homepage-sections/)): układ `cards` (kafle), `plain` (same loga), `wall` (gęsta ściana) albo `list` (wiersze z opisem), z nazwami kategorii albo bez.
6. Od PRO: karta **Logotypy w nagłówku strony > Zarządzaj** pokazuje wybrane loga w prawym górnym rogu każdego układu nagłówka.
## Efekt
[Dział zatytułowany „Efekt”](#efekt)
* Sekcja **Sponsorzy** na stronie głównej i podstrona `/sponsors` pokazują loga według kategorii, z linkami do stron sponsorów.
* Sponsor główny jest w osobnym, wyższym wierszu.
* Loga pojawiają się też w profilu klubu i w stopce, zależnie od układu.
## Przez API / MCP
[Dział zatytułowany „Przez API / MCP”](#przez-api--mcp)
| Krok | Narzędzie |
| ---------------------------------- | ------------------------------------------------------------------------------------------- |
| Kategorie | `list_sponsor_categories`, `create_sponsor_category {name, height?, show_on_website?}` |
| Nowy sponsor | `create_sponsor {name, category_id, logo_url, url?, about?}` |
| Lista i kolejność | `list_sponsors`, `reorder_sponsors {ids}`, `reorder_sponsor_categories {ids}` |
| Edycja i usunięcie | `update_sponsor`, `delete_sponsor` |
| Sekcja na stronie głównej | `create_page_block {content_type: "sponsors", layout, category_ids?, show_category_names?}` |
| Podstrona partnerów jednym krokiem | `create_sponsors_page` |
| Logotypy w nagłówku (PRO) | `get_header_partner_logos`, `update_header_partner_logos {enabled, size, items}` |
Logo z `logo_url` musi być publicznym adresem https; z dysku wgrywasz przez `POST /api/v1/uploads` i podajesz zwrócony `url`.
## Pułapki
[Dział zatytułowany „Pułapki”](#pułapki)
* **Kolejność kategorii to kolejność ich utworzenia.** Załóż je od najważniejszej.
* **Kategoria z wyłączonym “pokazuj na stronie”** nie wchodzi do domyślnej sekcji; żeby ją pokazać, wskaż ją jawnie w `category_ids` sekcji.
* Logo w JPG z białym tłem psuje każdy układ na kolorowym tle. Proś sponsora o PNG lub SVG.
* Zbyt wysoki wiersz dla małych logotypów rozciąga je i rozmywa.
## Zobacz też
[Dział zatytułowany „Zobacz też”](#zobacz-też)
* [Ułóż stronę główną z sekcji](/website/homepage-sections/)
* [Dodaj podstronę](/website/subpages/) (np. “Zostań sponsorem”)
# Dodaj kadrę
> Zawodnicy i sztab, numery, pozycje, drużyny w sezonie, zdjęcia profilowe i sekcja Kadra na stronie.
* Scenariusz
UC-009
* Plan
każdy; zakładki drużyn w sekcji Kadra od PRO
* Czas
20 minut na drużynę
## Cel
[Dział zatytułowany „Cel”](#cel)
Strona pokazuje aktualny skład z numerami, pozycjami i zdjęciami, a sztab jest osobno od zawodników.
## Zanim zaczniesz
[Dział zatytułowany „Zanim zaczniesz”](#zanim-zaczniesz)
* Lista zawodników: imię, nazwisko, numer, pozycja. Lista sztabu: imię, nazwisko, rola.
* Zdjęcia profilowe, najlepiej popiersia na jednolitym tle. Zdjęcie jest kadrowane do kwadratu z twarzą pośrodku.
* Pozycje dla dyscypliny (**Treści > Skład > Ustawienia**): każdy klub ma własną listę, np. Bramkarz, Obrońca, Pomocnik, Napastnik; role sztabu są osobną listą.
## Krok po kroku w panelu
[Dział zatytułowany „Krok po kroku w panelu”](#krok-po-kroku-w-panelu)
1. Otwórz **Treści > Skład** (`/app/players`). Zakładki: **Skład**, **Drużyny**, **Ustawienia**.
2. W **Ustawienia** sprawdź listę pozycji i ról sztabu. Dodaj brakujące (np. “Pomocnik”).
3. W **Drużyny** upewnij się, że jest drużyna, do której przypiszesz osoby. Nowy klub ma jedną własną drużynę; przy kilku grupach wiekowych dodaj kolejne.
4. Kliknij **+ Dodaj Zawodnika**: typ (zawodnik lub sztab), imię, nazwisko, numer (tylko zawodnik), pozycja albo rola, drużyna, data urodzenia, wzrost, waga, opis, zdjęcie.
5. Zapisz. Filtry **Wszyscy / Zawodnik / Sztab** i wyszukiwarka porządkują listę; przełącznik po prawej zmienia kafle na listę.
6. Dodaj sekcję **Kadra** na stronie głównej ([sekcje](/website/homepage-sections/)) i pozycję **Zawodnicy** w menu ([menu](/website/menu/)).
## Efekt
[Dział zatytułowany „Efekt”](#efekt)
* Podstrona `/players` pokazuje zawodników według pozycji, sztab osobno, z profilami.
* Sekcja **Kadra** na stronie głównej pokazuje skład wybranej drużyny (na PRO z zakładkami drużyn).
* Profil zawodnika ma zdjęcie, numer, pozycję, opis i statystyki z meczów, jeśli klub je prowadzi.
## Przez API / MCP
[Dział zatytułowany „Przez API / MCP”](#przez-api--mcp)
| Krok | Narzędzie |
| --------------------------------------- | --------------------------------------------------------------------------------------- |
| Pozycje i role sztabu klubu | `get_positions` |
| Własne drużyny | `list_clubs` (`is_my_team: true`) |
| Nowa drużyna | `create_player_team {name}` |
| Nowy zawodnik | `create_player {first_name, last_name, number?, position, club_id?, photo_url?, text?}` |
| Członek sztabu | `create_player {..., type: "staff", position: "Trener"}` |
| Zdjęcie, numer, opis | `update_player {id, photo_url?, number?, text?}` |
| Przynależność do kilku drużyn w sezonie | `set_player_teams {id, team_ids, primary_team_id}`, masowo `bulk_set_player_teams` |
| Usunięcie (trwałe) | `delete_player {id}` |
Nowa nazwa pozycji przekazana w `position` jest automatycznie dodawana do listy klubu. Zdjęcie z `photo_url` musi być publicznym adresem https; z dysku wgrywasz przez `POST /api/v1/uploads`.
## Pułapki
[Dział zatytułowany „Pułapki”](#pułapki)
* **Pusta kadra na stronie, choć zawodnicy są w panelu**: osoby nie są przypisane do domyślnej drużyny albo drużyna nie ma ustawionej kolejności. Sprawdź **Drużyny**.
* **Zdjęcie poziome z całą drużyną** po kadrowaniu do kwadratu pokazuje przypadkowy fragment. Wgrywaj portrety.
* **Usunięcie zawodnika jest trwałe** i zabiera jego wpisy w składach meczowych.
* Sztab nie ma numeru; numer przekazany dla sztabu jest ignorowany.
* Zawodnik może być w kilku drużynach naraz, ale jedna jest główna - to ona decyduje, gdzie pokazuje się w sekcji Kadra.
## Zobacz też
[Dział zatytułowany „Zobacz też”](#zobacz-też)
* [Dodaj mecze i wyniki](/content/matches/)
* [Ułóż stronę główną z sekcji](/website/homepage-sections/)
# Plan i architektura bazy wiedzy
> Dlaczego osobne repo i Starlight, jak baza łączy się z panelem, agentem AI, help center i landingiem, oraz plan rozwoju.
Decyzja z 2026-09-24. Ten dokument jest źródłem prawdy o tym, **gdzie** żyje wiedza o Sportigio i **jak** ma być utrzymywana.
## Problem
[Dział zatytułowany „Problem”](#problem)
Wiedza o produkcie była w czterech miejscach, żadne nie nadawało się dla klubów i agenta naraz:
| Miejsce | Co tam jest | Dlaczego nie wystarcza |
| ------------------------------------------ | --------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `club-web/docs/` (ok. 150 plików) | dokumentacja techniczna po polsku | dla developerów; nazwy klas i tras, sekrety wdrożeniowe, brak wersji EN/DE |
| `club-web/resources/ai/agent-knowledge.md` | mapa panelu dla agenta (`get_platform_guide`) | jeden plik, po polsku, rośnie wolniej niż lista narzędzi |
| `help.sportigio.com` | hostowane centrum pomocy | treść poza gitem, bez dostępu dla agenta, bez kontroli i18n, nie da się aktualizować promptem |
| Landing `get.sportigio.com/poradniki` | 2 poradniki | treść w słownikach TypeScript (plik typów ma 2 tys. linii) - dobre na 2 artykuły, złe na 100 |
## Decyzja
[Dział zatytułowany „Decyzja”](#decyzja)
**Osobne repo `sportigio-docs`** w folderze nadrzędnym firmy, obok `club-web`, `sportigio-founders` i `com-sportigio-get`. Silnik: **Astro Starlight**.
Dlaczego tak, a nie inaczej:
* **Markdown w gicie** - agent (Claude, Codex) aktualizuje bazę tym samym promptem, którym zmienia kod, w tym samym tygodniu. Review przez PR jak w kodzie.
* **Trzy języki bez dopłat** - Starlight ma i18n wbudowane: PL jako root, EN i DE jako lustra pod tą samą ścieżką, automatyczny fallback na polski, przełącznik języka, tłumaczenia UI.
* **Wyszukiwarka i tryb ciemny** z pudełka (Pagefind), zero backendu, statyczny `dist/`.
* **`llms.txt` i `llms-full.txt`** generowane przy buildzie (plugin `starlight-llms-txt`): ta sama treść, którą czyta człowiek, trafia do agenta bez osobnego pliku wiedzy.
* **Deploy na Cloudflare Pages**: push na `main` → Cloudflare → `npm run build` → `dist/` pod `docs.sportigio.com`. Bez GitHub Actions.
* **Koszt zero**. Mintlify i GitBook robią podobne rzeczy za abonament i z treścią pod cudzą kontrolą; Docusaurus i VitePress wymagają więcej własnej konfiguracji i18n.
Odrzucone: rozbudowa `club-web/docs/` (miesza wiedzę dla klubów z wiedzą dla developerów i sekretami), Notion (nie wersjonowane, słabe dla agenta, brak i18n), landing (słowniki TS), help.sportigio.com (poza gitem).
## Jednostka treści: use case
[Dział zatytułowany „Jednostka treści: use case”](#jednostka-treści-use-case)
Klub nie myśli modułami (“PageBlock v6”), tylko celami (“chcę, żeby na stronie były mecze”). Każda strona to jeden cel, z siedmioma stałymi sekcjami ([szablon](/contributing/template/)) i metadanymi we frontmatterze:
```yaml
useCase:
id: UC-004
module: website # website | content | earn | community | academy | business | ai | settings
surfaces: [panel, mcp] # gdzie da się to zrobić
plan: PRO # minimalny plan, jeśli dotyczy
time: 20 min
verified: 2026-09-24 # ostatnie przeklikanie na panelu
sources: [app/...] # pliki w club-web, które są źródłem prawdy
```
Sekcja **Przez API / MCP** jest obowiązkowa. Dzięki temu ta sama strona uczy człowieka klikać i agenta wywoływać narzędzia, a rozjazd między nimi jest widoczny od razu.
## Jak baza łączy się z resztą
[Dział zatytułowany „Jak baza łączy się z resztą”](#jak-baza-łączy-się-z-resztą)
```plaintext
club-web (kod, tests, docs techniczne)
│ zmiana funkcji
▼
skill docs-sync w club-web ──prompt──▶ sportigio-docs (PR) ──push main──▶ docs.sportigio.com
│ │
│ build │ /llms-full.txt
▼ ▼
zrzuty z klubu demo agent AI (get_platform_guide,
Sportigio FC (localhost) AI Center, Claude/Codex z MCP)
```
* **Klub demo Sportigio FC** (`club-web`, `klub1.sportigio.test.localhost`, space 2) to stan odniesienia: każdy use case jest tam przeklikany, zrzuty ekranu pochodzą stamtąd. Reset do zera: **Ustawienia > Zaawansowane > Strefa zagrożenia** (tylko localhost). Odbudowa danych: `build.py` z tej sesji (kolejność w [mapie narzędzi](/for-agents/tool-map/)).
* **help.sportigio.com** zostaje na okres przejściowy jako link w panelu; docelowo `SPORTIGIO_HELP_CENTER` w `club-web/config/sportigio.php` wskazuje na `docs.sportigio.com`.
* **Landing** linkuje do bazy z sekcji Poradniki zamiast trzymać własne artykuły.
## Etapy
[Dział zatytułowany „Etapy”](#etapy)
| Etap | Zakres | Stan |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| 1 | Repo, Starlight, i18n PL/EN/DE, brand, `llms.txt`, 10 use case’ów WWW i treści, mapa dla agentów, szablon i prompt aktualizacji | zrobione 2026-09-24 |
| 2 | Repo na GitHubie, Cloudflare Pages, `docs.sportigio.com` (zrobione 2026-11-02); link z panelu (`help_center`) i z landingu | w toku |
| 3 | Agent czyta bazę: `get_platform_guide` pobiera `/llms-full.txt` (cache 1 h) zamiast `agent-knowledge.md`; import wybranych stron do AI Center jako baza wiedzy publicznych agentów | do zrobienia |
| 4 | Kolejne 30 use case’ów z [backlogu](/contributing/backlog/): zarabianie, kibice, akademia, sponsoring, AI, ustawienia | w toku, po jednym module na tydzień |
| 5 | Kontrola dryfu: skrypt porównujący nazwy narzędzi w bazie z `tools/list` i ścieżki `/app/...` z `route:list`; wynik w CI repo | do zrobienia |
## Zasady utrzymania
[Dział zatytułowany „Zasady utrzymania”](#zasady-utrzymania)
1. Zmiana funkcji w `club-web` = zmiana strony w bazie w tym samym tygodniu ([prompt aktualizacji](/contributing/update-prompt/)).
2. Nowa strona najpierw po polsku, z datą `verified`. EN i DE mogą wejść osobnym PR-em.
3. Zrzuty ekranu tylko z klubu demo, w trybie jasnym, bez paska debugowania i banerów.
4. Nazwy z interfejsu, nie z kodu. Kod zostaje w `sources`.
5. Żadnych liczb i cen z pamięci - tylko z `config/plans.php` albo z produkcji.
# Backlog scenariuszy
> Kolejne use case'y do opisania, pogrupowane działami panelu, z priorytetem według pytań klubów.
Pierwsze dziesięć scenariuszy (UC-001 do UC-010) obejmuje ustawienia, stronę WWW i treści. Poniżej kolejka. Priorytet: **A** = kluby pytają o to w pierwszym tygodniu, **B** = w pierwszym miesiącu, **C** = rzadziej. Numery przydzielaj po kolei przy tworzeniu strony.
## Strona WWW i profil
[Dział zatytułowany „Strona WWW i profil”](#strona-www-i-profil)
| Priorytet | Scenariusz | Folder | Narzędzia MCP |
| --------- | ------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------- |
| A | Uruchom profil klubu (link in bio): linki, baner, następny mecz, QR | `website/` | `get_bio_settings`, `update_bio_settings`, `save_bio_link`, `reorder_bio_links` |
| A | Podepnij własną domenę (DNS, SSL, co robi Sportigio) | `website/` | `report_support_issue` |
| B | Popup promocyjny na stronie (kampania, newsletter, następny mecz) | `website/` | `list_promo_modals`, `create_promo_modal` |
| B | Sekcja “Zdjęcia” i galerie z meczu | `website/` | `create_page_block {photos}`, `create_post {gallery_image_urls}` |
| B | Mini-baza danych i lista na stronie (trenerzy, FAQ, cennik) | `website/` | `create_database`, `add_database_records`, `create_database_page` |
| C | Własny CSS i JS na stronie | `website/` | tylko panel |
| C | Analityka strony: wizyty, kliknięcia, źródła | `website/` | `get_space_stats` |
## Zarabianie
[Dział zatytułowany „Zarabianie”](#zarabianie)
| Priorytet | Scenariusz | Folder | Narzędzia MCP |
| --------- | ----------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------- |
| A | Uruchom konto płatnicze klubu (Stripe, Paymove) | `earn/` | tylko panel |
| A | Sprzedaj bilety na mecz: wydarzenie, rodzaje biletów, plan miejsc, skanowanie | `earn/` | `create_ticket_event`, `create_ticket_type`, `get_ticket_sales`, `create_scanner_link` |
| A | Karnety sezonowe | `earn/` | `create_ticket_type` |
| B | Sklep klubowy: produkt fizyczny, cyfrowy, zamówienia | `earn/` | `create_product`, `list_store_orders`, `update_store_order_status` |
| B | Pakiety członkowskie (Klub 100) i portal wspierającego | `earn/` | `create_membership_tier`, `list_membership_subscribers` |
| B | Zbiórka i strona wsparcia | `earn/` | `create_fundraiser`, `record_donation` |
| B | Kody rabatowe | `earn/` | `create_discount_code` |
| C | Rozliczenia i wypłaty | `earn/` | tylko panel |
## Kibice i komunikacja
[Dział zatytułowany „Kibice i komunikacja”](#kibice-i-komunikacja)
| Priorytet | Scenariusz | Folder | Narzędzia MCP |
| --------- | ---------------------------------------------------- | ------------ | --------------------------------------------------------------------- |
| A | Zbieraj kontakty: formularz, import, tagi, zgody | `community/` | `add_contact`, `tag_contact`, `list_contacts` |
| A | Wyślij newsletter (szkic przez AI, wysyłka w panelu) | `community/` | `create_campaign_draft` |
| B | Automatyczne maile wokół meczu | `community/` | tylko panel |
| B | Strefa Kibica: punkty, questy, eTrybuna na mecz | `community/` | `create_fan_quest`, `attach_game_activity`, `update_fanzone_settings` |
| B | Ankieta z własnym linkiem `/poll/{slug}` | `community/` | `create_voting` |
| B | Quiz i Liga Typera | `community/` | `create_quiz` |
| C | Program lojalnościowy z nagrodami | `community/` | `add_user_points` |
## Akademia
[Dział zatytułowany „Akademia”](#akademia)
| Priorytet | Scenariusz | Folder | Narzędzia MCP |
| --------- | -------------------------------------------- | ---------- | ----------------------------------------------------------------------------- |
| A | Nabór: formularz, pola, zgłoszenia | `academy/` | `create_recruitment`, `add_recruitment_field`, `list_recruitment_submissions` |
| A | Grupy treningowe i harmonogram | `academy/` | `create_training_group`, `create_training_schedule`, `get_academy_schedule` |
| A | Składki: kwoty, przypomnienia, ręczne wpłaty | `academy/` | `get_dues_status`, `send_dues_reminders`, `mark_dues_paid` |
| B | Komunikat do rodziców | `academy/` | `create_academy_announcement` |
| B | Deklaracje i zgody do podpisu online | `academy/` | `create_academy_document`, `send_document_sign_requests` |
| B | Portal rodzica: co widzi rodzic | `academy/` | `get_portal_settings` |
| C | Zajęcia dodatkowe i obozy | `academy/` | `create_activity`, `list_activity_signups` |
## Sponsoring i biznes
[Dział zatytułowany „Sponsoring i biznes”](#sponsoring-i-biznes)
| Priorytet | Scenariusz | Folder | Narzędzia MCP |
| --------- | ----------------------------------------- | ----------- | ----------------------------------------------------------------------------- |
| A | Media kit i oferta reklamowa | `business/` | `get_advertising_offer` |
| B | Inwentarz świadczeń i pakiety sponsorskie | `business/` | `create_sponsorship_asset`, `create_sponsor_package`, `apply_sponsor_package` |
| B | Umowa sponsorska i raport realizacji | `business/` | `create_sponsor_contract`, `get_sponsor_report` |
| B | Wydarzenie biznesowe z RSVP | `business/` | `create_business_event`, `invite_sponsors_to_event` |
| C | Strona Klubu Biznesu | `business/` | `get_business_club_page` |
Uwaga 2026-09-25: folder `business/` jest wciąż pusty, a panel zmienił się (hub BizZone ma blok “Wymaga uwagi”, lista CRM kolumnę i filtr “Umowa”, portal sponsora pokazuje umowę z realizacją i zdjęciami dowodowymi). Przegląd do przepisania na strony klubu: `club-web/docs/platform/bizzone-overview.md`.
## AI, integracje, ustawienia
[Dział zatytułowany „AI, integracje, ustawienia”](#ai-integracje-ustawienia)
| Priorytet | Scenariusz | Folder | Narzędzia MCP |
| --------- | --------------------------------------------- | ----------- | ----------------------------- |
| A | Klucz API i podłączenie MCP do Claude / Codex | `ai/` | tylko panel (`/app/api-keys`) |
| A | Asystent AI w panelu: co umie, jak pytać | `ai/` | `get_platform_guide` |
| B | Publiczny agent AI dla kibiców i rodziców | `ai/` | tylko panel (AI Center) |
| B | Zespół i uprawnienia | `settings/` | tylko panel |
| B | Plan, faktury, zmiana planu | `settings/` | `get_plan_info` |
| C | Webhooki automatyzacji (n8n, Make) | `ai/` | tylko panel |
Dodano UC-011: [Podłącz asystenta AI](/getting-started/connect-ai/), zweryfikowano lokalnie 2026-09-25.
Dodano UC-012 do UC-015 (sklep): [zamówienia](/earn/store-orders/), [maile do kupujących](/earn/store-emails/), [wiadomość do wielu kupujących](/earn/store-message-buyers/), [VAT](/earn/store-vat/), zweryfikowano lokalnie 2026-10-28. Zostaje osobny scenariusz o dodaniu produktu (fizyczny, cyfrowy, warianty).
Dodano UC-016: [Zmień kolejność sekcji na stronie głównej](/website/reorder-homepage-sections/), z nagraniem z lektorem, sprawdzone na produkcji 2026-10-30, lustra EN/DE z polskim nagraniem.
# Szablon use case'a
> Gotowy plik do skopiowania z frontmatterem i siedmioma sekcjami w stałej kolejności.
Skopiuj poniższy plik do właściwego folderu (`getting-started/`, `website/`, `content/`, `earn/`, `community/`, `academy/`, `business/`, `ai/`), nadaj angielską nazwę pliku (`homepage-sections.md`) i wypełnij sekcje w tej kolejności. Sekcje **Efekt** i **Pułapki** pomiń, jeśli nie dodają nic ponad to, co jest wyżej. Pozostałe sekcje zostają zawsze.
```md
---
title:
description:
sidebar:
order:
useCase:
id: UC-
module:
surfaces: [panel, api, mcp]
plan:
time:
verified:
sources:
- <ścieżka w club-web, np. app/Mcp/Tools/SponsorTools.php>
---
- Scenariusz
- UC-
- Plan
- Czas
- <...>
## Cel
## Zanim zaczniesz
-
## Krok po kroku w panelu
1. Otwórz **Dział > Pozycja** (`/app/...`).
2. Kliknij **Nazwa przycisku dokładnie jak w panelu**.
3. ...
## Efekt
-
## Przez API / MCP
| Krok | Narzędzie |
|---|---|
| | `nazwa_narzedzia {najważniejsze pola}` |
## Pułapki
- **** - .
## Zobacz też
- [](///)
```
## Zasady stylu
[Dział zatytułowany „Zasady stylu”](#zasady-stylu)
* Krótkie zdania. Jedna myśl na zdanie. Bez emoji, bez długich pauz (tylko “-”).
* Nazwy przycisków i zakładek **pogrubione**, dokładnie jak w interfejsie po polsku.
* Adresy panelu w nawiasie, w `kodzie`, jako wsparcie.
* Narzędzia MCP w `kodzie`, z nazwami pól, które decydują o wyniku.
* Pułapka to coś, co naprawdę zepsuło się klubowi albo agentowi. Nie wymyślaj.
* Zrzut ekranu z klubu demo, tryb jasny, szerokość 1440 px, bez paska debugowania.
## Wersje językowe
[Dział zatytułowany „Wersje językowe”](#wersje-językowe)
Ten sam plik pod tą samą ścieżką w `src/content/docs/en/` i `src/content/docs/de/`. Tłumacz tytuły, opisy, treść i nazwy przycisków (interfejs klubu ma wersje EN i DE). Nie tłumacz: nazw narzędzi MCP, pól API, ścieżek `/app/...`, nazw plików w `sources`.
# Prompt aktualizacji po zmianie w produkcie
> Gotowy prompt i checklista dla agenta, który po zmianie funkcji w club-web ma zaktualizować bazę wiedzy w trzech językach.
Każda zmiana funkcji w `club-web` wywołuje aktualizację tej bazy. Nie “kiedyś”, tylko w tym samym tygodniu, najlepiej w tym samym PR-ze co kod, jako osobny commit w repo `sportigio-docs`. W `club-web` jest skill `docs-sync`, który prowadzi agenta przez dokładnie ten proces; poniżej ten sam prompt do wklejenia ręcznie.
## Prompt
[Dział zatytułowany „Prompt”](#prompt)
```text
Zmieniliśmy funkcję w club-web. Zaktualizuj bazę wiedzy w repo sportigio-docs.
Co się zmieniło (wklej albo opisz):
Zrób po kolei:
1. Wypisz, których scenariuszy (UC-xxx) dotyczy zmiana. Szukaj po nazwach narzędzi MCP,
ścieżkach /app/... i nazwach zakładek. Jeśli żaden nie pasuje, zaproponuj nowy
scenariusz z contributing/template.md i dodaj go do contributing/backlog.md.
2. Dla każdego scenariusza: przeklikaj zmieniony krok na klubie demo Sportigio FC
(club-web, klub1.sportigio.test.localhost, space 2) albo na produkcji. Nie opisuj
z pamięci. Jeśli zmiana dotyczy narzędzia MCP, wywołaj je i sprawdź wynik odczytem.
3. Zaktualizuj polską stronę: kroki, nazwy przycisków, tabelę "Przez API / MCP", pułapki,
pole verified na dzisiejszą datę, sources na zmienione pliki.
4. Zaktualizuj lustra en/ i de/ pod tą samą ścieżką. Ta sama struktura nagłówków.
Nazwy przycisków po angielsku i niemiecku bierz z resources/lang/{en,de} w club-web,
nie tłumacz ich sam.
5. Jeśli zmieniły się zrzuty ekranu: zrób nowe z klubu demo (tryb jasny, 1440 px, bez
paska debugowania i banerów) i podmień pliki w src/assets/screens/.
6. Jeśli zmiana dotyczy narzędzi MCP, zaktualizuj for-agents/tool-map.md (PL/EN/DE).
7. npm run build w sportigio-docs. Build musi przejść.
8. Podsumuj w trzech zdaniach: co zmieniłeś, które strony, co zostało do zrobienia
(np. zrzut, którego nie dało się zrobić).
Reguły: AGENTS.md w sportigio-docs. Krótkie zdania, nazwy z interfejsu, bez AI slopu,
bez długich pauz, żadnych cen i liczb z pamięci.
```
## Checklista recenzenta
[Dział zatytułowany „Checklista recenzenta”](#checklista-recenzenta)
* [ ] Każda zmieniona strona ma `verified` z datą z tego tygodnia.
* [ ] PL, EN i DE mają te same nagłówki H2 w tej samej kolejności.
* [ ] Nazwy narzędzi w sekcji “Przez API / MCP” istnieją w `club-web/docs/mcp-tools.md`.
* [ ] Ścieżki `/app/...` istnieją (`php artisan route:list` w club-web).
* [ ] Zrzuty są z klubu demo i nie pokazują danych prawdziwych klubów.
* [ ] `npm run build` przeszedł; `dist/llms-full.txt` zawiera zmienioną stronę.
## Kiedy zakładać nowy scenariusz, a kiedy rozszerzać istniejący
[Dział zatytułowany „Kiedy zakładać nowy scenariusz, a kiedy rozszerzać istniejący”](#kiedy-zakładać-nowy-scenariusz-a-kiedy-rozszerzać-istniejący)
* **Nowy**, gdy klub zadałby o to osobne pytanie (“jak sprzedać bilety na mecz”).
* **Rozszerzenie**, gdy zmienia się krok w istniejącym celu (nowa wersja sekcji, nowe pole w formularzu, nowe narzędzie MCP do tego samego celu).
* Nie zakładaj strony dla ekranu, który jest tylko środkiem do celu (np. “zakładka Tagi”). Tagi opisuje scenariusz o aktualnościach.
## Rytm
[Dział zatytułowany „Rytm”](#rytm)
* Zmiana funkcji: aktualizacja w tygodniu wdrożenia.
* Raz w miesiącu: przegląd stron z `verified` starszym niż 90 dni. Przeklikaj albo oznacz w tytule “(do weryfikacji)”.
* Raz na kwartał: porównanie `for-agents/tool-map.md` z `tools/list` i backlog.
# Ustaw maile do kupujących
> Adres kontaktowy sklepu, co kupujący dostaje przy każdym statusie zamówienia, własne szablony wiadomości i pełna lista zmiennych.
* Scenariusz
UC-013
* Plan
każdy
* Czas
20 minut
## Cel
[Dział zatytułowany „Cel”](#cel)
Kupujący dostaje od klubu maile napisane jego językiem, w momentach, które klub wybrał, a jego odpowiedź trafia do osoby, która prowadzi sklep.
## Zanim zaczniesz
[Dział zatytułowany „Zanim zaczniesz”](#zanim-zaczniesz)
* Moduł **Sklep** włączony.
* Adres e-mail osoby, która odpowiada na pytania kupujących (np. `sklep@twojklub.pl`).
* Podgląd szablonu używa ostatniego opłaconego zamówienia. Gdy sklep nic jeszcze nie sprzedał, podgląd pokazuje przykładowe zamówienie.
## Krok po kroku w panelu
[Dział zatytułowany „Krok po kroku w panelu”](#krok-po-kroku-w-panelu)
1. Otwórz **Zarabianie > Sklep > Ustawienia** i wybierz **Maile** (`/app/earn/store/settings?section=emails`).
2. **Adres kontaktowy sklepu**: wpisz **Adres do odpowiedzi (reply-to)**. Puste pole oznacza adres kontaktowy klubu. Adres jest też w stopce każdej wiadomości ze sklepu.
3. **Co dostaje kupujący**: przy każdym zdarzeniu wybierz **Wbudowana wiadomość**, jeden z własnych szablonów albo **Nie wysyłaj**. Zdarzenia, po kolei:
* **Zamówienie opłacone (potwierdzenie)**,
* **Status: …** dla każdego kroku obiegu, także własnych kroków klubu,
* **Status: Anulowano** i **Status: Zwrócona**.
**Podgląd wiadomości** przy zdarzeniu pokazuje, co pójdzie. Zapisz przyciskiem **Zapisz ustawienia e-maili**.
4. **Własne szablony**: kliknij **Nowy szablon**. Z prawej otwiera się edytor z gotowym początkiem wiadomości. Podaj **Nazwa szablonu** (np. “Paczka w drodze”), **Temat** i **Treść**.
5. Pod treścią jest lista **Zmienne**. Kliknięcie wstawia zmienną w miejscu kursora. **Podgląd** pokazuje maila z danymi zamówienia. Zapisz przyciskiem **Zapisz szablon**.
6. Wróć do **Co dostaje kupujący** i podepnij szablon pod zdarzenie, np. **Status: Wysłano**.
### Zmienne w szablonie
[Dział zatytułowany „Zmienne w szablonie”](#zmienne-w-szablonie)
| Grupa | Zmienna | Co wstawia |
| ---------- | ---------------------- | ---------------------------------------------- |
| Kupujący | `{{buyer_name}}` | Imię i nazwisko (gdy brak, adres e-mail) |
| Kupujący | `{{buyer_first_name}}` | Imię |
| Kupujący | `{{buyer_email}}` | E-mail |
| Kupujący | `{{buyer_phone}}` | Telefon |
| Zamówienie | `{{order_number}}` | Numer zamówienia, np. `#1001` |
| Zamówienie | `{{order_date}}` | Data zamówienia (dd.mm.rrrr) |
| Zamówienie | `{{order_total}}` | Kwota zapłacona łącznie |
| Zamówienie | `{{order_status}}` | Aktualny status |
| Zamówienie | `{{products}}` | Produkty w jednej linii, z wariantem i ilością |
| Zamówienie | `{{products_table}}` | Tabela produktów z ceną, dostawą i sumą |
| Zamówienie | `{{order_url}}` | Link do strony zamówienia kupującego |
| Dostawa | `{{shipping_method}}` | Sposób dostawy |
| Dostawa | `{{shipping_address}}` | Adres dostawy (z Paczkomatem, jeśli wybrany) |
| Dostawa | `{{tracking_number}}` | Numer przesyłki |
| Dostawa | `{{tracking_url}}` | Link do śledzenia |
| Dostawa | `{{eta}}` | Przewidywana data |
| Klub | `{{club_name}}` | Nazwa klubu |
| Klub | `{{store_url}}` | Adres sklepu |
| Klub | `{{contact_email}}` | E-mail kontaktowy sklepu |
## Efekt
[Dział zatytułowany „Efekt”](#efekt)
* Przy każdym zdarzeniu kupujący dostaje wybraną wiadomość albo nic.
* Odpowiedź na maila ze sklepu trafia na adres kontaktowy sklepu.
* Każda wysłana wiadomość ma kopię w zamówieniu, w sekcji **Maile**.
* Szablonu użyjesz też ręcznie: z zamówienia (**Napisz wiadomość**) i w wysyłce do wielu kupujących ([Napisz do kupujących ze sklepu](/earn/store-message-buyers/)).
## Przez API / MCP
[Dział zatytułowany „Przez API / MCP”](#przez-api--mcp)
Nie ma narzędzi do adresu kontaktowego, szablonów ani automatyzacji maili sklepu. `get_store_settings` i `update_store_settings` obsługują obieg statusów i adresy powiadomień dla klubu o nowym zamówieniu (`notify_emails`), nie maile do kupujących. Agent kieruje klub do **Zarabianie > Sklep > Ustawienia > Maile**.
## Pułapki
[Dział zatytułowany „Pułapki”](#pułapki)
* **Literówka w zmiennej zostaje w mailu.** Nieznana zmienna, np. `{{order_numer}}`, nie jest zamieniana. Sprawdź **Podgląd** przed zapisem.
* **Usunięty szablon wraca do wbudowanej wiadomości.** Zdarzenia, które go używały, znów wysyłają **Wbudowana wiadomość**, nie milkną.
* **Własny szablon nie ma linku do pobrania produktu cyfrowego.** Link jest tylko w wbudowanym potwierdzeniu. Jeśli sprzedajesz produkty cyfrowe, zostaw dla **Zamówienie opłacone** opcję **Wbudowana wiadomość**. Wyjątek: produkt cyfrowy, który nie jest pierwszą pozycją koszyka, zawsze dostaje osobne wbudowane potwierdzenie.
* **Zmiana statusu przez API omija te ustawienia** i wysyła wbudowany mail o statusie (patrz [Obsłuż zamówienia ze sklepu](/earn/store-orders/)).
* Limit to 30 własnych szablonów.
## Zobacz też
[Dział zatytułowany „Zobacz też”](#zobacz-też)
* [Obsłuż zamówienia ze sklepu](/earn/store-orders/)
* [Napisz do kupujących ze sklepu](/earn/store-message-buyers/)
# Napisz do kupujących ze sklepu
> Jedna wiadomość do wielu kupujących naraz, z filtrem po statusie, dacie i produkcie, z podglądem i testem do siebie.
* Scenariusz
UC-014
* Plan
każdy
* Czas
10 minut
## Cel
[Dział zatytułowany „Cel”](#cel)
Wszyscy, którzy kupili nową koszulkę, dowiadują się z jednego maila, że dostawa przesunie się o tydzień albo że odbiór jest w klubie po meczu.
## Zanim zaczniesz
[Dział zatytułowany „Zanim zaczniesz”](#zanim-zaczniesz)
* Co najmniej jedno opłacone zamówienie w sklepie. Test do siebie też go wymaga.
* Treść wiadomości albo gotowy szablon z [Ustaw maile do kupujących](/earn/store-emails/).
## Krok po kroku w panelu
[Dział zatytułowany „Krok po kroku w panelu”](#krok-po-kroku-w-panelu)
1. Otwórz **Zarabianie > Sklep > Zamówienia** (`/app/earn/store/orders`) i kliknij **Nowa wiadomość**. Z prawej otwiera się panel **Nowa wiadomość do kupujących**.
2. **Do kogo**: zawęź odbiorców.
* **Status zamówienia**: **Wszystkie opłacone** albo wybrane statusy. Anulowane i zwrócone wchodzą tylko wtedy, gdy zaznaczysz ich status.
* **Data zamówienia**: od i do. Puste = bez ograniczenia.
* **Produkt**: **Dowolny produkt** albo jeden produkt.
Pod filtrem widać, do ilu kupujących pójdzie wiadomość.
3. **Wiadomość**: wybierz **Szablon** albo **Bez szablonu - własna treść**, wpisz **Temat** i **Treść**. Zmienne (np. `{{buyer_first_name}}`, `{{order_number}}`) wypełniają się danymi ostatniego zamówienia każdego kupującego.
4. Kliknij **Test do mnie** i sprawdź maila u siebie. Test używa ostatniego opłaconego zamówienia sklepu.
5. Kliknij **Wyślij** i potwierdź w oknie **Wysłać wiadomość?**.
## Efekt
[Dział zatytułowany „Efekt”](#efekt)
* Każdy adres z filtra dostaje jedną wiadomość, nawet jeśli ma kilka zamówień.
* Odpowiedzi trafiają na adres kontaktowy sklepu.
* Kopia trafia do zamówienia każdego odbiorcy, w sekcji **Maile**, jako **Wysyłka do kupujących**.
* Komunikat po wysyłce podaje liczbę wysłanych. Gdy część adresów nie przeszła, szczegóły są w zamówieniach.
## Przez API / MCP
[Dział zatytułowany „Przez API / MCP”](#przez-api--mcp)
Nie ma narzędzia do wysyłki do kupujących. Agent może przygotować listę przez `list_store_orders` i treść wiadomości, ale wysyłkę klub robi w panelu: **Zarabianie > Sklep > Zamówienia > Nowa wiadomość**.
## Pułapki
[Dział zatytułowany „Pułapki”](#pułapki)
* **Wysyłki nie da się cofnąć.** Zawsze najpierw **Test do mnie**.
* **Maksymalnie 2000 odbiorców naraz.** Przy większej liście panel odmawia wysyłki. Zawęź filtr datą albo produktem i wyślij w kilku turach.
* **Filtr bez wyników nic nie wysyła.** Gdy nikt nie pasuje, panel pokazuje komunikat i wiadomość nie wychodzi.
* **To nie jest newsletter.** Wiadomość idzie tylko do kupujących ze sklepu, w sprawie ich zamówień. Do kibiców z listy kontaktów służą kampanie mailowe.
## Zobacz też
[Dział zatytułowany „Zobacz też”](#zobacz-też)
* [Ustaw maile do kupujących](/earn/store-emails/)
* [Obsłuż zamówienia ze sklepu](/earn/store-orders/)
# Obsłuż zamówienia ze sklepu
> Zakładka Przegląd, lista zamówień, szczegóły zamówienia w szufladzie, statusy, telefon kupującego i wszystkie maile wysłane do kupującego.
* Scenariusz
UC-012
* Plan
każdy; metody dostawy (kurier, Paczkomat) w sklepie eCommerce PRO
* Czas
5 minut na zamówienie
## Cel
[Dział zatytułowany „Cel”](#cel)
Kibic, który kupił szalik, dostaje go na czas i wie, co dzieje się z jego zamówieniem, a klub widzi w jednym miejscu, ile sprzedaje i co czeka na wysyłkę.
## Zanim zaczniesz
[Dział zatytułowany „Zanim zaczniesz”](#zanim-zaczniesz)
* Moduł **Sklep** włączony i co najmniej jeden produkt w zakładce **Produkty**.
* Podłączone konto płatnicze klubu. Bez niego płatności działają w trybie testowym.
* Zakładka **Przegląd** pojawia się dopiero po pierwszym opłaconym zamówieniu. Wcześniej sklep otwiera się na liście produktów.
## Krok po kroku w panelu
[Dział zatytułowany „Krok po kroku w panelu”](#krok-po-kroku-w-panelu)
1. Otwórz **Zarabianie > Sklep** (`/app/earn/store`). Gdy sklep już sprzedaje, startuje na zakładce **Przegląd**:
* kafle **Sprzedaż** i **Zamówienia** z porównaniem do poprzedniego okresu, **Średnie zamówienie** z liczbą sprzedanych sztuk i **Do realizacji** z liczbą zaległych,
* przełącznik **7 dni**, **30 dni**, **90 dni** i wykres **Sprzedaż dzień po dniu**,
* **Najpopularniejsze produkty** i **Najnowsze zamówienia** (po sześć),
* podpowiedzi, co blokuje sklep: płatności w trybie testowym, sklep w trybie testowym z hasłem, brak adresu kontaktowego sklepu, brak metod dostawy. Każda ma przycisk **Otwórz ustawienia**.
2. Przejdź do zakładki **Zamówienia** (`/app/earn/store/orders`). Licznik przy nazwie to zamówienia, które czekają na realizację. Widok **Tabela** albo **Tablica**.
3. Kliknij zamówienie. **Szczegóły zamówienia** otwierają się w szufladzie z prawej strony (na telefonie od dołu), lista zostaje pod spodem. **Otwórz na całej stronie** daje pełną stronę zamówienia ze stałym adresem (`/app/earn/store/orders/{id}`), np. do wysłania koledze z zarządu.
4. W sekcji **Kupujący i dostawa** masz kupującego, **Adres e-mail**, **Numer telefonu** i **Adres wysyłki**. Telefon jest obowiązkowy w koszyku i zapisuje się też na koncie kupującego. Telefon i e-mail widać też w nagłówku zamówienia.
5. W sekcji **Realizacja** kliknij **Zmień stan**. Domyślny obieg: **Zamówienie przyjęte** > **W produkcji** > **Pakowanie** > **Wysłano**, plus własne kroki klubu. Z zaznaczonym **Powiadom kupującego mailem o tej zmianie** kupujący dostaje to, co ustawiono w [Ustaw maile do kupujących](/earn/store-emails/).
6. Po nadaniu paczki kliknij **Dodaj numer przesyłki**. Zaznacz **Wyślij numer kupującemu e-mailem**, a kupujący dostanie numer razem z linkiem do śledzenia.
7. Sekcja **Maile** pokazuje każdą wiadomość, która poszła do kupującego: potwierdzenie, zmiany statusu, automatyczne i własne wiadomości klubu, z datą, adresem i osobą, która wysłała. **Podgląd** przy wiadomości otwiera kopię dokładnie tej treści, którą kupujący otrzymał.
8. **Napisz wiadomość** (w nagłówku zamówienia i w sekcji **Maile**) wysyła maila do tego kupującego: wybierz **Szablon** albo **Bez szablonu - własna treść**, uzupełnij **Temat** i **Treść**, sprawdź **Podgląd wiadomości** i kliknij **Wyślij do** (adres kupującego). Zmienne jak `{{order_number}}` wypełniają się danymi tego zamówienia.
9. **Wyślij potwierdzenie ponownie** i **Wyślij aktualny status** ponawiają wbudowane maile, np. gdy kupujący napisze, że nic nie dostał.
## Efekt
[Dział zatytułowany „Efekt”](#efekt)
* Kupujący widzi aktualny status na stronie swojego zamówienia i dostaje maile przy zmianach, w kopii zapisanej w sekcji **Maile**.
* Odpowiedź kupującego na maila ze sklepu trafia na adres kontaktowy sklepu.
* Eksport zamówień (przycisk **CSV** nad listą) ma kolumny **Telefon**, **Stawki VAT**, kwotę netto i **Kwota VAT**.
## Przez API / MCP
[Dział zatytułowany „Przez API / MCP”](#przez-api--mcp)
| Krok | Narzędzie |
| ------------------------------------------------ | ----------------------------------------------------------- |
| Lista opłaconych zamówień | `list_store_orders` |
| Jedno zamówienie z telefonem i historią statusów | `get_store_order {id}` (pole `buyer_phone`) |
| Zmiana statusu, data dostawy, notatka | `update_store_order_status {id, status, eta?, admin_note?}` |
| Obieg statusów | `get_store_settings` (`status_flow`) |
| Produkty | `list_products`, `create_product`, `update_product` |
Tylko w panelu: zakładka **Przegląd**, **Napisz wiadomość**, podgląd wysłanych maili, ponowna wysyłka potwierdzenia, numer przesyłki, zwrot i anulowanie zamówienia.
## Pułapki
[Dział zatytułowany „Pułapki”](#pułapki)
* **Zmiana statusu przez API wysyła zawsze wbudowany mail o statusie.** Narzędzie `update_store_order_status` nie patrzy na ustawienie **Co dostaje kupujący** i nie zapisuje kopii w sekcji **Maile**. Jeśli klub ma dla statusu własny szablon albo **Nie wysyłaj**, zmieniaj status w panelu.
* **Starsze zamówienia nie mają telefonu.** Telefon zapisuje się w zamówieniu od chwili, gdy stał się obowiązkowy w koszyku. Przy wcześniejszych zamówieniach pole jest puste, także w `get_store_order` i w CSV.
* **Jedna płatność to jedno zamówienie.** Koszyk z kilkoma produktami jest jednym zamówieniem z kilkoma pozycjami, nie kilkoma zamówieniami.
## Zobacz też
[Dział zatytułowany „Zobacz też”](#zobacz-też)
* [Ustaw maile do kupujących](/earn/store-emails/)
* [Napisz do kupujących ze sklepu](/earn/store-message-buyers/)
* [Ustaw VAT w sklepie](/earn/store-vat/)
# Ustaw VAT w sklepie
> Domyślna stawka VAT według kraju klubu, własna stawka dla produktu i rachunek "w tym VAT" w potwierdzeniu zamówienia.
* Scenariusz
UC-015
* Plan
każdy
* Czas
5 minut
## Cel
[Dział zatytułowany „Cel”](#cel)
Kupujący dostaje potwierdzenie z kwotą VAT liczoną właściwą stawką, a klub ma te same liczby w eksporcie dla księgowości.
## Zanim zaczniesz
[Dział zatytułowany „Zanim zaczniesz”](#zanim-zaczniesz)
* Sprawdź z księgowym, czy klub jest płatnikiem VAT i jakie stawki mają Wasze produkty (np. odzież inną niż książki czy bilety).
* Kraj klubu decyduje o stawce domyślnej. Opis pod **Stawka VAT** pokazuje, który kraj i jaką stawkę przyjął sklep.
## Krok po kroku w panelu
[Dział zatytułowany „Krok po kroku w panelu”](#krok-po-kroku-w-panelu)
1. Otwórz **Zarabianie > Sklep > Ustawienia** i pigułkę **Zamówienia** (`/app/earn/store/settings`).
2. W wierszu **Stawka VAT** zostaw **Standardowa dla kraju** (np. 23% w Polsce, 19% w Niemczech) albo wybierz inną stawkę z listy dla kraju klubu. Klub, który nie jest płatnikiem VAT, wybiera **zw.**. Zapisz.
3. Produkt z inną stawką: **Zarabianie > Sklep > Produkty**, otwórz produkt, w polu **Stawka VAT** wybierz stawkę zamiast **Domyślna sklepu**. Zapisz.
Ceny w sklepie są zawsze brutto. VAT jest liczony “w tym”: cena się nie zmienia, zmienia się tylko podział na netto i VAT.
## Efekt
[Dział zatytułowany „Efekt”](#efekt)
* Mail z potwierdzeniem, strona “dziękujemy” i strona zamówienia kupującego pokazują rachunek: pozycje, dostawę, **Zapłacono łącznie** i linię **w tym VAT** ze stawką, osobno dla każdej stawki w koszyku.
* Gdy klub jest zwolniony, rachunek ma dopisek **Sprzedawca zwolniony z VAT**.
* Eksport zamówień (przycisk **CSV** nad listą zamówień) ma kolumny **Stawki VAT**, netto i **Kwota VAT**.
## Przez API / MCP
[Dział zatytułowany „Przez API / MCP”](#przez-api--mcp)
Nie ma narzędzia do stawki VAT sklepu ani produktu. `create_product` i `update_product` tworzą produkt ze stawką domyślną sklepu. Stawkę zmienia się w panelu.
## Pułapki
[Dział zatytułowany „Pułapki”](#pułapki)
* **Stawka jest zamrażana w chwili zakupu.** Zmiana stawki nie przelicza opłaconych zamówień. Starsze zamówienia bez zapisanej stawki biorą stawkę produktu, a potem domyślną sklepu.
* **Dostawa idzie po stawce sklepu**, nie po stawce produktu.
* **Rachunek to nie faktura.** Potwierdzenie zamówienia z rozbiciem VAT nie zastępuje faktury, jeśli kupujący o nią prosi.
## Zobacz też
[Dział zatytułowany „Zobacz też”](#zobacz-też)
* [Obsłuż zamówienia ze sklepu](/earn/store-orders/)
* [Ustaw maile do kupujących](/earn/store-emails/)
# Jak agent AI ma czytać tę bazę
> Zasady pracy agenta z bazą wiedzy Sportigio - kolejność działań, kontekst klubu, pliki, weryfikacja i uczciwość wobec ograniczeń.
Ta baza jest pisana dla dwóch odbiorców naraz: dla osoby z klubu i dla agenta AI, który pracuje przez narzędzia MCP Sportigio (`/api/v1/mcp`) albo REST `/api/v1`. Agentem może być asystent w panelu klubu, Claude lub Codex z kluczem API, albo integracja klubu.
## Skąd brać treść
[Dział zatytułowany „Skąd brać treść”](#skąd-brać-treść)
* **Cała baza jednym plikiem**: `/llms-full.txt` (pełny tekst) i `/llms.txt` (spis stron z opisami). Oba pliki są generowane z tych samych stron, które czyta człowiek.
* **Jedna strona**: adres strony bez zmian; treść jest zwykłym HTML z nagłówkami H2.
* Język źródłowy to polski. Wersje EN i DE są lustrami i mogą być o krok w tyle.
## Kolejność działań agenta
[Dział zatytułowany „Kolejność działań agenta”](#kolejność-działań-agenta)
1. **Ustal cel klubu**, nie ekran. Dopasuj do scenariusza z tej bazy po tytule i polu `id` (`UC-004`).
2. **Przeczytaj “Zanim zaczniesz”** i sprawdź warunki narzędziami do odczytu: `get_website_status`, `get_plan_info`, `get_module_catalog`, `list_*`.
3. **Wykonaj sekcję “Przez API / MCP”** narzędziami dokładnie o tych nazwach. Nazwy pochodzą z `tools/list`; jeśli narzędzia nie ma na Twojej liście, nie zgaduj - klucz może nie mieć scope’u.
4. **Zweryfikuj efekt** odczytem (`list_page_blocks`, `get_post`, `list_games`) i podaj klubowi publiczny adres do sprawdzenia.
5. **Powiedz wprost, czego nie zrobiłeś.** Jeśli krok jest tylko w panelu, podaj ścieżkę dokładnie tak, jak w sekcji “Krok po kroku w panelu”, jako klikalny link.
## Kontekst klubu
[Dział zatytułowany „Kontekst klubu”](#kontekst-klubu)
* Klucz klubu działa w kontekście tego klubu automatycznie.
* Klucz platformowy (Sportigio) wymaga `space_id` w **każdym** wywołaniu. `use_space` działa tylko w obrębie jednego requestu i nie przenosi się na kolejne. Bez `space_id` listy wracają puste i wygląda to jak “klub bez danych”.
## Pliki i obrazy
[Dział zatytułowany „Pliki i obrazy”](#pliki-i-obrazy)
* Każde pole graficzne w API (`logo_url`, `photo_url`, `image_url`) przyjmuje **publiczny adres https**. Adresy prywatne, lokalne i wewnętrzne są odrzucane; niektóre narzędzia w takim wypadku po cichu używają grafiki domyślnej.
* Plik z dysku wgrywasz przez `POST /api/v1/uploads` (multipart `file=@...`) i używasz zwróconego `url`. Narzędzie `upload_file` przyjmuje tylko `url` albo małe `data_base64`.
## Czego nie obiecywać
[Dział zatytułowany „Czego nie obiecywać”](#czego-nie-obiecywać)
* Sprzedaży i zwrotów biletów, wysyłki newsletterów i push (tylko szkice), zmian planu, zarządzania zespołem, własnej domeny (zgłoszenie do wsparcia przez `report_support_issue`).
* Sekcji, których nie ma w katalogu API: karuzela kart, licznik biletów, sklep, social media, sekcja z kolumnami - te tylko w panelu.
## Gdy baza i narzędzie się różnią
[Dział zatytułowany „Gdy baza i narzędzie się różnią”](#gdy-baza-i-narzędzie-się-różnią)
Twoja aktualna lista narzędzi jest źródłem prawdy o tym, co umiesz. Ta baza mówi, **jak** to robić i **co** klub widzi. Jeśli narzędzie istnieje, a baza o nim milczy, użyj narzędzia i zgłoś brak w bazie ([Rozwijanie bazy](/contributing/update-prompt/)).
# Mapa scenariuszy i narzędzi
> Każdy scenariusz z tej bazy z narzędziami MCP, które go realizują, i ścieżką w panelu dla kroków bez API.
Tabela do szybkiego dopasowania: cel klubu → scenariusz → narzędzia do odczytu i zapisu → ścieżka w panelu, gdy API nie wystarcza.
| Scenariusz | Cel klubu | Odczyt | Zapis | Tylko w panelu |
| --------------------------------------- | ----------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| [UC-001](/getting-started/first-steps/) | Nazwa, logo, kolory, social | `get_social_links` | `set_club_logo`, `update_social_links`, `save_club_profile` | Ustawienia > Ogólne (nazwa, dyscyplina), Ustawienia > Wygląd (kolory) |
| [UC-002](/website/publish/) | Opublikuj stronę | `get_website_status`, `get_plan_info` | `set_website_published`, `set_default_landing` | Ustawienia > Udostępnianie (subdomena, własna domena, przełącznik Strona WWW) |
| [UC-003](/website/appearance/) | Nagłówek, slider, stopka | `get_site_design_settings` | `update_site_design_settings` | Wygląd: czcionki, edytor stylów PRO |
| [UC-004](/website/homepage-sections/) | Sekcje strony głównej | `list_page_blocks` | `create_page_block`, `update_page_block`, `move_page_block`, `reorder_page_blocks`, `delete_page_block`, `create_club_banner` | Karuzela kart, licznik biletów, sklep, social media, sekcja z kolumnami |
| [UC-005](/website/menu/) | Menu strony | `list_menu_items` | `create_menu_item`, `update_menu_item`, `reorder_menu_items`, `delete_menu_item` | - |
| [UC-006](/website/subpages/) | Podstrony | `list_infopages`, `get_infopage` | `create_infopage`, `update_infopage`, `create_sponsors_page`, `create_database_page` | Usuwanie podstrony |
| [UC-007](/content/news/) | Aktualności | `list_posts`, `get_post`, `list_tags`, `get_game_context` | `create_post`, `update_post`, `delete_post`, `reorder_pinned_posts` | Upload okładki z dysku (albo `/api/v1/uploads`) |
| [UC-008](/content/matches/) | Mecze i wyniki | `list_clubs`, `list_games`, `get_game`, `get_standings`, `get_game_context` | `create_club`, `update_club`, `create_game`, `update_game`, `delete_game`, `save_game_link`, `configure_games_sync` | Nazwa ligi i sezonu, skład meczowy, wydarzenia meczowe |
| [UC-009](/content/squad/) | Kadra | `get_positions`, `list_players`, `get_player` | `create_player`, `update_player`, `create_player_team`, `set_player_teams`, `bulk_set_player_teams`, `delete_player` | Kolejność drużyn |
| [UC-010](/content/sponsors/) | Sponsorzy | `list_sponsor_categories`, `list_sponsors`, `get_header_partner_logos` | `create_sponsor_category`, `create_sponsor`, `update_sponsor`, `reorder_sponsors`, `reorder_sponsor_categories`, `update_header_partner_logos` | - |
| [UC-012](/earn/store-orders/) | Zamówienia ze sklepu | `list_store_orders`, `get_store_order`, `get_store_settings` | `update_store_order_status` (wysyła zawsze wbudowany mail o statusie) | Przegląd sklepu, Napisz wiadomość, podgląd wysłanych maili, numer przesyłki, zwrot, anulowanie |
| [UC-013](/earn/store-emails/) | Maile do kupujących | - | - | Ustawienia sklepu > Maile: adres kontaktowy, automatyzacje, własne szablony |
| [UC-014](/earn/store-message-buyers/) | Wiadomość do wielu kupujących | `list_store_orders` | - | Zamówienia > Nowa wiadomość |
| [UC-015](/earn/store-vat/) | VAT w sklepie | - | - | Ustawienia sklepu > Zamówienia > Stawka VAT; stawka produktu w formularzu produktu |
## Wspólne dla wszystkich
[Dział zatytułowany „Wspólne dla wszystkich”](#wspólne-dla-wszystkich)
* `POST /api/v1/uploads` - jedyna droga dla pliku z dysku; zwraca `url`.
* `report_support_issue` - gdy klub prosi o coś poza zasięgiem narzędzi (własna domena, zwrot płatności, zmiana planu).
* `get_platform_guide` - skrócony przewodnik po panelu wbudowany w agenta; ta baza jest jego rozwinięciem.
## Kolejność budowy nowego klubu
[Dział zatytułowany „Kolejność budowy nowego klubu”](#kolejność-budowy-nowego-klubu)
Sprawdzona 2026-09-24 na klubie demo, od zera do opublikowanej strony w jednym przebiegu:
1. `update_club` (własna drużyna: nazwa, herb) → `create_club` ×N (rywale)
2. `create_game` ×N → `update_game` (wyniki rozegranych)
3. `create_player` ×N (zawodnicy, potem sztab)
4. `create_sponsor_category` → `create_sponsor` ×N
5. `create_post` ×N (dwa przypięte)
6. `create_infopage` ×3 (O klubie, Kontakt, Zostań sponsorem)
7. `create_page_block`: `games_last_next` v6, `news` v6, `media_text`, `players`, `sponsors`, `newsletter`
8. `create_menu_item` (top ×6, buttons ×1, footer ×3), `update_social_links`
9. `update_site_design_settings` → `set_website_published` → `set_default_landing {website}`
10. Sprawdzenie w panelu: **Ustawienia > Udostępnianie**, przełącznik **Strona WWW**.
## Połączenie asystenta (UC-011)
[Dział zatytułowany „Połączenie asystenta (UC-011)”](#połączenie-asystenta-uc-011)
[Podłącz asystenta AI](/getting-started/connect-ai/). Powyższy katalog dotyczy `/api/v1/mcp`. Osobny `/api/mcp` dla ChatGPT udostępnia tylko `list_posts`, `list_games`, `list_sponsors`, bez zapisu. Odczytaj jego `tools/list`, aby poznać właściwe argumenty.
# Podłącz asystenta AI do klubu
> Połączenie Claude Code, Codexa i Cursora oraz zakres integracji ChatGPT.
## Cel
[Dział zatytułowany „Cel”](#cel)
Asystent korzysta z danych właściwego klubu przez MCP.
## Zanim zaczniesz
[Dział zatytułowany „Zanim zaczniesz”](#zanim-zaczniesz)
Potrzebujesz dostępu do zarządzania klubem, klucza API tego klubu oraz zainstalowanego Claude Code, Codexa lub Cursora. Instrukcję i odczyty sprawdzono lokalnie 2026-09-25. Integracja ChatGPT wymaga jeszcze konfiguracji i publikacji przez Sportigio.
## Krok po kroku w panelu
[Dział zatytułowany „Krok po kroku w panelu”](#krok-po-kroku-w-panelu)
1. Otwórz **Klucze API** (`/app/api-keys`) i **Podłącz asystenta AI**.
2. Wybierz zakładkę **Claude Code**, **Codex** albo **Cursor**.
3. Kliknij **Zarządzaj kluczami** i przygotuj osobny klucz klubowy. Do przeglądania wybierz `content:read`, `matches:read` i `sponsors:read`.
4. Udostępnij klucz procesowi asystenta jako zmienną środowiskową `SPORTIGIO_CLUB_MCP_TOKEN`. Nie wpisuj go do rozmowy ani pliku w repozytorium.
5. Kliknij **Kopiuj konfigurację**. Dodaj fragment do `.mcp.json` dla Claude Code, `~/.codex/config.toml` dla Codexa albo `~/.cursor/mcp.json` dla Cursora. Zachowaj istniejące serwery.
6. Uruchom ponownie asystenta i sprawdź serwer `sportigio-club`. Poproś o ostatnie posty bez wprowadzania zmian.
## Efekt
[Dział zatytułowany „Efekt”](#efekt)
Asystent łączy się z klubowym `/api/v1/mcp` i działa w zakresie uprawnień klucza. Zakładki generują konfigurację dla aktualnej domeny klubu. Claude Code oznacza aplikację CLI, nie Claude w przeglądarce.
## Przez API / MCP
[Dział zatytułowany „Przez API / MCP”](#przez-api--mcp)
Połączenia i sekretu nie tworzysz przez te narzędzia. Przygotuj je w panelu i konfiguracji klienta.
Osobny profil ChatGPT korzysta z `/api/mcp`, OAuth i zgody na jeden klub. Ma wyłącznie `list_posts`, `list_games`, `list_sponsors`, z polami `page`, `per_page` i dodatkowo `scope` dla meczów. Przed wywołaniem odczytaj `tools/list`, ponieważ schemat różni się od `/api/v1/mcp`. Dostęp wygasa po godzinie i wymaga ponownego połączenia. Aktywne połączenie można wcześniej odwołać na stronie **Podłącz asystenta AI**. Jeśli panel pokazuje oczekiwanie na konfigurację, klub nie uruchomi jeszcze integracji ChatGPT samodzielnie.
## Pułapki
[Dział zatytułowany „Pułapki”](#pułapki)
* Zmienna środowiskowa musi być widoczna dla procesu aplikacji. Zmienna ustawiona w terminalu nie zawsze trafia do aplikacji uruchomionej z Docka.
* Nie zastępuj całego pliku konfiguracji: dopisz serwer do istniejącej sekcji.
* Klucz platformowy superadmina nie jest kluczem klubu i nie należy do publicznego połączenia ChatGPT.
* Podczas testów lokalnych używaj `http://klub1.sportigio.test.localhost`. Zdalny ChatGPT wymaga publicznego HTTPS.
## Zobacz też
[Dział zatytułowany „Zobacz też”](#zobacz-też)
* [Mapa scenariuszy i narzędzi](/for-agents/tool-map/)
* [Aktualności klubu](/content/news/)
# Pierwsze kroki w panelu
> Logowanie, nazwa klubu, dyscyplina, logo, kolory i media społecznościowe - fundament, z którego korzysta strona, profil, bilety i maile.
* Scenariusz
UC-001
* Plan
każdy
* Czas
10 minut
## Cel
[Dział zatytułowany „Cel”](#cel)
Klub ma poprawną nazwę, logo, kolory i linki do social mediów, zanim zacznie cokolwiek publikować. Te ustawienia dziedziczy wszystko: strona WWW, profil (link in bio), bilety, maile do kibiców i portal rodzica.
## Zanim zaczniesz
[Dział zatytułowany „Zanim zaczniesz”](#zanim-zaczniesz)
* Konto administratora klubu (zaproszenie od właściciela przestrzeni albo rejestracja).
* Logo klubu w PNG z przezroczystym tłem, najlepiej kwadratowe, co najmniej 512 px.
* Adresy profili klubu na Facebooku, Instagramie, YouTube (wystarczy nazwa profilu).
## Krok po kroku w panelu
[Dział zatytułowany „Krok po kroku w panelu”](#krok-po-kroku-w-panelu)
1. Zaloguj się pod adresem klubu (`/login`). Po zalogowaniu widzisz **Pulpit** z powitaniem, statystykami i skrótami.
2. Otwórz **Ustawienia** (ikona koła zębatego na dole lewego paska) i zostań w zakładce **Ogólne**.
3. Wpisz **Nazwę organizacji**. To nazwa, którą kibic zobaczy w nagłówku strony, w tytule karty przeglądarki i w mailach.
4. Sprawdź **Dyscyplinę sportu** (przycisk **Zmień**). Dyscyplina decyduje o polach meczu i pozycjach zawodników, więc ustaw ją przed dodaniem kadry.
5. W sekcji **Media społecznościowe** wklej nazwę profilu albo pełny adres. Ikony na stronie pojawią się tylko dla wypełnionych pól.
6. Kliknij **Zapisz Zmiany**.
7. Przejdź do zakładki **Wygląd**. Wgraj **Logo** (herb w nagłówku, stopce, na biletach) oraz osobno **Ikonę aplikacji** (kwadrat na ekranie telefonu i w karcie przeglądarki).
8. Ustaw **Kolor główny** (tło nagłówka slidera, przyciski) i **Kolor akcentu**. Kliknij **Zapisz Zmiany**.
## Efekt
[Dział zatytułowany „Efekt”](#efekt)
* Nagłówek strony i profil pokazują nowe logo i nazwę.
* Slider, przyciski i karty meczów przyjmują kolor główny.
* Ikony social mediów w nagłówku i stopce prowadzą do wpisanych profili.
Sprawdź na stronie klubu (przycisk **Podgląd** w prawym górnym rogu panelu, ikona oka).
## Przez API / MCP
[Dział zatytułowany „Przez API / MCP”](#przez-api--mcp)
| Krok | Narzędzie |
| ------------------------------------ | ------------------------------------------------------------------------------- |
| Logo w nagłówku, stopce, na biletach | `set_club_logo {target: "logo", url}` |
| Ikona aplikacji / favicon | `set_club_logo {target: "icon", url}` |
| Media społecznościowe | `update_social_links {facebook, instagram, youtube, tiktok, linkedin, twitter}` |
| Opis klubu dla asystenta AI | `save_club_profile {club_info}` |
| Plik z dysku na adres URL | `POST /api/v1/uploads` (multipart `file=@logo.png`), potem `url` w polu `url` |
Nazwy organizacji, dyscypliny i kolorów nie da się dziś zmienić przez API - agent ma wskazać **Ustawienia > Ogólne** i **Ustawienia > Wygląd**.
## Pułapki
[Dział zatytułowany „Pułapki”](#pułapki)
* **Logo z białym tłem** wygląda jak biały kwadrat na ciemnym nagłówku. Użyj PNG z alfą.
* **Zbyt jasny kolor główny** zjada biały tekst na przyciskach. Sprawdź kontrast na podglądzie strony, zanim zapiszesz.
* Import logo z adresu URL działa tylko dla **publicznych adresów https**. Adresy lokalne i prywatne są odrzucane.
* Zmiana dyscypliny po dodaniu kadry nie przepisuje pozycji zawodników.
## Zobacz też
[Dział zatytułowany „Zobacz też”](#zobacz-też)
* [Opublikuj stronę klubu](/website/publish/)
* [Ustaw wygląd strony](/website/appearance/)
# Jak korzystać z tej bazy
> Układ stron, oznaczenia planów, ścieżki w panelu i to, jak czytać sekcję dla agentów AI.
Każda strona w tej bazie to jeden **scenariusz**: coś, co klub chce osiągnąć. Nie opisujemy ekranów po kolei, tylko drogę od celu do efektu, który widzi kibic, rodzic albo sponsor.
## Układ każdego scenariusza
[Dział zatytułowany „Układ każdego scenariusza”](#układ-każdego-scenariusza)
1. **Cel** - jedno zdanie.
2. **Zanim zaczniesz** - plan, włączony moduł, pliki, które warto mieć pod ręką.
3. **Krok po kroku w panelu** - ścieżka i nazwy przycisków dokładnie tak, jak je widać.
4. **Efekt** - co się zmienia na stronie i gdzie to sprawdzić.
5. **Przez API / MCP** - te same kroki narzędziami, których używa agent AI Sportigio.
6. **Pułapki** - rzeczy, które naprawdę psuły się klubom.
7. **Zobacz też** - powiązane scenariusze.
## Jak czytamy ścieżki
[Dział zatytułowany „Jak czytamy ścieżki”](#jak-czytamy-ścieżki)
Ścieżka `Treści > Mecze > Ustawienia` oznacza: lewy pasek panelu, dział **Treści**, pozycja **Mecze**, zakładka **Ustawienia**. Adres w nawiasie (`/app/games`) jest wsparciem - możesz go wkleić po domenie klubu, ale w panelu klikasz nazwy, nie adresy.
Nowy panel ma adresy `/app/...`. Kilka starszych ekranów (ustawienia konta, udostępnianie, ekran startowy) wciąż mieszka pod `/admin/...`. Oba działają na tej samej sesji.
## Oznaczenia
[Dział zatytułowany „Oznaczenia”](#oznaczenia)
* **Plan** - `FREE`, `LITE`, `PRO`, `CHAMPION`. Jeśli scenariusz ma oznaczony plan, kroki poniżej tego planu pokażą informację o wymaganym planie zamiast przełącznika.
* **Powierzchnie** - `panel` (klikanie), `api` (REST `/api/v1`), `mcp` (narzędzia agenta).
## Dla agentów AI
[Dział zatytułowany „Dla agentów AI”](#dla-agentów-ai)
Sekcja “Przez API / MCP” podaje nazwy narzędzi z listy `tools/list` serwera MCP Sportigio. Jeśli czegoś nie da się zrobić przez API, piszemy to wprost - agent ma wtedy podać klubowi ścieżkę w panelu, a nie udawać, że wykonał zadanie. Zasady pracy agenta z tą bazą: [Dla agentów AI](/for-agents/overview/).
# Ustaw wygląd strony
> Układ nagłówka, slider aktualności, stopka, nazwa klubu obok herbu, czcionki i style sekcji.
* Scenariusz
UC-003
* Plan
każdy; style sekcji i nagłówków podstron od PRO
* Czas
15 minut
## Cel
[Dział zatytułowany „Cel”](#cel)
Strona ma układ nagłówka, slidera i stopki dopasowany do klubu, bez ruszania kodu.
## Zanim zaczniesz
[Dział zatytułowany „Zanim zaczniesz”](#zanim-zaczniesz)
* Logo i kolory z [Pierwszych kroków](/getting-started/first-steps/).
* Co najmniej dwie przypięte aktualności, jeśli chcesz zobaczyć slider z treścią ([Dodaj aktualność](/content/news/)).
## Krok po kroku w panelu
[Dział zatytułowany „Krok po kroku w panelu”](#krok-po-kroku-w-panelu)
1. Otwórz **Strona www > Wygląd** (`/app/settings/website`, sekcja **Wygląd**).
2. **Układ nagłówka**: wybierz jeden z wariantów (`x1`, `x2`, `x2_big_logo`, `x2_center`, `x2_mega_menu`, `x4`, `x5`, `x6`, `x7`, `x8`). Każdy ma podgląd na żywo z Twoim logo i menu. `x6` to spokojny domyślny układ z menu w jednej linii; `x7` jest oznaczony PRO.
3. **Nazwa klubu obok herbu**: włącz, jeśli herb jest mało czytelny w małym rozmiarze.
4. **Slider aktualności (hero)**: wybierz wariant (`x1`, `x2`, `x3`, `x6`, `x6a`, `x7`). Slider pokazuje **przypięte** aktualności, nie najnowsze. Bez przypiętych wpisów nie renderuje się wcale.
5. **Stopka**: `domyślna`, `v1`, `simple` lub `v2`.
6. **Kod w prawym górnym rogu**: pole na własny HTML (odliczanie, baner sponsora, link). Zostaw puste, jeśli nie masz konkretnego celu.
7. Kliknij **Zapisz zmiany** u góry strony.
8. **Ustawienia > Wygląd - zaawansowane** (`/admin/settings`, zakładka Wygląd): czcionka nagłówków i tekstu (nazwa z Google Fonts albo adres pliku), drugi kolor główny i akcentu, kolory trybu ciemnego.
9. Od planu PRO w tej samej sekcji **Wygląd** działa edytor stylów: tytuły sekcji (`classic`, `editorial`, `slash`, `accent_bar`, `centered_line`, `boxed`, rozmiar S-XL), nagłówki podstron (`classic`, `image`, `minimal`, `outline`, `diagonal`, `logo_blur`), zakładki (`underline`, `chips`, `minimal`) i przyciski (`classic`, `square`). Każdy element ma własną kartę i mały podgląd; strona publiczna zmienia się dopiero po zapisie.
## Efekt
[Dział zatytułowany „Efekt”](#efekt)
Nagłówek, slider i stopka przyjmują wybrane układy na wszystkich podstronach. Sekcje strony głównej dziedziczą styl tytułów.
## Przez API / MCP
[Dział zatytułowany „Przez API / MCP”](#przez-api--mcp)
| Krok | Narzędzie |
| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Odczyt układów i dozwolonych wartości | `get_site_design_settings` |
| Zmiana nagłówka, slidera, stopki, kodu w rogu, nazwy przy herbie | `update_site_design_settings {header_version, hero_version, footer_alternative, top_right_code, header_show_club_name}` |
Wartości `header_version` i `hero_version` muszą pochodzić z listy zwróconej przez `get_site_design_settings`. Czcionek i edytora stylów PRO nie ma w API.
## Pułapki
[Dział zatytułowany „Pułapki”](#pułapki)
* **Slider jest pusty, choć są aktualności** - żadna nie jest przypięta. Zobacz [Dodaj aktualność](/content/news/).
* **Dwa powitania na górze strony**: slider z ustawień plus sekcja **Powitanie (hero)** na stronie głównej. Wybierz jedno.
* Czcionka wpisana z literówką nie ładuje się i strona spada na czcionkę domyślną bez komunikatu.
* Edytor stylów PRO na planie FREE/LITE pokazuje informację o planie także przy próbie zapisu.
## Zobacz też
[Dział zatytułowany „Zobacz też”](#zobacz-też)
* [Ułóż stronę główną z sekcji](/website/homepage-sections/)
* [Opublikuj stronę klubu](/website/publish/)
# Ułóż stronę główną z sekcji
> Edytor strony głównej - jakie sekcje istnieją, kiedy której użyć, jak zmieniać wersje, kolejność i widoczność.
* Scenariusz
UC-004
* Plan
każdy; karuzela kart, bazy danych i tła sekcji od PRO
* Czas
20 minut
## Cel
[Dział zatytułowany „Cel”](#cel)
Strona główna składa się z gotowych sekcji, które same biorą dane klubu: mecze, aktualności, kadrę, sponsorów. Klub układa kolejność i wybiera wersje wyglądu, nie pisze HTML.
## Zanim zaczniesz
[Dział zatytułowany „Zanim zaczniesz”](#zanim-zaczniesz)
* Treści, które sekcje mają pokazać: [aktualności](/content/news/), [mecze](/content/matches/), [kadra](/content/squad/), [sponsorzy](/content/sponsors/). Pusta sekcja pokazuje ramkę “materiały pojawią się tutaj”, a nie znika.
* Jedno dobre zdjęcie poziome, jeśli chcesz sekcję **Zdjęcie z tekstem** albo **Powitanie**.
## Krok po kroku w panelu
[Dział zatytułowany „Krok po kroku w panelu”](#krok-po-kroku-w-panelu)
1. Otwórz **Strona www > Strona główna** albo przycisk **Otwórz edytor strony głównej** w **Strona www > Przegląd** (`/app/page-blocks`).
2. Po lewej jest paleta **Dodaj moduł**. Kliknięcie kafla dodaje sekcję na koniec listy:
* **Ogólne**: Banner (grafika), Powitanie (hero), Zdjęcie z tekstem, Własna treść, Zdjęcia, Karuzela kart (PRO), Lista (baza danych).
* **Posty**: Aktualności, Lista postów, Video, Galerie.
* **Dyscyplina**: Mecze, Licznik biletowy, Kadra.
* **Inne**: Sponsorzy, Sklep, Social Media, Program klubowy, Zapis do newslettera, Reklama.
* **Layout**: Sekcja z kolumnami.
3. Kliknij nazwę sekcji na liście, żeby otworzyć jej ustawienia: tytuł, **wersja** układu, liczba elementów, widoczność na komputerze i telefonie. Ikona oka po prawej ukrywa sekcję bez usuwania.
4. Kolejność zmieniasz strzałkami góra/dół przy sekcji ([Zmień kolejność sekcji](/website/reorder-homepage-sections/)). Wiersze **Nagłówek**, **Slider - Aktualności** i **Stopka** nie są sekcjami - prowadzą do [ustawień wyglądu](/website/appearance/).
5. **Pokaż podgląd wszystkich** rozwija miniatury; **Podgląd** w prawym górnym rogu otwiera stronę publiczną.
### Które sekcje wybrać
[Dział zatytułowany „Które sekcje wybrać”](#które-sekcje-wybrać)
| Potrzeba | Sekcja | Uwagi |
| --------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------- |
| Terminarz i wyniki | **Mecze** (`games_last_next`) | wersja 6 = slider kart w barwie klubu; wersja 1 ma odliczanie do meczu |
| Najnowsze artykuły | **Aktualności** (`news`) | wersja 6 = spokojna siatka, domyślna dla nowych stron |
| Artykuły, galerie i wideo w jednym strumieniu | **Lista postów** (`posts`) | nie łącz z **Aktualności**, wpisy się zdublują |
| Skład drużyny | **Kadra** (`players`) | wersje 1-8; zakładki drużyn od PRO |
| Loga sponsorów | **Sponsorzy** (`sponsors`) | układ `cards`, `plain`, `wall` lub `list` z opisem |
| Zdjęcie i tekst z przyciskiem | **Zdjęcie z tekstem** (`media_text`) | przemiennie lewo/prawo, gdy jest kilka |
| Duże powitanie ze zdjęciem | **Powitanie** (`hero`) | pierwsza sekcja i tylko raz; zamiast slidera, nie obok |
| Zbieranie adresów e-mail | **Zapis do newslettera** (`newsletter`) | zapisy trafiają do kontaktów ze źródłem `website` |
| Wyróżnik: 1,5% podatku, nabór, zbiórka | baner klubu (`html` z gotowym układem) | w barwach klubu, trzy układy |
| Coś, czego nie ma w katalogu | **Własna treść** (`html`) | edytor z szablonami i “Poproś AI”; sam pilnujesz odstępów |
## Efekt
[Dział zatytułowany „Efekt”](#efekt)
Strona główna pokazuje sekcje w ustalonej kolejności, w barwach klubu, na komputerze i telefonie. Nowe mecze, wpisy i zawodnicy pojawiają się w sekcjach automatycznie.
## Przez API / MCP
[Dział zatytułowany „Przez API / MCP”](#przez-api--mcp)
| Krok | Narzędzie |
| --------------------------------------------------- | ------------------------------------------------------- |
| Lista sekcji i katalog typów z dozwolonymi wersjami | `list_page_blocks` |
| Nowa sekcja | `create_page_block {content_type, version, title, ...}` |
| Zmiana tytułu, wersji, widoczności, treści | `update_page_block {id, ...}` |
| Przesunięcie jednej sekcji pod inną | `move_page_block {id, reference_id, position}` |
| Pełna kolejność | `reorder_page_blocks {ids}` |
| Usunięcie | `delete_page_block {id}` |
| Gotowy baner wyróżnika w barwach klubu | `create_club_banner {kind, heading, ...}` |
| Zdjęcie do sekcji | `POST /api/v1/uploads`, potem `image_url` |
Kolejność, która działa dla nowego klubu: `games_last_next` v6, `news` v6, `media_text`, `players`, `sponsors`, `newsletter`. Przez API nie postawisz **Karuzeli kart**, **Licznika biletowego**, **Sklepu**, **Social Media** ani **Sekcji z kolumnami** - te tylko w panelu. Odwrotnie: sekcję **Nadchodzące wydarzenia** (`events_upcoming`) postawi tylko API.
## Pułapki
[Dział zatytułowany „Pułapki”](#pułapki)
* **Aktualności obok Listy postów** pokazują ten sam artykuł dwa razy.
* **Powitanie (hero) pod sliderem** daje dwa duże bloki na górze. Wybierz jedno ([wygląd](/website/appearance/)).
* **Sekcja Mecze nie znika po sezonie** - dalej pokazuje ostatnie wyniki.
* Zdjęcie do sekcji importowane z adresu URL musi być **publiczne (https)**. Adresy prywatne i lokalne są odrzucane bez komunikatu w panelu.
* Tło sekcji (`club`, `color`, `gradient`, `image`) i filtry tagów zapisują się tylko na PRO, także przez API.
## Zobacz też
[Dział zatytułowany „Zobacz też”](#zobacz-też)
* [Ustaw wygląd strony](/website/appearance/)
* [Dodaj podstronę](/website/subpages/)
* [Dodaj sponsora](/content/sponsors/)
# Zbuduj menu strony
> Menu górne, przyciski w nagłówku, stopka i menu mobilne - pozycje, podmenu, linki do podstron i modułów.
* Scenariusz
UC-005
* Plan
każdy
* Czas
10 minut
## Cel
[Dział zatytułowany „Cel”](#cel)
Kibic z nagłówka trafia do meczów, kadry, aktualności i podstron klubu, a w nagłówku jest jeden wyraźny przycisk (bilety, zapisy, sponsoring).
## Zanim zaczniesz
[Dział zatytułowany „Zanim zaczniesz”](#zanim-zaczniesz)
* Podstrony, do których chcesz linkować ([Dodaj podstronę](/website/subpages/)).
* Lista pięciu, najwyżej siedmiu pozycji menu górnego. Dłuższe menu łamie się na telefonie.
## Krok po kroku w panelu
[Dział zatytułowany „Krok po kroku w panelu”](#krok-po-kroku-w-panelu)
1. Otwórz **Strona www > Menu** (`/app/menu`). Na górze jest schemat strony z licznikami pozycji w każdym obszarze: **Menu Górne**, **TOP - Przyciski**, **Stopka**, **Menu dolne (mobile)**, **Blok - linki**.
2. Kliknij obszar, np. **Menu Górne**, potem **+ Dodaj pozycję menu**.
3. Wpisz nazwę i wybierz **jeden** cel:
* **Moduł** - gotowa strona Sportigio: Aktualności, Terminarz i Wyniki, Terminarz, Wyniki, Tabela (wskaż ligę), Zawodnicy (opcjonalnie drużyna), Galerie, Lista Video, Sponsorzy, Kalendarz, Oferta reklamowa, Wsparcie klubu, Klub biznesu;
* **Podstrona** - strona z **Treści > Strony**;
* **Własny adres** - pełny URL albo ścieżka względna, np. `/tickets`.
4. Zapisz. Pozycja pojawia się na liście z akcjami: **+** (dodaj pozycję podrzędną, czyli rozwijane podmenu), strzałki góra/dół (kolejność), **Edytuj**, kosz.
5. Przełącz zakładkę **TOP - Przyciski** i dodaj jeden przycisk akcji, np. **Zostań sponsorem** do podstrony sponsoringu albo **Bilety** do `/tickets`.
6. W **Stopce** powtórz najważniejsze linki: O klubie, Kontakt, Partnerzy.
### Zobacz na ekranie
[Dział zatytułowany „Zobacz na ekranie”](#zobacz-na-ekranie)
[Twoja przeglądarka nie odtwarza wideo. Pobierz GIF.](/media/uc-005/uc-005-add-menu-item.gif)
**Krok 2** - przycisk **+ Dodaj pozycję menu** nad listą.
**Krok 3** - cel pozycji: tu **Moduł** i wybór **Galerie Zdjęć** z listy. Tytuł wypełnia się sam.
**Krok 3** - własny tytuł zamiast podpowiedzianego.
**Krok 4** - **Zapisz** na dole panelu.
**Efekt** - nowa pozycja na końcu listy, od razu widoczna na stronie.
## Efekt
[Dział zatytułowany „Efekt”](#efekt)
Nagłówek pokazuje menu górne i przycisk, stopka swoje linki. Na telefonie menu składa się w hamburger; **Menu dolne (mobile)** to osobny pasek na dole ekranu, jeśli go wypełnisz.
## Przez API / MCP
[Dział zatytułowany „Przez API / MCP”](#przez-api--mcp)
| Krok | Narzędzie |
| ---------------------------------------- | ------------------------------------------------------------------------------------------- |
| Aktualne menu i lista dostępnych modułów | `list_menu_items` |
| Nowa pozycja | `create_menu_item {title, area: top\|buttons\|footer\|links, url \| infopage_id \| module}` |
| Podmenu | `create_menu_item {..., parent_id}` (tylko w obszarze `top`, jeden poziom) |
| Edycja | `update_menu_item {id, ...}` |
| Kolejność w jednym obszarze albo podmenu | `reorder_menu_items {area, ids, parent_id?}` |
| Usunięcie | `delete_menu_item {id}` |
Cel pozycji to dokładnie jedno z: `url`, `infopage_id`, `module`. Moduł `standing` wymaga `league_id`, moduł `players` przyjmuje `club_id` konkretnej drużyny.
## Pułapki
[Dział zatytułowany „Pułapki”](#pułapki)
* **Link do wyłączonego modułu znika ze strony**, choć jest na liście w panelu. Stan modułu wygrywa z widocznością linku - włącz moduł w **Ustawienia > Aktywne moduły**.
* **Menu dolne (mobile)** i **Blok - linki** są puste u nowego klubu i nie muszą być wypełnione. Blok linków to osobna sekcja profilu, nie strony [WWW](http://WWW).
* Link do Strefy Kibica ma być prawdziwą ścieżką (`/fan/typer`), nigdy `#`.
* Podmenu ma jeden poziom. Trzeci poziom nie istnieje.
## Zobacz też
[Dział zatytułowany „Zobacz też”](#zobacz-też)
* [Dodaj podstronę](/website/subpages/)
* [Ułóż stronę główną z sekcji](/website/homepage-sections/)
# Opublikuj stronę klubu
> Adres klubu, co otwiera się pod domeną główną, włączenie strony WWW i podpięcie własnej domeny.
* Scenariusz
UC-002
* Plan
LITE lub wyższy (publikacja WWW i własna domena)
* Czas
10 minut
## Cel
[Dział zatytułowany „Cel”](#cel)
Kibic wpisuje adres klubu i widzi stronę WWW, a nie ekran “w budowie” ani pusty profil.
## Zanim zaczniesz
[Dział zatytułowany „Zanim zaczniesz”](#zanim-zaczniesz)
* Plan **LITE** lub wyższy. Na planie FREE przełącznik strony WWW pokazuje informację o planie.
* [Pierwsze kroki](/getting-started/first-steps/): nazwa, logo, kolory.
* Co najmniej jedna sekcja na stronie głównej, inaczej strona będzie pusta ([Ułóż stronę główną z sekcji](/website/homepage-sections/)).
## Krok po kroku w panelu
[Dział zatytułowany „Krok po kroku w panelu”](#krok-po-kroku-w-panelu)
1. Otwórz **Ustawienia > Udostępnianie** (`/admin/sharing`).
2. **Adres klubu**: sprawdź subdomenę w polu **Adres Sportigio** (`nazwa.sportigio.com`). Dozwolone są małe litery, cyfry i myślniki. Ten adres zostaje z klubem na stałe.
3. **Strona główna**: wybierz, co otwiera się pod adresem klubu. Dla strony WWW zaznacz **Strona WWW**. Pozostałe powierzchnie zachowują swoje podadresy: `/bio`, `/www`, `/hub`.
4. **Twoje strony**: włącz przełącznik przy **Strona WWW**. Obok jest publiczny adres, pod którym strona będzie dostępna.
5. **Własna domena** (opcjonalnie): włącz **Użyj własnej domeny dla strony www** i wpisz domenę, np. `www.klub.pl`. Rekordy DNS ustawia zespół Sportigio po zgłoszeniu - klub nie ma zakładki do DNS.
6. Kliknij **Zapisz ustawienia udostępniania**. Panel przekierowuje na adres klubu i loguje Cię automatycznie, więc od razu widzisz efekt.
## Efekt
[Dział zatytułowany „Efekt”](#efekt)
* Adres klubu otwiera stronę [WWW](http://WWW). Profil (link in bio) dalej działa pod `/bio`.
* W **Strona www > Przegląd** (`/app/settings/website`) domena ma status **Opublikowane**.
* Prawy górny róg panelu (ikona oka) otwiera podgląd strony.
## Przez API / MCP
[Dział zatytułowany „Przez API / MCP”](#przez-api--mcp)
| Krok | Narzędzie |
| ------------------------------- | ---------------------------------------------------------------- |
| Stan publikacji i liczba sekcji | `get_website_status` |
| Włącz stronę | `set_website_published {published: true}` |
| Co otwiera adres klubu | `set_default_landing {landing: "website"}` (`bio`, `hub`, `app`) |
| Zgłoszenie własnej domeny | `report_support_issue` z nazwą domeny |
Subdomeny i własnej domeny nie da się ustawić przez API. Agent ma wskazać **Ustawienia > Udostępnianie** albo zgłosić domenę do wsparcia.
## Pułapki
[Dział zatytułowany „Pułapki”](#pułapki)
* **Bez publikacji kibic widzi “w budowie”**, mimo że `/tickets` i portale już działają.
* **Domyślnym landingiem nowego klubu jest profil (bio)**, nie strona [WWW](http://WWW). Pusty profil to najgorsze pierwsze wrażenie - ustaw stronę główną świadomie.
* **Dwa przełączniki, jedno słowo “publikacja”.** Narzędzie `set_website_published` ustawia publiczną widoczność przestrzeni, a przełącznik **Strona WWW** w Udostępnianiu włącza produkt. Po pracy przez API sprawdź w panelu, czy przełącznik jest włączony. Rozbieżność jest zgłoszona do ujednolicenia.
* Własna domena na planie FREE pokazuje plakietkę **LITE** i wraca do adresu platformowego.
* Zmiana subdomeny zmienia też adresy w kodach QR i materiałach, które klub już rozdał.
## Zobacz też
[Dział zatytułowany „Zobacz też”](#zobacz-też)
* [Ułóż stronę główną z sekcji](/website/homepage-sections/)
* [Ustaw wygląd strony](/website/appearance/)
* [Zbuduj menu strony](/website/menu/)
# Zmień kolejność sekcji na stronie głównej
> Przesuń sekcję strony głównej wyżej albo niżej strzałkami w edytorze, np. aktualności nad mecze.
* Scenariusz
UC-016
* Plan
każdy
* Czas
1 minuta
## Cel
[Dział zatytułowany „Cel”](#cel)
Kibic widzi na stronie głównej najpierw to, co klub uważa za najważniejsze, np. aktualności nad meczami.
## Zanim zaczniesz
[Dział zatytułowany „Zanim zaczniesz”](#zanim-zaczniesz)
Sekcje, które chcesz przestawić, są już na stronie głównej. Jak je dodać: [Ułóż stronę główną z sekcji](/website/homepage-sections/).
## Krok po kroku w panelu
[Dział zatytułowany „Krok po kroku w panelu”](#krok-po-kroku-w-panelu)
1. Otwórz **Strona www** i kliknij **Otwórz edytor strony głównej** (`/app/page-blocks`).
2. Po prawej jest lista sekcji w tej kolejności, w jakiej widać je na stronie: **1 Mecze**, **2 Aktualności**, **3 Skład** itd.
3. Przy sekcji, którą chcesz przesunąć, kliknij strzałkę w dół albo w górę. Jedno kliknięcie zamienia ją miejscami z sąsiednią sekcją.
4. Zmiana zapisuje się od razu. Nie ma przycisku **Zapisz**.
5. Odśwież stronę główną klubu i sprawdź nową kolejność.
### Zobacz na ekranie
[Dział zatytułowany „Zobacz na ekranie”](#zobacz-na-ekranie)
[Twoja przeglądarka nie odtwarza wideo. Pobierz MP4.](/media/uc-016/uc-016-reorder-sections.mp4)
| Czas | Na ekranie |
| ---- | --------------------------------------------------------------------------------------------------------- |
| 0:00 | Strona główna klubu: sekcja Mecze jest nad Aktualnościami. |
| 0:04 | Panel: **Strona www**, przycisk **Otwórz edytor strony głównej**. |
| 0:10 | Edytor: lista sekcji **Nagłówek**, **Slider - Aktualności**, **1 Mecze**, **2 Aktualności**, **3 Skład**. |
| 0:14 | Przy sekcji Mecze kliknięta strzałka w dół. Aktualności wskakują na 1. miejsce. |
| 0:19 | Odświeżona strona główna: Aktualności są nad Meczami. |
## Przez API / MCP
[Dział zatytułowany „Przez API / MCP”](#przez-api--mcp)
| Krok | Narzędzie |
| ---------------------------------- | ------------------------------------------------------------------- |
| Aktualna lista sekcji z id | `list_page_blocks` |
| Jedna sekcja tuż nad albo pod inną | `move_page_block {id, reference_id, position: "after" \| "before"}` |
| Pełna kolejność wszystkich sekcji | `reorder_page_blocks {ids}` |
Agent zawsze pobiera świeżą listę `list_page_blocks` tuż przed przesunięciem. Sekcje rozpoznaje po `content_type` (aktualności to `news`, mecze to `games_last_next`). Do przesunięcia jednej sekcji wystarczy `move_page_block` - nie wymaga pełnej listy id.
## Zobacz też
[Dział zatytułowany „Zobacz też”](#zobacz-też)
* [Ułóż stronę główną z sekcji](/website/homepage-sections/)
* [Ustaw wygląd strony](/website/appearance/)
# Dodaj podstronę
> Strony informacyjne - O klubie, Kontakt, regulaminy, oferta - z edytorem treści, okładką, adresem i widocznością.
* Scenariusz
UC-006
* Plan
każdy (liczba podstron zależy od planu)
* Czas
10 minut
## Cel
[Dział zatytułowany „Cel”](#cel)
Klub ma podstrony “O klubie”, “Kontakt”, “Zostań sponsorem” pod czytelnymi adresami i podpięte w menu.
## Zanim zaczniesz
[Dział zatytułowany „Zanim zaczniesz”](#zanim-zaczniesz)
* Tekst podstrony. Wystarczy kilka akapitów i nagłówki drugiego poziomu.
* Opcjonalnie zdjęcie na okładkę (poziome).
## Krok po kroku w panelu
[Dział zatytułowany „Krok po kroku w panelu”](#krok-po-kroku-w-panelu)
1. Otwórz **Treści > Strony** (`/app/infopages`). Zakładki: **Własne** (Twoje podstrony), **Domyślne** (strony systemowe, np. regulaminy portali), **Bazy danych** (mini-bazy do list na stronie).
2. Kliknij **+ Nowa Strona**.
3. Wpisz **Tytuł**. Adres (slug) powstaje z tytułu; możesz go zmienić przed pierwszą publikacją. Slug wchodzi wprost do adresu: `/o-klubie`.
4. Wpisz treść w edytorze (nagłówki, listy, linki, obrazy). Dla dłuższych stron używaj nagłówków H2 - przeglądarka i agent AI lepiej czytają strukturę.
5. Opcjonalnie wgraj **okładkę** i ustaw **widoczność**: publiczna, tylko dla zalogowanych albo tylko dla członków z pakietem (osoba bez dostępu widzi zajawkę i przycisk).
6. Zapisz. Na liście każda strona ma ikony: podgląd, udostępnij (link i QR), więcej.
7. Dodaj stronę do menu: [Zbuduj menu strony](/website/menu/).
## Efekt
[Dział zatytułowany „Efekt”](#efekt)
Podstrona jest dostępna pod `adres-klubu/slug`, z nagłówkiem strony w stylu z [ustawień wyglądu](/website/appearance/) i w menu, jeśli ją tam dodałeś.
## Przez API / MCP
[Dział zatytułowany „Przez API / MCP”](#przez-api--mcp)
| Krok | Narzędzie |
| --------------------------------------------- | ------------------------------------------------------------------------- |
| Lista podstron (id, tytuł, slug) | `list_infopages` |
| Nowa podstrona | `create_infopage {title, content (HTML), slug?, photo_url?, visibility?}` |
| Treść jednej strony | `get_infopage {id}` |
| Zmiana tytułu, treści, okładki | `update_infopage {id, ...}` |
| Podstrona sponsorów z gotową sekcją logotypów | `create_sponsors_page` |
| Podstrona z listą z mini-bazy | `create_database_page {database_id}` |
Treść to gotowy HTML bez `` i ``. Okładka z `photo_url` musi być publicznym adresem https.
## Pułapki
[Dział zatytułowany „Pułapki”](#pułapki)
* **Zmiana slugu po publikacji psuje linki** rozdane w social mediach i na drukach.
* **Strona nie jest widoczna, dopóki nie ma jej w menu** albo nie podlinkujesz jej z sekcji. Sam zapis nie dodaje pozycji menu.
* Podstrona z widocznością “członkowie” bez aktywnych pakietów członkowskich pokazuje wszystkim tylko zajawkę.
* Liczba podstron jest limitowana planem; przy limicie przycisk **+ Nowa Strona** pokazuje informację o planie.
## Zobacz też
[Dział zatytułowany „Zobacz też”](#zobacz-też)
* [Zbuduj menu strony](/website/menu/)
* [Dodaj sponsora](/content/sponsors/)