docs(gitea): 记录精简升级验收策略

Reviewed-on: #29

AGENTS.md

@@ -4,6 +4,8 @@
 - `apps/http-echo/` and `archive/traefik/` contain Kubernetes/Gateway API manifests; inspect their parent Gateway references before applying archived or brownfield resources.
 - `apps/tailscale/helm.sh` contains live Tailscale OAuth values; do not copy, print, or commit those values anywhere else.
 - Preserve the existing README intent in `apps/http-echo/` and `archive/traefik/` when updating manifests.
+- `CHANGELOG.md` 是冻结的历史快照，不再更新。持久的服务状态与运维知识写入对应
+  README/runbook；单次变化由 commit 和 PR 记录，agent 陷阱写入 `CLAUDE.md`。
 - 在 homelab 工作中，所有提交到 `git.ddupan.top` 的 commit message、PR、issue
   和项目文档默认优先使用中文。代码标识符、命令、配置键、上游专有名称，以及
   使用英文能避免歧义的技术字段可保留英文。

CHANGELOG.md

@@ -34,8 +34,7 @@ What changed in this homelab, when, and why. Newest first.
 | Gitea 1.26 result | Flux 以 Helm revision 16 成功完成 chart `12.6.0` / Gitea `1.26.4-rootless` 的 Recreate upgrade 和 migration 323–330；Pod 内/统一域名 API、临时 branch push/delete、Flux source 及 main/smoke 的全部 CI jobs 均通过，Pod 在约 15 分钟采样中保持零重启，Authelia OIDC init 同步与浏览器交互式管理员登录也已确认成功 |
 | Gitea 1.27 preparation | 预拉取 `1.27.3-rootless` 并将第二跳 desired state 原子设置为 chart `12.7.0`、显式 image `1.27.3` 和 `suspend: true`；合并只暂停并登记目标，不执行 migration，激活前必须从当前 1.26.4 数据建立新的配套回滚点 |
 | Gitea 1.27 activation | 按明确决定跳过新的 1.26.4 数据库/PVC 备份，激活变更只移除 HelmRelease 的 `suspend`；接受 migration 失败后不能无损回退到 1.26.4 的风险，现有 1.25.5 本地备份仅能作为会丢失第一跳后状态的灾难恢复点 |
-| Gitea 1.27 result | Flux 以 Helm revision 17 成功部署 chart `12.7.0` / 实际 Gitea `1.27.3-rootless`，migration 331–342 与 init containers 全部成功；内外 API、Git write 路径与 Flux source 均通过，Pod Ready 且零重启。Chart metadata 的 appVersion `1.27.0` 不代表实际固定镜像版本 |
-| Gitea upgrade policy | 连续两次跨 minor 升级证明当前 Flux + Recreate + rootless PVC + 外部 CNPG 路径稳定；后续常规 patch/minor 默认缩减为 release-note review、render、UpgradeSucceeded/Pod Ready/API、OIDC 与 Git 抽查。只有数据库/存储/rootless/PVC/部署策略/重大 chart 或 breaking migration 变化及实际失败时，才恢复停机备份和扩展验收 |
+| CI runner network | 修复 Actions job 容器访问 GitHub 超时：k3s Pod MTU 为 1450，而 DinD 动态 bridge 默认为 1500；为 Docker daemon 固定 `--mtu=1450`。隔离测试证明相同 curl 镜像在默认 bridge 超时、在 MTU 1450 bridge 下访问 GitHub 与 API 均约 0.1 秒成功 |
 
 ### Incident: Gitea 备份后的恢复命令被 stdin 校验阻塞
 
@@ -46,10 +45,11 @@ What changed in this homelab, when, and why. Newest first.
 旧版 Gitea 恢复后内外 API 和 Flux source 均正常；后续 runbook 不再把 stdin 管道与
 恢复命令放进同一个 shell transaction。
 
-`Carried forward`: migrate Gitea's remaining manual OIDC Secret to OpenBao/ESO,
-then add credential-free PR plan output and order the remaining Helm migrations
-by dependency and blast radius. Root Flux prune remains disabled until
-brownfield ownership is audited.
+`Carried forward`: complete the two-stage zero-change `gitea` HelmRelease
+adoption, migrate its remaining manual OIDC Secret to OpenBao/ESO, then upgrade
+Gitea and add credential-free PR plan output before ordering the remaining Helm
+migrations by dependency and blast radius. Root Flux prune remains disabled
+until brownfield ownership is audited.
 
 ## 2026-09-09
 

CLAUDE.md

@@ -132,9 +132,10 @@ recovered, so `.vault_pass.gpg` is the authoritative recovery path.
 
 ## Working rules
 
-- **Record changes in `CHANGELOG.md`.** One dated section per day, newest first; incidents
-  get their own subsection. Traps and procedures belong *here* in CLAUDE.md, not there —
-  the changelog is for humans reading what changed.
+- **Do not update `CHANGELOG.md`.** It is a frozen historical snapshot; requiring every PR
+  to append to one shared text file caused needless conflicts and duplicated Git/PR history.
+  Put durable service state and operational knowledge in the component README or runbook,
+  agent-facing traps here, and let commits/PRs record individual changes.
 - **Verify, don't assert.** Check the end state (`pvesm status`, `linstor node list`,
   `kubectl get pod`, `show ip route`) rather than trusting that a command "should have" worked.
   Several confident diagnoses in this repo's history were wrong until measured.

docs/superpowers/RETIRED.md

@@ -20,7 +20,7 @@ SUB-SKILL", checkbox task lists) that only ever suited one migration. Design
 documents now live directly in `docs/` — see `../cicd.md` — and the split that
 matters is:
 
-- `CHANGELOG.md` — what changed, for humans
+- `CHANGELOG.md` — frozen historical snapshot; Git commits and PRs now record changes
 - `CLAUDE.md` — traps and procedures, for agents
 - `docs/*.md` — design docs for work not yet built
 - `<service>/README.md` — how a service actually works

platform/gitea-runner/README.md

@@ -7,6 +7,12 @@ would still be privileged and is blocked by the node's AppArmor user-namespace
 policy, so this deployment uses regular DinD instead of weakening that host-wide
 policy. Only trusted workflows may target this runner.
 
+DinD 显式使用 `--mtu=1450`，与 k3s Pod 的 `eth0` 一致。不要在未验证节点 Pod
+MTU 的情况下删除或修改它：DinD 默认创建 MTU 1500 的 Actions bridge，容器虽然
+能够解析 GitHub、甚至建立 TCP 连接，但较大的 TLS 数据包会在嵌套网络路径中丢失，
+表现为 `github.com` / `api.github.com` 超时。Pod 网络和 `--network host` 正常不代表
+job bridge 正常。
+
 The runner is registered at instance scope so it is available to every repository
 on this Gitea instance. Repository permissions and protected-branch review are
 therefore the security boundary; do not enable Actions for untrusted repositories.

platform/gitea-runner/values.yaml

@@ -51,3 +51,8 @@ statefulset:
     repository: docker
     tag: 29.7.1-dind
     pullPolicy: IfNotPresent
+    # k3s uses a 1450-byte pod MTU. Without matching it here, nested Actions
+    # networks advertise 1500 and GitHub TLS packets disappear on the outer
+    # overlay path while direct pod traffic remains healthy.
+    extraArgs:
+      - --mtu=1450