docs: finalize COMPILE.md and tailored PHILOSOPHY.md

Author: andrestubbe

docs/COMPILE.md

@@ -1,13 +1,60 @@
-# FastImage Compilation Guide
+# Building FastImage 🛠️
 
-## Native C++ MSVC AVX2 Build Chain
+Complete build guide for compiling the native C++ AVX2 SIMD image processing engine and packaging the Java JAR.
 
-1. Requirements: Visual Studio 2022 / 2026 with "Desktop development with C++" and JDK 17+.
-2. Open Developer Command Prompt or PowerShell in the repository root.
-3. Run the automated native compilation script:
+---
+
+## Prerequisites
+
+* **Windows 10 or 11 (64-bit)**
+* **JDK 17+** ([Eclipse Adoptium](https://adoptium.net/) or [Oracle JDK](https://www.oracle.com/java/technologies/downloads/))
+* **Visual Studio 2022 or 2026** (Community, Professional, or Enterprise) with "Desktop development with C++" workload
+* **Windows 10/11 SDK** (installed with Visual Studio)
+* **Maven 3.9+**
+
+---
+
+## Automated One-Click Build
+
+FastImage provides an automated build script with Visual Studio and JDK discovery:
 
 ```cmd
+# In the FastImage repository root:
 compile.bat
 ```
 
-This compiles `fastimage.dll` with MSVC AVX2 flags (`/arch:AVX2 /O2 /D_CRT_SECURE_NO_WARNINGS`) and copies the output DLL to `src/main/resources/native/` and `src/main/resources/win32-x86-64/`.
+What `compile.bat` does automatically:
+1. Detects Visual Studio 2026 / 2022 Community via `vswhere.exe`.
+2. Sets up the 64-bit developer environment (`vcvars64.bat`).
+3. Compiles `src/main/native/fastimage.cpp` with MSVC AVX2 flags:
+   - `/O2` (maximum speed)
+   - `/arch:AVX2` (256-bit SIMD vectorization)
+   - `/D_CRT_SECURE_NO_WARNINGS`
+4. Automatically copies `fastimage.dll` to:
+   - `src/main/resources/native/fastimage.dll`
+   - `src/main/resources/win32-x86-64/fastimage.dll`
+   - `%USERPROFILE%\.fastcore\native\fastimage\fastimage.dll`
+
+---
+
+## Maven Java Packaging
+
+Once the native DLL is compiled, build and install to your local Maven repository:
+
+```bash
+# Build and install to ~/.m2/repository
+mvn clean install -DskipTests
+```
+
+---
+
+## JMH Benchmarking
+
+To build and execute the official JMH benchmark suite:
+
+```cmd
+run-benchmark.bat
+```
+
+---
+**Part of the FastJava Ecosystem** — *Making the JVM faster. ⚡*

docs/PHILOSOPHY.md

@@ -1,29 +1,29 @@
-# The Philosophy of FastXXX
+# The Philosophy of FastImage 💡
 
 > [!IMPORTANT]
 > **"Keine Kopien. Niemals. Kritischer JNI-Pfad. Native-First Performance."**
 
-FastXXX is built on the principle that modern Java applications require **native-first** acceleration for performance-critical operations that the standard JVM APIs don't fully optimize.
+FastImage is built on the conviction that 2D image processing, UI blurring, and computer vision pipelines in Java must never be crippled by JVM heap allocations, garbage collection stalls, or slow scalar rasterizers.
 
 ## Core Tenets
 
-1.  **Native-First Execution**
-    Bypass standard Java layers to reach the physical limits of the hardware using hand-tuned C++ and SIMD intrinsics.
+1.  **Native-First SIMD Execution**
+    Bypass standard Java2D and `BufferedImage` software loops to reach physical CPU limits using hand-tuned C++ with 256-bit AVX2 vector intrinsics.
 
-2.  **Zero-Copy JNI Architecture**
-    Minimize JNI transition costs by using direct memory access patterns and avoiding implicit memory copies between the JVM and the native layer.
+2.  **Off-Heap Zero-GC Architecture**
+    Maintain pixel buffers strictly in native unmanaged memory. Zero JVM Garbage Collection pauses even when processing uncompressed 1080p and 4K frames at 60+ FPS.
 
-3.  **Deterministic Latency**
-    Eliminate variance caused by JIT warm-up or garbage collection stalls in critical hot-paths.
+3.  **Zero-Copy Foreign Buffer Interop**
+    Seamlessly wrap raw 64-bit pointers, `FastPointer` handles, and `DirectByteBuffer` allocations from sibling modules (`FastScreen`, `FastCamera`, `FastRobot`) without duplicating memory.
 
-4.  **Hardware-Aware Optimization**
-    Leverage modern CPU features (AVX, SSE, NEON) to process data at hardware-native speeds.
+4.  **Hardware-Grade Filtering Algorithms**
+    Provide modern GPU-grade blur (Dual-Kawase) and box area-average downsampling in native CPU kernels for high-quality UI overlays and downscaling without aliasing artifacts.
 
-5.  **Blueprint Consistency**
-    As part of the **FastJava** ecosystem, FastXXX adheres to a standardized architecture:
-    *   **Native Backend**: Direct C++ implementation.
-    *   **Unified Loading**: Powered by `FastCore`.
-    *   **Premium Quality**: Built for high-performance systems and autonomous agents.
+5.  **FastJava Blueprint Consistency**
+    As part of the **FastJava** ecosystem:
+    *   **Native Backend**: Direct C++ implementation with AVX2 optimizations.
+    *   **Unified Loading**: Powered by `FastCore` for zero-dependency native deployment.
+    *   **Production Quality**: High-performance, clean chaining API, and thorough JMH profiling.
 
 ---
-**⚡ FastXXX — Powering the next generation of Native Java.**
+**⚡ FastImage — Powering the next generation of Native Java.**