@hexah/create-skin 0.1.5 → 0.1.6

package/README.md

@@ -38,7 +38,7 @@ localStorage.setItem('hexah.skinRemote', JSON.stringify({
   entry: 'https://<rand>.trycloudflare.com/remoteEntry.js',
   template: 'sdkremote',
   screens: { report: './ReportScreen' },
-  apiVersion: '0.2.0',
+  apiVersion: '0.11.0',
 }))
 ```
 
@@ -46,13 +46,111 @@ Odśwież stronę, w **Ustawieniach Gry** wybierz motyw **„SDK Remote (zdalna
 ekran zgłoszeń — zobaczysz swój `ReportScreen` na realnych danych. Po każdej zmianie w `src/`
 odśwież stronę (remote przebuduje się przez HMR).
 
+## Budowanie motywu — co masz do dyspozycji
+
+Importuj **wyłącznie** z `@hexah/skin-sdk` (+ `react` i `@mui/*` jako współdzielone singletony
+hosta). Nie masz dostępu do kodu gry — host dostarcza w runtime read-modele danych, usługi
+platformy, prymitywy UI i ciężkie sloty. Kontrakt jest wersjonowany (`SKIN_API_VERSION`,
+obecnie **0.11.0**); deklarowane `apiVersion` musi mieć ten sam major i minor ≤ host.
+
+### Trzy sposoby na skórkę
+
+1. **Pojedynczy ekran** — komponent zarejestrowany pod kluczem z `SCREEN_KEYS`. W
+   `rspack.config.js` wystawiasz go (`exposes`), w configu `localStorage` mapujesz na klucz
+   (`screens: { report: './ReportScreen' }`). Host renderuje go w miejscu danej podstrony.
+2. **Rama całej strony (layout/chrome)** — komponent dostaje `children` (aktywny ekran) i owija
+   go własnym paskiem/nawigacją/stopką. Wystawiasz np. `./SkinFrame` i podajesz w configu
+   `layout: './SkinFrame'`. Możesz dać samą ramę, same ekrany, albo jedno i drugie. Tutorial:
+   [`docs/skin-sdk/tutorial-frame.md`](https://github.com/Kroniki-Fallathanu/hexah/blob/develop/docs/skin-sdk/tutorial-frame.md).
+3. **Rozmieszczanie slotów** — ciężkie fragmenty z logiką/danymi (np. mapa świata, statystyki
+   zgłoszeń) renderuje host; Ty pobierasz je gotowe przez `useSlots()` i tylko ustawiasz w layoutcie.
+
+### Konwencja read-modeli
+
+Każdy read-model to hook zwracający obiekt metod. Metoda przyjmuje **jeden obiekt opcji** z
+polem `callback` (odbiera odpowiedź socketu) — pozostałe pola lecą do hosta jako `data`:
+
+```jsx
+const reports = useReports()
+reports.list({ page: 1, pageSize: 10, callback: (ret) => {
+  if (ret?.error) return
+  setIssues(ret.issues) // kształt zwrotki zależy od metody
+}})
+```
+
+### Hooki danych (jeden na podstronę menu)
+
+| Hook | Podstrona | Metody |
+| --- | --- | --- |
+| `useArticles` | Terminal / Aktualności / Kurier | `list`, `getBySlug`, `recordView`, `markKurierRead`, `listComments`, `createComment`, `toggleReaction` |
+| `useGptThreads` | Harold (GPT) | `list`, `get`, `create`, `remove`, `sendMessage` |
+| `useTales` | Operacje (opowieści) | `list`, `search`, `get`, `getFavorites`, `getPreferences`, `togglePreference`, `join`, `leave`, `toggleSubscribe`, `checkSubscribe` |
+| `useInn` | Mesa (karczma) | `listTales`, `getMembersCount` |
+| `useTown` | Metropolia (budynki) | `bankSend`, `innRest`, `innBuyTravelerKit`, `healerPlantsList`, `healerHeal`, `voltarToolsList`, `voltarBuy`, `hallTypes`, `hallPriceList`, `hallBuy`, `workshopPlansList`, `workshopPlanGet`, `workshopCraftItem`, `forgePlansList`, `forgePlanGet`, `forgeCraftMaterial`, `workPerform` |
+| `useGuild` | Frakcje (gildie) | `create`, `join`, `list`, `search`, `get`, `sendCrabs`, `headquartersRestInfo`, `headquartersRest`, `leave`, `getPermissions`, `specialActions`, `getProperties`, `hexmapPopulationTotal`, `hexmapMappingActivityMonth`, `provinceInfo`, `publicStats`, `hexmapPopulations`, `hexmapPopulationsByMember`, `warehouseGet`, `warehouseDeposit`, `warehouseYardWithdraw`, `materialsGet`, `materialsDonate`, `materialsDistribute` |
+| `useFamily` | Dynastie (rody) | `create`, `list`, `get`, `getProperties`, `choseName`, `invite`, `acceptInvitation`, `removeMember`, `editMember`, `editSpouse`, `transferOwner`, `setPermission`, `changeDescription`, `npcAccessGrant`, `npcAccessRevoke`, `npcAccessList`, `depositCrabs`, `depositInfluencePoints` |
+| `useVillages` | Kolonie (osady) | `found`, `takeAbandoned`, `get`, `list`, `buildCreate`, `buildCost`, `buildUpgrade`, `buildDemolish`, `buildMove`, `buildResetAll`, `depositCrabs`, `withdrawCrabs`, `sendResourcesToGuild`, `abandon`, `rebellionResolve`, `taxesSet`, `governorAssign`, `techniqueList`, `techniqueUpgrade`, `hexDecorationsUpdate`, `nameUpdate` |
+| `useShop` | Zaopatrzenie (sklep) | `getOffers`, `getItems`, `buyItem`, `startPayment` |
+| `useRanking` | Notowania (rankingi) | `ranking`, `rankingExplorer` |
+| `useAccountProfile` | Profil (konto) | `getAccountInfo`, `getBlockedList`, `blockUser`, `unblockUser`, `linkDiscord`, `getGlobalStats` |
+| `useSettings` | Konfiguracja | `updateSetting`, `setInvisibleOnline`, `updateNewsletterSubscription` |
+| `useReports` | Zgłoszenia (bugtracker) | `list`, `markAllRead`, `setIssueNotification` |
+
+### Read-modele stanu (czytają aktywny stan, bez argumentów)
+
+`useShard()` · `useShardUser()` · `useCharacter()` · `useAccount()` · `usePageData()` ·
+`useOnlineCharacters()` — zwracają bieżące dane świata/postaci/konta (lub `null`, gdy brak).
+
+### Usługi platformy
+
+- `useSnackbar()` → `{ notify }` — `notify([{ severity, message }])` pokazuje powiadomienie hosta.
+- `useDialog()` → `{ open, close }` — modal hosta (`open(config)` / `close()`).
+- `useGamePageShell({ title })` — ustawia tytuł/powłokę strony (wołaj w `useMemo`, jak w przykładzie).
+
+### Prymitywy UI (motywowalne komponenty MUI hosta)
+
+`PageBox` (kontener strony, pełna wysokość) · `HexahCharacterSection` · `AngularPanel` ·
+`StandardButton` (tekst ≤ 16 znaków) · `RoundAvatar` · `DataList` (lista wierszy z opisem/akcją) ·
+`HexahChip` · `HexahPagination` + `HexahPaginationItem`. Poza nimi używaj zwykłego `@mui/material`
+(`Box`, `Typography`, …) — to też instancja hosta.
+
+### Sloty (host renderuje, skórka rozmieszcza)
+
+```jsx
+import { useSlots, SLOT_KEYS } from '@hexah/skin-sdk'
+const slots = useSlots()
+const WorldMap = slots[SLOT_KEYS.WORLD_MAP]
+return WorldMap ? <WorldMap /> : null   // łagodna degradacja, gdy host nie dostarcza slotu
+```
+
+Zarejestrowane: `WORLD_MAP` (Mapa Sektora — mapa świata + ruiny), `ISSUE_STATS` (statystyki
+zgłoszeń). Zarezerwowane (jeszcze bez komponentu): `GAME_PAGE`, `ISSUE_RICH_CONTENT`,
+`ARTICLE_COMMENTS`, `ARTICLE_ISSUE_GRID`.
+
+### Stałe i utile
+
+- `SCREEN_KEYS` — klucze ekranów: `ARTICLE`, `KURIER`, `KURIER_REDAKCJA`, `KURIER_SKRZYNKA`,
+  `GPT_LIST`, `GPT_THREAD`, `REPORT`, `REPORT_DETAIL`, `ARTICLE_DETAIL`.
+- `SLOT_KEYS` — klucze slotów (jak wyżej). `DEFAULT_TEMPLATE` · `SKIN_API_VERSION`.
+- Utile nawigacji ekranu zgłoszeń (czyste funkcje): `buildReportListHref`, `buildReportDetailHref`,
+  `buildReportBackHref`, `parseReportListPage`, `parseReportStateFilter`, `parseReportTypeFilter`,
+  `parseReportMineFilter`, `parseReportPlannedFilter`; style chipów: `getStateChipSx`,
+  `getIssueTypeChipSx`.
+
+> Pełna mapa „podstrona menu → hook/slot" i decyzje projektowe:
+> [`docs/skin-sdk/data-hooks.md`](https://github.com/Kroniki-Fallathanu/hexah/blob/develop/docs/skin-sdk/data-hooks.md).
+
 ## Co generuje
 
 Gotowy projekt skórki:
 
-- `rspack.config.js` — `ModuleFederationPlugin` wystawiający `./ReportScreen`, paczki
-  współdzielone z hostem (`import: false`), dev server na `:3001` (CORS + `allowedHosts`).
-- `src/ReportScreen.jsx` — przykładowy ekran zbudowany na `@hexah/skin-sdk`.
+- `rspack.config.js` — `ModuleFederationPlugin` wystawiający ramę i ekrany, paczki współdzielone
+  z hostem (`import: false`), dev server na `:3001` (CORS + `allowedHosts`).
+- `src/SkinFrame.jsx`, `src/ReportScreen.jsx`, `src/ArticleScreen.jsx`, `src/GptListScreen.jsx` —
+  gotowe wzorce (rama całej strony + ekrany) na `@hexah/skin-sdk`.
+- `src/examples/` — referencja: wywołania pozostałych read-modeli danych i slotów (do kopiowania).
+- **`AGENTS.md` + `CLAUDE.md`** — zasady i granice dla asystentów AI (import tylko z SDK, brak
+  dostępu do kodu/backendu gry, współdzielone singletony). AI czyta je automatycznie.
 - `package.json`, `.gitignore`, `README.md` z instrukcją podłączenia do środowiska testowego.
 
 Nazwa kontenera Module Federation jest automatycznie sanityzowana z nazwy katalogu do

package/index.js

@@ -45,11 +45,13 @@ function main(argv) {
   console.log(
     "    entry: 'http://localhost:3001/remoteEntry.js', template: 'sdkremote',",
   );
-  console.log("    screens: { report: './ReportScreen' }, apiVersion: '0.2.0' }))");
+  console.log("    screens: { report: './ReportScreen' }, apiVersion: '0.11.0' }))");
   console.log("Zdeployowany test (https) wymaga publicznego URL — odpal tunel:");
   console.log("  npx cloudflared tunnel --url http://localhost:3001   # → https://<rand>.trycloudflare.com");
   console.log("i użyj tego URL w entry + hexah.skinRemoteAllowedOrigins. Patrz README.");
   console.log("Następnie w Ustawieniach Gry wybierz motyw „SDK Remote (zdalna skórka)\".");
+  console.log("");
+  console.log("Używasz AI (Claude/Cursor/Copilot)? Zasady i granice skórki są w AGENTS.md — wskaż je asystentowi.");
   return 0;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexah/create-skin",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Scaffolder skórki Hexah (zdalny kontener Module Federation, harness dev z HMR).",
   "bin": {
     "create-hexah-skin": "index.js"

package/template/AGENTS.md

@@ -0,0 +1,95 @@
+# AGENTS.md — zasady dla asystentów AI (skórka „__SKIN_NAME__")
+
+Ten plik czyta asystent AI (Claude Code, Cursor, Copilot i in.) pracujący w tym repozytorium.
+Trzymaj się go ściśle — wyznacza **twarde granice** skórki Hexah. Jeśli prośba użytkownika
+łamie te zasady, powiedz to wprost zamiast obchodzić regułę.
+
+## Czym jest ten projekt
+
+To **skórka (motyw) gry Hexah** zbudowana jako **zdalny kontener Module Federation** (rspack).
+Nie jest samodzielną aplikacją: ładuje ją działający host Hexah w runtime i renderuje Twoje
+komponenty wewnątrz gry. Budujesz **wyłącznie** na publicznym kontrakcie `@hexah/skin-sdk` —
+**nie masz i nie będziesz mieć dostępu do kodu gry (hosta)**.
+
+## Twarde granice (nie do złamania)
+
+1. **Importuj tylko z `@hexah/skin-sdk`** (oraz `react`, `react-dom`, `@mui/*`, `@emotion/*`,
+   `jotai`). **Nigdy** nie importuj z wnętrza gry (`@/...`, `frontend/...`, ścieżki hosta) —
+   takie moduły nie istnieją w buildzie skórki. Nie wymyślaj eksportów z SDK: jeśli czegoś nie
+   ma w `@hexah/skin-sdk`, to nie jest dostępne.
+2. **Nie pakuj współdzielonych bibliotek.** `react`/`react-dom`/`jotai`/`@mui/*`/`@emotion/*`/
+   `@hexah/skin-sdk` są w `rspack.config.js` jako `shared` z `import: false` (singletony hosta).
+   Nie zmieniaj tego na bundlowanie — dwa Reacty/store'y rozsypią aplikację.
+3. **Nie obchodź backendu gry.** Dane bierz **wyłącznie** z read-modeli SDK (`useReports`,
+   `useArticles`, …). Zakaz: własny `fetch`/`axios`/WebSocket do API gry, własny klient socket,
+   czytanie cookie/tokenów sesji, scrapowanie globalnego stanu.
+4. **Nie zaglądaj do wnętrza slotów.** Ciężkie fragmenty (mapa, statystyki) dostajesz jako
+   gotowe komponenty przez `useSlots()` — renderuje je host. Nie próbuj odtwarzać ich logiki ani
+   sięgać po ich dane.
+5. **`apiVersion` zgodne z hostem** (ten sam major, minor ≤ host). Nie podbijaj go „na zapas".
+6. **Zero sekretów w repo** (klucze, tokeny). Skórka jest publiczna i ładowana w przeglądarce.
+7. **Nie zakładaj nawigacji/motywu hosta.** Linki to zwykłe publiczne trasy `/game/*`. Routing,
+   motyw (kolory/spacing) i powłokę kontroluje host — używaj tokenów MUI (`sx`, `theme`), nie
+   hardkoduj kolorów/pikseli.
+
+## Powierzchnia, na której wolno budować
+
+- **Read-modele danych** (jeden hook na podstronę menu): `useArticles`, `useGptThreads`,
+  `useTales`, `useInn`, `useTown`, `useGuild`, `useFamily`, `useVillages`, `useShop`,
+  `useRanking`, `useAccountProfile`, `useSettings`, `useReports`.
+- **Read-modele stanu**: `useShard`, `useShardUser`, `useCharacter`, `useAccount`, `usePageData`,
+  `useOnlineCharacters`.
+- **Usługi platformy**: `useSnackbar` (`{ notify }`), `useDialog` (`{ open, close }`),
+  `useGamePageShell({ title })`.
+- **Prymitywy UI**: `PageBox`, `HexahCharacterSection`, `AngularPanel`, `StandardButton`
+  (tekst ≤ 16 znaków), `RoundAvatar`, `DataList`, `HexahChip`, `HexahPagination`,
+  `HexahPaginationItem`. Poza nimi zwykłe `@mui/material`.
+- **Sloty**: `useSlots()` + `SLOT_KEYS` (`WORLD_MAP`, `ISSUE_STATS`, …).
+- **Stałe**: `SCREEN_KEYS`, `SLOT_KEYS`, `DEFAULT_TEMPLATE`, `SKIN_API_VERSION`.
+
+> Pełna lista metod każdego hooka i opis API: README scaffolderu `@hexah/create-skin`
+> (sekcja „Budowanie motywu — co masz do dyspozycji") oraz README paczki `@hexah/skin-sdk`.
+> Najpierw sprawdź te dokumenty — nie zgaduj sygnatur.
+
+## Konwencja read-modeli
+
+Hook zwraca obiekt metod. Metoda przyjmuje **jeden obiekt opcji** z polem `callback`; pozostałe
+pola lecą do hosta jako `data`. Kształt zwrotki (`ret`) zależy od metody — najczęściej
+`{ results, pagination }` albo `{ error }`. Zawsze obsłuż `ret?.error` (np. przez `useSnackbar`).
+
+```jsx
+const articles = useArticles()
+articles.list({ page: 1, pageSize: 10, callback: (ret) => {
+  if (ret?.error) { notify([{ severity: 'error', message: ret.error }]); return }
+  setItems(ret.results || [])
+}})
+```
+
+## Trzy sposoby budowania skórki
+
+1. **Ekran** — komponent pod kluczem z `SCREEN_KEYS`. Wystaw w `rspack.config.js` → `exposes`,
+   zmapuj w configu `screens: { report: './ReportScreen' }`. Przykłady: `src/ReportScreen.jsx`,
+   `src/ArticleScreen.jsx`, `src/GptListScreen.jsx`.
+2. **Rama całej strony (chrome)** — komponent dostaje `children` (aktywny ekran) i owija go
+   paskiem/nawigacją/stopką. Wystaw `./SkinFrame`, podaj `layout: './SkinFrame'`. Przykład:
+   `src/SkinFrame.jsx`.
+3. **Rozmieszczanie slotów** — `const Map = useSlots()[SLOT_KEYS.WORLD_MAP]; return Map ? <Map/> : null`.
+   Zawsze degraduj łagodnie, gdy slot jest `undefined`. Przykłady: `src/examples/slots.jsx`.
+
+Wzorce wszystkich pozostałych read-modeli: `src/examples/dataHooks.jsx` (referencja do kopiowania).
+
+## Workflow i weryfikacja
+
+- Dev: `npm run dev` (rspack serve, HMR) → `remoteEntry.js` na `:3001`.
+- Test w grze: wystaw przez tunel (cloudflared), zautoryzuj origin i wskaż remote przez
+  `localStorage` na środowisku testowym — instrukcja w `README.md`.
+- Po zmianach upewnij się, że build przechodzi i import-checki trzymają granice z tego pliku.
+- Nie dodawaj zależności runtime, które dublują współdzielone singletony hosta.
+
+## Czego NIE robić (skrót)
+
+- ❌ import z kodu gry / „magiczne" eksporty SDK, których nie ma w dokumentacji
+- ❌ własny dostęp do backendu/socketów/sesji gry
+- ❌ bundlowanie react/jotai/@mui/@emotion/@hexah/skin-sdk
+- ❌ hardkodowane kolory/piksele zamiast tokenów MUI
+- ❌ sekrety w repo; podbijanie `apiVersion` ponad hosta

package/template/CLAUDE.md

@@ -0,0 +1,6 @@
+# CLAUDE.md
+
+Zasady i granice tego projektu (skórka Hexah) są w **[`AGENTS.md`](./AGENTS.md)** — przeczytaj je
+przed jakąkolwiek zmianą. W skrócie: importuj wyłącznie z `@hexah/skin-sdk` (+ React/MUI), nie
+sięgaj po kod gry ani jej backend, nie pakuj współdzielonych singletonów hosta. Pełna powierzchnia
+API: README scaffolderu `@hexah/create-skin` i README paczki `@hexah/skin-sdk`.

package/template/README.md

@@ -4,6 +4,10 @@ Skórka Hexah zbudowana jako **zdalny kontener Module Federation**. Renderuje si
 aplikacji Hexah na środowisku testowym — budujesz ją wyłącznie na publicznym SDK
 `@hexah/skin-sdk`, bez dostępu do kodu gry.
 
+> **Pracujesz z AI (Claude, Cursor, Copilot…)?** Zasady i granice skórki są w
+> [`AGENTS.md`](./AGENTS.md) (Claude czyta też `CLAUDE.md`). Wskaż ten plik asystentowi na starcie —
+> pilnuje, że skórka importuje tylko z `@hexah/skin-sdk` i nie sięga po kod ani backend gry.
+
 ## Start
 
 ```bash
@@ -31,22 +35,44 @@ localStorage.setItem('hexah.skinRemote', JSON.stringify({
   name: '__SKIN_FEDERATION_NAME__',
   entry: 'https://<rand>.trycloudflare.com/remoteEntry.js',
   template: 'sdkremote',
-  screens: { report: './ReportScreen' },
-  apiVersion: '0.2.0',
+  layout: './SkinFrame',          // rama całej strony (chrome) — opcjonalna
+  screens: {                      // ekrany pod kluczami SCREEN_KEYS — opcjonalne
+    report: './ReportScreen',
+    article: './ArticleScreen',
+    gptList: './GptListScreen',
+  },
+  apiVersion: '0.11.0',
 }))
 ```
 
-Odśwież, w **Ustawieniach Gry** wybierz motyw **„SDK Remote (zdalna skórka)"** i wejdź na ekran
-zgłoszeń — zobaczysz swój `ReportScreen` na realnych danych. HMR pokazuje zmiany w `src/` po
-odświeżeniu (i ponownym pobraniu remote'a).
+Odśwież, w **Ustawieniach Gry** wybierz motyw **„SDK Remote (zdalna skórka)"**. `SkinFrame` owinie
+wszystkie ekrany pod tym motywem, a `ReportScreen`/`ArticleScreen`/`GptListScreen` podmienią
+odpowiednie podstrony — na realnych danych. HMR pokazuje zmiany w `src/` po odświeżeniu (i ponownym
+pobraniu remote'a). Możesz podać samą `layout`, same `screens`, albo jedno i drugie.
 
 > Adres tunelu zmienia się po każdym restarcie cloudflared — wklej wtedy nowy URL w oba wpisy
 > `localStorage`.
 
 ## Co możesz edytować
 
-- `src/ReportScreen.jsx` — Twój ekran. Importuj wyłącznie z `@hexah/skin-sdk` (+ React/MUI).
-- `rspack.config.js` → `exposes` — dołóż kolejne ekrany (klucze z `SCREEN_KEYS`).
+Gotowe przykłady w `src/` (wystawione w `rspack.config.js` → `exposes`):
+
+- `src/SkinFrame.jsx` — **rama całej strony** (chrome): górny pasek + nawigacja + stopka, na
+  read-modelach stanu (`useCharacter`, `useShard`, `useShardUser`, `useOnlineCharacters`).
+- `src/ReportScreen.jsx` — ekran **Zgłoszeń** (`useReports` + `DataList`/`HexahChip`).
+- `src/ArticleScreen.jsx` — ekran **Aktualności** (`useArticles`).
+- `src/GptListScreen.jsx` — ekran **Harolda** (`useGptThreads` + `StandardButton`).
+
+Referencja (nie wystawiona — kopiuj do własnych ekranów):
+
+- `src/examples/dataHooks.jsx` — wywołanie **każdego** pozostałego read-modelu danych
+  (`useTales`, `useInn`, `useTown`, `useGuild`, `useFamily`, `useVillages`, `useShop`,
+  `useRanking`, `useAccountProfile`, `useSettings`).
+- `src/examples/slots.jsx` — sloty hosta przez `useSlots()` (`WORLD_MAP`, `ISSUE_STATS`).
+
+Dokładasz własne ekrany w `rspack.config.js` → `exposes` i mapujesz je w configu na klucze
+`SCREEN_KEYS`. **Pełna referencja** (trzy sposoby budowania, tabela hooków z metodami, UI, sloty)
+jest w README scaffolderu `@hexah/create-skin`: <https://www.npmjs.com/package/@hexah/create-skin>.
 
 ## Zasady
 
@@ -66,9 +92,13 @@ npm install @hexah/skin-sdk
 ```
 
 - Paczka na npm (pełna lista hooków i kontrakt): <https://www.npmjs.com/package/@hexah/skin-sdk>
-- Hooki danych per strona gry (`useArticles`, `useTales`, `useTown`, `useGuild`, `useVillages`,
-  `useReports`, `useSettings`, `useShop`, `useAccountProfile`, `useGptThreads`), stan
-  (`useShard`/`useCharacter`/…), usługi (`useSnackbar`/`useDialog`), sloty (`useSlots`) i
-  prymitywy UI — opis w README paczki.
+- Hooki danych per strona gry (`useArticles`, `useTales`, `useInn`, `useTown`, `useGuild`,
+  `useFamily`, `useVillages`, `useReports`, `useSettings`, `useShop`, `useAccountProfile`,
+  `useRanking`, `useGptThreads`), stan (`useShard`/`useCharacter`/…), usługi
+  (`useSnackbar`/`useDialog`), sloty (`useSlots`) i prymitywy UI.
+
+**Pełna referencja motywu** (trzy sposoby budowania, tabela hooków z metodami, prymitywy UI,
+sloty, stałe) jest w README scaffolderu `@hexah/create-skin` → sekcja **„Budowanie motywu — co
+masz do dyspozycji"**: <https://www.npmjs.com/package/@hexah/create-skin>.
 
 Importuj **wyłącznie** z `@hexah/skin-sdk`. Zadeklarowane `apiVersion` musi być zgodne z hostem.

package/template/rspack.config.js

@@ -39,7 +39,15 @@ module.exports = {
     new ModuleFederationPlugin({
       name: "__SKIN_FEDERATION_NAME__",
       filename: "remoteEntry.js",
-      exposes: { "./ReportScreen": "./src/ReportScreen.jsx" },
+      // Wystawione moduły skórki. Ekrany mapujesz w configu na klucze `SCREEN_KEYS`
+      // (`screens: { report: './ReportScreen', article: './ArticleScreen', ... }`), a ramę
+      // całej strony na pole `layout` (`layout: './SkinFrame'`). Dorzuć kolejne wg potrzeb.
+      exposes: {
+        "./SkinFrame": "./src/SkinFrame.jsx",
+        "./ReportScreen": "./src/ReportScreen.jsx",
+        "./ArticleScreen": "./src/ArticleScreen.jsx",
+        "./GptListScreen": "./src/GptListScreen.jsx",
+      },
       shared: {
         react: singleton("^19"),
         "react-dom": singleton("^19"),

package/template/src/ArticleScreen.jsx

@@ -0,0 +1,74 @@
+/**
+ * PRZYKŁAD ekranu Aktualności — rejestrowany pod `SCREEN_KEYS.ARTICLE`
+ * (config: `screens: { article: './ArticleScreen' }`).
+ *
+ * Pokazuje read-model `useArticles` (lista artykułów) + prymitywy UI hosta (`PageBox`,
+ * `DataList`, `HexahChip`) + `useGamePageShell` (tytuł strony). Konwencja read-modeli:
+ * metoda dostaje obiekt opcji z `callback`, reszta pól leci do hosta jako `data`.
+ */
+import { useEffect, useMemo, useState } from "react";
+import Box from "@mui/material/Box";
+import Typography from "@mui/material/Typography";
+import {
+  PageBox,
+  DataList,
+  HexahChip,
+  useArticles,
+  useSnackbar,
+  useGamePageShell,
+} from "@hexah/skin-sdk";
+
+export default function ArticleScreen() {
+  const articles = useArticles();
+  const { notify } = useSnackbar();
+  const [items, setItems] = useState([]);
+  useGamePageShell(useMemo(() => ({ title: "Aktualności (__SKIN_NAME__)" }), []));
+
+  useEffect(() => {
+    articles.list({
+      page: 1,
+      pageSize: 10,
+      callback: (ret) => {
+        if (ret?.error) {
+          notify([{ severity: "error", message: ret.error }]);
+          return;
+        }
+        setItems(ret.results || []);
+      },
+    });
+  }, [articles, notify]);
+
+  const rows = useMemo(
+    () =>
+      items.map((article) => ({
+        id: article.id,
+        title: article.title,
+        icon: article.cover?.url,
+        chips: article.pinned ? (
+          <HexahChip label="Przypięte" size="small" />
+        ) : null,
+        // Nawigacja do szczegółu to zwykły link do publicznej trasy gry.
+        rowClick: () => {
+          window.location.href = `/game/article/${article.slug}`;
+        },
+      })),
+    [items],
+  );
+
+  return (
+    <PageBox>
+      <Box sx={{ px: { xs: 2, sm: 3 }, pt: 2 }}>
+        <Typography variant="body2" sx={{ mb: 2, opacity: 0.8 }}>
+          Aktualności na realnych danych hosta (read-model `useArticles`).
+        </Typography>
+        {rows.length === 0 ? (
+          <Typography color="primary" sx={{ py: 2 }}>
+            Brak artykułów do wyświetlenia.
+          </Typography>
+        ) : (
+          <DataList itemsList={rows} />
+        )}
+      </Box>
+    </PageBox>
+  );
+}

package/template/src/GptListScreen.jsx

@@ -0,0 +1,87 @@
+/**
+ * PRZYKŁAD ekranu wątków Harolda (GPT) — rejestrowany pod `SCREEN_KEYS.GPT_LIST`
+ * (config: `screens: { gptList: './GptListScreen' }`).
+ *
+ * Pokazuje read-model `useGptThreads` (lista + tworzenie wątku), usługę `useDialog`
+ * (modal hosta) oraz prymityw `StandardButton` (tekst ≤ 16 znaków).
+ */
+import { useEffect, useMemo, useState } from "react";
+import Box from "@mui/material/Box";
+import Typography from "@mui/material/Typography";
+import {
+  PageBox,
+  DataList,
+  StandardButton,
+  useGptThreads,
+  useSnackbar,
+  useGamePageShell,
+} from "@hexah/skin-sdk";
+
+export default function GptListScreen() {
+  const gpt = useGptThreads();
+  const { notify } = useSnackbar();
+  const [threads, setThreads] = useState([]);
+  useGamePageShell(useMemo(() => ({ title: "Harold (__SKIN_NAME__)" }), []));
+
+  const reload = useMemo(
+    () => () =>
+      gpt.list({
+        page: 1,
+        pageSize: 20,
+        callback: (ret) => {
+          if (ret?.error) {
+            notify([{ severity: "error", message: ret.error }]);
+            return;
+          }
+          setThreads(ret.results || ret.threads || []);
+        },
+      }),
+    [gpt, notify],
+  );
+
+  useEffect(() => {
+    reload();
+  }, [reload]);
+
+  const startThread = () => {
+    gpt.create({
+      message: "Witaj, Haroldzie!",
+      callback: (ret) => {
+        if (ret?.error) {
+          notify([{ severity: "error", message: ret.error }]);
+          return;
+        }
+        reload();
+      },
+    });
+  };
+
+  const rows = useMemo(
+    () =>
+      threads.map((thread) => ({
+        id: thread.id,
+        title: thread.title || `Wątek #${thread.id}`,
+        rowClick: () => {
+          window.location.href = `/game/harold/${thread.id}`;
+        },
+      })),
+    [threads],
+  );
+
+  return (
+    <PageBox>
+      <Box sx={{ px: { xs: 2, sm: 3 }, pt: 2 }}>
+        <Box sx={{ display: "flex", justifyContent: "flex-end", mb: 2 }}>
+          <StandardButton onClick={startThread}>Nowy wątek</StandardButton>
+        </Box>
+        {rows.length === 0 ? (
+          <Typography color="primary" sx={{ py: 2 }}>
+            Brak wątków — załóż pierwszy.
+          </Typography>
+        ) : (
+          <DataList itemsList={rows} />
+        )}
+      </Box>
+    </PageBox>
+  );
+}

package/template/src/SkinFrame.jsx

@@ -0,0 +1,84 @@
+/**
+ * PRZYKŁAD: skórka jako RAMA CAŁEJ STRONY (chrome). Host renderuje aktywny ekran i podaje go
+ * jako `children` — skórka owija go własnym górnym paskiem, nawigacją i stopką. To podmienia
+ * cały layout gry pod Twoim szablonem (rejestrowane przez config z polem `layout: './SkinFrame'`).
+ *
+ * Pokazuje read-modele STANU: `useCharacter`, `useShard`, `useShardUser`, `useOnlineCharacters`.
+ * Importuj WYŁĄCZNIE z `@hexah/skin-sdk` (+ React/MUI). Nawigacja to zwykłe linki do tras
+ * `/game/*` (publiczne adresy) — nie masz dostępu do wewnętrznego routingu gry.
+ */
+import Box from "@mui/material/Box";
+import Typography from "@mui/material/Typography";
+import {
+  useCharacter,
+  useShard,
+  useShardUser,
+  useOnlineCharacters,
+} from "@hexah/skin-sdk";
+
+const NAV = [
+  ["/game/article", "Aktualności"],
+  ["/game/tale?filter=MojeAktywne", "Operacje"],
+  ["/game/town", "Metropolia"],
+  ["/game/guild", "Frakcje"],
+  ["/game/map", "Mapa"],
+  ["/game/rank", "Notowania"],
+];
+
+export default function SkinFrame({ children }) {
+  const character = useCharacter();
+  const shard = useShard();
+  const shardUser = useShardUser();
+  const online = useOnlineCharacters();
+
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", minHeight: "100vh" }}>
+      <Box
+        component="header"
+        sx={{
+          px: 3,
+          py: 1.5,
+          display: "flex",
+          alignItems: "center",
+          gap: 2,
+          flexWrap: "wrap",
+          bgcolor: "background.paper",
+          borderBottom: "2px solid",
+          borderColor: "primary.main",
+        }}
+      >
+        <Typography variant="h6" sx={{ fontWeight: 700 }}>
+          __SKIN_NAME__
+        </Typography>
+        <Box component="nav" sx={{ display: "flex", gap: 2, flex: 1, flexWrap: "wrap" }}>
+          {NAV.map(([href, label]) => (
+            <Typography
+              key={href}
+              component="a"
+              href={href}
+              variant="body2"
+              sx={{ textDecoration: "none", color: "text.primary" }}
+            >
+              {label}
+            </Typography>
+          ))}
+        </Box>
+        <Typography variant="caption" color="text.secondary">
+          {character?.name ?? "—"}
+          {shardUser?.user?.username ? ` (${shardUser.user.username})` : ""} ·{" "}
+          {shard?.name ?? ""} · online: {Array.isArray(online) ? online.length : 0}
+        </Typography>
+      </Box>
+
+      <Box component="main" sx={{ flex: 1 }}>
+        {children}
+      </Box>
+
+      <Box component="footer" sx={{ px: 3, py: 1, textAlign: "center", opacity: 0.6 }}>
+        <Typography variant="caption">
+          „__SKIN_NAME__" — rama całej strony (Skin SDK)
+        </Typography>
+      </Box>
+    </Box>
+  );
+}

package/template/src/examples/dataHooks.jsx

@@ -0,0 +1,133 @@
+/**
+ * KSIĄŻKA KUCHARSKA read-modeli danych (REFERENCJA — nieeksportowana w `rspack.config.js`).
+ *
+ * Te komponenty nie trafiają do builda, dopóki nie dodasz ich do `exposes` albo nie zaimportujesz
+ * z ekranu/ramy. Pokazują wywołanie KAŻDEGO pozostałego read-modelu danych z `@hexah/skin-sdk`.
+ * Wzorzec stały: hook zwraca obiekt metod; metoda dostaje obiekt opcji z `callback`, a pozostałe
+ * pola lecą do hosta jako `data`. Kształt zwrotki (`ret`) zależy od metody — najczęściej
+ * `{ results, pagination }` lub `{ error }`.
+ *
+ * Pełna lista metod każdego hooka: README scaffolderu `@hexah/create-skin`
+ * (sekcja „Budowanie motywu — co masz do dyspozycji").
+ */
+import { useEffect, useState } from "react";
+import Typography from "@mui/material/Typography";
+import {
+  useTales,
+  useInn,
+  useTown,
+  useGuild,
+  useFamily,
+  useVillages,
+  useShop,
+  useRanking,
+  useAccountProfile,
+  useSettings,
+} from "@hexah/skin-sdk";
+
+/** Operacje (opowieści): lista moich aktywnych. */
+export function TalesExample() {
+  const tales = useTales();
+  const [list, setList] = useState([]);
+  useEffect(() => {
+    tales.list({
+      filter: "MojeAktywne",
+      page: 1,
+      callback: (ret) => setList(ret?.results || []),
+    });
+  }, [tales]);
+  return <Typography>Opowieści: {list.length}</Typography>;
+}
+
+/** Mesa (karczma): opowieści karczmiane + licznik bywalców. */
+export function InnExample() {
+  const inn = useInn();
+  const [counts, setCounts] = useState({});
+  useEffect(() => {
+    inn.listTales({ page: 1, callback: () => {} });
+    inn.getMembersCount({ callback: (ret) => setCounts(ret || {}) });
+  }, [inn]);
+  return <Typography>Bywalców łącznie: {counts.countAll ?? 0}</Typography>;
+}
+
+/** Metropolia: lista planów warsztatu (przykład jednej z 17 akcji `useTown`). */
+export function TownExample() {
+  const town = useTown();
+  const [plans, setPlans] = useState([]);
+  useEffect(() => {
+    town.workshopPlansList({ callback: (ret) => setPlans(ret?.results || ret || []) });
+  }, [town]);
+  return <Typography>Plany warsztatu: {plans.length}</Typography>;
+}
+
+/** Frakcje (gildie): publiczna lista. */
+export function GuildExample() {
+  const guild = useGuild();
+  const [guilds, setGuilds] = useState([]);
+  useEffect(() => {
+    guild.list({ page: 1, callback: (ret) => setGuilds(ret?.results || ret || []) });
+  }, [guild]);
+  return <Typography>Frakcje: {guilds.length}</Typography>;
+}
+
+/** Dynastie (rody): lista rodów. */
+export function FamilyExample() {
+  const family = useFamily();
+  const [families, setFamilies] = useState([]);
+  useEffect(() => {
+    family.list({ callback: (ret) => setFamilies(ret?.results || ret || []) });
+  }, [family]);
+  return <Typography>Rody: {families.length}</Typography>;
+}
+
+/** Kolonie (osady): moje osady. */
+export function VillagesExample() {
+  const villages = useVillages();
+  const [list, setList] = useState([]);
+  useEffect(() => {
+    villages.list({ callback: (ret) => setList(ret?.results || ret || []) });
+  }, [villages]);
+  return <Typography>Kolonie: {list.length}</Typography>;
+}
+
+/** Zaopatrzenie (sklep): dostępne oferty premium. */
+export function ShopExample() {
+  const shop = useShop();
+  const [offers, setOffers] = useState([]);
+  useEffect(() => {
+    shop.getOffers({ callback: (ret) => setOffers(ret?.results || ret || []) });
+  }, [shop]);
+  return <Typography>Oferty: {offers.length}</Typography>;
+}
+
+/** Notowania: ranking główny z filtrami. */
+export function RankingExample() {
+  const ranking = useRanking();
+  const [rows, setRows] = useState([]);
+  useEffect(() => {
+    ranking.ranking({ page: 1, callback: (ret) => setRows(ret?.results || []) });
+  }, [ranking]);
+  return <Typography>Ranking — wpisów: {rows.length}</Typography>;
+}
+
+/** Profil (konto): informacje o koncie. */
+export function AccountProfileExample() {
+  const profile = useAccountProfile();
+  const [info, setInfo] = useState(null);
+  useEffect(() => {
+    profile.getAccountInfo({ callback: (ret) => setInfo(ret || null) });
+  }, [profile]);
+  return <Typography>Konto: {info ? "wczytane" : "—"}</Typography>;
+}
+
+/** Konfiguracja: zmiana ustawienia (np. niewidoczność online). */
+export function SettingsExample() {
+  const settings = useSettings();
+  const toggleInvisible = () =>
+    settings.setInvisibleOnline({ enabled: true, callback: () => {} });
+  return (
+    <Typography component="button" onClick={toggleInvisible}>
+      Ukryj online
+    </Typography>
+  );
+}

package/template/src/examples/slots.jsx

@@ -0,0 +1,31 @@
+/**
+ * PRZYKŁAD slotów (REFERENCJA — nieeksportowana). Sloty to ciężkie fragmenty z logiką/danymi,
+ * które renderuje HOST (mapa świata, statystyki zgłoszeń itp.). Skórka pobiera je gotowe przez
+ * `useSlots()` i tylko ROZMIESZCZA — nie ma dostępu do ich wnętrza ani do kodu gry.
+ *
+ * Zawsze degraduj łagodnie: gdy host nie dostarcza danego slotu, `slots[KLUCZ]` jest `undefined`.
+ */
+import Box from "@mui/material/Box";
+import Typography from "@mui/material/Typography";
+import { useSlots, SLOT_KEYS } from "@hexah/skin-sdk";
+
+/** Mapa Sektora (mapa świata + ruiny) wstawiona we własny kontener skórki. */
+export function WorldMapExample() {
+  const slots = useSlots();
+  const WorldMap = slots[SLOT_KEYS.WORLD_MAP];
+  if (!WorldMap) {
+    return <Typography>Slot mapy niedostępny.</Typography>;
+  }
+  return (
+    <Box sx={{ position: "relative", height: "70vh" }}>
+      <WorldMap />
+    </Box>
+  );
+}
+
+/** Statystyki zgłoszeń (wykresy) — np. obok listy na ekranie zgłoszeń. */
+export function IssueStatsExample() {
+  const slots = useSlots();
+  const IssueStats = slots[SLOT_KEYS.ISSUE_STATS];
+  return IssueStats ? <IssueStats /> : null;
+}