docs: บันทึกกับดัก repo ใหม่ที่ CI ไม่ยอมรัน + CLAUDE.md ของ repo นี้

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,36 @@
+## ทำไมต้องเปลี่ยน
+
+<!-- ปัญหาหรือความต้องการที่ทำให้เกิด PR นี้ ถ้ามี issue ให้ลิงก์ -->
+
+Closes #
+
+## เปลี่ยนอะไร
+
+<!-- สรุปให้คนที่ไม่ได้อยู่ในหัวคุณเข้าใจได้ ไม่ต้องไล่ทีละไฟล์ diff บอกอยู่แล้ว -->
+
+-
+
+## ทดสอบยังไง
+
+<!-- คนรีวิวต้องทำตามได้จริง -->
+
+```bash
+
+```
+
+## ผลกระทบ
+
+- [ ] เป็น breaking change (ถ้าใช่ ระบุด้านล่างว่าใครต้องแก้ตาม)
+- [ ] ต้องรัน migration
+- [ ] ต้องเพิ่ม/แก้ env var หรือ secret (ระบุชื่อ ไม่ต้องใส่ค่า)
+- [ ] กระทบ repo อื่น
+
+<!-- ถ้าติ๊กข้อไหน อธิบายตรงนี้ + ลิงก์ PR ที่เกี่ยวข้องแบบ myorg/repo#123 -->
+
+## Checklist ก่อนขอรีวิว
+
+- [ ] อ่าน diff ของตัวเองใน GitHub แล้ว
+- [ ] CI เขียว
+- [ ] ไม่มี debug log / โค้ดที่ comment ทิ้ง / `TODO` ค้าง
+- [ ] ไม่มี secret หรือค่า config ที่ hardcode
+- [ ] เปลี่ยนจริงไม่เกิน ~400 บรรทัด (ถ้าเกิน อธิบายว่าทำไมแตกไม่ได้)

CLAUDE.md

@@ -0,0 +1,57 @@
+# workshop-github
+
+handbook + template + script สำหรับทำให้ทุก repo ของทีมเป็นมาตรฐานเดียวกัน
+ใช้ในการอบรมทีม และเป็นแหล่งอ้างอิงหลังอบรมจบ
+
+## คำสั่งที่ใช้บ่อย
+
+```bash
+./scripts/validate.sh              # ตรวจทั้ง repo — CI เรียกตัวเดียวกันนี้
+./scripts/validate.sh templates    # เฉพาะ YAML/JSON และ gate job
+./scripts/check-setup.sh           # ตรวจว่าเครื่องพร้อม (ตัวที่ผู้เข้าอบรมรัน)
+```
+
+ต้องมี `python3` + `pyyaml`, `shellcheck`, `gh`, `jq`
+ถ้าเครื่องไม่มี shellcheck `validate.sh` จะเตือนแล้วข้ามไป — **แต่ CI จะรันให้ ทำให้ PR แดงได้**
+
+## โครงสร้าง
+
+```
+docs/         handbook 8 บท เรียงตามลำดับที่ต้องอ่าน (00 = agenda, 99 = cheatsheet)
+templates/    ไฟล์ที่ทีมก๊อปไปใช้กับ repo จริง — พังเมื่อไหร่กระทบทุก repo ที่ก๊อปไปแล้ว
+scripts/      เครื่องมือติดตั้ง/ตรวจสอบ ต้องรันได้บนเครื่องคนอื่นด้วย
+```
+
+## กติกาของ repo นี้
+
+- **ทุกอย่างเข้าผ่าน PR ที่ CI เขียว** main มี branch protection อยู่ push ตรงเข้าไม่ได้
+- **แก้ `templates/github/workflows/ci-*.yml` แล้วห้ามทำให้ job ชื่อ `ci` หายหรือรอ job ไม่ครบ**
+  handbook สัญญากับทีมไว้ว่า required status check ชื่อ `ci` ใช้ได้กับทุก template —
+  ถ้าผิดสัญญา คนที่ก๊อปไปตั้ง branch protection จะเจอ PR ค้างโดยไม่รู้สาเหตุ
+  (`validate.sh templates` ตรวจข้อนี้ให้)
+- **repo นี้เป็น public** ห้ามมีอีเมลจริง ชื่อ org จริง IP หรือ token
+  ตัวอย่างให้ใช้ `myorg`, `you@company.com`, `example.com` เท่านั้น
+- **ตัวอย่างคำสั่งในเอกสารต้องรันได้จริง** ก่อนเขียนลงไปให้ลองรันก่อน
+  โดยเฉพาะ `gh api` ที่ path เปลี่ยนบ่อย — เอกสารที่คำสั่งพังทำให้คนเลิกเชื่อทั้งเล่ม
+- แก้เอกสารแล้วเช็คลิงก์ด้วย `./scripts/validate.sh docs`
+
+## เขียนเอกสารแบบไหน
+
+ผู้อ่านคือคนในทีมที่กำลังรีบ ไม่ใช่คนที่อยากเรียนทฤษฎี
+
+- บอก**ผลจริงที่จะเกิด** ไม่ใช่บอกว่าควรทำเพราะเป็น best practice
+- ทุกหัวข้อจบด้วยคำสั่งที่ก๊อปไปวางได้ หรือ checklist ที่ติ๊กได้
+- ตารางชนะย่อหน้า เมื่อเนื้อหาเป็นการเทียบหรือแจกแจง
+- ภาษาไทย ยกเว้นศัพท์เทคนิคที่แปลแล้วงงกว่าเดิม (PR, branch, commit, merge)
+
+## ข้อตกลงการทำงาน
+
+- งานที่แตะเกิน 2 ไฟล์ → plan mode ก่อน
+- ห้าม `git push`, `gh pr merge` — คนกดเอง
+- commit ตาม Conventional Commits (`docs:` `ci:` `fix:` `chore:`)
+- รัน `./scripts/validate.sh` ให้เขียวก่อนเปิด PR เสมอ
+
+## ที่ยังไม่มี
+
+- `CODEOWNERS` — ยังไม่ใส่เพราะ repo มีคนเดียว ใส่ไปก็ไม่มีผล (approve PR ตัวเองไม่ได้)
+  เพิ่มเมื่อมีคนที่สอง พร้อมเปลี่ยน ruleset เป็น `--approvals 1 --checks ci`

docs/04-ci-branch-protection.md

@@ -16,6 +16,41 @@
 ถ้าตั้ง required check ก่อนที่ CI จะเสถียร ทีมจะติดแหง็ก merge อะไรไม่ได้เลย
 แล้วคนจะขอปิด protection ทิ้ง — จบเห่
 
+### ข้อยกเว้น: repo ที่เพิ่งสร้างใหม่
+
+**repo ที่ยังไม่เคยมี workflow อยู่บน default branch เลย จะไม่รัน CI ให้ ถึงไฟล์จะอยู่บน branch ของ PR แล้วก็ตาม**
+
+อาการ: เปิด PR ที่เพิ่ม `.github/workflows/ci.yml` เข้ามา แต่ไม่มี check ขึ้นเลย
+
+```bash
+gh api repos/OWNER/REPO/actions/runs --jq .total_count        # → 0
+gh api repos/OWNER/REPO/actions/workflows --jq '.workflows | length'  # → 0
+gh api repos/OWNER/REPO/actions/permissions --jq .enabled     # → true (Actions ไม่ได้ปิด)
+```
+
+ทั้งสามบรรทัดบอกตรงกันว่า GitHub ยัง**ไม่รู้จัก** workflow นี้ ไม่ใช่ว่ามันรันแล้วพัง
+
+ทางออก — ยอมรับว่ารอบแรกต้อง merge โดยที่ CI ยังไม่เคยเขียว:
+
+```
+1. merge PR ที่เพิ่ม workflow เข้า main (CI ยังไม่รัน — ปกติ)
+2. GitHub register workflow แล้วรันจาก trigger push:main
+3. ตรวจว่า run แรกเขียวจริง และจดชื่อ check ที่ได้
+4. ค่อยตั้ง required check
+```
+
+**อย่าตั้ง required check ก่อนเห็น run แรกสำเร็จ** ไม่งั้น repo จะ merge อะไรไม่ได้เลย
+เพราะ check ที่ไม่เคยมีอยู่จริงจะค้างที่ `Expected — Waiting for status` ตลอดกาล
+
+ตรวจชื่อ check ที่ใช้ได้จริงหลัง run แรกจบ:
+
+```bash
+gh api "repos/OWNER/REPO/commits/$(git rev-parse main)/check-runs" \
+  --jq '.check_runs[] | "\(.name) → \(.conclusion)"'
+```
+
+ชื่อที่เอาไปใส่ `--checks` ต้องตรงกับคอลัมน์ซ้ายเป๊ะ ๆ รวมทั้งตัวพิมพ์เล็กใหญ่
+
 ---
 
 ## 4.2 ปัญหาที่ทุกคนเจอ: ชื่อ check ไม่นิ่ง

docs/99-cheatsheet.md

@@ -98,6 +98,7 @@ reflog กู้ได้เกือบทุกอย่างที่เค
 | `refusing to allow an OAuth App to create or update workflow` | token ไม่มี scope `workflow` | `gh auth refresh -h github.com -s workflow` |
 | push แล้วขึ้น `protected branch hook declined` | กำลัง push ตรงเข้า main | ถูกแล้ว — เปิด branch + PR |
 | PR merge ไม่ได้ ปุ่มเทา ทั้งที่ CI เขียว | มี review thread ที่ยังไม่ resolve / branch ไม่ up-to-date | resolve ให้หมด แล้ว `gh pr update-branch 142` |
+| เปิด PR แล้วไม่มี check ขึ้นเลย (repo เพิ่งสร้าง) | GitHub ยังไม่ register workflow เพราะยังไม่เคยมีบน default branch | merge workflow เข้า main รอบแรกก่อน แล้วค่อยตั้ง required check — ดู [04](04-ci-branch-protection.md) |
 | required check ค้าง "Expected — Waiting for status" | ชื่อ check ใน ruleset ไม่ตรงกับชื่อ job จริง | เทียบชื่อกับ `gh pr checks` แล้วแก้ ruleset — ดู [04](04-ci-branch-protection.md) |
 | CI ผ่านบนเครื่อง แต่แดงบน GitHub | เวอร์ชัน runtime / env var ต่างกัน | pin เวอร์ชันใน workflow ให้ตรงกับ local แล้วดู `gh run view --log-failed` |
 | commit ไม่ขึ้น contribution graph | `user.email` ไม่ตรงกับอีเมลที่ verified บน GitHub | ดู [01](01-setup.md) |