From 2289f9a289fe578d4b9a03f2533c98457bf6025d Mon Sep 17 00:00:00 2001
From: hzqst <113660872@qq.com>
Date: Wed, 21 Oct 2026 13:47:50 +0800
Subject: [PATCH] docs: move C/C++ formatting notes into project memory

The formatting section is developer-only tooling guidance, so it no longer
belongs in the user-facing READMEs. Record it as the CppFormatting memory note
and link to it from AGENTS.md.

Co-Authored-By: Claude Code <noreply@anthropic.com>
---
 AGENTS.md               |  1 +
 README.md               | 33 ----------------------
 README.zh-CN.md         | 30 --------------------
 memory/CppFormatting.md | 61 +++++++++++++++++++++++++++++++++++++++++
 4 files changed, 62 insertions(+), 63 deletions(-)
 create mode 100644 memory/CppFormatting.md

diff --git a/AGENTS.md b/AGENTS.md
index 2f23103..2009d8c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,6 +15,7 @@ This file provides guidance and important rules working with code in this reposi
 
 - Project overview and codebase entry points: `project_overview`
 - Build commands, dependency pinning, gamedata sync, verification status: `build_and_verification`
+- C/C++ formatting toolchain, commands and check scope: `CppFormatting`
 
 ### When notes are insufficient: source entry points (query and read on demand)
 
diff --git a/README.md b/README.md
index f9ca9a6..ed4985a 100644
--- a/README.md
+++ b/README.md
@@ -42,36 +42,3 @@ Enable `VGUI2Extension.dll` in MetaHook's `metahook/configs/plugins.lst`, then l
 ## License
 
 Licensed under the [MIT License](LICENSE); each dependency keeps its own license.
-
-## C/C++ formatting
-
-Formatting uses [MetaHookSv/FormatValidation](https://github.com/MetaHookSv/FormatValidation)
-and clang-format **23.1.3**, with the DiligentCore style (4 spaces, preserved include
-order). Install the formatter for the Python interpreter used by CMake:
-
-```sh
-python -m pip install clang-format==23.1.3
-cmake -S . -B build/format "-DFORMAT_VALIDATION_ONLY=ON"
-cmake --build build/format --target format-check
-cmake --build build/format --target format
-```
-
-The format-only configuration needs CMake 3.21+, Git, Python 3.9+ (CI uses 3.12),
-and a build generator; `-G Ninja` works without Visual Studio. It prepares no native
-SDK or game dependencies. Formatting targets are explicit and are not part of a
-normal DLL build. With a Visual Studio generator, add `--config Debug` or
-`--config Release` when building a formatting target.
-
-The aggregate provides `FORMAT_VALIDATION_SOURCE_PATH=thirdparty/FormatValidation`.
-Standalone components accept that CMake variable or its environment counterpart;
-if empty, FetchContent downloads the fixed tooling commit. Quote relative paths,
-for example `"-DFORMAT_VALIDATION_SOURCE_PATH=../../thirdparty/FormatValidation"`.
-Configuration generates the ignored root `.clang-format` for editors; change the
-shared style rather than that generated copy. An optional
-`FORMAT_VALIDATION_CLANG_FORMAT_EXECUTABLE` selects an explicit formatter, whose
-version must still match the pin.
-
-Checks cover owned C/C++ files in `src/`, `include/`, and `tests/`, including
-non-ignored new files. Repository-relative exclusions live in `.clang-format-ignore`.
-Third-party sources and build artifacts are excluded. The `clang-format` workflow
-checks the full scope on pushes, pull requests, and manual runs.
diff --git a/README.zh-CN.md b/README.zh-CN.md
index f92a756..299176d 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -38,33 +38,3 @@ VGUI2Extension 是 MetaHook 的 UI 扩展插件，为其他插件提供修改 Go
 ## 许可证
 
 项目采用 [MIT License](LICENSE)；各依赖保留自己的许可证。
-
-## C/C++ 格式化
-
-使用 [MetaHookSv/FormatValidation](https://github.com/MetaHookSv/FormatValidation)
-共享工具及固定版本 **clang-format 23.1.3**，采用 DiligentCore 风格（4 空格，保留
-include 顺序）。为 CMake 使用的 Python 解释器安装格式工具：
-
-```sh
-python -m pip install clang-format==23.1.3
-cmake -S . -B build/format "-DFORMAT_VALIDATION_ONLY=ON"
-cmake --build build/format --target format-check
-cmake --build build/format --target format
-```
-
-格式专用配置需要 CMake 3.21+、Git、Python 3.9+（CI 使用 3.12）及构建生成器；
-使用 `-G Ninja` 可无需 Visual Studio。它不准备原生 SDK 或游戏依赖。
-格式目标需显式执行，不加入普通 DLL 构建。使用 Visual Studio 生成器时，执行目标
-需追加 `--config Debug` 或 `--config Release`。
-
-聚合仓库注入 `FORMAT_VALIDATION_SOURCE_PATH=thirdparty/FormatValidation`。
-独立组件支持该 CMake 参数及同名环境变量；为空时通过 FetchContent 获取固定工具
-提交。相对路径应加引号，例如
-`"-DFORMAT_VALIDATION_SOURCE_PATH=../../thirdparty/FormatValidation"`。
-配置时在仓库根目录生成被 gitignore 的 `.clang-format` 供编辑器使用；格式规则应
-在共享仓库修改，不修改生成副本。可通过 `FORMAT_VALIDATION_CLANG_FORMAT_EXECUTABLE`
-指定工具路径，但版本仍须与固定版本一致。
-
-检查覆盖 `src/`、`include/`、`tests/` 中维护的 C/C++ 文件，包括未被 Git 忽略的新文件。
-相对仓库根目录的排除规则位于 `.clang-format-ignore`；第三方源和构建产物不纳入检查。
-`clang-format` workflow 在 push、pull request 和手动运行时执行全量检查。
diff --git a/memory/CppFormatting.md b/memory/CppFormatting.md
new file mode 100644
index 0000000..147b7ab
--- /dev/null
+++ b/memory/CppFormatting.md
@@ -0,0 +1,61 @@
+---
+title: CppFormatting
+type: guide
+permalink: vgui2extension/cpp-formatting
+---
+
+# C/C++ formatting
+
+Formatting notes for this repository. The aggregator keeps the same note as
+`metahooksv/cpp-formatting`; this copy carries the standalone paths.
+
+## Toolchain and style
+
+Formatting uses
+[MetaHookSv/FormatValidation](https://github.com/MetaHookSv/FormatValidation) and
+clang-format **23.1.3**, with the DiligentCore style (4 spaces, preserved include
+order). Install the formatter for the Python interpreter used by CMake:
+
+```sh
+python -m pip install clang-format==23.1.3
+cmake -S . -B build/format "-DFORMAT_VALIDATION_ONLY=ON"
+cmake --build build/format --target format-check
+cmake --build build/format --target format
+```
+
+The format-only configuration needs CMake 3.21+, Git, Python 3.9+ (CI uses 3.12),
+and a build generator; `-G Ninja` works without Visual Studio. It prepares no
+native SDK or game dependencies. Formatting targets are explicit and are not part
+of a normal DLL build. With a Visual Studio generator, add `--config Debug` or
+`--config Release` when building a formatting target.
+
+`format-check` and `format` are the top-level aliases; this component also exposes
+`VGUI2Extension-format-check` and `VGUI2Extension-format`.
+
+## Source path resolution
+
+`cmake/FormatValidation.cmake` accepts `FORMAT_VALIDATION_SOURCE_PATH` as a CMake
+variable or environment variable. When it is empty, FetchContent downloads the
+retained tooling commit `13c9fabe058e1f887ad1b03bb6884de911192c6a` (`v1.0.0`), which must not move.
+
+Quote relative paths, for example
+`"-DFORMAT_VALIDATION_SOURCE_PATH=../../thirdparty/FormatValidation"`.
+Configuration generates the gitignored root `.clang-format`; change the shared
+style rather than that generated copy. An optional
+`FORMAT_VALIDATION_CLANG_FORMAT_EXECUTABLE` selects an explicit formatter, whose
+version must still match the pin.
+
+## Checked scope
+
+Checks cover owned C/C++ files under `src/`, `include/` and `tests/`, including
+non-ignored new files. Repository-relative exclusions live in
+`.clang-format-ignore`; external SDK trees, third-party sources and build artifacts
+are excluded. `.github/workflows/clang-format.yml` runs the same full-scope check
+on pushes, pull requests and manual runs.
+
+## Known constraints
+
+- Keep MSVC inline assembly inside explicit blocks; formatting unbraced assembly
+  can absorb the following C++ statements.
+- Do not hand-edit the generated `.clang-format`; change the shared FormatValidation
+  style instead.