diff --git a/README-CN.md b/README-CN.md
new file mode 100644
index 00000000..b328ac82
--- /dev/null
+++ b/README-CN.md
@@ -0,0 +1,430 @@
+[简体中文](README-CN.md) | [English](README.md)
+
+<div align="center">
+
+# TypePHP
+
+**PHP 原生 AOT 编译器**
+
+将 PHP 源码提前（AOT）编译为原生机器码，生成独立的可执行文件、PHP 扩展和静态库，
+同时保留你熟悉的 PHP 语法。
+
+</div>
+
+---
+
+## 什么是 TypePHP？
+
+TypePHP 是一个 AOT（Ahead-Of-Time，提前编译）编译器，它把 PHP 源码翻译为 C++，
+再编译为原生机器码。与字节码缓存或虚拟机不同，它不会在运行时解释 opcode，
+而是直接生成在 CPU 上运行的原生二进制。
+
+它保留熟悉的 PHP 语法，同时引入编译期类型信息，让编译器为你的性能热点生成快速、
+静态类型的 C++ 代码，而其余代码仍运行在久经考验的 Zend 引擎上。
+
+## 特性
+
+- **真正的 AOT 编译** —— PHP 先降级为 C++17，再编译为原生机器码。无解释器、
+  无 opcode 缓存、无 JIT 预热。
+- **三种构建模式** —— 同一份代码可编译为独立 `bin` 可执行文件、可加载的 PHP
+  `ext` 扩展，或 `lib` 静态库。
+- **原生类型系统** —— `int`、`float`、`bool` 直接映射为 C++ 标量类型
+  （`int64_t`、`double`、`bool`），数值代码可获得数量级的性能提升。
+- **高精度数值** —— `bigInt`（GMP）、`decimal`（libmpdec）、`bigFloat`（MPFR），
+  零开销算术运算。
+- **强类型容器** —— `std::array`、`std::vector`、`std::map`、`std::ordered_map`，
+  元素类型在编译期确定；最高比 PHP 数组快 **10 倍**，性能与 C++ `std::vector` 相当。
+- **通用方法（Universal Methods）** —— 在原生类型上直接调用方法
+  （`$s->upper()`、`$arr->contains()`、`$big->mul(2)`），零运行时派发开销。
+- **混合 C++ / PHP 编程** —— 在性能关键内核中直接调用 C++ 函数（反之亦然）。
+- **编译期函数与关键词** —— `any()`、`refval()`、`objval()`、`expected()`、
+  `unexpected()`，以及 `toInt()`、`toString()`、`toArray()` 等。
+- **编译期安全检查** —— `#[Immutable]` 只读契约和 `#[ArrayDef]` 数组结构元数据，
+  在编译期检查，零运行时开销。
+- **现代 PHP 支持** —— PHP 8.4 property hooks、非对称可见性、PHP 8.5
+  `clone()`-with 以及 `(void)` 丢弃表达式。
+- **跨平台与 WASM** —— 面向 x86-64 和 ARM64 的 Linux、Windows、macOS 目标，
+  以及 WASI 0.2 和浏览器（Jco）输出。
+- **Python 桥接** —— 为 Python 模块生成 IDE helper，并将 Python 脚本转换为 TypePHP。
+
+## 为什么选择 TypePHP？
+
+| | TypePHP AOT | 字节码缓存（OPcache） | JIT（PHP 8+） |
+|---|---|---|---|
+| 编译目标 | 原生机器码 | 字节码 | 机器码（trace） |
+| 启动 / 预热 | 无（已编译完成） | 每进程预热 | JIT 预热 |
+| 类型驱动优化 | 编译期、全程序 | 无 | 有限，基于 trace |
+| 独立可执行文件 | 支持 | 不支持 | 不支持 |
+| 源码保护 | 编译为机器码 | 字节码（可还原） | 字节码（可还原） |
+| 性能确定性 | 是 | 否 | 否 |
+
+**相较原生 PHP 的优势：**
+
+- **接近原生的性能。** 数值密集和容器密集的热点路径会编译为与 C++ 程序相同的机器码。
+  见下方[基准测试](#基准测试)。
+- **源码保护。** 源码被编译掉——交付物是原生二进制，而不是可读的 PHP 文件。
+- **零依赖部署。** 二进制模式生成单个自包含可执行文件，无需 PHP 运行时即可运行。
+- **渐进式类型，真正带来收益。** 只在性能关键处添加 `use native_types`、`std::`
+  容器和类型声明，其余保持普通 PHP。
+- **完整 PHP 生态互通。** 扩展模式以标准 PHP 扩展形式加载到 `php-fpm`，
+  现有框架和工具链可继续使用。
+
+## 前置要求
+
+- **PHP 8.4 – 8.5**，需包含 `embed` 模块（`libphp.so`）
+- **GCC 9+**（或 Clang），支持 **C++17**
+- **CMake 3.24+**
+- 高精度数学库：**GMP**、**MPFR**、**libmpdec**
+
+```shell
+# Ubuntu/Debian
+sudo apt install libgmp-dev libmpfr-dev libmpdec-dev
+
+# RHEL/CentOS/Fedora
+sudo dnf install gmp-devel mpfr-devel libmpdec-devel
+
+# Arch Linux
+sudo pacman -S gmp mpfr mpdecimal
+```
+
+> GMP 用于 `bigInt`，MPFR 用于 `bigFloat`，libmpdec 用于 `decimal`。
+
+预览版目前以 **Linux** 为主要开发平台（推荐 Ubuntu 22.04）。Windows 和 macOS
+打包通过同一入口点支持。
+
+## 安装
+
+### 通过 Composer
+
+```bash
+composer require --dev swoole/typephp
+```
+
+然后编译你的项目：
+
+```bash
+vendor/bin/tpc.php project.yml
+```
+
+在 TypePHP 源码仓库中开发时，改用本地入口：
+
+```bash
+bin/tpc.php project.yml
+```
+
+### 构建 `libphp.so`
+
+`tpc` 需要以 `embed` SAPI 构建的 PHP。如果 Linux 上缺少 `libphp.so`，
+`tpc.php` 可以交互式下载 PHP 源码并自动构建。详见
+[自动构建 libphp.so](docs/LIBPHP_INSTALLER.md)。
+
+## 快速开始
+
+创建 `hello.php`：
+
+```php
+<?php
+
+function main(): void
+{
+    echo "Hello World!\n";
+    var_dump(PHP_VERSION);
+    var_dump(php_uname());
+}
+```
+
+编译并运行：
+
+```bash
+bin/tpc.php hello.php
+./hello
+```
+
+输出：
+
+```
+Hello World!
+string(5) "8.4.x"
+string(16) "Linux ..."
+```
+
+> 二进制模式需要全局 `main()` 函数。它可以声明为无参数，或
+> `main(int $argc, array $argv)` 以接收命令行参数，且必须返回 `void`。
+
+## 编译模式
+
+TypePHP 支持三种构建模式，通过 `-m` / `--mode` 选择：
+
+| 模式 | 参数 | 输出 | 需要 `main()` | 典型用途 |
+|---|---|---|---|---|
+| 二进制 | `-m bin`（默认） | 可执行文件 | 是 | CLI 工具、常驻服务、独立应用 |
+| 扩展 | `-m ext` | `.so` / `.dll` | 否 | `php-fpm` 上的 Web 应用、即插即用 PHP 扩展 |
+| 库 | `-m lib` | 静态库 | 否 | 将编译后的代码嵌入其他项目 |
+
+```bash
+# 二进制（默认）
+bin/tpc.php app.php -o myapp
+
+# PHP 扩展
+bin/tpc.php extension/ -m ext -o my_extension
+
+# 静态库
+bin/tpc.php lib/ -m lib -o mylib
+```
+
+详见[编译模式](docs/COMPILATION_MODES.md)。
+
+## 使用示例
+
+### 1. 原生类型 —— 编译期数值加速
+
+```php
+<?php
+use native_types;
+
+function fib(int $n): int
+{
+    if ($n == 1 || $n == 2) {
+        return 1;
+    }
+    return fib($n - 1) + fib($n - 2);
+}
+
+function main(int $argc, array $argv): void
+{
+    $n = (int)$argv[1];
+    $begin = microtime(true);
+    echo fib($n) . "\n";
+    echo "Time: " . (microtime(true) - $begin) . "\n";
+}
+```
+
+```bash
+bin/tpc.php fib.php -O3 -o fib
+./fib 30
+```
+
+使用 `use native_types` 后，`int` 变量变为 C++ `int64_t`，算术运算直接编译为
+CPU 指令，而不是 ZendVM 调用。
+
+### 2. 高精度数值
+
+```php
+<?php
+declare(strict_types=1);
+use native_types;
+
+function main(): void
+{
+    // 54 位整数 —— 自动识别并存储为 bigInt
+    $a = std::bigInt("123456789012345678901234567890123456789012345678901234");
+    $b = std::bigInt("987654321098765432109876543210987654321098765432109876");
+
+    echo $a->add($b)->toString() . "\n";   // 精确计算，不会溢出
+
+    // 精确的十进制运算 —— 无二进制浮点误差
+    $c = std::decimal("0.1")->add(std::decimal("0.2"));
+    echo $c->toString() . "\n";            // "0.3"
+
+    // 256 位浮点数
+    $pi = std::bigFloat("3.14159265358979323846264338327950288419716939937510");
+    echo $pi->mul(2)->toString() . "\n";
+}
+```
+
+详见[高精度类型](docs/HIGH_PRECISION_TYPES.md)和[原生类型](docs/NATIVE_TYPES.md)。
+
+### 3. 强类型容器
+
+```php
+<?php
+use native_types;
+
+function main(): void
+{
+    $vector = std::vector(Type::Int);
+
+    $vector[] = 1;
+    $vector[] = 2;
+    $vector[] = 3;
+
+    $sum = 0;
+    foreach ($vector as $value) {
+        $sum += $value;
+    }
+
+    echo $sum . "\n";       // 6
+    echo $vector[1] . "\n"; // 2
+
+    // 固定 key/value 类型的映射
+    $map = std::ordered_map(Type::String, Type::Int);
+    $map["a"] = 1;
+    $map["b"] = 2;
+}
+```
+
+详见 [Std 容器](docs/STD_CONTAINERS.md)。
+
+### 4. 通用方法
+
+```php
+<?php
+
+function main(): void
+{
+    $s = "hello world";
+    echo $s->length() . "\n";       // strlen()
+    echo $s->upper() . "\n";        // strtoupper()
+    echo $s->substr(0, 5) . "\n";   // substr()
+
+    $arr = [1, 3, 5, 7, 9];
+    echo $arr->count() . "\n";      // count()
+    var_dump($arr->contains(3));    // in_array()
+
+    $big = std::bigInt("12345678901234567890");
+    echo $big->mul(2)->toString() . "\n";
+}
+```
+
+原生类型上的方法调用在编译期被解析为直接的 C/C++ 函数调用——没有虚表查找、
+没有反射、没有运行时派发。详见[通用方法](docs/UNIVERSAL_METHODS.md)。
+
+### 5. 混合 C++ / PHP
+
+用 C++ 编写性能关键内核，并在 PHP 中调用：
+
+```cpp
+// math.cpp
+#include <phpx.h>
+
+using namespace php;
+
+var php_fast_sum(Int a, Int b) {
+    return a + b;
+}
+```
+
+```php
+<?php
+// math.stub.php —— 声明 C++ 函数签名
+function fast_sum(int $a, int $b): int;
+```
+
+```php
+<?php
+function main(): void
+{
+    echo fast_sum(3, 4) . "\n";  // 7
+}
+```
+
+详见[混合 C++/PHP](docs/MIXED_CPP_PHP.md)。
+
+## 基准测试
+
+一个 10000×100000 的元素累加循环，对比 PHP 数组、TypePHP `std::array`
+与原生 C++：
+
+| 实现 | 耗时 |
+|---|---|
+| PHP 数组（JIT） | 67.6 秒 |
+| `std::array`（TypePHP AOT） | **6.4 秒** |
+| C++ `std::vector` | 6.2 秒 |
+
+`std::array` 比 PHP 数组快约 **10 倍**，性能与手写 C++ 完全一致。
+完整基准测试见 [Std 容器](docs/STD_CONTAINERS.md)。
+
+## 命令行
+
+```bash
+bin/tpc.php <file|dir|project.yml> [options] [-- program-args...]
+```
+
+常用示例：
+
+```bash
+# 编译单个文件
+bin/tpc.php app.php
+
+# 优化并运行，`--` 后的参数传给生成的程序
+bin/tpc.php app.php -O3 -r -- --flag value
+
+# 编译 project.yml 定义的项目
+bin/tpc.php project.yml -O2 -j 8
+
+# 生成 PHP 扩展
+bin/tpc.php extension/ -m ext -o my_extension
+
+# 只生成 C++（跳过编译与链接）
+bin/tpc.php app.php --dry --build-dir /tmp/typephp-build
+
+# 编译为 WASI 0.2
+bin/tpc.php --wasm app.php
+
+# 编译为浏览器目标（需要 jco）
+bin/tpc.php --wasm=browser app.php
+```
+
+主要选项：
+
+| 选项 | 说明 |
+|---|---|
+| `-O <0-3>` | 优化级别（默认 `0`） |
+| `-d`, `--debug` | 调试构建，带符号和源码跟踪 |
+| `-o`, `--output <file>` | 输出文件名 |
+| `-m`, `--mode <bin\|lib\|ext>` | 构建模式（默认 `bin`） |
+| `-r`, `--run` | 构建成功后运行 |
+| `-j`, `--job <num>` | 并行编译任务数（默认 `4`） |
+| `--build-dir <dir>` | 生成 C++ 与中间产物的目录 |
+| `--dry` | 只生成 C++，跳过编译与链接 |
+| `--php-version <8.4\|8.5>` | 接受的 PHP 语法版本 |
+| `--cxx-std <ver>` | C++ 标准（如 `c++17`、`c++20`） |
+| `--march <arch>` | 目标指令集（如 `native`） |
+| `--lto` | 启用链接时优化 |
+| `--sanitize <type>` | 启用 sanitizer（如 `address`） |
+
+运行 `bin/tpc.php --help` 查看权威的最新参数列表。详见
+[编译器命令行](docs/COMPILER_CLI.md)，包括 Bash 补全：
+
+```bash
+source <(./tpc --generate-completion=bash)
+```
+
+## Python 桥接
+
+TypePHP 内置一个 Python 工具子模块，复用 `tpc` 入口：
+
+```shell
+# 为 Python 模块生成 IDE helper
+./tpc --gen-python-helper math
+./tpc --gen-python-helper numpy --output-dir .ide-helper
+
+# 将 Python 脚本转换为 TypePHP
+./tpc --convert-python-to-php script.py > script.php
+```
+
+详见 [Python 工具子模块](docs/python/tools.md)。
+
+## 文档
+
+- [快速入门](docs/QUICKSTART.md) —— 最小编译流程
+- [编译模式](docs/COMPILATION_MODES.md) —— `bin`、`ext`、`lib`
+- [编译器命令行](docs/COMPILER_CLI.md) —— CLI 参数与项目配置
+- [不兼容 PHP 特性清单](docs/INCOMPATIBLE_PHP_FEATURES.md) —— 当前限制
+- [原生类型](docs/NATIVE_TYPES.md) —— 原生标量类型
+- [高精度类型](docs/HIGH_PRECISION_TYPES.md) —— BigInt / Decimal / BigFloat
+- [Std 容器](docs/STD_CONTAINERS.md) —— 强类型容器
+- [通用方法](docs/UNIVERSAL_METHODS.md) —— 零开销方法
+- [编译期函数](docs/COMPILE_TIME_FUNCTIONS.md) —— `any()`、`refval()`、`objval()` 等
+- [混合 C++/PHP](docs/MIXED_CPP_PHP.md) —— C++/PHP 互操作
+- [`#[Immutable]`](docs/IMMUTABLE.md) —— 编译期只读契约
+- [WASI 构建](docs/WASI_BUILD.md) —— WASI 目标
+
+## 授权协议
+
+TypePHP 采用 [GNU General Public License v3.0](LICENSE) 授权。
+
+## 社区
+
+- 代码仓库：<https://github.com/swoole/typephp>
+- 版权所有 © 2026 上海识沃网络科技有限公司（Swoole）
diff --git a/README.md b/README.md
index 6fa44b43..c5727644 100644
--- a/README.md
+++ b/README.md
@@ -1,94 +1,449 @@
-# 依赖
-- 编译器和生成程序均需要 PHP 8.4 以上版本，支持 PHP 8.4～8.5
-- 需要 GCC-9 以上版本，支持 C++17 标准
-- 需要 CMake-3.24 以上版本
-- 需要高精度数学库：`GMP`、`MPFR`、`libmpdec`
+[English](README.md) | [简体中文](README-CN.md)
 
-# Composer 安装
+<div align="center">
 
-在项目中安装 TypePHP：
+# TypePHP
+
+**A native AOT compiler for PHP**
+
+Compile PHP source code into native machine code ahead of time — producing
+standalone executables, PHP extensions, and static libraries — while keeping
+the PHP syntax you already know.
+
+</div>
+
+---
+
+## What is TypePHP?
+
+TypePHP is an Ahead-Of-Time (AOT) compiler that translates PHP source code into
+C++ and then into native machine code. Unlike a bytecode cache or a VM, it does
+not interpret opcodes at runtime: it generates optimized native binaries that
+run directly on the CPU.
+
+It keeps familiar PHP syntax and adds compile-time type information, so the
+compiler can emit fast, statically-typed C++ for your hot paths — while the
+rest of your code continues to run on the battle-tested Zend engine.
+
+## Features
+
+- **True AOT compilation** — PHP is lowered to C++17, then to native machine
+  code. No interpreter, no opcode cache, no JIT warm-up.
+- **Three build modes** — build a standalone `bin` executable, a loadable PHP
+  `ext` extension, or a `lib` static library from the same codebase.
+- **Native type system** — `int`, `float`, and `bool` map directly to C++
+  scalar types (`int64_t`, `double`, `bool`) for orders-of-magnitude speedups
+  on numeric code.
+- **High-precision numerics** — `bigInt` (GMP), `decimal` (libmpdec), and
+  `bigFloat` (MPFR) with zero-overhead arithmetic.
+- **Strongly-typed containers** — `std::array`, `std::vector`, `std::map`, and
+  `std::ordered_map` with compile-time element types; up to **10×** faster than
+  PHP arrays and on par with C++ `std::vector`.
+- **Universal methods** — call methods directly on primitives
+  (`$s->upper()`, `$arr->contains()`, `$big->mul(2)`) with zero runtime
+  dispatch overhead.
+- **Mixed C++ / PHP** — call C++ functions from PHP (and vice versa) for
+  performance-critical kernels.
+- **Compile-time functions & keywords** — `any()`, `refval()`, `objval()`,
+  `expected()`, `unexpected()`, plus `toInt()`, `toString()`, `toArray()` and
+  friends.
+- **Compile-time safety** — `#[Immutable]` read-only contracts and `#[ArrayDef]`
+  array-shape metadata, checked at compile time with zero runtime cost.
+- **Modern PHP support** — PHP 8.4 property hooks, asymmetric visibility,
+  PHP 8.5 `clone()`-with, and `(void)` discard expressions.
+- **Cross-platform & WASM** — Linux, Windows, and macOS targets for x86-64 and
+  ARM64, plus WASI 0.2 and browser (Jco) output.
+- **Python bridge** — generate IDE helpers for Python modules and convert
+  Python scripts to TypePHP.
+
+## Why TypePHP?
+
+| | TypePHP AOT | Opcode cache (OPcache) | JIT (PHP 8+) |
+|---|---|---|---|
+| Compilation target | Native machine code | Bytecode | Machine code (trace) |
+| Startup / warm-up | None (already compiled) | Per-process warm-up | JIT warm-up |
+| Type-driven optimization | Compile-time, full-program | None | Limited, trace-based |
+| Standalone executable | Yes | No | No |
+| Source code protection | Compiled to machine code | Bytecode (reversible) | Bytecode (reversible) |
+| Deterministic performance | Yes | No | No |
+
+**Strengths over plain PHP:**
+
+- **Near-native performance.** Numeric and container-heavy hot paths compile
+  down to the same machine code a C++ program would produce. See the
+  [benchmark](#benchmark) below.
+- **Source protection.** Your source is compiled away — shipped artifacts are
+  native binaries, not readable PHP files.
+- **Zero-dependency deployment.** Binary mode produces a single self-contained
+  executable that runs without a PHP runtime.
+- **Gradual typing that actually pays off.** Add `use native_types`, `std::`
+  containers, and type declarations only where performance matters; the rest
+  stays ordinary PHP.
+- **Full PHP ecosystem interop.** Extension mode loads as a standard PHP
+  extension into `php-fpm`, so existing frameworks and tooling keep working.
+
+## Requirements
+
+- **PHP 8.4 – 8.5** with the `embed` module (`libphp.so`)
+- **GCC 9+** (or Clang) with **C++17**
+- **CMake 3.24+**
+- High-precision math libraries: **GMP**, **MPFR**, **libmpdec**
+
+```shell
+# Ubuntu/Debian
+sudo apt install libgmp-dev libmpfr-dev libmpdec-dev
+
+# RHEL/CentOS/Fedora
+sudo dnf install gmp-devel mpfr-devel libmpdec-devel
+
+# Arch Linux
+sudo pacman -S gmp mpfr mpdecimal
+```
+
+> GMP powers `bigInt`, MPFR powers `bigFloat`, and libmpdec powers `decimal`.
+
+The preview currently targets **Linux** as the primary development platform
+(Ubuntu 22.04 recommended). Windows and macOS packaging is supported through
+the same entry point.
+
+## Installation
+
+### Via Composer
 
 ```bash
 composer require --dev swoole/typephp
 ```
 
-安装后可直接编译项目：
+Then compile your project:
 
 ```bash
 vendor/bin/tpc.php project.yml
 ```
 
-在 TypePHP 源码仓库中则使用：
+When working inside the TypePHP source repository, use the local entry point
+instead:
 
 ```bash
 bin/tpc.php project.yml
 ```
 
-Linux 环境缺少 `libphp.so` 时，`tpc.php` 可以交互式下载 PHP 源码并自动构建，详见 [自动构建 libphp.so](docs/LIBPHP_INSTALLER.md)。
+### Building `libphp.so`
 
-Python namespace IDE helper 与 Python 源码转换也使用同一入口：
+`tpc` requires a PHP built with the `embed` SAPI. If `libphp.so` is missing on
+Linux, `tpc.php` can interactively download the PHP source and build it for
+you. See [Automatic libphp.so build](docs/LIBPHP_INSTALLER.md).
 
-```shell
-./tpc --gen-python-helper math
-./tpc --gen-python-helper numpy --output-dir .ide-helper
-./tpc --convert-python-to-php script.py > script.php
+## Quick Start
+
+Create `hello.php`:
+
+```php
+<?php
+
+function main(): void
+{
+    echo "Hello World!\n";
+    var_dump(PHP_VERSION);
+    var_dump(php_uname());
+}
 ```
 
-详细说明见 [Python 工具子模块](docs/python/tools.md)。
+Compile and run it:
 
-```shell
-# Ubuntu/Debian
-sudo apt install libgmp-dev libmpfr-dev libmpdec-dev
+```bash
+bin/tpc.php hello.php
+./hello
+```
 
-# RHEL/CentOS/Fedora
-sudo dnf install gmp-devel mpfr-devel libmpdec-devel
+Output:
 
-# Arch Linux
-sudo pacman -S gmp mpfr mpdecimal
+```
+Hello World!
+string(5) "8.4.x"
+string(16) "Linux ..."
 ```
 
-> GMP 用于 `BigInt` 任意精度整数，MPFR 用于 `BigFloat` 高精度浮点数，libmpdec 用于 `Decimal` 十进制高精度小数。
+> Binary mode requires a global `main()` function. It may be declared with no
+> parameters, or as `main(int $argc, array $argv)` to receive command-line
+> arguments, and must return `void`.
 
-> 预览版目前仅支持 `Linux` 系统，建议使用 `Ubuntu 22.04`
+## Compilation Modes
 
-## PHP
-必须包含 embed 模块
+TypePHP supports three build modes, selected with `-m` / `--mode`:
 
-## PHPX
-可使用 `composer install` 安装依赖。
-进入 `vendor/swoole/phpx` 目录，编译 `phpx`
+| Mode | Flag | Output | Needs `main()` | Typical use |
+|---|---|---|---|---|
+| Binary | `-m bin` (default) | Executable | Yes | CLI tools, long-running services, standalone apps |
+| Extension | `-m ext` | `.so` / `.dll` | No | Web apps on `php-fpm`, drop-in PHP extension |
+| Library | `-m lib` | Static library | No | Embedding compiled code into other projects |
 
-```shell
-cd vendor/swoole/phpx
-cmake .
-make -j32
+```bash
+# Binary (default)
+bin/tpc.php app.php -o myapp
+
+# PHP extension
+bin/tpc.php extension/ -m ext -o my_extension
+
+# Static library
+bin/tpc.php lib/ -m lib -o mylib
 ```
 
-## 动态链接库
-```shell
-sudo ldconfig -p | grep php
+See [Compilation modes](docs/COMPILATION_MODES.md) for details.
+
+## Examples
+
+### 1. Native types — compile-time numeric speedup
+
+```php
+<?php
+use native_types;
+
+function fib(int $n): int
+{
+    if ($n == 1 || $n == 2) {
+        return 1;
+    }
+    return fib($n - 1) + fib($n - 2);
+}
+
+function main(int $argc, array $argv): void
+{
+    $n = (int)$argv[1];
+    $begin = microtime(true);
+    echo fib($n) . "\n";
+    echo "Time: " . (microtime(true) - $begin) . "\n";
+}
 ```
-必须包含 `libphp.so` 和 `libphpx.so`
 
-若编译完成，但找不到动态链接库，需要修改
-```shell
-vim /etc/ld.so.conf.d/swoole.conf 
+```bash
+bin/tpc.php fib.php -O3 -o fib
+./fib 30
+```
+
+With `use native_types`, `int` variables become C++ `int64_t` and arithmetic
+compiles to plain CPU instructions instead of ZendVM calls.
+
+### 2. High-precision numerics
+
+```php
+<?php
+declare(strict_types=1);
+use native_types;
+
+function main(): void
+{
+    // 54-digit integer — automatically detected and stored as bigInt
+    $a = std::bigInt("123456789012345678901234567890123456789012345678901234");
+    $b = std::bigInt("987654321098765432109876543210987654321098765432109876");
+
+    echo $a->add($b)->toString() . "\n";   // exact, no overflow
+
+    // Exact decimal arithmetic — no binary floating-point error
+    $c = std::decimal("0.1")->add(std::decimal("0.2"));
+    echo $c->toString() . "\n";            // "0.3"
+
+    // 256-bit floating point
+    $pi = std::bigFloat("3.14159265358979323846264338327950288419716939937510");
+    echo $pi->mul(2)->toString() . "\n";
+}
+```
+
+See [High-precision types](docs/HIGH_PRECISION_TYPES.md) and
+[Native types](docs/NATIVE_TYPES.md).
+
+### 3. Strongly-typed containers
+
+```php
+<?php
+use native_types;
+
+function main(): void
+{
+    $vector = std::vector(Type::Int);
+
+    $vector[] = 1;
+    $vector[] = 2;
+    $vector[] = 3;
+
+    $sum = 0;
+    foreach ($vector as $value) {
+        $sum += $value;
+    }
+
+    echo $sum . "\n";       // 6
+    echo $vector[1] . "\n"; // 2
+
+    // key-value map with fixed key/value types
+    $map = std::ordered_map(Type::String, Type::Int);
+    $map["a"] = 1;
+    $map["b"] = 2;
+}
+```
+
+See [Std containers](docs/STD_CONTAINERS.md).
+
+### 4. Universal methods
+
+```php
+<?php
+
+function main(): void
+{
+    $s = "hello world";
+    echo $s->length() . "\n";       // strlen()
+    echo $s->upper() . "\n";        // strtoupper()
+    echo $s->substr(0, 5) . "\n";   // substr()
+
+    $arr = [1, 3, 5, 7, 9];
+    echo $arr->count() . "\n";      // count()
+    var_dump($arr->contains(3));    // in_array()
+
+    $big = std::bigInt("12345678901234567890");
+    echo $big->mul(2)->toString() . "\n";
+}
+```
+
+Method calls on primitives are resolved at compile time into direct C/C++
+function calls — no vtable lookup, no reflection, no runtime dispatch. See
+[Universal methods](docs/UNIVERSAL_METHODS.md).
+
+### 5. Mixed C++ / PHP
+
+Write performance-critical kernels in C++ and call them from PHP:
+
+```cpp
+// math.cpp
+#include <phpx.h>
+
+using namespace php;
+
+var php_fast_sum(Int a, Int b) {
+    return a + b;
+}
 ```
 
-添加路径
+```php
+<?php
+// math.stub.php — declares the C++ function signature
+function fast_sum(int $a, int $b): int;
 ```
-/home/swoole/workspace/projects/phpx/lib
-/opt/php-8.4/lib/
+
+```php
+<?php
+function main(): void
+{
+    echo fast_sum(3, 4) . "\n";  // 7
+}
 ```
 
-## Release packaging
+See [Mixed C++/PHP](docs/MIXED_CPP_PHP.md).
+
+## Benchmark
+
+A 10000×100000 element update loop, comparing PHP arrays against TypePHP's
+`std::array` and native C++:
+
+| Implementation | Time |
+|---|---|
+| PHP array (JIT) | 67.6 s |
+| `std::array` (TypePHP AOT) | **6.4 s** |
+| C++ `std::vector` | 6.2 s |
+
+`std::array` is roughly **10× faster** than PHP arrays and performs
+identically to hand-written C++. See the full benchmark in
+[Std containers](docs/STD_CONTAINERS.md).
 
-Use the same PHP entry point on Windows, Linux, and macOS:
+## Command Line
+
+```bash
+bin/tpc.php <file|dir|project.yml> [options] [-- program-args...]
+```
+
+Common usage:
+
+```bash
+# Compile a single file
+bin/tpc.php app.php
+
+# Optimize and run, passing args to the program after `--`
+bin/tpc.php app.php -O3 -r -- --flag value
+
+# Compile a project defined in project.yml
+bin/tpc.php project.yml -O2 -j 8
+
+# Build a PHP extension
+bin/tpc.php extension/ -m ext -o my_extension
+
+# Only generate C++ (skip compile & link)
+bin/tpc.php app.php --dry --build-dir /tmp/typephp-build
+
+# Compile to WASI 0.2
+bin/tpc.php --wasm app.php
+
+# Compile for the browser (requires jco)
+bin/tpc.php --wasm=browser app.php
+```
+
+Key options:
+
+| Option | Description |
+|---|---|
+| `-O <0-3>` | Optimization level (default `0`) |
+| `-d`, `--debug` | Debug build with symbols and source tracking |
+| `-o`, `--output <file>` | Output file name |
+| `-m`, `--mode <bin\|lib\|ext>` | Build mode (default `bin`) |
+| `-r`, `--run` | Run after a successful build |
+| `-j`, `--job <num>` | Parallel compile jobs (default `4`) |
+| `--build-dir <dir>` | Directory for generated C++ and intermediates |
+| `--dry` | Generate C++ only, skip compile and link |
+| `--php-version <8.4\|8.5>` | PHP syntax version to accept |
+| `--cxx-std <ver>` | C++ standard (e.g. `c++17`, `c++20`) |
+| `--march <arch>` | Target instruction set (e.g. `native`) |
+| `--lto` | Enable link-time optimization |
+| `--sanitize <type>` | Enable a sanitizer (e.g. `address`) |
+
+Run `bin/tpc.php --help` for the authoritative, up-to-date list. See
+[Compiler CLI](docs/COMPILER_CLI.md) for details, including Bash completion:
+
+```bash
+source <(./tpc --generate-completion=bash)
+```
+
+## Python bridge
+
+TypePHP ships a Python tool submodule that shares the `tpc` entry point:
 
 ```shell
-php package.php
+# Generate IDE helpers for Python modules
+./tpc --gen-python-helper math
+./tpc --gen-python-helper numpy --output-dir .ide-helper
+
+# Convert a Python script to TypePHP
+./tpc --convert-python-to-php script.py > script.php
 ```
 
-Windows packaging requires `PHP_HOME` and `PHPX_HOME`; Linux packaging requires
-UPX; macOS uses `strip` when available. TypePHP rejects 32-bit targets and
-supports common 64-bit CPU architectures, including x86-64 and ARM64.
+See [Python tool submodule](docs/python/tools.md).
+
+## Documentation
+
+- [Quick Start](docs/QUICKSTART.md) — minimal compilation flow
+- [Compilation modes](docs/COMPILATION_MODES.md) — `bin`, `ext`, `lib`
+- [Compiler CLI](docs/COMPILER_CLI.md) — CLI arguments and project config
+- [Incompatible PHP features](docs/INCOMPATIBLE_PHP_FEATURES.md) — current limits
+- [Native types](docs/NATIVE_TYPES.md) — native scalar types
+- [High-precision types](docs/HIGH_PRECISION_TYPES.md) — BigInt / Decimal / BigFloat
+- [Std containers](docs/STD_CONTAINERS.md) — strongly-typed containers
+- [Universal methods](docs/UNIVERSAL_METHODS.md) — zero-overhead methods
+- [Compile-time functions](docs/COMPILE_TIME_FUNCTIONS.md) — `any()`, `refval()`, `objval()`, …
+- [Mixed C++/PHP](docs/MIXED_CPP_PHP.md) — C++/PHP interop
+- [`#[Immutable]`](docs/IMMUTABLE.md) — compile-time read-only contracts
+- [WASI build](docs/WASI_BUILD.md) — WASI targets
+
+## License
+
+TypePHP is licensed under the [GNU General Public License v3.0](LICENSE).
+
+## Community
+
+- Repository: <https://github.com/swoole/typephp>
+- Copyright © 2026 上海识沃网络科技有限公司 (Swoole)