docs: update guides for refactored python layout

Co-authored-by: wawahejun <hejunlbbc@gmail.com>

README.md

@@ -9,6 +9,20 @@ small, but its workflow mirrors production operator libraries:
 4. Expose a Python API with out-of-place, out-variant, and prepared execution.
 5. Validate correctness against PyTorch and benchmark steady-state execution.
 
+## Python Layout
+
+```text
+python/
+  operator_runtime/
+    backend.py
+    ops/
+    _internal/
+  operator_runtime_testing/
+```
+
+- `operator_runtime.ops` contains public operator bindings.
+- `operator_runtime._internal` contains private FFI/runtime plumbing.
+- `operator_runtime_testing` contains test-only helpers such as assertions and benchmark utilities.
 
 ## Operators
 
@@ -49,7 +63,7 @@ The TileLang backend requires the `tilelang` Python package.
 
 1. Create `ops/<name>/nvidia/<name>_cuda.h` with the C API (4 functions: create, workspace, execute, destroy).
 2. Create `ops/<name>/nvidia/<name>_cuda.cu` with the CUDA implementation.
-3. Create `python/operator_runtime/ops/<name>.py` using `ctypes_bindings.bind_*` functions.
+3. Create `python/operator_runtime/ops/<name>.py` using `operator_runtime._internal.bind_*` functions.
 4. Create `tests/cases/<name>.py` with `correctness_cases()`, `api_error_cases()`, and `benchmark_cases()`.
 5. Create `tests/ops/test_<name>.py` and `tests/bench/<name>.py`.
 6. Re-run `cmake ..` in the build directory (the glob will pick up the new `.cu` file).

README.zh.md

@@ -8,6 +8,21 @@
 4. 提供 Python API，支持 out-of-place、out-variant 和 prepared 执行。
 5. 通过 PyTorch 做正确性验证，并做稳定态性能测试。
 
+## Python 目录结构
+
+```text
+python/
+  operator_runtime/
+    backend.py
+    ops/
+    _internal/
+  operator_runtime_testing/
+```
+
+- `operator_runtime.ops` 放公开算子绑定。
+- `operator_runtime._internal` 放私有 FFI 和运行时细节。
+- `operator_runtime_testing` 放断言、benchmark 等仅测试使用的工具。
+
 ## 算子
 
 | 算子 | NVIDIA C++ | TileLang | MetaX |
@@ -43,6 +58,18 @@ python tests/run_ops.py --op all --backend nvidia --mode bench
 
 TileLang 后端需要安装 `tilelang` Python 包。
 
+## 如何新增算子
+
+1. 创建 `ops/<name>/nvidia/<name>_cuda.h`，提供 4 个 C API：create、workspace、execute、destroy。
+2. 创建 `ops/<name>/nvidia/<name>_cuda.cu`，实现 CUDA 逻辑。
+3. 创建 `python/operator_runtime/ops/<name>.py`，使用 `operator_runtime._internal.bind_*` 绑定。
+4. 创建 `tests/cases/<name>.py`，提供 `correctness_cases()`、`api_error_cases()` 和 `benchmark_cases()`。
+5. 创建 `tests/ops/test_<name>.py` 和 `tests/bench/<name>.py`。
+6. 在构建目录里重新执行 `cmake ..`，因为 glob 会自动拾取新的 `.cu` 文件。
+7. 在 `python/operator_runtime/__init__.py` 中导出公共 API。
+
+这里没有 YAML、没有代码生成、也没有额外的注册步骤。
+
 ## 生产映射
 
 | 训练概念 | 生产等价物 |

docs/how-to-add-an-operator.md

@@ -1,7 +1,5 @@
 # 如何开发一个新算子
 
-本文只描述当前仓库里新增算子的实际流程，不展开代码细节。
-
 ## 目标
 
 在当前项目里，新增一个可运行算子的最小闭环包括四部分：
@@ -11,15 +9,6 @@
 3. 在 `tests/` 下补正确性测试和 benchmark 入口。
 4. 重新构建并验证。
 
-## 当前仓库的真实约束
-
-- 现在没有 `operator.yaml`。
-- 现在没有代码生成步骤。
-- 现在没有单独的 operator registry 文件。
-- NVIDIA 的 `.cu` 文件通过目录约定自动发现。
-- 新增或重命名 `.cu` 后，需要重新执行一次 `cmake ..`。
-
-也就是说，新增算子主要依赖目录结构和命名约定，而不是额外的注册配置。
 
 ## Step 1：明确算子接口