From b77419f4d2fc1e050a577c57067c06248e91b124 Mon Sep 17 00:00:00 2001
From: Patryk Gensch <43010113+patryk025@users.noreply.github.com>
Date: Sun, 31 May 2026 17:00:14 +0200
Subject: [PATCH] docs: add Quickstart (local, docker compose + Ghidra worker)
 to README

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 README.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 58 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index f67fb04..c2ce3e9 100644
--- a/README.md
+++ b/README.md
@@ -6,9 +6,11 @@ Cel: katalog gier (z ISO/ZIP), wersje silnika z hashami, oraz ekstrakcja i poró
 
 ## Status
 
-Faza 1: **ekstraktor `snapshot.json` z Ghidry** (walidacja na golden pair PIKLIB8 ↔ bloomoo).
-Infrastruktura (FastAPI + worker + DB + front) dochodzi dopiero, gdy format snapshotu
-będzie sprawdzony na realnych binariach.
+Pełny łańcuch działa: **binarka → (Ghidra worker) → `snapshot.json` → katalog (DB) → diff → UI**.
+Ekstraktor pokrywa 5 osi (typy / metody / eventy / pola skryptowe / ciała metod) + bonus layout C++,
+zwalidowany na golden pair PIKLIB8 (MSVC6) ↔ bloomoo (MSVC8). Nad tym: FastAPI + katalog (SQLite/Postgres),
+diff z normalizacją ciał i miarą „podobnych wersji", Command Center UI, pipeline akwizycji ISO/ZIP
+i pełny stack `docker compose` z workerem Ghidry. Zobacz **Quickstart** niżej.
 
 ## Architektura (docelowa)
 
@@ -22,6 +24,59 @@ Front (centrum dowodzenia) ─ FastAPI (katalog/hashe/diff) ─ PostgreSQL
                               Worker: Ghidra headless + extract_engine_surface.py
 ```
 
+## Quickstart
+
+### 1. Lokalnie, bez Dockera (działa od ręki — golden snapshoty są w repo)
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[api,dev]"
+
+# zasiej katalog dwoma wersjami z golden pair
+python -m ams.api.importer --game "Reksio i UFO"          snapshots/PIKLIB8.dll.snapshot.json
+python -m ams.api.importer --game "Reksio i Kapitan Nemo" snapshots/bloomoodll.dll.snapshot.json
+
+uvicorn ams.api.app:create_app --factory      # → http://127.0.0.1:8000/
+```
+
+Diff też z CLI: `python -m ams OLD.json NEW.json --owner CMC_Animo --only dispatch`.
+
+### 2. Pełny stack w Dockerze (Ghidra w workerze) — upload ISO/ZIP → snapshot
+
+```bash
+docker compose up --build        # db(Postgres) + redis + api + worker(Ghidra)
+```
+
+Pierwszy build workera **ściąga Ghidrę (~1 GB) + JDK 21** (wolny, ale cache'owany). Potem wgraj grę
+przyciskiem **+ wgraj** w UI (http://localhost:8000) albo z CLI:
+
+```bash
+curl -F file=@"/sciezka/do/gra.iso" -F game="Reksio i Czarodzieje" http://localhost:8000/jobs
+curl http://localhost:8000/jobs/1            # status: queued → started → finished
+```
+
+Worker rozpakowuje (bsdtar: ISO/ZIP), content-based znajduje DLL silnika, hashuje, odpala
+Ghidra headless + `extract_engine_surface.py` → snapshot → import do Postgresa → UI.
+
+### 3. Ghidra w obrazie — wersja / troubleshooting
+
+Worker (`docker/worker.Dockerfile`, `eclipse-temurin:21-jdk`) pobiera Ghidrę i ustawia
+`GHIDRA_HOME=/opt/ghidra`. Wersja jest przypięta w `ARG GHIDRA_URL`. Jeśli build padnie na pobieraniu,
+nadpisz URL realnym wydaniem z [releases NSA](https://github.com/NationalSecurityAgency/ghidra/releases)
+(nazwa pliku: `ghidra_<wer>_PUBLIC_<data>.zip`):
+
+```bash
+docker compose build worker \
+  --build-arg GHIDRA_URL=https://github.com/NationalSecurityAgency/ghidra/releases/download/Ghidra_11.3.2_build/ghidra_11.3.2_PUBLIC_20250415.zip
+docker compose up
+```
+
+### 4. Ekstrakcja ręcznie w GUI Ghidry (alternatywa, bez Dockera)
+
+*Script Manager → Manage Script Directories* → wskaż `ghidra_scripts/`, otwórz program (DLL),
+uruchom `extract_engine_surface.py`. Snapshot ląduje w `snapshots/<nazwa>.snapshot.json`,
+potem zaimportuj go przez `python -m ams.api.importer …`.
+
 ## Zasada ekstrakcji
 
 Ekstrakcja stoi na **kotwicach semantycznych** (cele wywołań, referowane literały