diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d066e23
--- /dev/null
+++ b/README.md
@@ -0,0 +1,125 @@
+# CLeonOS
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+Experimental x86_64 operating system project with a C kernel, Rust-assisted runtime pieces, user-space ELF apps, and a stage-based development history.
+
+## Highlights
+
+- x86_64 kernel booted by Limine
+- RAM-disk VFS layout (`/system`, `/shell`, `/temp`, `/driver`)
+- Virtual TTY subsystem (multi TTY, ANSI handling, cursor, PSF font support)
+- Keyboard and mouse input stack, plus desktop mode on TTY2
+- User-space ELF app model with syscall ABI (`int 0x80`)
+- User shell with external command apps (`ls`, `cat`, `grep`, `mkdir`, `cp`, `mv`, `rm`, etc.)
+- Pipe and redirection support in user shell (`|`, `>`, `>>`)
+- Optional host-side CLeonOS-Wine runner (Python + Unicorn) in [`wine/`](wine)
+
+## Repository Layout
+
+```text
+.
+|- clks/                 # Kernel sources (arch, drivers, scheduler, tty, syscall, ...)
+|- cleonos/              # Userland runtime, libc-like layer, user apps, Rust user library
+|- ramdisk/              # Static files copied into runtime ramdisk
+|- configs/              # Boot configuration (Limine)
+|- cmake/                # Shared CMake scripts (tool checks, logging, limine setup)
+|- docs/                 # Stage documents and syscall reference
+|- wine/                 # Host runner for CLeonOS user ELF (no full VM required)
+|- CMakeLists.txt        # Main build definition
+|- Makefile              # Developer-friendly wrapper around CMake targets
+```
+
+## Build Requirements
+
+Minimum required tools:
+
+- `cmake` (>= 3.20)
+- `make`
+- `git`
+- `tar`
+- `xorriso`
+- `sh` (POSIX shell)
+- `rustc`
+- Kernel/user toolchain (resolved automatically with fallback):
+  - kernel: `x86_64-elf-gcc`/`x86_64-elf-ld` (or fallback `gcc`/`clang` + `ld.lld`)
+  - user: `cc` + `ld`
+
+For building Limine from source, install extras such as `autoconf`, `automake`, `libtool`, `pkg-config`, `mtools`, and `nasm`.
+
+For runtime:
+
+- `qemu-system-x86_64` (for `make run` / `make debug`)
+
+## Quick Start
+
+```bash
+git clone <your-repo-url>
+cd cleonos
+git submodule update --init --recursive
+make run
+```
+
+If you already have Limine artifacts and want to skip configure:
+
+```bash
+make run LIMINE_SKIP_CONFIGURE=1
+```
+
+## Common Targets
+
+- `make setup` - check tools and prepare Limine
+- `make kernel` - build kernel ELF
+- `make userapps` - build user-space ELF apps
+- `make ramdisk` - package runtime ramdisk
+- `make iso` - build bootable ISO
+- `make run` - launch QEMU
+- `make debug` - launch QEMU with `-s -S` for GDB
+- `make clean` - clean `build/x86_64`
+- `make clean-all` - clean all build output
+
+## Debugging (GDB)
+
+Start debug VM:
+
+```bash
+make debug
+```
+
+Attach in another terminal:
+
+```bash
+gdb build/x86_64/clks_kernel.elf
+(gdb) target remote :1234
+```
+
+## User Shell Examples
+
+```sh
+help
+ls /shell
+cat /shell/init.cmd
+grep -n exec /shell/init.cmd
+cat /shell/init.cmd | grep -n exec
+ls /shell > /temp/shell_list.txt
+```
+
+## Documentation
+
+- Stage index: [`docs/README.md`](docs/README.md)
+- Syscall ABI reference: [`docs/syscall.md`](docs/syscall.md)
+
+## CI
+
+GitHub Actions workflow [`build-os.yml`](.github/workflows/build-os.yml) builds the OS ISO on push and pull request, and uploads the ISO as an artifact.
+
+## Contributing
+
+1. Fork and create a feature branch.
+2. Keep changes stage-oriented and update docs when behavior changes.
+3. Run at least `make iso` before opening a PR.
+4. Include boot log snippets or screenshots for kernel/user visible changes.
+
+## License
+
+Apache-2.0. See [`License`](License).
diff --git a/README.zh-CN.md b/README.zh-CN.md
new file mode 100644
index 0000000..4c9633f
--- /dev/null
+++ b/README.zh-CN.md
@@ -0,0 +1,125 @@
+# CLeonOS
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+一个实验性的 x86_64 操作系统项目，包含 C 内核、Rust 辅助运行时代码、用户态 ELF 应用，以及按 Stage 演进的开发历史。
+
+## 项目特性
+
+- 基于 Limine 启动的 x86_64 内核
+- RAM-disk VFS 目录布局（`/system`、`/shell`、`/temp`、`/driver`）
+- 虚拟 TTY 子系统（多 TTY、ANSI、光标、PSF 字体）
+- 键盘/鼠标输入栈，TTY2 提供桌面模式
+- 用户态 ELF 应用模型，syscall ABI 使用 `int 0x80`
+- 用户 Shell + 外部命令 ELF（`ls`、`cat`、`grep`、`mkdir`、`cp`、`mv`、`rm` 等）
+- Shell 管道与重定向（`|`、`>`、`>>`）
+- 可选主机侧 CLeonOS-Wine 运行器（Python + Unicorn），位于 [`wine/`](wine)
+
+## 仓库结构
+
+```text
+.
+|- clks/                 # 内核源码（架构、驱动、调度、TTY、syscall 等）
+|- cleonos/              # 用户态运行时、基础库、用户应用、Rust 用户库
+|- ramdisk/              # 运行时 ramdisk 的静态文件
+|- configs/              # 启动配置（Limine）
+|- cmake/                # CMake 公共脚本（工具检查、日志、limine 初始化）
+|- docs/                 # Stage 文档与 syscall 文档
+|- wine/                 # 主机侧用户 ELF 运行器（无需完整虚拟机）
+|- CMakeLists.txt        # 主构建定义
+|- Makefile              # 面向开发者的 CMake 包装入口
+```
+
+## 构建依赖
+
+最低需要：
+
+- `cmake`（>= 3.20）
+- `make`
+- `git`
+- `tar`
+- `xorriso`
+- `sh`（POSIX shell）
+- `rustc`
+- 内核/用户工具链（会自动回退查找）：
+  - 内核：`x86_64-elf-gcc` / `x86_64-elf-ld`（可回退到 `gcc`/`clang` + `ld.lld`）
+  - 用户态：`cc` + `ld`
+
+如需从源码构建 Limine，请安装额外依赖：`autoconf`、`automake`、`libtool`、`pkg-config`、`mtools`、`nasm`。
+
+运行时还需要：
+
+- `qemu-system-x86_64`（用于 `make run` / `make debug`）
+
+## 快速开始
+
+```bash
+git clone <your-repo-url>
+cd cleonos
+git submodule update --init --recursive
+make run
+```
+
+如果你已经准备好 Limine 产物，可跳过 configure：
+
+```bash
+make run LIMINE_SKIP_CONFIGURE=1
+```
+
+## 常用目标
+
+- `make setup` - 检查工具并准备 Limine
+- `make kernel` - 构建内核 ELF
+- `make userapps` - 构建用户态 ELF 应用
+- `make ramdisk` - 打包运行时 ramdisk
+- `make iso` - 生成可启动 ISO
+- `make run` - 启动 QEMU
+- `make debug` - 以 `-s -S` 启动 QEMU 供 GDB 附加
+- `make clean` - 清理 `build/x86_64`
+- `make clean-all` - 清理全部构建产物
+
+## 调试（GDB）
+
+先启动调试 VM：
+
+```bash
+make debug
+```
+
+再在另一个终端连接：
+
+```bash
+gdb build/x86_64/clks_kernel.elf
+(gdb) target remote :1234
+```
+
+## User Shell 示例
+
+```sh
+help
+ls /shell
+cat /shell/init.cmd
+grep -n exec /shell/init.cmd
+cat /shell/init.cmd | grep -n exec
+ls /shell > /temp/shell_list.txt
+```
+
+## 文档
+
+- Stage 索引：[`docs/README.md`](docs/README.md)
+- Syscall ABI 文档：[`docs/syscall.md`](docs/syscall.md)
+
+## CI
+
+GitHub Actions 工作流 [`build-os.yml`](.github/workflows/build-os.yml) 会在 push/PR 时自动构建 ISO，并上传为 artifact。
+
+## 贡献指南
+
+1. Fork 仓库并创建功能分支。
+2. 尽量按 Stage 组织改动，并同步更新文档。
+3. 提交 PR 前至少执行一次 `make iso`。
+4. 涉及可见行为变化时，附上启动日志片段或截图。
+
+## 许可证
+
+Apache-2.0。详见 [`License`](License)。