> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kazzle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Konfiguracja

> Pełna dokumentacja kazzle.config.ts — manifestu aplikacji.

# Konfiguracja

Każda aplikacja Kazzle ma plik `kazzle.config.ts` w katalogu głównym projektu. Plik ten definiuje zawartość aplikacji — komponenty, umiejętności i metadane.

## Szybki start

```typescript theme={"theme":"material-theme-darker"}
import { defineConfig } from '@kazzle/app';

export default defineConfig({
  components: [
    { name: 'My App', type: 'ui', path: '.' }
  ]
});
```

Funkcja pomocnicza `defineConfig` zapewnia autouzupełnianie TypeScript i walidację. Typy pochodzą z pakietu `@kazzle/app` dołączonego do każdego szablonu.

## Pola najwyższego poziomu

| Pole           | Typ                          | Wymagane | Opis                                                                                                                                                                                       |
| -------------- | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`         | `string`                     | nie      | Nazwa wyświetlana w katalogu aplikacji. Jeśli pominięte, używany jest slug.                                                                                                                |
| `subtitle`     | `string`                     | nie      | Krótki jednowierszowy opis wyświetlany pod nazwą aplikacji w katalogu (np. "Kontroluj aplikacje Mac z Kazzle"). Wymagane do publikacji — pominięcie powoduje błąd.                         |
| `version`      | `string`                     | nie      | Etykieta wersji ustawiona przez autora (np. "1.2.0"). Tylko do wyświetlania; zapisywana przy publikacji i wyświetlana na klonach jako wersja źródłowa.                                     |
| `icon`         | `string`                     | nie      | Ścieżka do pliku ikony aplikacji względem katalogu głównego repozytorium (png, jpg, svg, webp, ico). Przesyłana do CDN przy publikacji.                                                    |
| `accentColor`  | `string`                     | nie      | Opcjonalny kolor akcentu marki jako ciąg szesnastkowy (np. "#3b82f6"). Koloruje chipę ikony aplikacji i nagłówek szczegółów. Jeśli pominięte, akcent jest automatycznie pobierany z ikony. |
| `kazzleAuth`   | `"optional"` \| `"required"` | nie      | Bramka tożsamości dla powierzchni uruchamiania aplikacji — "optional" (tożsamość podana, jeśli użytkownik Kazzle jest obecny) lub "required" (musi być zalogowany użytkownik Kazzle).      |
| `launchUrl`    | `string`                     | nie      | Bezwzględny adres URL otwarty w Kazzle po kliknięciu aplikacji, używany dosłownie. Jeśli pominięte, powierzchnia uruchamiania to wdrożony podgląd komponentu UI.                           |
| `webhookUrl`   | `string`                     | nie      | Punkt końcowy wydawcy, na który Kazzle wysyła POST przy app.installed / app.uninstalled (dostarcza klucz instalacji).                                                                      |
| `components`   | object\[]                    | nie      | Komponenty wykonywalne — frontedy UI lub procesy w tle                                                                                                                                     |
| `skills`       | object\[]                    | nie      | Definicje umiejętności AI — pliki markdown, które AI czyta w celu zdobycia wiedzy domenowej                                                                                                |
| `capabilities` | `object`                     | nie      | Opcjonalne funkcje integracji pulpitu, takie jak skróty klawiaturowe, powiadomienia i obecność na pasku stanu                                                                              |

## Pola komponentu

Każdy wpis w `components[]`:

| Pole                   | Typ                      | Wymagane        | Opis                                                                                                  |
| ---------------------- | ------------------------ | --------------- | ----------------------------------------------------------------------------------------------------- |
| `name`                 | `string`                 | tak             | Unikalna nazwa komponentu w aplikacji                                                                 |
| `type`                 | `"ui"` \| `"process"`    | tak             | Typ komponentu — ui (maks. 1) lub process                                                             |
| `path`                 | `string`                 | tak             | Ścieżka wejścia w katalogu aplikacji                                                                  |
| `runtime`              | object                   | nie             | Polecenia i opcjonalne przesłonięcia env: `{ dev?, prod? }`                                           |
| `runtime.dev.command`  | `string`                 | nie             | Polecenie uruchomienia serwera deweloperskiego (np. `"bun run dev"`)                                  |
| `runtime.dev.env`      | object                   | nie             | Przesłonięcie env tylko dla deweloperów. Powraca do `env` komponentu.                                 |
| `runtime.prod.command` | `string`                 | nie             | Polecenie uruchomienia w produkcji (np. `"bun run start"`)                                            |
| `runtime.prod.build`   | `string`                 | nie             | Polecenie budowania dla produkcji (np. `"vite build"`)                                                |
| `runtime.prod.env`     | object                   | nie             | Przesłonięcie env tylko dla produkcji. Powraca do `env` komponentu.                                   |
| `schedule`             | `string`                 | nie             | Harmonogram cron dla komponentów procesów (np. `"*/5 * * * *"`)                                       |
| `trigger`              | `"webhook"` \| `"event"` | nie             | Tryb wyzwalacza dla komponentów procesów                                                              |
| `env`                  | object                   | nie             | Kolekcja sekretów + środowisko do wstrzykiwania zmiennych env                                         |
| `env.collection`       | `string`                 | tak (jeśli env) | Slug kolekcji sekretów                                                                                |
| `env.environment`      | `string`                 | tak (jeśli env) | Slug środowiska                                                                                       |
| `env.include`          | `string[]`               | nie             | Wstrzyknij tylko te nazwy zmiennych env. Jeśli pominięte, wstrzyknij wszystkie z kolekcji+środowiska. |

## Pola umiejętności

Każdy wpis w `skills[]`:

| Pole   | Typ      | Wymagane | Opis                                                           |
| ------ | -------- | -------- | -------------------------------------------------------------- |
| `name` | `string` | tak      | Nazwa umiejętności                                             |
| `path` | `string` | tak      | Ścieżka do pliku SKILL.md względem katalogu głównego aplikacji |

## Ograniczenia

* **Maks. 1 komponent UI** na aplikację
* Wartości `name` komponentu muszą być unikalne w aplikacji

## Przykłady szablonów

### ai app

```typescript theme={"theme":"material-theme-darker"}
import { defineConfig } from '@kazzle/app';

export default defineConfig({
  /** Jednowierszowy opis do katalogu. Wymagane do publikacji. */
  subtitle: 'My App',
  icon: 'components/ui/public/favicon.svg',
  components: [
    { name: 'ui', type: 'ui', path: './components/ui' },
    { name: 'server', type: 'process', path: './components/server/index.ts', runtime: { dev: { command: 'bun run dev' }, prod: { command: 'bun run start' } } },
  ],
});
```

### ui db app

```typescript theme={"theme":"material-theme-darker"}
import { defineConfig } from '@kazzle/app';

export default defineConfig({
  /** Jednowierszowy opis do katalogu. Wymagane do publikacji. */
  subtitle: 'My App',
  icon: 'components/ui/public/favicon.svg',
  components: [
    { name: 'ui', type: 'ui', path: './components/ui' },
    { name: 'server', type: 'process', path: './components/server/index.ts', runtime: { dev: { command: 'bun run dev' }, prod: { command: 'bun run start' } } },
  ],
});
```

### ui app

```typescript theme={"theme":"material-theme-darker"}
import { defineConfig } from '@kazzle/app';

export default defineConfig({
  /** Jednowierszowy opis do katalogu. Wymagane do publikacji. */
  subtitle: 'My App',
  /** Ścieżka do ikony aplikacji względem katalogu głównego repozytorium. Przesyłana do CDN przy publikacji. */
  icon: 'components/ui/public/favicon.svg',
  /** Komponenty aplikacji — każdy wpis definiuje jednostkę do wdrożenia. Maks. 1 komponent UI. */
  components: [
    { name: 'My App', type: 'ui', path: './components/ui' },
  ],
});
```