Finch 2.3.0: docs for Windows, LSP and VS Code; cheat sheets (en, pl); portable LSP test

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/pl/dla-inzynierow.md

@@ -38,7 +38,10 @@ Język z perspektywy użytkownika opisuje [przewodnik dla techników](dla-techni
 20. [Semantyka a C](#20-semantyka-a-c)
 21. [Spis funkcji](#21-spis-funkcji)
 22. [Rozbudowa kompilatora](#22-rozbudowa-kompilatora)
-23. [Znane ograniczenia](#23-znane-ograniczenia)
+23. [Platformy i Windows](#23-platformy-i-windows)
+24. [Serwer języka](#24-serwer-języka)
+25. [Rozszerzenie VS Code](#25-rozszerzenie-vs-code)
+26. [Znane ograniczenia](#26-znane-ograniczenia)
 
 ---
 
@@ -886,12 +889,103 @@ przed wyskokiem z zasięgów.
 
 ---
 
-## 23. Znane ograniczenia
+## 23. Platformy i Windows
+
+`src/target.h` trzyma `g_target`: triple LLVM, flagi `windows` / `msvc` / `cross`, kompilator C (`cc`)
+i rozszerzenie plików wykonywalnych. `setTarget()` wybiera kompilator C: `FINCH_CC`, potem `CC` (nie przy
+kompilacji krzyżowej), potem `x86_64-w64-mingw32-gcc` dla `--target windows` z Linuksa, `clang` na
+Windowsie, `cc` na Uniksie. Przez tę warstwę idzie wszystko, co zależy od platformy:
+
+- **Nagłówki:** libclang parsuje z `--target=<triple>` (więc `long` ma 32 bity na Windowsie i używane są
+  właściwe nagłówki), a na Windowsie z `-D_USE_MATH_DEFINES`. Katalogi nagłówków pochodzą z `<cc> -E -v`.
+- **Procesy:** `capture()` / `runCommand()` opakowują `popen` / `system` (`_popen` na Windowsie) i dekodują
+  kody wyjścia (POSIX `WIFEXITED`/sygnały albo kody Windowsa i wyjątki NTSTATUS, np. `0xC0000005`).
+  `shellQuote()` cytuje dla `sh` (`'…'`) albo `cmd.exe` (`"…"`); linia polecenia dla `cmd /c`, która
+  zaczyna się od cudzysłowu, dostaje dodatkową parę cudzysłowów.
+- **Linkowanie:** bez `-lm` przy MSVC; nazwy `.exe`; klucz cache runtime'u obejmuje triple i kompilator C.
+  Komunikaty linkera MSVC (`LNK2019 unresolved external symbol`, `LNK1104`/`LNK1181 cannot open file`) są
+  tłumaczone tak jak komunikaty GNU ld.
+- **Uruchamianie:** program dla Windowsa zbudowany na Linuksie uruchamia się przez `wine`.
+- **Informacje dla debuggera:** CodeView dla celów MSVC, DWARF w pozostałych.
+- **Runtime:** na Windowsie nie ma `getline` ani `sys/wait.h`; `stdin`/`stdout`/`stderr` są tam makrami,
+  więc `finch_std_stream(i)` udostępnia je Finchowi, gdy nagłówek nie ma dla nich zmiennej `extern`.
+- **Wypisywanie wskaźników** jest wszędzie takie samo: `null` albo `0x…`.
+
+### Konwencja wywołań Microsoft x64
+
+`classify()` rozgałęzia się po `g_target.windows`. Struktura o rozmiarze dokładnie 1, 2, 4 albo 8 bajtów
+idzie jako **jedna liczba całkowita** tego rozmiaru, nawet jeśli zawiera floaty (`{float, float}` → `i64`).
+Każda inna struktura jest **pośrednia (Indirect)**: wywołujący kopiuje ją na swój stos i przekazuje adres
+kopii (bez `byval`: funkcja dostaje zwykły wskaźnik). Wyniki 1/2/4/8-bajtowe wracają w `rax` jako liczba;
+wszystko inne przez ukryty wskaźnik `sret`. Każdy argument zajmuje jedno miejsce, więc nie ma liczenia
+rejestrów. `cThunk()` robi to samo w drugą stronę dla callbacków.
+
+`tests/windows.sh` buduje każdy test z `--target windows`, uruchamia go w Wine i porównuje wynik: przechodzą
+wszystkie, łącznie z `c_structs` (który wtedy sprawdza reguły Microsoftu na bibliotece C zbudowanej MinGW).
+CI dodatkowo buduje `finch.exe` przez MSVC na Windows Server i uruchamia tam `tests/run.sh`.
+
+### Budowanie finch.exe
+
+CI używa Visual Studio 2022, Ninja i oficjalnego pakietu `clang+llvm-21.x-x86_64-pc-windows-msvc`
+(biblioteki statyczne, `/MT`, więc `CMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded`). Dwa szczegóły Windowsa
+w `CMakeLists.txt`: ten pakiet podaje ścieżkę do biblioteki DIA SDK z maszyny, na której zbudowano LLVM,
+więc jest ona przekierowywana na zainstalowane Visual Studio; a osadzony runtime jest zapisywany jako
+kilka surowych napisów, bo MSVC ogranicza jeden literał do 16 KB. LLVM jest inicjalizowany tylko z
+natywnym backendem, żeby budowanie statyczne nie wciągało wszystkich architektur.
+
+---
+
+## 24. Serwer języka
+
+`finch lsp` (`src/lsp.cpp`) mówi protokołem LSP przez stdin/stdout, używając `llvm::json`. Przy
+`didOpen`/`didChange` uruchamia na dokumencie prawdziwy front-end: `Loader` (z tekstem otwartych
+dokumentów jako nadpisaniem plików), `importHeaders` (w cache na zestaw importów, bo czytanie nagłówków
+jest najwolniejsze) i `generate()` bez optymalizacji i emisji. Dwa przełączniki pozwalają użyć
+kompilatora wewnątrz serwera:
+
+- `g_throwErrors`: `failAt()` rzuca `FinchError{file, line, col, msg}` zamiast wypisywać i kończyć proces.
+  Serwer publikuje to jako diagnostykę (dla właściwego pliku, także wewnątrz importowanego modułu) i czyści
+  diagnostyki, które zniknęły.
+- `g_index`: podczas generowania kodu `Codegen::note()` zapisuje `SymRef` dla każdej rozwiązywanej nazwy
+  (zmienne, parametry, pola, funkcje, konstruktory, funkcje i stałe C, funkcje wbudowane, metody, elementy
+  modułów): jej zakres, opis w markdownie i pozycję definicji. `define()` i `declareStructs()` dokładają
+  `FnInfo` / `StructIndex`; `addVar()` dokłada `VarInfo` z zakresem linii otaczającej funkcji. Pozycje nazw
+  pochodzą z pól `namePos`, które zapisuje parser.
+
+Zapytania korzystają z tego indeksu:
+
+| Zapytanie | Źródło |
+|---|---|
+| hover, definition | `SymRef` pod kursorem |
+| completion | słowa kluczowe, typy, funkcje wbudowane, zmienne otaczającej funkcji, funkcje, struktury, importowane moduły, nazwy z C pasujące do wpisanego początku; po `nazwa.`: pola struktury (także przez `ptr[T]`), metody tablic/tekstów albo zawartość modułu |
+| signatureHelp | cofa się do niezamkniętego `(`, liczy przecinki na najwyższym poziomie i szuka sygnatury Fincha / C / wbudowanej |
+| documentSymbol | funkcje i struktury (z polami) z pliku |
+
+Kod w trakcie pisania (`p.`, `add(1, `) się nie kompiluje, więc serwer trzyma **ostatnią udaną** analizę
+każdego dokumentu i dołącza z niej funkcje, struktury i zmienne do podpowiedzi. `tests/lsp_test.py`
+steruje serwerem tak jak edytor i sprawdza każdą funkcję.
+
+`src/builtins_doc.h` to jedyny opis funkcji wbudowanych i metod, używany przy hover, podpowiedziach
+i podpowiedziach parametrów (i odwzorowany w ściągach).
+
+---
+
+## 25. Rozszerzenie VS Code
+
+`editors/vscode` to zwykłe rozszerzenie w JavaScripcie: `extension.js` uruchamia `finch lsp` przez
+`vscode-languageclient` (ścieżka z ustawienia `finch.path`) i dodaje **Run** / **Build** jako zadania
+`ProcessExecution` (bez cytowania dla powłoki; matcher `$finch` zamienia linie `plik:linia:kol: error:`
+w wpisy w Problems). `syntaxes/finch.tmLanguage.json` to gramatyka TextMate, testowana przez `npm test`
+z `vscode-textmate` + `vscode-oniguruma` (tym samym silnikiem, którego używa VS Code);
+`language-configuration.json` daje komentarze, nawiasy, automatyczne domykanie i wcięcia; `snippets/`
+szablony. CI pakuje je przez `vsce` do `finch-lang.vsix`.
+
+## 26. Znane ograniczenia
 
 - Brak metod w strukturach, typów generycznych, map, `match`, domknięć i błędów jako wartości (`int("x")`, `read_file` robią panic).
 - Teksty to bajty: `.len`, `s[i]`, `upper()` nie znają Unicode.
 - Wiszące wskaźniki (`addr` zmiennej, która zniknęła, użycie po `free`) nie są wykrywane.
 - Wielkość przesunięć i konwersje float→int nie są sprawdzane (poison w LLVM, jak w C).
 - C: unie i struktury z polami bitowymi przez wartość, makra-funkcje, `long double`.
-- Testowana jedna platforma: Linux x86-64 (kod ABI jest specyficzny dla System V x86-64).
+- Dwa systemy: Linux i Windows, oba x86-64 (ABI System V i Microsoft x64). Jeszcze bez macOS i ARM.
 - Kompilator samohostujący nie ma importu C, liczb z rozmiarem ani `defer` i nie zwalnia pamięci.

docs/pl/dla-poczatkujacych.md

@@ -77,7 +77,7 @@ Jeśli ostatnia linijka skończy się bez słowa `error`, Finch jest gotowy.
 ./build/finch version
 ```
 
-Powinieneś zobaczyć coś w stylu `finch 2.0.0`.
+Powinieneś zobaczyć coś w stylu `finch 2.3.0`.
 
 ---
 

docs/pl/dla-technikow.md

@@ -29,10 +29,11 @@ kompilator działa w środku. Do tego służy [przewodnik dla inżynierów](dla-
 16. [Moduły](#16-moduły)
 17. [Biblioteki z C](#17-biblioteki-z-c)
 18. [Błędy](#18-błędy)
-19. [Debugowanie](#19-debugowanie)
-20. [Rozwiązywanie problemów](#20-rozwiązywanie-problemów)
-21. [Struktura projektu i testy](#21-struktura-projektu-i-testy)
-22. [Obecne ograniczenia](#22-obecne-ograniczenia)
+19. [Edytor: VS Code](#19-edytor-vs-code)
+20. [Debugowanie](#20-debugowanie)
+21. [Rozwiązywanie problemów](#21-rozwiązywanie-problemów)
+22. [Struktura projektu i testy](#22-struktura-projektu-i-testy)
+23. [Obecne ograniczenia](#23-obecne-ograniczenia)
 
 ---
 
@@ -59,8 +60,24 @@ i komunikaty błędów, które mówią, jak problem naprawić.
 
 ## 2. Instalacja
 
-Finch działa obecnie na **Linuksie x86-64**. Testowany był z **LLVM 21**.
-Z innymi wersjami LLVM prawdopodobnie się nie skompiluje, bo API C++ LLVM zmienia się między wydaniami.
+Finch działa na **Linuksie i Windowsie, x86-64**, i jest budowany z **LLVM 21**.
+
+### Windows
+
+1. Pobierz **`finch-windows-x64.zip`** z [wydań](https://github.com/Nexoniarz/Finch/releases) i rozpakuj,
+   np. do `C:\finch`. W środku są `finch.exe` i `libclang.dll`.
+2. Zainstaluj **LLVM 21** (`LLVM-21.x.x-win64.exe` z [wydań LLVM](https://github.com/llvm/llvm-project/releases))
+   i zaznacz *Add LLVM to the system PATH*. Finch używa jego `clang` do linkowania programów.
+3. Zainstaluj **Visual Studio Build Tools 2022** z pakietem *Desktop development with C++*: dostarcza biblioteki
+   Windowsa, z którymi linkowany jest każdy program.
+4. Dodaj `C:\finch` do PATH, otwórz nowy terminal i wpisz `finch version`.
+
+Programy to zwykłe pliki `.exe`. Żeby zbudować Fincha ze źródeł na Windowsie, idź za `.github/workflows/ci.yml`
+(Visual Studio 2022 + pakiet `clang+llvm-21.x-x86_64-pc-windows-msvc` z wydań LLVM).
+
+### Linux
+
+Z innymi wersjami LLVM Finch prawdopodobnie się nie skompiluje, bo API C++ LLVM zmienia się między wydaniami.
 
 ### Opcja A: Nix (zalecana, nic nie instalujesz ręcznie)
 
@@ -70,7 +87,7 @@ cd Finch
 nix-shell                        # pobiera LLVM, libclang, clang, cmake, ninja, pkg-config
 cmake -S . -B build -G Ninja
 ninja -C build
-./build/finch version            # finch 2.0.0 (LLVM 21.x)
+./build/finch version            # finch 2.3.0 (LLVM 21.x)
 ```
 
 ### Opcja B: pakiety z twojej dystrybucji
@@ -91,6 +108,16 @@ cmake -S . -B build -G Ninja -DLLVM_DIR=/usr/lib/llvm-21/lib/cmake/llvm
 ninja -C build
 ```
 
+### Budowanie programów na Windowsa pod Linuksem
+
+Z zainstalowanym kompilatorem krzyżowym MinGW-w64 (`x86_64-w64-mingw32-gcc`; na Niksie
+`pkgsCross.mingwW64.buildPackages.gcc`):
+
+```sh
+finch build gra.fch --target windows       # gra.exe
+finch run gra.fch --target windows         # uruchamia ją w Wine, jeśli jest zainstalowane
+```
+
 ### Dodanie `finch` do PATH (opcjonalnie)
 
 ```sh
@@ -669,7 +696,18 @@ Zamiast niezdefiniowanego zachowania (jak w C) Finch zatrzymuje się z komunikat
 
 ---
 
-## 19. Debugowanie
+## 19. Edytor: VS Code
+
+Rozszerzenie **Finch** (`editors/vscode`, dołączane też do każdego wydania jako plik `.vsix`) daje:
+podświetlanie składni, błędy na bieżąco, podpowiedzi (także pola i metody po `.`), typy po najechaniu
+myszą, idź do definicji (F12), konspekt pliku, podpowiedzi parametrów, szablony i przycisk ▶ **Run**
+(`Ctrl+F5`). Błędy z **Finch: Build This File** trafiają do panelu Problems.
+
+Instalacja: Rozszerzenia → `…` → *Install from VSIX…* → wybierz `finch-lang-*.vsix`. Rozszerzenie uruchamia
+`finch` z PATH; jeśli jest gdzie indziej, ustaw **Finch: Path** w ustawieniach. Inne edytory obsługujące
+Language Server Protocol (Neovim, Helix, Zed, Emacs, Sublime) mogą używać `finch lsp` bezpośrednio.
+
+## 20. Debugowanie
 
 ```sh
 finch build gra.fch -g -O0 -o gra
@@ -682,11 +720,12 @@ gdb ./gra
 ```
 
 `-g` dodaje informacje dla debuggera (linijki, funkcje, zmienne, pola struktur). `-O0` zostawia wszystkie
-zmienne widoczne; bez niego optymalizator może część z nich usunąć.
+zmienne widoczne; bez niego optymalizator może część z nich usunąć. Na Windowsie `-g` zapisuje format
+CodeView, który czyta debugger Visual Studio i WinDbg.
 
 ---
 
-## 20. Rozwiązywanie problemów
+## 21. Rozwiązywanie problemów
 
 | Problem | Rozwiązanie |
 |---|---|
@@ -697,12 +736,14 @@ zmienne widoczne; bez niego optymalizator może część z nich usunąć.
 | `can't find the module 'x'` | Połóż `x.fch` obok importującego pliku albo ustaw `FINCH_PATH`. |
 | `couldn't build the Finch runtime` | Brak działającego kompilatora C. Zainstaluj gcc lub clang albo ustaw `CC`. |
 | Biblioteka nie znajduje się przy starcie programu | Zlinkowano ją z folderu, którego system nie przeszukuje. Uruchamiaj w tym samym `nix-shell` albo zainstaluj ją systemowo. |
+| Windows: `finch` nie linkuje (błędy `LNK…` o `libcmt`, `kernel32`) | Zainstaluj Visual Studio Build Tools z *Desktop development with C++*. |
+| Windows: `finch.exe` się nie uruchamia (brak `libclang.dll`) | Trzymaj `libclang.dll` obok `finch.exe`. |
 | `clang` w `nix-shell` nie widzi `stdio.h` | Masz stary `shell.nix`: `llvmPackages.clang` musi być przed `llvmPackages.libclang`. |
 | Program nigdy się nie kończy | Warunek pętli nigdy nie staje się fałszywy. Naciśnij Ctrl+C. |
 
 ---
 
-## 21. Struktura projektu i testy
+## 22. Struktura projektu i testy
 
 ```
 Finch/
@@ -715,7 +756,8 @@ Finch/
 │   ├── fail/       programy, które muszą się nie udać, z oczekiwanym błędem w 1. linijce
 │   ├── run.sh      uruchamia testy (MEMCHECK=1 sprawdza też pamięć valgrindem)
 │   └── boot.sh     buduje kompilator samohostujący nim samym i porównuje
-├── docs/           ta dokumentacja (en, pl)
+├── editors/vscode/ rozszerzenie VS Code
+├── docs/           ta dokumentacja (en, pl), łącznie ze ściągą
 ├── shell.nix       środowisko deweloperskie Nix
 └── CMakeLists.txt
 ```
@@ -724,11 +766,13 @@ Finch/
 tests/run.sh                 # → 59 passed, 0 failed
 MEMCHECK=1 tests/run.sh      # to samo pod valgrindem: bez wycieków i złych dostępów do pamięci
 tests/boot.sh                # sprawdzenie samohostowania (wymaga clanga)
+tests/windows.sh             # każdy test zbudowany na Windowsa i uruchomiony w Wine
+python3 tests/lsp_test.py    # serwer języka
 ```
 
 ---
 
-## 22. Obecne ograniczenia
+## 23. Obecne ograniczenia
 
 Finch 2.0 to kompletny mały język, ale nie skończony. Jeszcze nie ma:
 
@@ -736,6 +780,6 @@ Finch 2.0 to kompletny mały język, ale nie skończony. Jeszcze nie ma:
 - Błędów jako wartości: błąd w `int("x")` albo `read_file` zatrzymuje program. Sprawdzaj wcześniej (`file_exists`).
 - Tekstu świadomego Unicode: `.len`, `s[i]` i `upper()` działają na bajtach / ASCII.
 - Wątków.
-- Platform innych niż Linux x86-64.
+- Platform innych niż Linux i Windows na x86-64 (macOS, ARM).
 
 Plan rozwoju jest w [README](../../README.pl.md#plan-rozwoju).

docs/pl/sciaga.md

@@ -0,0 +1,316 @@
+# Ściąga Fincha
+
+Cały Finch na jednej stronie. Wyjaśnienia są w [przewodnikach](../../README.pl.md#dokumentacja).
+
+> 🇬🇧 English version: [cheatsheet.md](../en/cheatsheet.md)
+
+---
+
+## Polecenie `finch`
+
+| Polecenie | Robi |
+|---|---|
+| `finch run plik.fch [argumenty…]` | skompiluj i uruchom (argumenty trafiają do programu) |
+| `finch build plik.fch [-o nazwa]` | zrób program (`nazwa.exe` na Windowsie) |
+| `finch ir plik.fch` | pokaż LLVM IR |
+| `finch lsp` | serwer języka (korzystają z niego edytory) |
+| `finch version` | wersja |
+| `-l lib` | dolinkuj bibliotekę C (jak `link "lib"`) |
+| `--target windows` / `linux` / triple | zbuduj dla innego systemu |
+| `-g` | informacje dla debuggera (gdb, lldb, Visual Studio) |
+| `-O0` | bez optymalizacji |
+
+Zmienne środowiskowe: `FINCH_PATH` (foldery z modułami), `FINCH_CC` / `CC` (kompilator C, który linkuje).
+
+---
+
+## Plik
+
+```c
+import "stdio.h"        // nagłówek C
+import ksztalty         // moduł Fincha: ksztalty.fch
+link "m"                // biblioteka C albo "moje.c" / ".o" / ".a"
+
+struct Punkt {
+    int x
+    int y = 0           // wartość domyślna
+}
+
+fn main() {
+    print("Cześć")
+}
+```
+
+`main` to `fn main()`, `fn main() -> int` (kod wyjścia) albo `fn main([]str args)`.
+Jedna instrukcja na linijkę, bez średników, `{` w tej samej linijce, bez nawiasów wokół warunków.
+
+---
+
+## Zmienne
+
+| Kod | Znaczenie |
+|---|---|
+| `x := 5` | nowa zmienna, typ zgadnięty |
+| `int x = 5` | nowa zmienna, typ podany |
+| `int x` | zero / `""` / `[]` / `null` / wartości domyślne struktury |
+| `x = 7` | przypisanie |
+| `x += 1` `-=` `*=` `/=` `%=` | zmiana |
+
+---
+
+## Typy
+
+| Typ | Przykład |
+|---|---|
+| `int` (= `i64`) | `42`, `-7`, `0xFF`, `1_000_000` |
+| `float` (= `f64`) | `3.14` |
+| `bool` | `true` (prawda), `false` (fałsz) |
+| `char` | `'A'`, `'\n'` |
+| `str` | `"tekst\t\"w cudzysłowie\""` |
+| `i8 i16 i32 i64` | ze znakiem, z rozmiarem |
+| `u8 u16 u32 u64` | bez znaku, z rozmiarem |
+| `f32 f64` | zmiennoprzecinkowe |
+| `[]T` | tablica: `[1, 2, 3]`, `[]str imiona` |
+| `ptr[T]`, `ptr` | wskaźnik, wskaźnik bez typu |
+| `Nazwa` / `modul.Nazwa` | struktura |
+
+Znaki specjalne: `\n \t \r \0 \\ \" \'`.
+
+---
+
+## Operatory
+
+| Priorytet | Operatory |
+|---|---|
+| 5 | `*` `/` `%` `<<` `>>` `&` |
+| 4 | `+` `-` `\|` `^` (`+` skleja też tekst) |
+| 3 | `==` `!=` `<` `<=` `>` `>=` |
+| 2 | `&&` (i) |
+| 1 | `\|\|` (lub) |
+| jednoargumentowe | `-x` `!x` (nie) `~x` |
+
+`x & 1 == 0` znaczy `(x & 1) == 0`.
+
+---
+
+## Sterowanie
+
+```c
+if a > b { … } else if a == b { … } else { … }
+while x > 0 { … }
+for i in 0..10 { … }          // 0 … 9
+for el in lista { … }         // każdy element (albo znak str)
+break     continue     return wartosc
+defer sprzatanie()            // uruchomi się na końcu bloku
+```
+
+---
+
+## Funkcje
+
+```c
+fn dodaj(int a, int b) -> int {
+    return a + b
+}
+fn przywitaj(str imie) {      // bez wyniku
+    print("Cześć", imie)
+}
+```
+
+Parametry zachowują się jak kopie. Kolejność w pliku nie ma znaczenia. Przecinek po ostatnim argumencie jest dozwolony.
+
+---
+
+## Struktury
+
+| Kod | Znaczenie |
+|---|---|
+| `struct P { … }` | definicja (jedno pole na linijkę, `= domyślna` opcjonalnie) |
+| `P(1, 2)` | utworzenie, wszystkie pola po kolei |
+| `P(x: 1)` | utworzenie po nazwie, reszta domyślna/zero |
+| `p.x`, `p.x = 5` | odczyt, zmiana pola |
+| `b := a` | pełna kopia |
+
+---
+
+## Tablice `[]T`
+
+| Kod | Daje |
+|---|---|
+| `a.len` | liczba elementów |
+| `a[i]`, `a[i] = x` | element (z kontrolą zakresu) |
+| `a.push(x)` | dodaj na końcu |
+| `a.pop()` | zabierz ostatni i go oddaj |
+| `a.insert(i, x)` | wstaw na pozycję i |
+| `a.remove(i)` | usuń pozycję i i ją oddaj |
+| `a.clear()` | wyczyść |
+| `a.resize(n)` | długość n (nowe elementy to zera) |
+| `a.find(x)` | indeks albo -1 |
+| `a.contains(x)` | bool |
+| `a.sort()` | posortuj (liczby, znaki, str) |
+| `a.reverse()` | odwróć |
+| `a.slice(s, e)` | nowa tablica z s … e-1 |
+| `a.join(sep)` | `[]str` → jeden str |
+| `a.ptr` | adres pierwszego elementu (dla C) |
+
+---
+
+## Tekst `str`
+
+| Kod | Daje |
+|---|---|
+| `s.len` | liczba bajtów (ą, ż… to 2) |
+| `s[i]`, `s[i] = 'x'` | znak |
+| `a + b` | sklejony tekst |
+| `s.sub(a, b)` | fragment a … b-1 |
+| `s.find(t)` | pozycja albo -1 |
+| `s.contains(t)` | czy zawiera |
+| `s.starts_with(t)`, `s.ends_with(t)` | czy zaczyna / kończy się |
+| `s.split(sep)` | `[]str` |
+| `s.trim()` | bez spacji na końcach |
+| `s.upper()`, `s.lower()` | A–Z / a–z |
+| `s.replace(a, b)` | każde a → b |
+| `s.repeat(n)` | n razy |
+| `s.bytes()` | `[]u8` |
+| `s.ptr` | `ptr[char]` (dla C) |
+| `==` `!=` `<` `>` | porównanie |
+
+---
+
+## Zamiana typów
+
+| Kod | Wynik |
+|---|---|
+| `int(3.9)` | `3` |
+| `int("42")` | `42` (zatrzymuje program, jeśli to nie liczba) |
+| `int('A')` | `65` |
+| `float(7)`, `float("2.5")` | `7`, `2.5` |
+| `u8(300)` | `44` (zostawia najniższe bity) |
+| `char(66)` | `'B'` |
+| `bool(0)` | `false` |
+| `str(42)`, `str(1.5)`, `str(true)`, `str('c')` | tekst |
+| `str(bajty)` | `[]u8` → tekst |
+| `str(p)` | `char*` z C → tekst |
+| `ptr(p)`, `ptr(16)` | wskaźnik bez typu, ze wskaźnika albo liczby |
+| `int(p)` | wskaźnik → adres |
+
+Automatycznie tylko wtedy, gdy nic nie ginie: mniejsza → większa liczba, dowolna całkowita → float, `f32` → `f64`.
+
+---
+
+## Funkcje wbudowane
+
+| Funkcja | Robi |
+|---|---|
+| `print(a, b, …)` | wypisz, spacje między, nowa linia na końcu |
+| `input()`, `input("Pytanie? ")` | wczytaj linijkę |
+| `read_file(sciezka)` | plik → str |
+| `write_file(sciezka, tekst)` | str → plik, `true`, jeśli się udało |
+| `file_exists(sciezka)` | czy plik istnieje |
+| `delete_file(sciezka)` | usuń plik |
+| `shell(polecenie)` | uruchom polecenie, jego kod wyjścia |
+| `exit(kod)` | zakończ program od razu |
+| `addr(x)` | wskaźnik na x; `addr(fn)` = callback dla C |
+| `new(wartosc)` | wartość na stercie → `ptr[T]` |
+| `free(p)` | oddaj ją |
+
+---
+
+## Wskaźniki
+
+| Finch | C |
+|---|---|
+| `ptr[int] p` | `int *p` |
+| `addr(x)` | `&x` |
+| `p.value` | `*p` |
+| `p.pole` | `p->pole` |
+| `p[i]` | `p[i]` |
+| `null` | `NULL` |
+| `ptr` | `void *` |
+
+---
+
+## Pamięć
+
+- Tablice, teksty i struktury zwalniają się same na końcu swojego bloku. Bez `free`.
+- `b := a` kopiuje; wynik wywołania jest przenoszony; `return x` przenosi.
+- `new(...)` + `free(...)` (często z `defer`) do list wiązanych, drzew, współdzielenia.
+- Pamięć z C: funkcjami z C (`malloc` / `free`, `fclose`, …).
+
+---
+
+## Moduły
+
+```c
+import ksztalty          // ksztalty.fch obok tego pliku (albo w FINCH_PATH)
+ksztalty.pole(b)         // jego funkcje
+ksztalty.Pudlo(2, 3)     // jego struktury
+ksztalty.Pudlo inne      // w deklaracjach
+```
+
+---
+
+## C
+
+| Kod | Znaczenie |
+|---|---|
+| `import "x.h"` | funkcje, struktury, enumy, liczbowe `#define`, zmienne globalne |
+| `link "nazwa"` | libnazwa.so / nazwa.lib (najpierw pkg-config) |
+| `link "plik.c"` | skompiluj własny plik C |
+| `addr(mojaFn)` | funkcja Fincha jako callback |
+
+| Typ C | Finch |
+|---|---|
+| `int` / `long long` / `unsigned` | `i32` / `i64` / `u32` (wg rozmiaru) |
+| `float` / `double` | `f32` / `f64` |
+| `char *` (parametr, wynik) | `str` |
+| `char *` (pole, za wskaźnikiem) | `ptr[char]` |
+| `struct X` | `X` |
+| `T *` | `ptr[T]` |
+| `void *`, uchwyty | `ptr` |
+| `T x[N]` (w strukturze) | `[N]T` |
+
+---
+
+## Błędy w czasie działania (program zatrzymuje się z plikiem i linijką)
+
+| Komunikat | Przyczyna |
+|---|---|
+| `division by zero` | `/` albo `%` przez 0 |
+| `index 5 is out of range (the length is 3)` | `a[5]` |
+| `pop() on an empty array` | `pop()` na pustej tablicy |
+| `used .value on a null pointer` | `.value` / `.pole` / `[i]` przez `null` |
+| `can't turn "x" into int` | `int("x")` |
+| `can't read the file "…"` | `read_file` |
+
+---
+
+## VS Code (rozszerzenie „Finch”)
+
+| Klawisz / akcja | Robi |
+|---|---|
+| ▶ / `Ctrl+F5` | uruchom plik |
+| `Finch: Build This File` | zbuduj; błędy trafiają do panelu Problems |
+| `F12` | idź do definicji |
+| najechanie myszą | typ / sygnatura / opis |
+| `Ctrl+Spacja` | podpowiedzi (po `.`: pola, metody, zawartość modułu) |
+| `Ctrl+Shift+O` | funkcje i struktury w pliku |
+| `main`, `fn`, `fnr`, `struct`, `for`, `foreach`, `if`, `ife`, `while`, `input` + Tab | szablony |
+| ustawienie `finch.path` | gdzie jest finch / finch.exe |
+
+---
+
+## Słowa kluczowe
+
+| Słowo | Po polsku |
+|---|---|
+| `fn` | funkcja |
+| `return` | zwróć |
+| `if` / `else` | jeżeli / w przeciwnym razie |
+| `while` | dopóki |
+| `for` … `in` | dla … w |
+| `break` / `continue` | przerwij / kontynuuj |
+| `true` / `false` / `null` | prawda / fałsz / nic |
+| `import` / `link` | zaimportuj / dolinkuj |
+| `struct` | struktura |
+| `defer` | odłóż (na koniec bloku) |