docs: update README with performance roadmap

AGENTS.md

@@ -8,6 +8,20 @@
 - Все ограничения и договорённости фиксируются исключительно в `AGENTS.md`.
 - Добавление CI-проверок (CI-guard) для принудительного контроля этих правил запрещено.
 
+## Загрузка больших файлов через GitHub API
+
+- Это правило применяется только при работе из облачной среды ChatGPT/OpenAI, где агент изменяет GitHub через подключённый GitHub-коннектор/API. При обычной локальной работе с клоном репозитория следует использовать стандартные `git add`/`git commit`/`git push`; описанный ниже обход там не нужен.
+- GitHub Contents API (`create_file`/`update_file`) нельзя считать универсальным способом загрузки: для крупных файлов он может упираться в лимит около 1 МБ.
+- Для крупного файла нужно использовать Git Data API и собирать commit вручную:
+  1) получить полное содержимое файла и создать blob через `create_blob` (`utf-8` для текста либо `base64` для бинарных данных);
+  2) если Git blob SHA уже известен и соответствующий blob существует в object storage репозитория, шаг `create_blob` можно пропустить и использовать этот SHA напрямую;
+  3) создать tree через `create_tree`, обязательно указав tree текущего head commit как `base_tree_sha`, чтобы не потерять остальные файлы ветки;
+  4) создать commit через `create_commit`, указав текущий head commit как `parent_sha`;
+  5) передвинуть ветку на новый commit через `update_ref` без force;
+  6) проверить результат через `compare_commits` относительно целевой ветки.
+- Нельзя создавать tree от устаревшего base/head: это может незаметно удалить из нового commit изменения, уже находившиеся в ветке.
+- В случае с `src/lua/vm.zig` blob уже существовал под SHA `cbeb0e2c1af19b831fbffb65e529dcaed9dce325`. Поэтому файл был добавлен в `docs/readme-performance-roadmap` цепочкой `create_tree → create_commit → update_ref`, минуя лимит Contents API.
+
 ## Toolchain target
 
 - Проект таргетит актуальную установленную версию Zig, доступную как `zig`.