1 files changed, 75 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ba80bb4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,75 @@
+# plan9-kencc-linux
+
+Кросс-сборка **компиляторов / ассемблеров / линкеров Plan 9 (kencc)** для всех
+архитектур **с Linux-хоста**, плюс болваночное **UEFI-приложение** (PE32+),
+собранное этим же тулчейном. Ничего юниксового в цепочке сборки самих `.efi`.
+
+Собрано и проверено на Linux/musl. Пилилось телеграм-ботом (Claude) по заказу
+чата ancap.in.ua.
+
+## Что внутри
+```
+bin/                 готовые бинари: 8c 6c 5c vc qc kc (компиляторы) + 6a 6l
+scripts/
+  setup.sh           клонирует plan9foundation + plan9port, собирает plan9port
+  build_arch.sh <X>  собирает C-компилятор арки X (5|6|8|v|q|k)
+  build_al.sh  <Xa|Xl> собирает ассемблер/линкер
+  build_all.sh       собирает весь кросс-кит
+efi/
+  hello.c            сам EFI-апп (наш код)
+  fetch_ref.sh       тянет pe64.s/efi.h/mem.h из 9legacy (nboot/efi)
+  efi_build.sh       6a+6c+6l -> dd -> bootx64.efi (PE32+)
+  mkesp.py           заворачивает .efi в загрузочный ESP (FAT16)
+patches/             патчи по каждой правке (документация)
+PATCHES.md           почему каждый патч нужен
+```
+
+## Идея
+Фронтенд-компилятора Plan 9 (`cc/`) + кодогенераторы арок (`5c`,`6c`,`8c`,`vc`,`qc`,`kc`)
+пишутся на Plan 9 C и рассчитаны на родную сборку в Plan 9. Мы собираем их на Linux,
+компилируя **plan9port**-овским `9c`/`9l` (они дают `lib9`/`libbio`/`libmach` и
+дружат с хостовым gcc/musl). Всё, что мешает, лечится небольшими патчами (см. `PATCHES.md`).
+
+| арка | комп | ассемблер | линкер |
+|------|------|-----------|--------|
+| 386   | 8c | 8a | 8l |
+| amd64 | 6c | 6a | 6l |
+| arm   | 5c | 5a | 5l |
+| mips  | vc | va | vl |
+| power | qc | qa | ql |
+| sparc | kc | ka | kl |
+
+## Быстрый старт
+```sh
+# 1. зависимости (plan9foundation + plan9port)
+bash scripts/setup.sh
+export PLAN9SRC=$PWD/deps/plan9foundation
+export PLAN9PORT=$PWD/deps/plan9port
+# (опц. musl: export MUSL_ENV=/path/to/env.sh)
+
+# 2. собрать всё
+bash scripts/build_all.sh          # -> build/*/{6c,6a,6l,...}
+
+# 3. один компилятор
+bash scripts/build_arch.sh 6        # -> build/6c/6c
+
+# 4. проверить
+echo 'int f(void){return 42;}' > t.c
+build/6c/6c t.c && ls t.6           # объектник Plan9 .6
+```
+
+## EFI-болванка
+```sh
+cd efi
+./fetch_ref.sh                       # pe64.s/efi.h/mem.h из 9legacy
+PLAN9SRC=$PWD/../deps/plan9foundation ./efi_build.sh
+# -> bootx64.efi : PE32+ x64 EFI_APPLICATION
+python3 mkesp.py bootx64.efi esp.img # -> загрузочный ESP (/EFI/BOOT/BOOTX64.EFI)
+# запуск:  qemu-system-x86_64 -bios OVMF.fd -drive format=raw,file=esp.img
+```
+
+## Готовые бинари
+В `bin/` лежат уже собранные компиляторы/асм/линкер (Linux/musl x86_64).
+Под свой хост пересобери скриптами — байт-в-байт воспроизводимо.
+
+Лицензии и авторство исходников — см. `NOTICE`.