diff --git a/README.md b/README.md
new file mode 100644
index 0000000..081cf49
--- /dev/null
+++ b/README.md
@@ -0,0 +1,339 @@
+# ViperOS
+
+[English](#english) | [中文](#中文)
+
+A bare-metal 64-bit operating system written in the [Viper](https://git.gvsds.com/GVSDS/TransPyC) language. Boots via UEFI, ships a self-implemented FAT32 driver, runs ELF-format user applications, and includes a complete user-space SDK.
+
+用 [Viper](https://git.gvsds.com/GVSDS/TransPyC) 语言编写的裸机 64 位操作系统。UEFI 启动、自研 FAT32 驱动、运行 ELF 格式用户程序，配套完整的用户态 SDK。
+
+---
+
+<a id="中文"></a>
+
+## 中文
+
+### 这是什么
+
+`ViperOS` 是 Viper 语言的旗舰演示项目：**一个完整可启动的操作系统**。和"Linux 发行版"或"教学用 mini-OS"不同，ViperOS 用 Viper 写一切——内核、设备驱动、用户程序、库、SDK 都用同一种语言（Viper 的 Python 语法 + LLVM 后端）。
+
+主要组成：
+- **VKernel** —— 64 位微内核（x86_64-none-elf 目标）
+- **UEFI 引导器** —— `boot/boot.c`（GNU-EFI 编译为 `disk/EFI/BOOT/bootx64.efi`）
+- **FAT32 驱动** —— 自研实现，支持挂载、目录、文件操作
+- **4 个用户应用** —— HelloWorld / Terminal / Gargantua / Scene3D
+- **2 个动态库** —— SerialLogger / VPUI64
+- **ViperPOS SDK** —— 用户态开发库（系统调用、窗口、文件系统、进程）
+
+### 目录结构
+
+```
+ViperOS/
+├── .gitignore              # 忽略所有 output/、temp/、构建产物
+├── build.py                # 顶层构建入口：构建→打包→启动 QEMU
+├── linker.ld               # 顶层链接脚本
+├── boot/                   # UEFI 引导器
+│   ├── Makefile
+│   └── boot.c
+├── VKernel/                # 内核
+│   ├── project.json        # 内核构建配置
+│   ├── linker.ld
+│   └── Kernel/
+│       ├── main.py         # 内核入口
+│       ├── bootinfo.py
+│       ├── drivers/        # 驱动
+│       │   ├── core/cpu/   # APIC、CPU、FPU
+│       │   ├── devfs/      # 设备文件系统
+│       │   ├── fs/fat32/   # FAT32 驱动（自研）
+│       │   ├── input/      # 键盘、鼠标
+│       │   ├── serial/     # 8250 UART
+│       │   ├── storage/    # IDE
+│       │   ├── usb/        # USB HID / UHCI
+│       │   └── video/      # VESA Framebuffer + UI
+│       ├── execrunner/     # ELF 加载器
+│       ├── intr/           # 中断子系统（GDT/IDT/ISR/Syscall）
+│       ├── mm/             # 内存管理
+│       ├── paging/         # 分页
+│       ├── sched/          # 协程、进程、调度
+│       ├── services/       # 内核服务
+│       └── platform/       # 平台相关（PIC/PIT/RTC/Timer）
+├── Apps/                   # 用户应用（每个子目录一个独立 ELF）
+│   ├── HelloWorld/
+│   ├── Terminal/
+│   ├── Gargantua/
+│   └── Scene3D/
+├── Libs/                   # 动态库（每个子目录一个 .so）
+│   ├── SerialLogger/
+│   └── VPUI64/
+├── vpsdk/                  # ViperPOS SDK（应用开发用）
+│   ├── __init__.py
+│   ├── stdlib.py
+│   ├── syscall.py
+│   ├── window.py
+│   ├── vpui.py
+│   ├── fs.py
+│   ├── process.py
+│   ├── dynlib.py
+│   └── wiki/               # SDK 自带 wiki
+├── Scripts/
+│   ├── check_disk.py
+│   ├── disk.ps1            # ImDisk 打包 FAT32 镜像
+│   └── disk.sh             # Linux 等价脚本
+└── disk/                   # 被打包进 disk.img 的文件
+    ├── EFI/BOOT/bootx64.efi
+    ├── app/helloworld.asm
+    ├── apps/               # .elf 拷贝目标（构建时填充）
+    ├── libs/               # .so 拷贝目标（构建时填充）
+    └── sys/kernel/x86_64/kernel.bin
+```
+
+### 前提条件
+
+| 工具 | 说明 |
+|------|------|
+| `python` ≥ 3.10 | 运行 TransPyC 编译器 |
+| `llc` | LLVM 静态编译器 |
+| `ld.lld` | LLD 链接器（裸机版本） |
+| `qemu-system-x86_64` | QEMU 模拟器 |
+| `imdisk` | Windows 下创建/挂载磁盘镜像的驱动；Linux 平台用 `disk.sh` 替代 |
+| `gnu-efi` 工具链 | 编译 UEFI 引导器（`boot/boot.c`） |
+| [TransPyC](https://git.gvsds.com/GVSDS/TransPyC) | 编译器，**必须克隆在与 ViperOS 同级的目录** |
+
+目录布局要求：
+
+```
+D:\Users\TermiNexus\Desktop\TransPyC\
+├── TransPyC\        # 编译器仓库
+├── ViperOS\         # 本仓库
+└── ViperTemplateProject\
+```
+
+### 快速开始
+
+```powershell
+# 1. 在 ViperOS 目录下直接运行
+cd D:\Users\TermiNexus\Desktop\TransPyC\ViperOS
+
+# 2. 完整构建并启动 QEMU
+python build.py
+
+# 3. 串口日志写入 serial.log
+```
+
+`build.py` 会自动完成：
+1. 调用 `Projectrans.py` 编译 VKernel → `VKernel/output/kernel.bin`
+2. 编译 2 个动态库（SerialLogger、VPUI64）
+3. 编译 4 个应用（HelloWorld、Terminal、Gargantua、Scene3D）
+4. 拷贝所有产物到 `disk/apps/`、`disk/libs/`、`disk/sys/kernel/x86_64/`
+5. 调用 `Scripts/disk.ps1` 创建 64MB FAT32 镜像 `disk.img`
+6. 启动 QEMU（TCG 加速、`-no-reboot` 防止三重错误后重启）
+
+退出 QEMU 后查看 `serial.log` 可看到内核启动日志。
+
+### 常用构建参数
+
+```powershell
+python build.py --noclean      # 不清缓存，保留 temp/ 加速二次构建
+python build.py --kernel-only  # 只重编译内核，跳过应用和库
+```
+
+⚠ 不支持 `--noqemu`（`build.py` 第 76 行注释明确"不准使用 --noqemu"）。
+
+### 添加新应用
+
+1. 在 `Apps/` 下新建目录，例如 `Apps/MyApp/`
+2. 创建 `App/MyApp/main.py`（参考 `Apps/HelloWorld/main.py`）
+3. 创建 `App/MyApp/project.json`（参考 `Apps/HelloWorld/project.json`，注意 `triple = "x86_64-none-elf"`、`linker` 用 `ld.lld` 输出 `.elf`）
+4. 在 `build.py` 中追加构建 + 拷贝命令
+5. 在 `disk/apps/MyApp/` 目录放应用需要的资源（运行时通过 vpsdk 访问）
+
+### 添加新驱动
+
+在 `VKernel/Kernel/drivers/<子系统>/<设备>/` 下添加 `<设备>.py`，参考 `fs/fat32/fat32.py`（最大的驱动，自研 FAT32 完整实现）。在 `VKernel/Kernel/main.py` 中注册驱动初始化。
+
+### 平台说明
+
+| 平台 | 状态 |
+|------|------|
+| Windows 10/11 + mingw + QEMU | ✅ 主平台，CI 测试覆盖 |
+| Linux x86_64 + clang + QEMU | ⚠ 理论可用，需把 `build.py` 改用 `disk.sh`，ld.lld 用系统 lld |
+| macOS | ❌ 未测试 |
+| 真实硬件 | ❌ 暂未支持（仅 UEFI x86_64） |
+
+### 调试
+
+- **QEMU 串口日志**：`build.py` 启动时把 `-serial file:serial.log`，所有 `printf` 写到该文件
+- **GDB**：`qemu-system-x86_64` 加 `-s -S` 然后用 `gdb` 连 `localhost:1234`
+- **崩溃排查**：`build.py` 默认带 `-no-reboot`，避免三重错误后无限重启
+
+### 进一步阅读
+
+- [TransPyC 编译器仓库](https://git.gvsds.com/GVSDS/TransPyC)
+- [Viper 语言概览](https://git.gvsds.com/GVSDS/TransPyC/blob/main/wiki/01-overview.md)
+- [ViperOS SDK wiki](vpsdk/wiki/01-overview.md)
+- [Viper 模板项目（ViperTemplateProject）](https://git.gvsds.com/GVSDS/Viper_TemplateProject)
+
+---
+
+<a id="english"></a>
+
+## English
+
+### What is this
+
+`ViperOS` is the flagship demo of the [Viper](https://git.gvsds.com/GVSDS/TransPyC) language: a **complete bootable operating system** written in Viper. Unlike a Linux distro or a teaching mini-OS, ViperOS uses one language for everything — kernel, device drivers, user programs, libraries, SDK all use Viper (Python syntax + LLVM backend).
+
+Main components:
+- **VKernel** — 64-bit microkernel (target `x86_64-none-elf`)
+- **UEFI bootloader** — `boot/boot.c` (compiled by GNU-EFI to `disk/EFI/BOOT/bootx64.efi`)
+- **FAT32 driver** — self-implemented, supports mount/dir/file operations
+- **4 user applications** — HelloWorld / Terminal / Gargantua / Scene3D
+- **2 dynamic libraries** — SerialLogger / VPUI64
+- **ViperPOS SDK** — user-space development kit (syscall, window, fs, process)
+
+### Directory layout
+
+```
+ViperOS/
+├── .gitignore              # ignores all output/, temp/, build artifacts
+├── build.py                # top-level build entry: build -> pack -> QEMU
+├── linker.ld               # top-level linker script
+├── boot/                   # UEFI bootloader
+│   ├── Makefile
+│   └── boot.c
+├── VKernel/                # kernel
+│   ├── project.json        # kernel build config
+│   ├── linker.ld
+│   └── Kernel/
+│       ├── main.py         # kernel entry
+│       ├── bootinfo.py
+│       ├── drivers/        # device drivers
+│       │   ├── core/cpu/   # APIC, CPU, FPU
+│       │   ├── devfs/      # device filesystem
+│       │   ├── fs/fat32/   # self-implemented FAT32 driver
+│       │   ├── input/      # keyboard, mouse
+│       │   ├── serial/     # 8250 UART
+│       │   ├── storage/    # IDE
+│       │   ├── usb/        # USB HID / UHCI
+│       │   └── video/      # VESA framebuffer + UI
+│       ├── execrunner/     # ELF loader
+│       ├── intr/           # GDT/IDT/ISR/syscall
+│       ├── mm/             # memory management
+│       ├── paging/         # paging
+│       ├── sched/          # coroutine, process, scheduler
+│       ├── services/       # kernel services
+│       └── platform/       # platform glue (PIC/PIT/RTC/Timer)
+├── Apps/                   # user apps (each subdir = one ELF)
+│   ├── HelloWorld/
+│   ├── Terminal/
+│   ├── Gargantua/
+│   └── Scene3D/
+├── Libs/                   # shared libraries (each subdir = one .so)
+│   ├── SerialLogger/
+│   └── VPUI64/
+├── vpsdk/                  # ViperPOS SDK (for user apps)
+│   ├── __init__.py
+│   ├── stdlib.py
+│   ├── syscall.py
+│   ├── window.py
+│   ├── vpui.py
+│   ├── fs.py
+│   ├── process.py
+│   ├── dynlib.py
+│   └── wiki/               # SDK wiki
+├── Scripts/
+│   ├── check_disk.py
+│   ├── disk.ps1            # ImDisk-based FAT32 image builder
+│   └── disk.sh             # Linux-equivalent
+└── disk/                   # files packed into disk.img
+    ├── EFI/BOOT/bootx64.efi
+    ├── app/helloworld.asm
+    ├── apps/               # .elf destination (filled at build time)
+    ├── libs/               # .so destination (filled at build time)
+    └── sys/kernel/x86_64/kernel.bin
+```
+
+### Prerequisites
+
+| Tool | Notes |
+|------|-------|
+| `python` ≥ 3.10 | runs TransPyC |
+| `llc` | LLVM static compiler |
+| `ld.lld` | LLD linker (bare-metal) |
+| `qemu-system-x86_64` | QEMU emulator |
+| `imdisk` | Windows disk-image mount utility; on Linux use `disk.sh` instead |
+| `gnu-efi` toolchain | builds the UEFI bootloader (`boot/boot.c`) |
+| [TransPyC](https://git.gvsds.com/GVSDS/TransPyC) | compiler; **must be cloned as a sibling of ViperOS** |
+
+Required layout:
+
+```
+D:\Users\TermiNexus\Desktop\TransPyC\
+├── TransPyC\        # compiler repo
+├── ViperOS\         # this repo
+└── ViperTemplateProject\
+```
+
+### Quick start
+
+```powershell
+# 1. From the ViperOS directory
+cd D:\Users\TermiNexus\Desktop\TransPyC\ViperOS
+
+# 2. Full build and launch QEMU
+python build.py
+
+# 3. Serial log is written to serial.log
+```
+
+`build.py` automatically:
+1. Calls `Projectrans.py` to build VKernel -> `VKernel/output/kernel.bin`
+2. Builds 2 shared libraries (SerialLogger, VPUI64)
+3. Builds 4 applications (HelloWorld, Terminal, Gargantua, Scene3D)
+4. Copies all artifacts into `disk/apps/`, `disk/libs/`, `disk/sys/kernel/x86_64/`
+5. Calls `Scripts/disk.ps1` to create a 64MB FAT32 image `disk.img`
+6. Launches QEMU (TCG accel, `-no-reboot` to prevent reboot on triple fault)
+
+After quitting QEMU, inspect `serial.log` for kernel boot messages.
+
+### Common build flags
+
+```powershell
+python build.py --noclean      # keep temp/ to speed up subsequent builds
+python build.py --kernel-only  # only rebuild the kernel, skip apps/libs
+```
+
+`--noqemu` is **NOT supported** (see comment at line 76 of `build.py`).
+
+### Adding a new application
+
+1. Create a directory under `Apps/`, e.g. `Apps/MyApp/`
+2. Add `App/MyApp/main.py` (see `Apps/HelloWorld/main.py` for reference)
+3. Add `App/MyApp/project.json` (see `Apps/HelloWorld/project.json`; set `triple = "x86_64-none-elf"`, link with `ld.lld` to produce `.elf`)
+4. Add build + copy commands in `build.py`
+5. Put any runtime resources in `disk/apps/MyApp/` (read at runtime via vpsdk)
+
+### Adding a new driver
+
+Add `<device>.py` under `VKernel/Kernel/drivers/<subsystem>/<device>/`. See `fs/fat32/fat32.py` (largest, full FAT32 implementation). Register the init in `VKernel/Kernel/main.py`.
+
+### Platform support
+
+| Platform | Status |
+|----------|--------|
+| Windows 10/11 + mingw + QEMU | ✅ primary, CI-tested |
+| Linux x86_64 + clang + QEMU | ⚠ theoretically works, requires modifying `build.py` to use `disk.sh` and system lld |
+| macOS | ❌ untested |
+| Real hardware | ❌ not yet (UEFI x86_64 only) |
+
+### Debugging
+
+- **QEMU serial log**: `build.py` passes `-serial file:serial.log`; all `printf` output goes there
+- **GDB**: add `-s -S` to `qemu-system-x86_64` and attach `gdb` to `localhost:1234`
+- **Crash triage**: `build.py` always uses `-no-reboot`, avoiding reboot loops after triple faults
+
+### Further reading
+
+- [TransPyC compiler](https://git.gvsds.com/GVSDS/TransPyC)
+- [Viper language overview](https://git.gvsds.com/GVSDS/TransPyC/blob/main/wiki/01-overview.md)
+- [ViperOS SDK wiki](vpsdk/wiki/01-overview.md)
+- [Viper template project (ViperTemplateProject)](https://git.gvsds.com/GVSDS/Viper_TemplateProject)