Initial commit

2026-05-03 07:26:12 +00:00
commit 776d374b59
57 changed files with 15968 additions and 0 deletions
@@ -0,0 +1,978 @@
+# Programming Guide
+
+Tento dokument sluzi ako prakticky sprievodca template-om. Pri kazdej casti popisuje:
+
+- co template poskytuje
+- ci sa dana cast musi pouzit
+- ako sa pouziva
+- kratky priklad
+- ako sa da rozsirit
+
+Poznamka:
+
+- vsetko v tomto template je navrhnute tak, aby sa dalo pouzit postupne
+- projekt nemusis prijat ako jeden velky balik
+- niektore casti su povinne len technicky, nie architektonicky
+
+## Prehlad
+
+Template poskytuje tieto hlavne casti:
+
+- Nuxt 4 aplikaciu
+- TypeScript
+- Nuxt UI ako predvolenu UI vrstvu
+- i18n pre `sk` a `en`
+- Pinia store-y
+- volitelnu auth kostru
+- API vrstvu pripravenu na OpenAPI
+- logger composable a plugin
+- globalne SCSS styly a tokeny
+- VS Code konfiguraciu
+- lint, format, typecheck a test skripty
+- Vitest test harness pre store-y, pluginy, middleware a locale konzistenciu
+
+## Nuxt 4 Aplikacia
+
+Co poskytuje:
+
+- zakladnu strukturu Nuxt 4 projektu
+- `app/` adresar pre pages, layouts, plugins, stores a composables
+- `nuxt.config.ts` pre centralnu konfiguraciu
+
+Musi sa pouzit:
+
+- ano
+- je to jadro celeho template-u
+
+Ako pouzit:
+
+- vytvaraj routy v `app/pages`
+- vytvaraj spolocne layouty v `app/layouts`
+- pridavaj runtime logiku cez `app/plugins` a `app/composables`
+
+Priklad:
+
+```vue
+<!-- app/pages/about.vue -->
+<template>
+  <div>About page</div>
+</template>
+```
+
+Moznosti rozsirenia:
+
+- pridat dalsie Nuxt moduly do `nuxt.config.ts`
+- doplnit server routes do `server/routes`
+- doplnit middleware, plugins a composables podla potrieb projektu
+
+## TypeScript
+
+Co poskytuje:
+
+- typovanie pre komponenty, composables, stores a plugin injections
+- centralne rozsirene Nuxt typy v `app/types`
+
+Musi sa pouzit:
+
+- prakticky ano
+- template je na TypeScripte postaveny
+
+Ako pouzit:
+
+- zapisuj nove composables a utility v `.ts`
+- definuj domenove typy do `app/types`
+
+Priklad:
+
+```ts
+export interface Customer {
+  id: string
+  name: string
+}
+```
+
+Moznosti rozsirenia:
+
+- pridat dalsie domenove typy
+- rozsirit `RouteMeta` alebo `NuxtApp` injekcie
+- doplnit typy pre generovane OpenAPI klienty
+
+Odporucanie:
+
+- pri rozsireni `NuxtApp` injekcii alebo aliasov udrzuj v synchronizacii aj `vitest.config.ts`, aby sa dali nove pluginy testovat mimo Nuxt runtime
+
+## Nuxt UI
+
+Co poskytuje:
+
+- standardnu komponentovu vrstvu pre formularove a bezne aplikacne UI
+- komponenty ako `UApp`, `UButton`, `UCard`, `UInput`, `USelect`, `UFormField`, `UAlert`
+- integrovany color mode a konzistentne API komponentov
+
+Musi sa pouzit:
+
+- nie
+- ale je to predvolena UI vrstva template-u
+
+Ako pouzit:
+
+- v page alebo komponente pouzi `U*` komponenty priamo
+- nevytvaraj dalsiu vlastnu vrstvu zakladnych button/input/card komponentov, ak na to nie je silny dovod
+
+Priklad:
+
+```vue
+<template>
+  <UCard variant="soft">
+    <template #header>
+      <h2>Profil</h2>
+    </template>
+
+    <UFormField label="Meno">
+      <UInput v-model="name" />
+    </UFormField>
+
+    <UButton>Ulozit</UButton>
+  </UCard>
+</template>
+
+<script setup lang="ts">
+const name = ref('')
+</script>
+```
+
+Moznosti rozsirenia:
+
+- vytvarat vlastne feature komponenty nad Nuxt UI
+- doplnit komplexne custom komponenty, napriklad diagramy alebo editory
+- zmenit vzhlad cez app config, CSS a globalne styly
+
+Odporucany pristup:
+
+- bezne app UI nech riesi Nuxt UI
+- specializovane vizualizacie nech riesia vlastne Vue komponenty alebo specializovane kniznice
+
+## i18n
+
+Co poskytuje:
+
+- lokalizaciu pre `sk` a `en`
+- preklady v `i18n/locales/sk.json` a `i18n/locales/en.json`
+- default locale `sk`
+
+Musi sa pouzit:
+
+- nie
+- ale je uz zapojene a pripravene
+
+Ako pouzit:
+
+- texty zapisuj do locale JSON suborov
+- v komponente pouzi `useI18n()`
+
+Priklad:
+
+```ts
+const { t } = useI18n()
+const title = t('app.title')
+```
+
+```json
+{
+  "app": {
+    "title": "Moja aplikacia"
+  }
+}
+```
+
+Moznosti rozsirenia:
+
+- pridat dalsie jazyky do `nuxt.config.ts`
+- doplnit dalsie namespace v locale JSON suboroch
+- zaviest konvencie pre preklady podla modulov, napriklad `users.list.title`
+
+Automaticke overenie:
+
+- template obsahuje test, ktory porovnava strukturu klucov v `i18n/locales/sk.json` a `i18n/locales/en.json`
+- pri pridani noveho textu ho dopln do oboch suborov, inak test zlyha
+
+## Pinia
+
+Co poskytuje:
+
+- centralny stav aplikacie
+- pripraveny `auth` store v `app/stores/auth.ts`
+- pripraveny `ui` store v `app/stores/ui.ts`
+
+Musi sa pouzit:
+
+- nie
+- ale je odporucany pre zdielany stav
+
+Ako pouzit:
+
+- lokalny stav formulara drz v komponente
+- globalny alebo zdielany stav drz v store
+
+Priklad auth store:
+
+```ts
+const authStore = useAuthStore()
+
+if (authStore.isAuthenticated) {
+  console.log(authStore.displayName)
+}
+```
+
+Priklad ui store:
+
+```ts
+const uiStore = useUiStore()
+
+uiStore.startLoading()
+
+try {
+  uiStore.pushNotification({
+    title: 'Hotovo',
+    message: 'Data boli ulozene.',
+    tone: 'success'
+  })
+} finally {
+  uiStore.stopLoading()
+}
+```
+
+Moznosti rozsirenia:
+
+- pridat dalsie store-y, napriklad `filters`, `settings`, `drafts`
+- napojit `ui` store na globalne toasty alebo loading overlay
+- rozsirit `auth` store o session info alebo permission model
+
+Automaticke overenie:
+
+- existuju unit testy pre `auth` aj `ui` store, takze zmeny v ich API alebo vypocitavanych hodnotach vies chytit skor, nez sa dostanu do UI
+
+## Autorizacia A Auth Kostra
+
+Co poskytuje:
+
+- vendor-neutral auth vrstvu
+- `useAuth()` composable
+- auth plugin v `app/plugins/auth.ts`
+- globalny middleware v `app/middleware/auth.global.ts`
+- route meta typy `public`, `requiresAuth`, `roles`
+
+Musi sa pouzit:
+
+- nie
+- auth je volitelna
+
+Ako pouzit:
+
+- nastav mod cez `.env`
+- route ochran len tam, kde to dava zmysel
+
+Dostupne mody:
+
+- `disabled`
+- `mock`
+- `userinfo`
+
+Priklad `.env`:
+
+```env
+NUXT_PUBLIC_AUTH_MODE=mock
+```
+
+Priklad v komponente:
+
+```ts
+const auth = useAuth()
+
+await auth.ensureInitialized()
+
+if (auth.isAuthenticated.value) {
+  console.log(auth.user.value?.email)
+}
+```
+
+Priklad ochrany route:
+
+```ts
+definePageMeta({
+  requiresAuth: true
+})
+```
+
+Priklad ochrany podla role:
+
+```ts
+definePageMeta({
+  requiresAuth: true,
+  roles: ['ADMIN']
+})
+```
+
+Moznosti rozsirenia:
+
+- napojit `userinfo` mod na realny backend alebo oauth2-proxy endpoint
+- doplnit mapovanie backend user modelu
+- pridat jemnejsi access model typu `permissions` alebo `hasAccess(user)`
+- doplnit login alebo logout UI do layoutu
+
+Automaticke overenie:
+
+- auth plugin ma testy pre `disabled`, `mock` a `userinfo`
+- middleware ma testy pre `public`, `requiresAuth` a `roles`
+- to znamena, ze zmeny v auth kostre vies overit bez browser manualu
+
+## API Vrstva
+
+Co poskytuje:
+
+- centralnu API konfiguraciu v `nuxt.config.ts`
+- API plugin v `app/plugins/api.client.ts`
+- `useApi()` composable
+- wrapper vrstvu v `api/wrappers`
+
+Musi sa pouzit:
+
+- nie
+- ale je to odporucany sposob volania backendu
+
+Ako pouzit:
+
+- z komponentov volaj `useApi()`
+- konkretne HTTP detaily drz vo wrapperoch
+
+Priklad:
+
+```ts
+const api = useApi()
+
+const health = await api.example.getHealth()
+const welcome = await api.example.getWelcome()
+```
+
+Zakladne env:
+
+```env
+NUXT_PUBLIC_API_BASE_URL=/api
+NUXT_PUBLIC_API_TIMEOUT_MS=10000
+```
+
+Moznosti rozsirenia:
+
+- pridat dalsie API wrappery do `api/wrappers`
+- rozdelit klientov podla domen, napriklad `users`, `projects`, `reports`
+- doplnit error handling, retry alebo auth headers
+
+Odporucanie:
+
+- UI nema volat `fetch` napriamo, ak to nie je jednorazova drobnost
+- preferuj centralnu API vrstvu pre konzistenciu
+
+Automaticke overenie:
+
+- ukazkovy wrapper `api/wrappers/example.ts` aj plugin `app/plugins/api.client.ts` maju Vitest testy
+- pri pridani dalsieho wrappera je dobry standard doplnit rovnaky test hned s implementaciou
+
+## OpenAPI Priprava
+
+Co poskytuje:
+
+- `openapi-spec` pre specifikacie a generator configy
+- `openapi-client` pre generovanych klientov
+- `openapi-ts.config.ts`
+- skripty `pnpm generate:api` a `pnpm generate:example-api`
+
+Musi sa pouzit:
+
+- nie
+- je to priprava pre projekty, kde FE alebo BE kontrakt existuje ako OpenAPI
+
+Ako pouzit:
+
+1. vloz alebo nahrad OpenAPI specifikaciu v `openapi-spec`
+2. uprav `openapi-ts.config.ts`
+3. spusti generator
+4. napoj vysledok cez `api/wrappers`
+
+Priklad:
+
+```bash
+pnpm generate:api
+```
+
+Moznosti rozsirenia:
+
+- generovat viac klientov pre viac backendov
+- verzovat alebo neverzovat generovany kod podla timovej dohody
+- doplnit wrappery, ktore skryju rozdiely medzi backendmi
+
+Odporucanie:
+
+- negenerovany kod nech ostane v `api/wrappers` a `app/composables`
+- komponenty nech nevolaju generovany OpenAPI klient priamo
+- generator je Node-native, takze workflow funguje aj bez Javy
+
+## Logger
+
+Co poskytuje:
+
+- jednoduchy logger plugin
+- `useLogger()` composable
+- dostupnost cez Nuxt inject
+
+Musi sa pouzit:
+
+- nie
+
+Ako pouzit:
+
+```ts
+const logger = useLogger()
+
+logger.info('User opened page', { section: 'dashboard' })
+logger.error('Save failed', { id: '123' })
+```
+
+Moznosti rozsirenia:
+
+- napojit logovanie na externe sluzby
+- doplnit odlisne spravanie pre dev a production
+- pridat korelacne ID alebo request context
+
+Automaticke overenie:
+
+- logger plugin ma test na format vystupu
+- `useLogger()` ma test na spravne Nuxt inject spravanie
+
+## Testovanie A Overenie
+
+Co sa overuje automaticky:
+
+- store-y
+- pluginy
+- middleware
+- API wrappery
+- i18n kluce
+
+Zakladny verify workflow:
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm test:run
+pnpm build
+```
+
+Cielene spustenie infrastructure testov template-u:
+
+```bash
+pnpm vitest run tests/auth.plugin.spec.ts tests/auth.middleware.spec.ts tests/i18n.locales.spec.ts tests/api.plugin.spec.ts tests/logger.plugin.spec.ts tests/use-logger.spec.ts
+```
+
+Poznamka:
+
+- testy pre pluginy a middleware pouzivaju `vitest.config.ts`, kde su nastavene aliasy `~`, `@`, `~~` a `@@`
+- ak pridas nove runtime injekcie alebo novu rozsirenu Nuxt vrstvu, je dobre doplnit test este v tom istom PR
+
+## Globalne Styly A Tokeny
+
+Co poskytuje:
+
+- `app/assets/styles/ui.css`
+- `app/assets/styles/_tokens.scss`
+- `app/assets/styles/_theme.scss`
+- `app/assets/styles/_base.scss`
+- `app/assets/styles/main.scss`
+
+Musi sa pouzit:
+
+- ciastocne ano
+- stylova vrstva je sucast template-u, ale mozes ju zmensit alebo vymenit
+
+Ako pouzit:
+
+- `ui.css` nechaj ako vstup pre `tailwindcss` a `@nuxt/ui`
+- layoutove a globalne upravy rob v `_base.scss`
+- Nuxt UI farby skus najprv nastavit v `nuxt.config.ts` cez `appConfig.ui.colors`
+- `_theme.scss` pouzi len na male override-y nad Nuxt UI tokenmi
+- zakladne app-level hodnoty drz v `_tokens.scss`
+
+Priklad:
+
+```ts
+export default defineNuxtConfig({
+  appConfig: {
+    ui: {
+      colors: {
+        primary: 'blue',
+        neutral: 'slate'
+      }
+    }
+  }
+})
+```
+
+Moznosti rozsirenia:
+
+- doplnit branding projektu
+- upravit typografiu, spacing a farby
+- v pripade potreby jemne prepisat Nuxt UI tokeny bez budovania vlastneho design systemu
+
+Odporucany mentalny model:
+
+- Nuxt UI je zdroj pravdy pre komponentovy vizual
+- `_tokens.scss` drzi male spolocne hodnoty pre app shell
+- `_theme.scss` riesi rozdiel medzi light a dark vizualom
+- `_base.scss` riesi vlastne layout triedy a app-specific CSS
+
+### Co menit v ktorom subore
+
+`nuxt.config.ts`
+
+- semanticke farby pre Nuxt UI ako prvy krok
+- ine Nuxt-level nastavenia
+
+Priklad:
+
+```ts
+export default defineNuxtConfig({
+  appConfig: {
+    ui: {
+      colors: {
+        primary: 'blue',
+        neutral: 'slate'
+      }
+    }
+  }
+})
+```
+
+`app/assets/styles/ui.css`
+
+- nechaj len import Nuxt UI vrstvy
+- tento subor nie je miesto na app-specific styling
+
+Priklad:
+
+```css
+@import "tailwindcss";
+@import "@nuxt/ui";
+```
+
+`app/assets/styles/_tokens.scss`
+
+- radius
+- font family
+- layout max width
+
+Priklad:
+
+```scss
+:root {
+  --font-family-base: 'Segoe UI', sans-serif;
+  --page-max-width: 1320px;
+  --ui-radius: 1rem;
+}
+```
+
+`app/assets/styles/_theme.scss`
+
+- jemne prepisy Nuxt UI CSS tokenov
+- light/dark rozdiely bez stavania vlastnej komponentovej kniznice
+
+Priklad:
+
+```scss
+:root,
+.light {
+  --ui-primary: var(--ui-color-primary-600);
+  --ui-bg: #f8fafc;
+}
+
+.dark {
+  --ui-primary: var(--ui-color-primary-400);
+  --ui-bg: #0b1220;
+}
+```
+
+`app/assets/styles/_base.scss`
+
+- vlastne wrapper triedy
+- spacing a layout pre shell
+- app-specific utility a responzivne pravidla
+
+Priklad:
+
+```scss
+.page-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 1.25rem;
+}
+```
+
+### Ako funguje light, dark a system tema
+
+Template pouziva `useColorMode()` a prepinac v `app/layouts/default.vue`.
+
+Pouzivane hodnoty:
+
+- `light`
+- `dark`
+- `system`
+
+Priklad vlastneho prepinaca:
+
+```vue
+<script setup lang="ts">
+const colorMode = useColorMode()
+
+function cycleTheme() {
+  colorMode.preference =
+    colorMode.preference === 'light'
+      ? 'dark'
+      : colorMode.preference === 'dark'
+        ? 'system'
+        : 'light'
+}
+</script>
+
+<template>
+  <UButton @click="cycleTheme">
+    Zmenit temu
+  </UButton>
+</template>
+```
+
+Kedy menit `preference` a kedy CSS premenne:
+
+- `colorMode.preference` meni aktivny mod
+- CSS premenne v `_theme.scss` menia, ako light a dark mod vyzera
+
+### Typicke scenare uprav
+
+1. Chces iny primary button color.
+   Najprv skus `appConfig.ui.colors` v `nuxt.config.ts`, a ak chces presnejsi vysledok, dolad `--ui-primary` v `_theme.scss`.
+2. Chces tmavsi dark background a jemnejsie card borders.
+   Uprav `--ui-bg`, `--ui-bg-muted` a `--ui-border` v `_theme.scss`.
+3. Chces vacsi radius pre buttony, inputs a cards.
+   Zmen `--ui-radius` v `_tokens.scss`.
+4. Chces sirsi layout alebo iny spacing hero sekcie.
+   Uprav `_base.scss`.
+
+### Priklady praktickych uprav
+
+Zmena radiusu pre celu app:
+
+```scss
+:root {
+  --ui-radius: 1rem;
+}
+```
+
+Jemnejsi light mode:
+
+```scss
+:root,
+.light {
+  --ui-bg: #f8fafc;
+  --ui-bg-muted: #f1f5f9;
+  --ui-border: #dbe4ee;
+}
+```
+
+Vyraznejsi dark mode:
+
+```scss
+.dark {
+  --ui-bg: #0b1220;
+  --ui-bg-muted: #111827;
+  --ui-border: #1f2937;
+  --ui-text: #e5eef9;
+}
+```
+
+Silnejsia primarna farba v light mode a jemnejsia v dark mode:
+
+```scss
+:root {
+  --ui-primary: var(--ui-color-primary-700);
+}
+
+.dark {
+  --ui-primary: var(--ui-color-primary-400);
+}
+```
+
+## Docker Release Image
+
+Co poskytuje:
+
+- [Dockerfile](/c:/Data/Development/MANET/prjtemplates/vue/Dockerfile)
+- [.dockerignore](/c:/Data/Development/MANET/prjtemplates/vue/.dockerignore)
+- produkcny image pre Nitro server
+
+Musi sa pouzit:
+
+- nie
+- ale je to odporucana cesta pre release a deploy
+
+Ako pouzit:
+
+- buildni image cez `docker build`
+- spusti kontajner s namapovanym portom `3000`
+- runtime premenne dodaj cez `-e`
+
+Priklad:
+
+```bash
+docker build -t nuxt-workspace-template:latest .
+docker run --rm -p 3000:3000 nuxt-workspace-template:latest
+```
+
+Priklad s runtime premennymi:
+
+```powershell
+docker run --rm -p 3000:3000 `
+  -e NUXT_PUBLIC_API_BASE_URL=https://api.example.com `
+  -e NUXT_PUBLIC_AUTH_MODE=userinfo `
+  nuxt-workspace-template:latest
+```
+
+Poznamky:
+
+- build stage pouziva `node:24-bookworm-slim`
+- runtime stage pouziva hardened `gcr.io/distroless/nodejs24-debian12:nonroot`
+- kontajner spusta `.output/server/index.mjs`
+- image je urceny pre release alebo deploy, nie pre hot-reload development
+
+## Layout
+
+Co poskytuje:
+
+- spolocny shell aplikacie v `app/layouts/default.vue`
+- branding, prepinanie locale a prepinanie temy
+
+Musi sa pouzit:
+
+- nie
+- ale je to predvoleny layout
+
+Ako pouzit:
+
+- nechaj sem spolocne prvky aplikacie
+- stranky sa do neho renderuju cez `<slot />`
+
+Priklad rozsirenia:
+
+- pridat navigation bar
+- pridat user menu
+- pridat globalne notifikacie alebo loading indikator
+
+## Demo Stranka
+
+Co poskytuje:
+
+- ukazkovu domovsku stranku v `app/pages/index.vue`
+- priklad pouzitia i18n, loggera, Nuxt UI a theme switchingu
+
+Musi sa pouzit:
+
+- nie
+- je to iba demo start point
+
+Ako pouzit:
+
+- nahrad ju vlastnym dashboardom alebo landing page
+
+Moznosti rozsirenia:
+
+- prerobit na prehlad systemu
+- pouzit ju ako interny style guide pre tim
+- rozdelit ukazky do samostatnych routes
+
+## VS Code
+
+Co poskytuje:
+
+- `.vscode` konfiguraciu
+
+Musi sa pouzit:
+
+- nie
+- ale je to odporucany editorovy setup pre konzistentny workflow
+
+Ako pouzit:
+
+- otvor repo vo VS Code
+- spusti `pnpm dev`
+
+Moznosti rozsirenia:
+
+- pridat dalsie VS Code extensions
+- upravit Node verziu na hoste
+- pridat lokalne helper sluzby podla potrieb projektu
+
+## Kvalita Kodu
+
+Co poskytuje:
+
+- ESLint
+- Prettier
+- Typecheck
+- Vitest
+
+Musi sa pouzit:
+
+- technicky nie
+- prakticky ano, ak chces udrzatelny projekt
+
+Ako pouzit:
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm test:run
+pnpm format
+```
+
+Moznosti rozsirenia:
+
+- doplnit unit testy
+- doplnit component testy
+- zapojit CI pipeline
+- pridat pre-commit hooks
+
+## Runtime Config
+
+Co poskytuje:
+
+- centralne public config hodnoty v `nuxt.config.ts`
+- API a auth env premenne
+
+Musi sa pouzit:
+
+- nie
+- ale je to odporucany sposob konfiguracie
+
+Ako pouzit:
+
+Priklad `.env`:
+
+```env
+NUXT_PUBLIC_API_BASE_URL=/api
+NUXT_PUBLIC_API_TIMEOUT_MS=10000
+NUXT_PUBLIC_AUTH_MODE=disabled
+NUXT_PUBLIC_AUTH_USERINFO_URL=/api/auth/me
+```
+
+Prakticky start:
+
+1. skopiruj `.env.example` do `.env`
+2. nastav `NUXT_PUBLIC_API_BASE_URL`
+3. rozhodni `NUXT_PUBLIC_AUTH_MODE`
+4. ak budes pouzivat `userinfo`, dopln aj login, logout a userinfo URL
+
+Poznamka:
+
+- public runtime config patri do `.env`, nie natvrdo do komponentov
+
+Moznosti rozsirenia:
+
+- pridat dalsie public a private env premenne
+- rozdelit config podla modulov
+- doplnit feature flags
+
+## Co Je Povinny Zaklad A Co Je Volitelne
+
+Povinny zaklad:
+
+- Nuxt 4
+- TypeScript
+- zakladna adresarova struktura
+- `nuxt.config.ts`
+
+Silno odporucane, ale volitelne:
+
+- Nuxt UI
+- i18n
+- Pinia
+- API vrstva
+- logger
+- globalne styly
+
+Volitelne casti:
+
+- auth kostra
+- OpenAPI generator workflow
+- lokalny host workflow nad VS Code
+- demo stranka v aktualnej podobe
+
+## Odporucany Sposob Pouzitia Template-u
+
+Ak chces z template-u spravit realny projekt, odporucany postup je:
+
+1. uprav branding, title a preklady
+2. rozhodni, ci pouzijes auth a v akom mode
+3. nastav API base URL a priprav prve wrappery
+4. ak mate OpenAPI kontrakt, nahraj specifikaciu a nastav generator
+5. zacni stavat stranky priamo nad Nuxt UI komponentmi
+6. zdielany stav presuvaj do Pinia store-ov
+7. pred odovzdanim pravidelne pustaj lint, typecheck a testy
+
+Ako spravit prvy krok prakticky:
+
+- v `package.json` zmen `name`
+- v `nuxt.config.ts` uprav `app.head.title`, `titleTemplate` a `description`
+- v `i18n/locales/sk.json` a `i18n/locales/en.json` prepis demo texty
+- v `app/pages/index.vue` nahrad ukazkovu domovsku stranku vlastnym obsahom
+- v `nuxt.config.ts`, `app/assets/styles/_tokens.scss`, `_theme.scss` a `_base.scss` dolad semanticke farby, spacing a globalny vizual
+
+## Odporucany Sposob Rozsirovania
+
+Najrozumnejsie miesto pre rozsirovanie podla typu zmeny:
+
+- nova route alebo obrazovka:
+  `app/pages`
+- nova zdielana UI cast alebo zlozitejsi widget:
+  `app/components`
+- nova zdielana logika:
+  `app/composables`
+- novy globalny stav:
+  `app/stores`
+- nove backend volania:
+  `api/wrappers`
+- nova OpenAPI specifikacia:
+  `openapi-spec`
+- nova plugin integracia:
+  `app/plugins`
+- nove typy:
+  `app/types`
+
+Priklad rozsirania o novu feature:
+
+1. vytvor `app/pages/users/list.vue`
+2. pridaj `api/wrappers/users.ts`
+3. dopln typy do `app/types/api.ts` alebo pouzi generovany klient
+4. ak treba, pridaj `app/stores/users.ts`
+5. texty dopln do `i18n/locales/*.json`
+
+## Zaverecne Odporucanie
+
+Tento template nie je monolit, ktory musis pouzit cely. Je to pripraveny zaklad, z ktoreho si mozes zobrat:
+
+- len Nuxt UI a i18n
+- len API a OpenAPI workflow
+- len auth skeleton
+- alebo kompletne vsetky vrstvy spolu
+
+Najlepsie funguje vtedy, ked:
+
+- bezne UI stavas priamo s Nuxt UI
+- backend komunikaciu drzis v wrapperoch
+- zdielany stav davas do Pinie
+- auth zapinas len tam, kde ho naozaj potrebujes