diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e1fe40f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,289 @@
+# Viper Template Project
+
+[English](#english) | [中文](#中文)
+
+A minimal, ready-to-use template for bootstrapping a new [Viper](../wiki/01-overview.md) language project on **Windows (x86_64-pc-windows-gnu)**.
+
+Windows 平台（x86_64-pc-windows-gnu）下 [Viper](../wiki/01-overview.md) 语言新项目的最小可用模板。
+
+---
+
+<a id="中文"></a>
+
+## 中文
+
+### 这是什么
+
+`ViperTemplateProject` 是基于 `Viper` 语言的 **Windows 桌面应用模板**。克隆本仓库后，你可以立即得到一个能够：
+
+- 设置 Windows 控制台为 UTF-8 编码（避免中文乱码）
+- 打印一行 `你好，世界`
+- 通过 `llc + clang++`（mingw 工具链）编译为原生 `app.exe`
+
+的最小 Viper 项目。
+
+模板对应的语言编译器是 [TransPyC](https://git.gvsds.com/GVSDS/TransPyC)；关于 Viper 语言本身的概览，参见 [TransPyC 仓库 wiki](../wiki/01-overview.md)。
+
+### 目录结构
+
+```
+ViperTemplateProject/
+├── .gitignore           # 忽略 build/、*.o、*.exe、缓存等
+├── README.md            # 本文件
+├── project.vpj          # 项目配置（编译器、链接器、目标三元组等）
+└── App/
+    └── main.py          # 入口文件
+```
+
+### 前提条件
+
+| 工具 | 说明 |
+|------|------|
+| `python` ≥ 3.10 | 用于运行 TransPyC 编译器 |
+| `llc` | LLVM 静态编译器，编译 `.ll` → `.o` |
+| `clang++` | mingw 工具链下的链接驱动（`x86_64-w64-mingw32`） |
+| `TransPyC` 仓库 | 本编译器，克隆在 `ViperTemplateProject/..` 同一目录下 |
+
+环境变量建议（PowerShell）：
+
+```powershell
+$env:PATH = "D:\msys64\mingw64\bin;D:\LLVM\bin;$env:PATH"
+```
+
+### 快速开始
+
+```powershell
+# 1. 确保目录布局正确
+#    D:\Users\TermiNexus\Desktop\TransPyC\
+#    ├── TransPyC\        # 编译器仓库
+#    └── ViperTemplateProject\   # 本仓库
+
+cd D:\Users\TermiNexus\Desktop\TransPyC\ViperTemplateProject
+
+# 2. 编译并运行
+python ..\TransPyC\Projectrans.py `
+    --project .\project.vpj `
+    --clean-cache=false
+
+# 3. 产物位于 output\app.exe
+.\output\app.exe
+```
+
+预期输出：
+
+```
+你好，世界
+```
+
+### 编写你的第一个程序
+
+打开 `App/main.py`，替换 `print("你好，世界")` 为任意合法 Viper 表达式。例如：
+
+```python
+import w32.win32console as w32cmd
+import t, c
+
+pagecode: t.CDefine = 65001
+
+@t.CExport
+def main() -> int:
+    w32cmd.SetConsoleOutputCP(pagecode)
+    w32cmd.SetConsoleCP(pagecode)
+
+    # 你的代码从这里开始
+    a: t.CInt = 1
+    b: t.CInt = 2
+    print("a + b =", a + b)
+
+    return 0
+```
+
+### 修改项目配置
+
+打开 `project.vpj`，按需调整：
+
+| 字段 | 含义 | 模板默认值 |
+|------|------|-----------|
+| `name` | 项目名（仅显示用） | `Standard Template Project` |
+| `source_dir` | 源文件根目录 | `./App` |
+| `temp_dir` | 中间产物目录（`.pyi` / `.stub.ll`） | `./temp` |
+| `output_dir` | 最终产物目录 | `./output` |
+| `compiler.cmd` | 汇编器 | `llc` |
+| `compiler.flags` | 传给 `llc` 的参数 | `["-filetype=obj", "-relocation-model=pic"]` |
+| `linker.cmd` | 链接器 | `clang++` |
+| `linker.flags` | 链接器参数 | mingw 标准库 + `kernel32` |
+| `linker.output` | 产物名 | `app.exe` |
+| `includes` | 标准库搜索路径 | `["../includes"]` |
+| `target.triple` | LLVM 目标三元组 | `x86_64-pc-windows-gnu` |
+| `target.datalayout` | LLVM 数据布局 | mingw 默认 |
+| `options.target` | 后端目标 | `llvm` |
+| `options.strict_mode` | 严格类型检查 | `true` |
+| `options.slice_level` | 切片级别 | `3` |
+
+### 跨平台使用
+
+本模板默认针对 **Windows + mingw**。若需在其他平台使用，修改 `project.vpj` 的 `compiler.cmd` / `linker.cmd` / `target.triple`：
+
+- **Linux (x86_64)**：`triple = "x86_64-unknown-linux-gnu"`，`linker.cmd = "clang++"`
+- **macOS (x86_64)**：`triple = "x86_64-apple-darwin*"`，`linker.cmd = "clang++"`
+- **裸机 x86_64 (ViperOS)**：`triple = "x86_64-none-elf"`，`linker.cmd = "ld.lld"`，需要 `isr.s` 启动文件
+
+### 常见问题
+
+**Q: 报错 `cannot find includes/os` / `cannot find includes/atom` 之类？**
+A: 检查 `project.vpj` 中的 `includes` 字段是否指向 `TransPyC/includes`。`../includes` 假设本仓库与 `TransPyC` 仓库同级。
+
+**Q: 输出 `app.exe` 双击闪退？**
+A: 在终端中运行 `.\output\app.exe` 而非双击，并确认 mingw 与 LLVM 在 `PATH` 中。
+
+**Q: 想完全清理构建产物？**
+A: 使用 `python ..\TransPyC\Projectrans.py --project .\project.vpj --clean-cache` 清理缓存；删除 `output/` 和 `temp/` 即可彻底重置。
+
+**Q: `StandardTemplateProject` 和本仓库是什么关系？**
+A: 本仓库 `ViperTemplateProject` 是 `StandardTemplateProject` 的独立仓库版本。如果你仍想保留 `StandardTemplateProject` 放在 `TransPyC` 仓库内，只需把它加入 `TransPyC/.gitignore` 的 `# 排除独立仓库的目录` 小节。
+
+### 进一步阅读
+
+- [Viper 语言概览](../wiki/01-overview.md)
+- [类型系统](../wiki/02-type-system.md)
+- [OOP 与对象模型](../wiki/06-oop.md)
+- [自举路线图](../wiki/13-bootstrapping.md)
+
+---
+
+<a id="english"></a>
+
+## English
+
+### What is this
+
+`ViperTemplateProject` is a **Windows desktop application template** based on the [Viper](../wiki/01-overview.md) language. After cloning, you immediately have a minimal Viper project that:
+
+- Sets the Windows console to UTF-8 (avoids mojibake for non-ASCII output)
+- Prints `你好，世界`
+- Compiles to a native `app.exe` via `llc + clang++` (mingw toolchain)
+
+The corresponding compiler is [TransPyC](https://git.gvsds.com/GVSDS/TransPyC). For a Viper language overview, see the [TransPyC wiki](../wiki/01-overview.md).
+
+### Directory layout
+
+```
+ViperTemplateProject/
+├── .gitignore           # ignores build/, *.o, *.exe, caches, etc.
+├── README.md            # this file
+├── project.vpj          # project config (compiler, linker, target triple, ...)
+└── App/
+    └── main.py          # entry point
+```
+
+### Prerequisites
+
+| Tool | Notes |
+|------|-------|
+| `python` ≥ 3.10 | runs the TransPyC compiler |
+| `llc` | LLVM static compiler, `.ll` → `.o` |
+| `clang++` | mingw toolchain driver (`x86_64-w64-mingw32`) |
+| `TransPyC` repo | the compiler, cloned as a sibling of `ViperTemplateProject` |
+
+Suggested `PATH` (PowerShell):
+
+```powershell
+$env:PATH = "D:\msys64\mingw64\bin;D:\LLVM\bin;$env:PATH"
+```
+
+### Quick start
+
+```powershell
+# 1. Make sure the layout is right
+#    D:\Users\TermiNexus\Desktop\TransPyC\
+#    ├── TransPyC\             # compiler repo
+#    └── ViperTemplateProject\ # this repo
+
+cd D:\Users\TermiNexus\Desktop\TransPyC\ViperTemplateProject
+
+# 2. Build and run
+python ..\TransPyC\Projectrans.py `
+    --project .\project.vpj `
+    --clean-cache=false
+
+# 3. Output is at output\app.exe
+.\output\app.exe
+```
+
+Expected output:
+
+```
+你好，世界
+```
+
+### Writing your first program
+
+Open `App/main.py` and replace `print("你好，世界")` with any valid Viper expression. Example:
+
+```python
+import w32.win32console as w32cmd
+import t, c
+
+pagecode: t.CDefine = 65001
+
+@t.CExport
+def main() -> int:
+    w32cmd.SetConsoleOutputCP(pagecode)
+    w32cmd.SetConsoleCP(pagecode)
+
+    # your code goes here
+    a: t.CInt = 1
+    b: t.CInt = 2
+    print("a + b =", a + b)
+
+    return 0
+```
+
+### Editing project.vpj
+
+| Field | Meaning | Template default |
+|-------|---------|------------------|
+| `name` | display name | `Standard Template Project` |
+| `source_dir` | source root | `./App` |
+| `temp_dir` | intermediate artifacts (`.pyi` / `.stub.ll`) | `./temp` |
+| `output_dir` | final artifacts | `./output` |
+| `compiler.cmd` | assembler | `llc` |
+| `compiler.flags` | flags passed to `llc` | `["-filetype=obj", "-relocation-model=pic"]` |
+| `linker.cmd` | linker | `clang++` |
+| `linker.flags` | linker flags | mingw stdlib + `kernel32` |
+| `linker.output` | output name | `app.exe` |
+| `includes` | standard library search paths | `["../includes"]` |
+| `target.triple` | LLVM target triple | `x86_64-pc-windows-gnu` |
+| `target.datalayout` | LLVM data layout | mingw default |
+| `options.target` | backend target | `llvm` |
+| `options.strict_mode` | strict type checking | `true` |
+| `options.slice_level` | slice level | `3` |
+
+### Cross-platform use
+
+This template targets **Windows + mingw** by default. To use on another platform, adjust `compiler.cmd` / `linker.cmd` / `target.triple` in `project.vpj`:
+
+- **Linux (x86_64)**: `triple = "x86_64-unknown-linux-gnu"`, `linker.cmd = "clang++"`
+- **macOS (x86_64)**: `triple = "x86_64-apple-darwin*"`, `linker.cmd = "clang++"`
+- **Bare-metal x86_64 (ViperOS)**: `triple = "x86_64-none-elf"`, `linker.cmd = "ld.lld"`, requires `isr.s` startup
+
+### FAQ
+
+**Q: Error like `cannot find includes/os` or `cannot find includes/atom`?**
+A: Check that the `includes` field in `project.vpj` points to the `TransPyC/includes` directory. `../includes` assumes this repo lives next to `TransPyC`.
+
+**Q: `app.exe` flashes and closes on double-click?**
+A: Run `.\output\app.exe` from a terminal, not by double-clicking. Make sure mingw and LLVM are on `PATH`.
+
+**Q: How to fully clean build artifacts?**
+A: `python ..\TransPyC\Projectrans.py --project .\project.vpj --clean-cache` clears the cache. To reset everything, also delete `output/` and `temp/`.
+
+**Q: What is the relationship with `StandardTemplateProject`?**
+A: This repo `ViperTemplateProject` is the standalone-repo version of `StandardTemplateProject`. If you still want `StandardTemplateProject` to live inside the `TransPyC` repo, add it to the `# 排除独立仓库的目录` section in `TransPyC/.gitignore`.
+
+### Further reading
+
+- [Viper language overview](../wiki/01-overview.md)
+- [Type system](../wiki/02-type-system.md)
+- [OOP and object model](../wiki/06-oop.md)
+- [Bootstrapping roadmap](../wiki/13-bootstrapping.md)