Show the trace loop from an error code to a log entry and HTTP envelope.

The example keeps the two modules decoupled and checks that one trace id appears on both sides.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/integration.md

@@ -0,0 +1,64 @@
+# 错误码、日志与 trace_id
+
+两个库互不导入。错误码库负责稳定的码和 HTTP 信封，日志库负责把同一次调用的运行记录留下来。对齐点只有两个：
+
+- 追踪头都是 `X-Trace-Id`
+- 日志通过 `ErrorCode()` / `ErrorFields()` 识别错误，不需要 `import error-code-system`
+
+## 一次失败怎么串起来
+
+```text
+HTTP 中间件生成或沿用 X-Trace-Id
+        │
+        ▼
+errcode.Wrap(...) 得到规范码
+        │
+        ├─ httpx.WriteError  →  {"error":{"code","message","reason","trace_id"}}
+        │
+        └─ log.WithContext(ctx).Error(msg, err)
+                 │
+                 ▼
+           日志条目含 trace_id + code + 字段
+                 │
+                 ▼
+           HTTP sink 批量 POST 到 :8092
+                 │
+                 ▼
+           GET /v1/logs?trace_id=... 或 ?q=agent.provider_unavailable
+```
+
+查问题先拿响应里的 `trace_id` 或 `code`。`trace_id` 能拉出这一次调用的全部日志；`code` 能跨请求看同一类失败。副作用是 `possible` 或 `unknown` 的码不要无条件重放，先看日志里这次执行写过什么。
+
+## 最小示例
+
+可运行副本：`Logging-System/examples/trace`（需要两个仓库是同级目录）。
+
+```go
+reg := errcode.NewRegistry()
+domains.RegisterAll(reg)
+
+cfg, _ := config.Load("log.json") // 见 Logging-System/docs/example.json
+log, _ := config.Build(cfg)
+defer log.Close()
+
+ctx := logsys.WithTrace(r.Context(), httpx.TraceID(r))
+err := errcode.Wrap(cause, errcode.AgentProviderUnavailable, "模型不可达", "model", "glm-4")
+log.WithContext(ctx).Error("provider down", err)
+
+httpx.WriteError(reg, w, r, err)
+```
+
+日志条目里会有 `trace_id=...` 和 `code=agent.provider_unavailable`。采集器侧：
+
+```bash
+logctl query --addr http://127.0.0.1:8092 --trace <响应里的 trace_id>
+```
+
+## 接入现有仓库时
+
+本轮不改 Agent-Native / Agent-Squad。对应关系已经写在错误码仓库：
+
+- `docs/agent-native-mapping.md`
+- `docs/agent-squad-mapping.md`
+
+接入时保持现有事件名和 `AssessStepFailure` 分类，只把对外的错误字符串换成规范码，并把 `run_id` 写入日志字段。`run_id` 回答「哪一次编排」，`trace_id` 回答「哪一次请求」，两者都保留。