prrevers 1.1.0__tar.gz

prrevers-1.1.0/.gitignore

@@ -0,0 +1,127 @@
+# --- Python ---
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# --- Virtualenvs ---
+.venv/
+venv/
+env/
+ENV/
+.python-version
+
+# --- Testing & coverage ---
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+.cache
+nosetests.xml
+
+# --- Type checkers ---
+.mypy_cache/
+.ruff_cache/
+.pyre/
+.pytype/
+
+# --- IDEs ---
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# --- Jupyter ---
+.ipynb_checkpoints
+*.ipynb
+
+# --- Project-specific: never commit game data ---
+tests/golden/**/*.apk
+tests/golden/**/*.exe
+tests/golden/**/*.dll
+tests/golden/**/*.so
+tests/golden/**/*.bin
+tests/golden/**/*.obb
+tests/golden/**/*.pak
+tests/golden/**/*.pck
+tests/golden/**/*.ipa
+tests/golden/**/extracted/
+
+# But DO commit small synthetic fixtures
+!tests/golden/**/fixture.zip
+!tests/golden/**/*.json
+!tests/golden/**/*.ksy
+!tests/golden/**/README.md
+
+# Синтетические PE-файлы golden-фикстур e2e-тестов: 62-байтные MZ-заглушки
+# и сборки из нулей — НЕ game data. Каждая строка явная и точная, чтобы
+# случайно закоммитить настоящий .exe/.dll было невозможно.
+!tests/golden/unity-mono-win/input/Game.exe
+!tests/golden/unity-mono-win/input/Game_Data/Managed/Assembly-CSharp.dll
+!tests/golden/unity-mono-win/input/Game_Data/Managed/UnityEngine.CoreModule.dll
+!tests/golden/web-electron-install/input/Game.exe
+# Синтетический IL2CPP APK (~1 КБ, 4 записи-заглушки из нулей) — НЕ game
+# data; см. tests/golden/unity-il2cpp-apk/README.md.
+!tests/golden/unity-il2cpp-apk/input/game.apk
+
+# --- Secrets & tokens — never commit ---
+.env
+.env.*
+*.pem
+*.key
+secrets/
+credentials.json
+token.json
+
+# --- Output of extraction runs ---
+output/
+extracted/
+exports/
+work/
+tmp/
+*.tmp
+
+# Рабочий каталог CLI/MCP по умолчанию (cli.py, mcp_server.py):
+# любое «prrevers …» сыплет туда распакованные ассеты — в коммит
+# этому месту нечего попадать, поэтому игнорируется весь каталог.
+prrevers-out/
+
+# --- OS ---
+.DS_Store
+Thumbs.db
+
+# --- Logs ---
+*.log
+logs/
+
+# uv.lock не хранится в репозитории (решение 686b44e):
+# зависимости фиксирует CI через pip + pyproject constraints.
+uv.lock
+
+# Сборка документационного сайта (mkdocs build) — артефакт, не исходник.
+site/

prrevers-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pradushkoai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

prrevers-1.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.5
+Name: prrevers
+Version: 1.1.0
+Summary: AI-assisted reverse engineering toolkit for game developers — Windows & Android.
+Project-URL: Homepage, https://github.com/Pradushkoai/PRRevers
+Project-URL: Repository, https://github.com/Pradushkoai/PRRevers
+Project-URL: Issues, https://github.com/Pradushkoai/PRRevers/issues
+Project-URL: Changelog, https://github.com/Pradushkoai/PRRevers/releases
+Author: Pradushkoai
+License: MIT License
+        
+        Copyright (c) 2026 Pradushkoai
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: android,decompilation,games,godot,llm,mcp,reverse-engineering,unity,unreal,windows
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Disassemblers
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pydantic>=2.6
+Requires-Dist: rich>=13.7
+Provides-Extra: assets
+Requires-Dist: unitypy>=1.20; extra == 'assets'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff~=0.6.9; extra == 'dev'
+Requires-Dist: types-click; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Provides-Extra: frida
+Requires-Dist: frida>=16.0.0; extra == 'frida'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# PRRevers
+
+> AI-ассистированный тулз для **гейм-девов**: извлекает механики, ассеты и форматы данных из Windows и Android игр, чтобы учиться у них и вдохновляться на собственные проекты.
+
+[![CI](https://github.com/Pradushkoai/PRRevers/actions/workflows/ci.yml/badge.svg)](https://github.com/Pradushkoai/PRRevers/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://docs.astral.sh/ruff/)
+
+PRRevers — **не** декомпилятор, **не** дизассемблер и **не** замена тулзам вроде Ghidra, IDA, AssetRipper или Il2CppDumper. Это **оркестратор**: он связывает эти тулзы вместе, определяет движок, извлекает код/ассеты/данные и использует LLM-агента, чтобы объяснить механики и сгенерировать дизайн-доки, пригодные для использования в вашей собственной игре.
+
+> **Этика и легальность.** PRRevers предназначен **исключительно для исследований и обучения**. Анализируйте только те игры, которыми вы законно владеете или на которые у вас есть явное разрешение на реверс-инжиниринг. Не распространяйте извлечённый код или ассеты. Прочитайте [docs/ETHICS.ru.md](docs/ETHICS.ru.md) перед использованием.
+
+> **English version:** [README.en.md](README.en.md)
+
+---
+
+## Режимы работы
+
+PRRevers предоставляет шесть CLI-режимов, каждый как отдельная подкоманду:
+
+| Команда | Что делает | Когда использовать |
+|---|---|---|
+| `prrevers inspect <file>` | Разовый прогон: детект движка → экстракция → декомпиляция → анализ → дизайн-док | Быстрый обзор одной игры |
+| `prrevers session <file>` | Интерактивный REPL: детект + экстракция один раз, дальше задаёте вопросы | Глубокое изучение игры |
+| `prrevers compare <a> <b>` | Side-by-side сравнение двух игр: таблица механик, diff дизайн-доков, отчёт `compare/<a>-vs-<b>.md` | Выбор между стратегиями реализации |
+| `prrevers trace <file>` | Динамика: аттач к запущенной игре (Frida), хуки из статики, трейс → дизайн-док | Наблюдение механик в рантайме |
+| `prrevers mcp serve` | MCP-сервер: инструменты PRRevers для Claude Code / Cursor | LLM-агент вместо CLI |
+| `prrevers catalog <dir>` | Batch-детект движка для каждого файла в директории, таблица | Кураторская библиотека референсов |
+
+Утилиты: `prrevers tools install/list` (установка внешних тулзов в user data dir и статус), `prrevers version`.
+
+Полное описание — в [docs/architecture.ru.md § Режимы работы](docs/architecture.ru.md).
+
+## Зачем это нужно?
+
+Реверс-инжиниринг игры, чтобы у неё поучиться — это мультитулзовая, многодневная рутина:
+
+1. Определить движок (Unity Mono / IL2CPP / Unreal / Godot / кастомный).
+2. Распаковать контейнер (APK / PAK / PCK / OBB).
+3. Запустить правильный экстрактор под правильный формат.
+4. Открыть результат в Ghidra / dnSpy / UModel.
+5. Смотреть на тысячи классов и функций, чтобы найти одну механику, которая вас интересует.
+
+PRRevers автоматизирует шаги 1–3 и добавляет LLM-агента поверх 4–5, который может отвечать на вопросы вроде *«как работает инвентарь в этой игре?»* и генерировать дизайн-док.
+
+## Архитектура
+
+Пайплайн состоит из 4 этапов плюс слой оракулов, который независимо проверяет каждый этап:
+
+```
+[файл] → Детекторы → Экстракторы → Анализаторы (LLM) → Синтезаторы → [ваш проект]
+                                            ↑
+                                       Оракулы (проверяют каждый этап)
+```
+
+Ключевые архитектурные решения:
+
+- **Плагин-система движков** через протокол `EngineAdapter` + `entry_points`. Добавить новый движок теперь можно без правки ядра.
+- **Типизированная модель `Citation`** вместо `list[str]` в evidence — верифицируется `CitationOracle`.
+- **Протокол `LLMBackend`** — любой класс, реализующий протокол, можно подключить.
+- **Content-addressed кэш** — повторный запуск на том же входе почти мгновенный.
+- **Сессии** — интерактивный REPL с сохраняемой историей Q&A.
+- **Stage-level оракулы** — `DetectionOracle` (согласованность вердикта), `ExtractionOracle` (заявленные файлы против реальной ФС) и `RoundTripOracle` (побайтовая сверка с оригинальным архивом + SHA256-integrity) проверяют этапы сразу после выполнения.
+- **Pure-Python экстракторы** — stdlib `zipfile`/`shutil`/`json`+`struct` покрывают ZIP-контейнеры, Unity-layout и Electron `app.asar` без установки apktool; первая обёртка над внешним тулзом — ILSpy (`prrevers tools install ilspy`) — превращает Mono-сборки в читаемый C#.
+
+Полное обоснование архитектуры: [docs/architecture.ru.md](docs/architecture.ru.md).
+
+## Документация
+
+Документационный сайт (mkdocs-material): архитектура, роадмап, внешние
+тулзы, этика, кейсы — с навигацией и поиском.
+
+```bash
+uv sync --extra docs   # или: pip install -e ".[docs]"
+mkdocs serve           # localhost:8000
+mkdocs build --strict  # проверка: битые ссылки ломают сборку (и CI)
+```
+
+CI собирает сайт в strict-режиме на каждый push.
+
+## Статус
+
+`main` — закрыты v0.1.0 (Unity Mono + web-игры end-to-end), v0.2.0 (IL2CPP: Il2CppDumper + Ghidra headless), v0.3.0 (LLM-анализатор: Ollama / OpenAI / Anthropic / GigaChat / LiteLLM, цитаты `file:line`), v0.4.0 (REPL-сессии + MCP-сервер), v0.5.0 (Unity-ассеты: AssetRipper → UnityPy fallback + манифест + `AssetRoundTripOracle`), v0.6.0 (синтез для game-dev: clean-room скелеты Unity C# / Godot GDScript + переводчик шейдеров HLSL→GLSL→AGSL + импортёр уровней (схема v1 → `.tscn` / C#, `LevelRoundTripOracle`)), v0.7.0 (Unreal и нативные движки: `UnrealPakExtractor` + `UModelExtractor` + `GhidraNativeExtractor` для кастомных C++ движков + фингерпринтинг кастомных движков — Ren'Py/Cocos2d-x/MonoGame/LÖVE/RGSS/Clickteam → нативная Ghidra-дорога), v0.8.0 (динамический анализ: `prrevers trace` — аттач к живому процессу через Frida (опциональный extras `[frida]`), хуки по адресам из собственной статики (дамп Il2CppDumper / Ghidra-манифест), подсистемы inventory/combat/save_load, JSONL-трейс + `TraceOracle` + trace-to-doc дизайн-док из событий `[ts Метод]`; без живой игры — честный отказ, трейсы не выдумываются). Экстракция без внешних тулзов: **ZIP-контейнеры** (APK / OBB / raw ZIP), **Windows-установки Unity** (Mono / IL2CPP layout), **Electron `app.asar`**; декомпиляция `Assembly-CSharp.dll` → C# через ILSpy (`prrevers tools install ilspy`; без тулза — честный warning, не тихая деградация); распаковка Unreal `.pak` — тулзом из установки движка (`$UNREAL_PAK`), экспорт ассетов — UModel (gildor.org, вручную). Детекция движков реальная (Unity Mono/IL2CPP, Unreal, Godot, GameMaker, Web — Cordova/Capacitor/Electron, известные кастомные — фингерпринтингом строковых маркеров). Анализ — реален при подключённом LLM-бэкенде; синтез — дизайн-доки + clean-room скелеты под целевой движок (Unity C# / Godot GDScript, `--target-engine`) + переводы шейдеров + импорт уровней, v0.9.0 (compare mode: две игры через один пайплайн — сравнительная таблица механик, diff дизайн-доков по секциям, `ComparisonOracle`), v1.0.0 (стабильный API: заморожены top-level экспорты, CLI-команды и имена MCP-инструментов; цикл депрекации; PyPI-релиз-инженерия — `pip install prrevers` после проставленного владельцем тега; документационный сайт mkdocs; первый опубликованный end-to-end кейс «Gold Rush» — своя Electron-игра, [docs/cases/web-gold-rush.md](docs/cases/web-gold-rush.md)). См. [docs/ROADMAP.ru.md](docs/ROADMAP.ru.md) и [CHANGELOG.md](CHANGELOG.md).
+
+## Установка
+
+```bash
+# из PyPI (начиная с v1.0.0)
+pip install prrevers
+
+# опциональные возможности — extras (см. ниже)
+pip install "prrevers[mcp]"   # MCP-сервер для Claude Code / Cursor
+pip install "prrevers[assets]" # pure-Python fallback Unity-ассетов
+pip install "prrevers[frida]" # динамический анализ (живой процесс игры)
+
+# из репозитория (разработка)
+git clone https://github.com/Pradushkoai/PRRevers.git
+cd PRRevers
+pip install -e ".[dev]"
+pre-commit install
+
+# опционально: pure-Python fallback экстракции Unity-ассетов
+# (AssetRipper остаётся внешним тулзом — см. таблицу ниже)
+pip install -e ".[assets]"
+
+# опционально: динамический анализ (v0.8.0) — аттач к живой игре
+# через Frida: локально Windows/macOS/Linux или Android по USB
+pip install -e ".[frida]"
+```
+
+Внешние тулзы, которые оркестрирует PRRevers (см. [docs/external-tools.ru.md](docs/external-tools.ru.md); `prrevers tools install <name>` ставит их в user data dir автоматически):
+
+| Тулз | Назначение | Требуется для |
+| --- | --- | --- |
+| `ILSpy` (ilspycmd) | Декомпиляция .NET / Unity Mono в C# | Unity Mono-игры (`prrevers tools install ilspy`) |
+| `apktool` | Распаковка APK | Android-игры (смелали/ресурсы) |
+| `Il2CppDumper` | Дамп метадаты Unity IL2CPP | Unity IL2CPP-игры |
+| `AssetRipper` | Экспорт Unity-ассетов | Unity-ассеты |
+| `Ghidra` (headless) | Анализ нативного кода | Кастомные движки / IL2CPP |
+| `jadx` | DEX → Java | не-Unity Android-игры |
+
+## Быстрый старт
+
+```bash
+prrevers inspect path/to/game.apk
+prrevers inspect path/to/game.exe --engine auto
+prrevers session path/to/game.apk --name mygame
+prrevers catalog /path/to/games/folder
+
+# опционально: C# из Assembly-CSharp.dll (нужен .NET SDK)
+prrevers tools install ilspy
+
+# динамический анализ (v0.8.0): игра должна быть ЗАПУЩЕНА
+pip install -e ".[frida]"
+prrevers trace path/to/game.apk --list-processes   # найти pid/name игры
+prrevers trace path/to/game.apk --pid 4242 --duration 120 \
+    --subsystem inventory --subsystem combat
+# → трейс prrevers-out/traces/*.jsonl + дизайн-док
+# prrevers-out/synthesized/*-trace.md (с LLM — анализ механик по событиям,
+# без LLM — честный stub из таблицы частот)
+```
+
+## Контрибьюшн
+
+Контрибьюшны приветствуются. Сначала прочитайте [CONTRIBUTING.md](CONTRIBUTING.md). Участвуя, вы соглашаетесь следовать [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Лицензия
+
+[MIT](LICENSE) © Pradushkoai

prrevers-1.1.0/README.md

@@ -0,0 +1,150 @@
+# PRRevers
+
+> AI-ассистированный тулз для **гейм-девов**: извлекает механики, ассеты и форматы данных из Windows и Android игр, чтобы учиться у них и вдохновляться на собственные проекты.
+
+[![CI](https://github.com/Pradushkoai/PRRevers/actions/workflows/ci.yml/badge.svg)](https://github.com/Pradushkoai/PRRevers/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://docs.astral.sh/ruff/)
+
+PRRevers — **не** декомпилятор, **не** дизассемблер и **не** замена тулзам вроде Ghidra, IDA, AssetRipper или Il2CppDumper. Это **оркестратор**: он связывает эти тулзы вместе, определяет движок, извлекает код/ассеты/данные и использует LLM-агента, чтобы объяснить механики и сгенерировать дизайн-доки, пригодные для использования в вашей собственной игре.
+
+> **Этика и легальность.** PRRevers предназначен **исключительно для исследований и обучения**. Анализируйте только те игры, которыми вы законно владеете или на которые у вас есть явное разрешение на реверс-инжиниринг. Не распространяйте извлечённый код или ассеты. Прочитайте [docs/ETHICS.ru.md](docs/ETHICS.ru.md) перед использованием.
+
+> **English version:** [README.en.md](README.en.md)
+
+---
+
+## Режимы работы
+
+PRRevers предоставляет шесть CLI-режимов, каждый как отдельная подкоманду:
+
+| Команда | Что делает | Когда использовать |
+|---|---|---|
+| `prrevers inspect <file>` | Разовый прогон: детект движка → экстракция → декомпиляция → анализ → дизайн-док | Быстрый обзор одной игры |
+| `prrevers session <file>` | Интерактивный REPL: детект + экстракция один раз, дальше задаёте вопросы | Глубокое изучение игры |
+| `prrevers compare <a> <b>` | Side-by-side сравнение двух игр: таблица механик, diff дизайн-доков, отчёт `compare/<a>-vs-<b>.md` | Выбор между стратегиями реализации |
+| `prrevers trace <file>` | Динамика: аттач к запущенной игре (Frida), хуки из статики, трейс → дизайн-док | Наблюдение механик в рантайме |
+| `prrevers mcp serve` | MCP-сервер: инструменты PRRevers для Claude Code / Cursor | LLM-агент вместо CLI |
+| `prrevers catalog <dir>` | Batch-детект движка для каждого файла в директории, таблица | Кураторская библиотека референсов |
+
+Утилиты: `prrevers tools install/list` (установка внешних тулзов в user data dir и статус), `prrevers version`.
+
+Полное описание — в [docs/architecture.ru.md § Режимы работы](docs/architecture.ru.md).
+
+## Зачем это нужно?
+
+Реверс-инжиниринг игры, чтобы у неё поучиться — это мультитулзовая, многодневная рутина:
+
+1. Определить движок (Unity Mono / IL2CPP / Unreal / Godot / кастомный).
+2. Распаковать контейнер (APK / PAK / PCK / OBB).
+3. Запустить правильный экстрактор под правильный формат.
+4. Открыть результат в Ghidra / dnSpy / UModel.
+5. Смотреть на тысячи классов и функций, чтобы найти одну механику, которая вас интересует.
+
+PRRevers автоматизирует шаги 1–3 и добавляет LLM-агента поверх 4–5, который может отвечать на вопросы вроде *«как работает инвентарь в этой игре?»* и генерировать дизайн-док.
+
+## Архитектура
+
+Пайплайн состоит из 4 этапов плюс слой оракулов, который независимо проверяет каждый этап:
+
+```
+[файл] → Детекторы → Экстракторы → Анализаторы (LLM) → Синтезаторы → [ваш проект]
+                                            ↑
+                                       Оракулы (проверяют каждый этап)
+```
+
+Ключевые архитектурные решения:
+
+- **Плагин-система движков** через протокол `EngineAdapter` + `entry_points`. Добавить новый движок теперь можно без правки ядра.
+- **Типизированная модель `Citation`** вместо `list[str]` в evidence — верифицируется `CitationOracle`.
+- **Протокол `LLMBackend`** — любой класс, реализующий протокол, можно подключить.
+- **Content-addressed кэш** — повторный запуск на том же входе почти мгновенный.
+- **Сессии** — интерактивный REPL с сохраняемой историей Q&A.
+- **Stage-level оракулы** — `DetectionOracle` (согласованность вердикта), `ExtractionOracle` (заявленные файлы против реальной ФС) и `RoundTripOracle` (побайтовая сверка с оригинальным архивом + SHA256-integrity) проверяют этапы сразу после выполнения.
+- **Pure-Python экстракторы** — stdlib `zipfile`/`shutil`/`json`+`struct` покрывают ZIP-контейнеры, Unity-layout и Electron `app.asar` без установки apktool; первая обёртка над внешним тулзом — ILSpy (`prrevers tools install ilspy`) — превращает Mono-сборки в читаемый C#.
+
+Полное обоснование архитектуры: [docs/architecture.ru.md](docs/architecture.ru.md).
+
+## Документация
+
+Документационный сайт (mkdocs-material): архитектура, роадмап, внешние
+тулзы, этика, кейсы — с навигацией и поиском.
+
+```bash
+uv sync --extra docs   # или: pip install -e ".[docs]"
+mkdocs serve           # localhost:8000
+mkdocs build --strict  # проверка: битые ссылки ломают сборку (и CI)
+```
+
+CI собирает сайт в strict-режиме на каждый push.
+
+## Статус
+
+`main` — закрыты v0.1.0 (Unity Mono + web-игры end-to-end), v0.2.0 (IL2CPP: Il2CppDumper + Ghidra headless), v0.3.0 (LLM-анализатор: Ollama / OpenAI / Anthropic / GigaChat / LiteLLM, цитаты `file:line`), v0.4.0 (REPL-сессии + MCP-сервер), v0.5.0 (Unity-ассеты: AssetRipper → UnityPy fallback + манифест + `AssetRoundTripOracle`), v0.6.0 (синтез для game-dev: clean-room скелеты Unity C# / Godot GDScript + переводчик шейдеров HLSL→GLSL→AGSL + импортёр уровней (схема v1 → `.tscn` / C#, `LevelRoundTripOracle`)), v0.7.0 (Unreal и нативные движки: `UnrealPakExtractor` + `UModelExtractor` + `GhidraNativeExtractor` для кастомных C++ движков + фингерпринтинг кастомных движков — Ren'Py/Cocos2d-x/MonoGame/LÖVE/RGSS/Clickteam → нативная Ghidra-дорога), v0.8.0 (динамический анализ: `prrevers trace` — аттач к живому процессу через Frida (опциональный extras `[frida]`), хуки по адресам из собственной статики (дамп Il2CppDumper / Ghidra-манифест), подсистемы inventory/combat/save_load, JSONL-трейс + `TraceOracle` + trace-to-doc дизайн-док из событий `[ts Метод]`; без живой игры — честный отказ, трейсы не выдумываются). Экстракция без внешних тулзов: **ZIP-контейнеры** (APK / OBB / raw ZIP), **Windows-установки Unity** (Mono / IL2CPP layout), **Electron `app.asar`**; декомпиляция `Assembly-CSharp.dll` → C# через ILSpy (`prrevers tools install ilspy`; без тулза — честный warning, не тихая деградация); распаковка Unreal `.pak` — тулзом из установки движка (`$UNREAL_PAK`), экспорт ассетов — UModel (gildor.org, вручную). Детекция движков реальная (Unity Mono/IL2CPP, Unreal, Godot, GameMaker, Web — Cordova/Capacitor/Electron, известные кастомные — фингерпринтингом строковых маркеров). Анализ — реален при подключённом LLM-бэкенде; синтез — дизайн-доки + clean-room скелеты под целевой движок (Unity C# / Godot GDScript, `--target-engine`) + переводы шейдеров + импорт уровней, v0.9.0 (compare mode: две игры через один пайплайн — сравнительная таблица механик, diff дизайн-доков по секциям, `ComparisonOracle`), v1.0.0 (стабильный API: заморожены top-level экспорты, CLI-команды и имена MCP-инструментов; цикл депрекации; PyPI-релиз-инженерия — `pip install prrevers` после проставленного владельцем тега; документационный сайт mkdocs; первый опубликованный end-to-end кейс «Gold Rush» — своя Electron-игра, [docs/cases/web-gold-rush.md](docs/cases/web-gold-rush.md)). См. [docs/ROADMAP.ru.md](docs/ROADMAP.ru.md) и [CHANGELOG.md](CHANGELOG.md).
+
+## Установка
+
+```bash
+# из PyPI (начиная с v1.0.0)
+pip install prrevers
+
+# опциональные возможности — extras (см. ниже)
+pip install "prrevers[mcp]"   # MCP-сервер для Claude Code / Cursor
+pip install "prrevers[assets]" # pure-Python fallback Unity-ассетов
+pip install "prrevers[frida]" # динамический анализ (живой процесс игры)
+
+# из репозитория (разработка)
+git clone https://github.com/Pradushkoai/PRRevers.git
+cd PRRevers
+pip install -e ".[dev]"
+pre-commit install
+
+# опционально: pure-Python fallback экстракции Unity-ассетов
+# (AssetRipper остаётся внешним тулзом — см. таблицу ниже)
+pip install -e ".[assets]"
+
+# опционально: динамический анализ (v0.8.0) — аттач к живой игре
+# через Frida: локально Windows/macOS/Linux или Android по USB
+pip install -e ".[frida]"
+```
+
+Внешние тулзы, которые оркестрирует PRRevers (см. [docs/external-tools.ru.md](docs/external-tools.ru.md); `prrevers tools install <name>` ставит их в user data dir автоматически):
+
+| Тулз | Назначение | Требуется для |
+| --- | --- | --- |
+| `ILSpy` (ilspycmd) | Декомпиляция .NET / Unity Mono в C# | Unity Mono-игры (`prrevers tools install ilspy`) |
+| `apktool` | Распаковка APK | Android-игры (смелали/ресурсы) |
+| `Il2CppDumper` | Дамп метадаты Unity IL2CPP | Unity IL2CPP-игры |
+| `AssetRipper` | Экспорт Unity-ассетов | Unity-ассеты |
+| `Ghidra` (headless) | Анализ нативного кода | Кастомные движки / IL2CPP |
+| `jadx` | DEX → Java | не-Unity Android-игры |
+
+## Быстрый старт
+
+```bash
+prrevers inspect path/to/game.apk
+prrevers inspect path/to/game.exe --engine auto
+prrevers session path/to/game.apk --name mygame
+prrevers catalog /path/to/games/folder
+
+# опционально: C# из Assembly-CSharp.dll (нужен .NET SDK)
+prrevers tools install ilspy
+
+# динамический анализ (v0.8.0): игра должна быть ЗАПУЩЕНА
+pip install -e ".[frida]"
+prrevers trace path/to/game.apk --list-processes   # найти pid/name игры
+prrevers trace path/to/game.apk --pid 4242 --duration 120 \
+    --subsystem inventory --subsystem combat
+# → трейс prrevers-out/traces/*.jsonl + дизайн-док
+# prrevers-out/synthesized/*-trace.md (с LLM — анализ механик по событиям,
+# без LLM — честный stub из таблицы частот)
+```
+
+## Контрибьюшн
+
+Контрибьюшны приветствуются. Сначала прочитайте [CONTRIBUTING.md](CONTRIBUTING.md). Участвуя, вы соглашаетесь следовать [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Лицензия
+
+[MIT](LICENSE) © Pradushkoai

prrevers-1.1.0/docs/ETHICS.en.md

@@ -0,0 +1,77 @@
+# Ethics & responsible use
+
+PRRevers is a research tool. Using it correctly is your responsibility.
+This page exists to make that responsibility explicit.
+
+## What this tool is for
+
+- **Learning** how other games implement mechanics you admire.
+- **Documenting** software you own when no documentation is available.
+- **Interoperability** — reading save files, level formats, or mod formats
+  so you can build tools around games you love.
+- **Security research** on software you have authorization to test.
+
+## What this tool is not for
+
+- Pirating, cracking, or bypassing DRM / copy protection.
+- Redistributing code, assets, audio, or text extracted from games you
+  do not have the rights to.
+- Cheating in online games or gaining competitive advantages.
+- Analyzing software you do not own or do not have permission to study.
+
+## The clean-room rule
+
+PRRevers's synthesizers produce **original code** that implements the
+same behavior as the analyzed game's mechanic. They do not copy
+decompiled code verbatim. This is the same principle that lets
+clean-room reimplementations of BIOSes, file formats, and protocols
+exist legally.
+
+What this means in practice:
+
+1. **Read** the analysis output (a design doc), not the decompiled code.
+2. **Implement** the mechanic in your own style, in your own codebase.
+3. **Cite** the inspiration where appropriate, just like you would cite
+   a paper.
+
+If you find yourself copy-pasting decompiled code into your game, stop.
+That is not what PRRevers is for.
+
+## Jurisdiction
+
+The legality of reverse engineering varies by country:
+
+- **United States** — DMCA §1201 prohibits circumventing technological
+  protection measures, even for interoperability. Reverse engineering
+  for interoperability is generally allowed under §1201(f), but
+  distribution of tools that enable circumvention is restricted.
+- **European Union** — Software Directive 91/250/EEC (now
+  Directive 2009/24/EC) explicitly permits reverse engineering for
+  interoperability. But circumventing DRM is restricted.
+- **Russia** — Civil Code Article 1280 permits reverse engineering for
+  interoperability, with conditions.
+- **Other jurisdictions** — check local law. PRRevers's authors are not
+  lawyers and this document is not legal advice.
+
+When in doubt, consult a lawyer. The fact that PRRevers *can* analyze a
+file does not mean it *should*.
+
+## Reporting misuse
+
+If you become aware of PRRevers being used to redistribute copyrighted
+assets, crack DRM, or otherwise violate the project's intent, please
+report it via a GitHub issue (for non-sensitive reports) or to the
+maintainer's email listed in `SECURITY.md`.
+
+The maintainers reserve the right to:
+
+- Close issues / PRs that demonstrate or facilitate misuse.
+- Remove examples from the documentation that reference specific
+  commercial games by name.
+- Decline contributions whose primary purpose is circumvention.
+
+## Summary
+
+> **If you don't own it or don't have permission, don't reverse it.**
+> **If you reverse it, don't redistribute what you find.**
+> **If you learn from it, write your own code.**