diff --git a/README.md b/README.md
index ddaf73e..e0a6794 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,7 @@
 - [注册治理](docs/governance.md)
 - [agent-native](docs/agent-native-mapping.md)
 - [agent-squad](docs/agent-squad-mapping.md)
+- [和日志系统对齐](docs/integration.md)
 
 ## 进程内用法
 
diff --git a/docs/integration.md b/docs/integration.md
new file mode 100644
index 0000000..8d5789b
--- /dev/null
+++ b/docs/integration.md
@@ -0,0 +1,13 @@
+# 错误码、日志与 trace_id
+
+错误码仓库与日志仓库互不导入。对齐方式、调用顺序和查询命令见同级仓库 Logging-System 的 `docs/integration.md`。两个仓库需要放在同级目录时，可运行示例是 `Logging-System/examples/trace`。
+
+本地副本要点：
+
+1. HTTP 层回显 `X-Trace-Id`（`httpx.Trace`）。
+2. 用 `errcode.Wrap` 带上规范码；未知码回落 `sys.unknown_code`。
+3. `httpx.WriteError` 的信封带 `code` 和 `trace_id`。
+4. 同一 context 上的日志会带同一个 `trace_id`。若错误实现了 `ErrorCode()` / `ErrorFields()`，日志条目同时带上码和字段。
+5. 用 `trace_id` 到采集器查这一次调用，用 `code` 查同一类失败。
+
+副作用为 `possible` 或 `unknown` 的码禁止无条件重放。agent-native 与 agent-squad 的现有字符串如何落到规范码，见 [agent-native-mapping.md](agent-native-mapping.md) 与 [agent-squad-mapping.md](agent-squad-mapping.md)。