[CLAUDE] Docs: S59 session-end closeout - 10 dot ship prod-verified #273->#282 + gotcha #61/#62 + harvest gate PASS 5/5

- Session log MOI 2026-06-11-S59-wipe-tree-pmh-uat-batch.md (wipe testing data +
  tree 4 tang + 71 ma PMH + 6 vong UAT realtime, bundle FINAL B1DtNT9C/D6uF3Mln Run #282).
- STATUS/HANDOFF flush S59 (header + table + In Progress + Recently Done + bundle line).
- gotchas.md +2: #61 sqlcmd -f 65001 (console mojibake vs data-hong-that) + #62 rename
  natural-key DB-truoc-code-sau (seed per-code idempotent). CLAUDE.md root cite 62.
- Agent-memory 5 file: cicd x9 run entries + UTC-annotate #275 + bundle status-line final,
  inv-codebase recon S59 + curate S51->archive, H1 x2 + H2 x2 closeout entries.
- H2 GATE PASS 5/5 (0 miss, 0 on-behalf can append) + H1 ALL-4-FRESH (cross-count
  verified: gotcha 62 x3 nguon, bundle 4-source). RAG: 2 chunk S59 stored, rerank 0.875.
- Chore monthly 07-01: curate cicd L1 ~56KB + inv 32.9KB + STATUS/HANDOFF re-tier (uu tien).

docs/gotchas.md

@@ -1096,6 +1096,34 @@ for h in resp.points:    # ← .points không phải iterable trực tiếp
 
 ---
 
+### 61. sqlcmd chạy file .sql chứa tiếng Việt PHẢI `-f 65001` — console mojibake là display-only nhưng thiếu flag thì DATA hỏng thật (Session 59)
+
+**Triệu chứng:** Output sqlcmd trên VPS hiện `H? th?ng trung th?`, `Ph?n th<74>` — không phân biệt được "console hiển thị sai" (vô hại) với "data trong DB đã hỏng" (thảm họa, nhất là với UPDATE/INSERT chứa nvarchar tiếng Việt).
+
+**Root cause 2 lớp:** (1) Console VPS codepage OEM → mọi output Unicode đều mojibake = **display-only**, data vẫn đúng. (2) NHƯNG sqlcmd mặc định cũng đọc **input file** theo OEM codepage — file `.sql` UTF-8 no-BOM (như Write tool tạo) chứa `N'Bê tông'` sẽ bị decode sai → **ghi vào DB chuỗi hỏng THẬT**. Hai hiện tượng nhìn giống hệt nhau trên console.
+
+**Fix + phòng tái diễn (S59 proven):** (1) Mọi lệnh `sqlcmd -i <file>` với file chứa tiếng Việt → thêm **`-f 65001`** (đọc input UTF-8). (2) **KHÔNG kết luận data đúng/hỏng từ console VPS** — verify độc lập: chạy cùng file trên LocalDB local (console local hiện tiếng Việt đúng) + curl API prod đọc JSON (UTF-8 end-to-end). S59 rename 71 WorkItems: console VPS mojibake nhưng API JSON trả `"2 MEP Sub Hệ thống trung thế"` nguyên vẹn → data đúng.
+
+**References:** `scripts/s59-rename-workitems-pmh.sql` (run với `-f 65001`) · verify pattern: login admin → GET `/api/catalogs/work-items` JSON.
+
+---
+
+### 62. Đổi mã (natural-key) của data có seed per-code idempotent — PHẢI UPDATE DB prod TRƯỚC khi deploy seed mới, sai thứ tự = nhân đôi rows (Session 59)
+
+**Triệu chứng tiềm năng (đã né):** Seed kiểu `SeedRealMasterDataAsync` so khớp theo `Code` (`if (existingCodes.Contains(code)) continue`). Đổi 71 mã WorkItems `VT-01→MAT-1`… nếu **push code trước**: app restart chạy seed với tuples MỚI → thấy 71 mã mới "chưa tồn tại" (DB còn mã cũ) → INSERT 71 row mới = **142 rows trùng tên khác mã** trên prod.
+
+**Quy trình đúng (S59 proven, Run #276 verify 71 — không phải 142):**
+1. Viết SQL `UPDATE … SET Code=mới, Name=mới WHERE Code=cũ` (**GIỮ NGUYÊN Id** — record đang được trỏ tới không gãy; phiếu PE/2026/A/001 vừa tạo vẫn đúng hạng mục).
+2. Chạy SQL trên **prod + LocalDB Dev** trước.
+3. Sửa seed tuples trong code → commit + push SAU. App restart: seed thấy đủ mã mới → add 0.
+4. cicd verify count ĐÚNG N (N×2 = FAIL nghiêm trọng — đưa vào prompt verify).
+
+**Tổng quát:** idempotent-by-natural-key chỉ an toàn khi key bất biến — mọi rename key phải đổi DB và seed "cùng khoảnh khắc" theo thứ tự **DB-trước-code-sau** (với CI auto-deploy-on-push).
+
+**References:** `scripts/s59-rename-workitems-pmh.sql` · `DbInitializer.cs` SeedRealMasterDataAsync · gotcha #57 họ hàng (soft-delete vs UNIQUE filtered) · Run #276 cicd verdict.
+
+---
+
 ## Checklist debug bug mới
 
 1. Build pass không? → fail → check using + package version compat