> Źródło: https://redai.pl/dev/manifest-narzedzie-php/ (dokumentacja modułów portalu redAi). Cała dokumentacja w jednym pliku: https://redai.pl/dev/moduly.md

## Manifest `narzedzie.php`

Manifest to plik PHP, który zwraca tablicę (`return [...]`). To jedyny plik obowiązkowy.

**Manifest ma być samymi stałymi.** Wolno: napisy, liczby, `true`, `false`, `null`, tablice oraz `Nazwa\Klasy::class`. Nie wolno: wywołań funkcji (`__()`, `env()`, `config()`), zmiennych, stałych typu `__DIR__`, konkatenacji z wyrażeniami. redai.pl nie wykonuje kodu z Waszej paczki: manifest czytamy parserem tokenów PHP. Manifest z wyrażeniem zostanie odrzucony przy wysyłce.

| Pole | Typ | Obowiązkowe | Co robi |
|---|---|---|---|
| `nazwa` | napis | tak | Nazwa w menu, na liście narzędzi i w Modułach. |
| `wersja` | napis `x.y.z` | tak (w katalogu) | Numer wersji modułu (semver). Każda wysyłka musi mieć wyższy numer niż poprzednia. |
| `zmiany` | tablica | zalecane | Lista zmian: klucz = wersja, wartość = lista zdań dla użytkownika. Najnowsza pierwsza. |
| `wymaga_portalu` | napis `x.y.z` | nie | Minimalna wersja portalu instancji. Starszy portal nie dostanie modułu w katalogu. |
| `opis` | napis | tak | Jedno zdanie: co z tego macie. `{host}` zamienia się na domenę instancji. |
| `ikona` | emoji | nie | Ikona na liście narzędzi. Domyślnie 🔧. |
| `ikona_svg` | napis | nie | Wnętrze SVG 24x24 (obrys, bez znacznika `<svg>`) do menu po lewej. |
| `kategoria` | napis | nie | Grupa w Modułach: `dokumenty`, `komunikacja`, `rejestry`. Domyślnie `dokumenty`. |
| `kolejnosc` | liczba | nie | Pozycja na liście, mniejsza = wyżej. Domyślnie 100. |
| `domyslnie` | bool | nie | Czy moduł jest włączony od razu. Dla modułów z katalogu zostawcie `false`. |
| `trasy.prefiks` | napis | nie | Początek adresów. Domyślnie `narzedzia/<klucz z myślnikami>`. |
| `trasy.nazwy` | napis | nie | Przedrostek nazw tras. Domyślnie `<klucz>.` |
| `trasy.start` | napis | nie | Nazwa trasy ekranu startowego bez przedrostka. Domyślnie `index`. |
| `konfig` | napis | nie | Klucz `config()` dla `konfig.php`. Domyślnie `<klucz>`. |
| `komendy` | lista klas | nie | Komendy artisan z `src/`. |
| `klasa` | klasa | nie | Własna klasa haków. Domyślnie `src/Narzedzie.php`. |
| `aliasy` | tablica | nie | Stara klasa => nowa. Potrzebne tylko przy przenoszeniu kodu, zwykle puste. |
| `opis_pozycji` | tablica | zalecane | Karta modułu w Modułach i ekran przed włączeniem (szczegóły niżej). |

`opis_pozycji` ma klucze:

| Klucz | Co pokazuje |
|---|---|
| `daje` | Lista „Co Wam to daje”, 2-4 zdania. |
| `przyklady` | Lista przykładów użycia. |
| `przyklady_tytul` | Nagłówek przykładów, np. „Co zrobicie w narzędziu”. |
| `szczegoly` | Szczegóły działania. Tu wpiszcie też każdy zewnętrzny adres, z którym moduł się łączy. |
| `kroki` | Kroki startu, np. „Włączcie narzędzie przyciskiem poniżej.” |
| `wlacz` | Napis na przycisku włączenia. |

Pełny przykład z wersją i listą zmian:

```php
<?php

return [
    'nazwa' => 'Faktury kosztowe',
    'wersja' => '1.2.0',
    'zmiany' => [
        '1.2.0' => ['Import faktur z pliku CSV.', 'Szybsza lista przy tysiącach faktur.'],
        '1.1.0' => ['Filtr po kontrahencie.'],
        '1.0.0' => ['Pierwsza wersja.'],
    ],
    'wymaga_portalu' => '1.3.20',
    'opis' => 'Faktury kosztowe w jednym miejscu, z wyszukiwaniem po kontrahencie.',
    'ikona' => '🧾',
    'ikona_svg' => '<path d="M6 3h12v18l-3-2-3 2-3-2-3 2z"/><path d="M9 8h6M9 12h6"/>',
    'kategoria' => 'dokumenty',
    'kolejnosc' => 50,
    'domyslnie' => false,
    'trasy' => [
        'prefiks' => 'narzedzia/faktury-kosztowe',
        'nazwy' => 'faktury_kosztowe.',
        'start' => 'index',
    ],
    'konfig' => 'faktury_kosztowe',
    'komendy' => [Narzedzia\FakturyKosztowe\Importuj::class],
    'opis_pozycji' => [
        'daje' => ['Wszystkie faktury kosztowe w jednej liście.', 'Wyszukiwanie po kontrahencie i kwocie.'],
        'przyklady' => ['Wgrajcie CSV z banku i sprawdźcie, czego brakuje.'],
        'przyklady_tytul' => 'Co zrobicie w narzędziu',
        'szczegoly' => ['Moduł nie łączy się z żadnym zewnętrznym adresem.'],
        'kroki' => ['Włączcie narzędzie przyciskiem poniżej.', 'Kliknijcie „Nowa faktura”.'],
        'wlacz' => 'Włączcie narzędzie',
    ],
];
```

Teksty dla użytkownika piszcie jak w całym portalu: 2. osoba liczby mnogiej („Wy/Wasze”), bez em-dashów, bez żargonu i nazw plików.