Plan i architektura bazy wiedzy

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

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

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

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) i metadanymi we frontmatterze:

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ą

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).
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

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: 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

Zmiana funkcji w club-web = zmiana strony w bazie w tym samym tygodniu (prompt aktualizacji).
Nowa strona najpierw po polsku, z datą verified. EN i DE mogą wejść osobnym PR-em.
Zrzuty ekranu tylko z klubu demo, w trybie jasnym, bez paska debugowania i banerów.
Nazwy z interfejsu, nie z kodu. Kod zostaje w sources.
Żadnych liczb i cen z pamięci - tylko z config/plans.php albo z produkcji.