Aggiorna e approfondisci tutta la documentazione

Riscritti tutti i file doc/ e README.md per riflettere lo stato attuale
del gioco (8 livelli, multi-nemico, corsa, finale tragico, musica
dedicata, fog scalabile, flush dinamico, claimed.png death screen, ecc.):

- index.md: nuovo indice con riferimenti ai 7 capitoli aggiornati.
- architecture.md: tabella moduli con righe, variabili chiave globals,
  pipeline asset, vincoli hardware (ROM/WRAM/VRAM/OAM).
- graphics.md: proiezione iso, fog scalabile (fog_radius), auto-tiling
  multi-pass, flush dinamico 16-righe con wrap, HUD stamina + livello.
- generation.md: DFS con stack WRAM, dimensioni crescenti 7->21, botola
  a distanza scalabile, spawn multi-nemico.
- gameplay.md: DAS, camminata, corsa, salto, stamina scalabile,
  progressione 8 livelli, schermate (death/going deeper/finale).
- ai.md: multi-entity (8 fantasmi), greedy, cooldown scalabile, hitbox,
  culling.
- audio.md: 4 canali APU, 5 tracce (title 112/3canali, gameplay 96,
  gameover 128, finale 192 loop, going deeper 96), SFX.
- AScreamFromTheDark_report.md: riscritto completamente (~200 righe),
  tutte le sezioni aggiornate, workaround storici, debiti tecnici.
- README.md: intro, caratteristiche, soundtrack, architettura, test.

doc/index.md

@@ -1,25 +1,23 @@
-# Game Boy Iso-Engine: Documentazione Tecnica
+# A Scream from the Dark — Documentazione Tecnica
 
-Benvenuto nella documentazione tecnica del progetto. Questo motore per Game Boy a 8-bit è stato progettato per dimostrare come tecniche avanzate (prospettiva isometrica, fog of war, generazione procedurale e intelligenza artificiale) possano essere implementate sulle ristrette risorse hardware del Game Boy (CPU Sharp LR35902 a 4.19 MHz, 8KB WRAM).
+Benvenuto nella documentazione tecnica di **A Scream from the Dark**, un survival-horror procedurale in prospettiva isometrica 2.5D per Game Boy (DMG/CGB). Il gioco è scritto in C con **GBDK-2020** (compilatore **SDCC**) e dimostra come tecniche avanzate — prospettiva isometrica, fog of war dinamico, generazione procedurale, AI multi-nemico, audio polifonico e progressione di difficoltà — possano essere implementate sulle ristrette risorse hardware del Game Boy (CPU Sharp LR35902 a 4.19 MHz, 8 KB WRAM, 32 KB ROM).
+
+## Il gioco in breve
+
+Sei imprigionato in un labirinto generato casualmente, illuminato solo da un ristretto quadrato di visibilità. Un **fantasma** si nasconde nel buio e ti bracca. L'unica via di fuga è una **botola** posta lontano dalla partenza: raggiungerla significa sprofondare più giù (*Going Deeper*) e affrontare un livello più grande e più difficile. Dopo **8 livelli** il gioco finisce con un **finale tragico**.
 
 ## Indice dei Capitoli
 
-La documentazione è suddivisa in file separati, ognuno dedicato a un aspetto specifico dell'engine.
+1. **[Architettura di Base](architecture.md)** — Struttura del codice, moduli, stato globale, pipeline asset, vincoli hardware.
 
-1. **[Architettura di Base](architecture.md)**
-   Struttura del codice, organizzazione in moduli (src, assets, scripts) e gestione dello stato globale per evitare dipendenze circolari in C.
+2. **[Motore Grafico e Rendering](graphics.md)** — Proiezione isometrica, auto-tiling multi-pass, fog of war scalabile, flush dinamico, VRAM management.
 
-2. **[Motore Grafico e Rendering](graphics.md)**
-   La matematica dietro la proiezione isometrica, l'ottimizzazione dell'auto-tiling, il sistema "Fog of War" basato sulla distanza di Chebyshev e la gestione dei metasprite.
+3. **[Generazione Procedurale del Livello](generation.md)** — DFS con stack WRAM, creazione di loop, posizionamento della botola, dimensioni crescenti.
 
-3. **[Generazione Procedurale del Livello](generation.md)**
-   Come l'algoritmo Depth-First Search (DFS) crea un labirinto perfetto, come vengono generati i loop per il gameplay e come la distanza di Manhattan posiziona il traguardo.
+4. **[Fisica e Controlli del Giocatore](gameplay.md)** — DAS, state machine, camminata, corsa (B+direzione), salto evasivo, stamina, progressione livelli, finale tragico.
 
-4. **[Fisica e Controlli del Giocatore](gameplay.md)**
-   Il sistema di input con Delayed Auto-Shift (DAS), la State Machine rigida per l'allineamento alla griglia, e la complessa meccanica del salto con traiettoria parabolica e costo in Stamina.
+5. **[Intelligenza Artificiale (Fantasmi)](ai.md)** — Multi-entity (fino a 8 fantasmi), pathfinding greedy, cooldown scalabile, hitbox pixel-perfect.
 
-5. **[Intelligenza Artificiale (Il Fantasma)](ai.md)**
-   Perché il nemico usa un algoritmo Greedy invece di A*, il sistema di cooldown dei movimenti per bilanciare il gameplay, e la hitbox "Pixel-Perfect" che scatena il Game Over.
+6. **[Sintesi Audio e Musica](audio.md)** — 4 canali APU, sequencer via VBL interrupt, title music (112 note, 3 canali), gameplay eerie, gameover, finale dedicato (192 note, loop).
 
-6. **[Sintesi Audio e Musica](audio.md)**
-   Come l'engine manipola direttamente i registri hardware APU (Audio Processing Unit) per creare arpeggi finti, percussioni bianche (noise channel) e melodie atmosferiche.
+7. **[Report Tecnico Approfondito](AScreamFromTheDark_report.md)** — Analisi completa di architettura, funzionalità, workaround storici e debiti tecnici.