diff --git a/README.md b/README.md
new file mode 100644
index 0000000..23b246e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,179 @@
+
+
+# SkyWalker-1
+
+**Reverse-engineered documentation, custom firmware, and Python tooling for the Genpix SkyWalker-1 DVB-S USB 2.0 satellite receiver.**
+
+[](https://skywalker-1.warehack.ing)
+[](https://skywalker-1.warehack.ing/firmware/custom-v301/)
+[](#license)
+
+
+
+---
+
+The SkyWalker-1 is a standalone USB 2.0 DVB-S receiver built around a **Cypress FX2LP** (CY7C68013A) microcontroller and **Broadcom BCM4500** satellite demodulator. It was designed by [Genpix Electronics](https://www.genpix-electronics.com/index.php?act=viewDoc&docId=9) for DVB-S, Turbo-coded, Digicipher II, and DSS reception.
+
+This project documents the device's complete internal architecture -- every vendor command, register, GPIO pin, and data path -- built up from Linux kernel driver analysis, Ghidra firmware disassembly of five firmware images, Windows BDA driver source review, and original custom firmware development.
+
+**[Browse the full documentation at skywalker-1.warehack.ing](https://skywalker-1.warehack.ing)**
+
+## What's Here
+
+```
+skywalker-1/
+ firmware/ Custom FX2 firmware (SDCC + fx2lib, 1441 lines of C)
+ skywalker1.c Full replacement firmware with 10 custom vendor commands
+ Makefile Build rules targeting CY7C68013A
+ dscr.a51 USB descriptors (VID 0x09C0, PID 0x0203)
+ firmware-dump/ Extracted stock firmware binaries (v2.06, v2.10, v2.13 x3)
+ firmware-driver/ Genpix Windows BDA driver source (reference material)
+ tools/ Python utilities for direct hardware interaction
+ skywalker.py Multi-mode RF tool: spectrum, scan, monitor, lband, track
+ skywalker_lib.py Shared library: USB transport, BCM4500 register access
+ fw_load.py FX2 RAM firmware loader via 0xA0 vendor request
+ tune.py Transponder tuner with lock detection and BER readout
+ ts_analyze.py MPEG-2 transport stream parser and PID analyzer
+ eeprom_dump.py Full EEPROM image extraction
+ eeprom_write.py EEPROM flash tool with C2 format support
+ wine_memdump.py Extract firmware from Genpix Windows updater EXEs
+ test_*.py Boot sequence and I2C debug/isolation harnesses
+ site/ Astro Starlight documentation (37 pages, 9 sections)
+ docs/ Raw analysis documents and master hardware reference
+```
+
+## Hardware at a Glance
+
+| | |
+|---|---|
+| **MCU** | Cypress CY7C68013A (FX2LP) -- 8051 core at 48 MHz, USB 2.0 Hi-Speed |
+| **Demodulator** | Broadcom BCM4500 -- DVB-S / Turbo / DCII / DSS, 128-pin MQFP |
+| **IF Range** | 950 -- 2150 MHz |
+| **Symbol Rate** | 256 Ksps -- 30 Msps |
+| **LNB Control** | 13/18V, 22 kHz tone, DiSEqC 1.0/1.2, legacy switches |
+| **Connector** | IEC F-type female |
+| **Transport** | 8-bit parallel bus via GPIF into USB bulk endpoint EP2 |
+
+```
+ +--[ I2C EEPROM 0x51 ]
+ |
+USB 2.0 HS | I2C Bus (400 kHz)
+Host PC <----> [ CY7C68013A FX2LP ] <-----> [ BCM4500 Demod 0x08 ]
+ | 8051 @ 48 MHz | |
+ | GPIF Engine |<-----------+ 8-bit parallel TS
+ | EP2 Bulk IN |
+ | GPIO (P0/P3) |---> [ 22 kHz Osc ] ---> LNB/Coax
+ | |---> [ LNB Voltage Ctrl ]
+ +-----------------+
+ |
+ +--[ Tuner/LNB IC 0x10 ]
+```
+
+**Supported modulations:** DVB-S (QPSK), DVB-S (BPSK), Turbo QPSK, Turbo 8PSK, Turbo 16QAM, Digicipher II (Combo, Split I/Q, Offset QPSK), DSS (QPSK).
+
+> DVB-S2 is **not supported**. The BCM4500 predates DVB-S2 and contains no LDPC or BCH decoder hardware. This is a silicon limitation -- no firmware update can change it. See the [DVB-S2 investigation](https://skywalker-1.warehack.ing/driver/dvb-s2/).
+
+## Custom Firmware
+
+The stock EEPROM firmware was replaced with an open-source implementation built from scratch using **SDCC** and **fx2lib**. It implements all stock vendor commands (kernel driver compatible) plus 10 new diagnostic and analysis commands:
+
+| Command | ID | Purpose |
+|---------|-----|---------|
+| Spectrum Sweep | `0xB0` | AGC-based power sweep across IF range |
+| Raw Demod Read | `0xB1` | Direct BCM4500 indirect register read |
+| Raw Demod Write | `0xB2` | Direct BCM4500 indirect register write |
+| Blind Scan | `0xB3` | Carrier detection at arbitrary frequency |
+| Signal Monitor | `0xB7` | Combined SNR + AGC + lock in single transfer |
+| Tune Monitor | `0xB8` | Tune + dwell + measure in one round-trip |
+| Multi Reg Read | `0xB9` | Batch read of contiguous indirect registers |
+
+Build and load:
+
+```bash
+cd firmware
+make # requires SDCC + fx2lib
+make load # RAM-loads via fw_load.py (does not touch EEPROM)
+```
+
+## Python Tools
+
+All tools communicate directly with the SkyWalker-1 over USB using `pyusb`. No kernel driver required.
+
+```bash
+# Load custom firmware into FX2 RAM
+python tools/fw_load.py firmware/build/skywalker1.bix
+
+# Tune to a transponder and check lock
+python tools/tune.py --freq 12224 --sr 20000 --pol H --mod dvb-s
+
+# Sweep the IF band and render ASCII spectrum
+python tools/skywalker.py spectrum --start 950 --stop 2150 --step 5
+
+# Real-time signal strength (dish alignment)
+python tools/skywalker.py monitor --freq 1175
+
+# Dump full EEPROM contents
+python tools/eeprom_dump.py --output eeprom.bin
+```
+
+The `skywalker.py` multi-mode tool provides five operating modes: `spectrum` (sweep analyzer), `scan` (transponder finder), `monitor` (signal strength meter), `lband` (direct L-band input), and `track` (carrier/beacon tracker with CSV logging).
+
+## Documentation Site
+
+The full documentation is published at **[skywalker-1.warehack.ing](https://skywalker-1.warehack.ing)** and covers:
+
+| Section | Pages | Covers |
+|---------|-------|--------|
+| **Hardware** | 4 | Board architecture, GPIO pin map, RF specifications |
+| **USB Interface** | 4 | 30 vendor commands, boot sequence, endpoint layout |
+| **BCM4500** | 5 | Register map, indirect access protocol, tuning sequence, GPIF streaming, signal monitoring |
+| **LNB & DiSEqC** | 3 | Voltage/tone control, DiSEqC 1.0/1.2, legacy Dish switches |
+| **I2C Bus** | 2 | Bus architecture, STOP corruption bug root cause analysis |
+| **Firmware** | 7 | 5 stock versions compared, custom v3.01 and v3.02, storage formats |
+| **Driver** | 2 | Linux gp8psk kernel driver, DVB-S2 incompatibility investigation |
+| **Tools** | 7 | Every Python utility documented with usage examples |
+| **Reference** | 1 | Consolidated master reference (registers, commands, GPIO, I2C) |
+
+To run the docs site locally:
+
+```bash
+cd site
+npm install
+npm run dev # http://localhost:4321
+```
+
+
+Docker deployment
+
+The docs site includes a multi-stage Dockerfile with dev and prod targets. Production serves static files through Caddy.
+
+```bash
+cd site
+
+# Development (HMR via volume mounts)
+APP_ENV=dev docker compose up --build
+
+# Production (static build served by Caddy)
+APP_ENV=prod docker compose up --build -d
+```
+
+
+
+## Project History
+
+This project started with USB packet captures and `lsusb` output, then progressed through increasingly deep layers of the hardware:
+
+1. **EEPROM extraction** -- dumped raw firmware bytes over I2C
+2. **Ghidra disassembly** -- decompiled five 8051 firmware images, mapped all functions and vendor commands
+3. **Windows driver analysis** -- cross-referenced Ghidra findings against Genpix BDA driver source
+4. **Linux driver analysis** -- mapped kernel `gp8psk` driver to decoded vendor commands
+5. **Custom firmware** -- wrote a full replacement in C, discovered and fixed the [I2C STOP corruption bug](https://skywalker-1.warehack.ing/i2c/stop-corruption-bug/)
+6. **RF tooling** -- built spectrum analyzer, blind scanner, and signal monitor on top of the custom command set
+
+## Contributing
+
+This is a niche reverse-engineering project for a specific piece of satellite hardware. If you have a SkyWalker-1 (or other Genpix device using the BCM4500), contributions are welcome -- particularly additional firmware dumps, register documentation, or corrections to the analysis.
+
+## License
+
+The custom firmware source, Python tools, and documentation are open source. Stock firmware binaries in `firmware-dump/` are proprietary Genpix Electronics images retained for research and interoperability purposes.