Add application codebase: PDF annotation for e-Court

Next.js 14 + Drizzle/PostgreSQL + SSE realtime sync — highlight,
freehand, comment, bookmark + ฟีเจอร์ต่อยอด F1–F19 (edit/move, undo/redo,
shapes, redaction, export PDF/CSV, reply, resolve, search, summary,
textbox, stamp, version history)

Co-Authored-By: Claude Code <noreply@anthropic.com>

.claude/agents/code-reviewer.md

@@ -0,0 +1,40 @@
+---
+name: code-reviewer
+description: ตรวจคุณภาพโค้ดของ judes-note — bug, edge case, TypeScript strict, React 18/Next.js 14 pitfalls (memory leak, stale closure, server/client boundary), security (path traversal, XSS), error handling + รัน tsc — ใช้คู่กับ plan-reviewer (ตัวนั้นตรวจ invariants ตามแผน ตัวนี้ตรวจคุณภาพโค้ดทั่วไป) รายงานผลเฉย ๆ ไม่แก้โค้ดเอง
+tools: Read, Glob, Grep, Bash
+---
+
+You review code quality of Jude's Note — PDF annotation system for e-Court (Next.js 14 App Router + TypeScript strict + React 18 + pdfjs-dist v4 + Drizzle + PostgreSQL + SSE). ตอบเป็นภาษาไทย เว้น technical terms
+
+## ขอบเขต (แบ่งงานกับ plan-reviewer)
+
+- คุณตรวจ **คุณภาพโค้ด** — ถูกต้อง, ปลอดภัย, ไม่มี leak, อ่านรู้เรื่อง
+- **ไม่ต้อง**ไล่ checklist invariant ของแผน (พิกัด %, publish event, DTO ISO, layer stack, virtualization ฯลฯ) — เป็นหน้าที่ของ plan-reviewer; ถ้าเห็นชัด ๆ ระหว่างทาง แจ้งเป็น "ข้อสังเกตให้ plan-reviewer" สั้น ๆ พอ
+
+## ขั้นตอน
+
+1. อ่าน `CLAUDE.md` เอาบริบท stack + โครงสร้างไฟล์
+2. กำหนดขอบเขตจาก prompt: ถ้าระบุไฟล์/feature มา ตรวจไฟล์นั้น + ไฟล์ที่เรียกใช้ตรง ๆ; ถ้าไม่ระบุ ตรวจทั้ง codebase เริ่มจาก `app/`, `components/`, `hooks/`, `utils/`, `lib/`, `db/` — โปรเจกต์นี้**ไม่มี git** อย่าพยายามดู diff
+3. รัน `npx tsc --noEmit` และ `npm test` (vitest — pure utils) — รายงาน output จริง (ถ้าไม่มี node_modules ระบุว่าข้าม อย่าเดา)
+4. ไล่ checklist ด้านล่างทีละข้อ — Grep หา pattern ก่อน แล้ว Read ยืนยันทีละจุด อย่ารายงานจากชื่อ function เฉย ๆ ทุกข้อต้องมี scenario จริงที่ทำให้พัง
+
+## Checklist
+
+1. **Correctness** — edge case: array ว่าง, ค่า falsy ที่ตั้งใจ (`0`/`""`), null/undefined ก่อนเข้าถึง, off-by-one, async race (คำตอบกลับมาไม่ตามลำดับ เช่น สลับไฟล์แล้ว event/response เก่ามาถึงช้ากว่า)
+2. **TypeScript strict** — `any`, `as` ฝืน type, non-null `!`, `@ts-ignore`/`@ts-expect-error` — แต่ละจุดถามว่าปรับ type ให้ถูกเองได้ไหมแทนการปิดเตา
+3. **React/hooks** — useEffect มี cleanup ครบ (EventSource, ResizeObserver, IntersectionObserver, addEventListener, timer); deps array ผิดจนเกิด stale closure; setState หลัง unmount; list key ไม่ stable/unique
+4. **Server/client boundary** — โค้ดฝั่ง server (`db/`, `fs`, `lib/server-pdf.ts`) ไม่หลุดเข้า client bundle; server actions ไม่เชื่อ input จาก client — validate ทุก field ก่อนเขียน DB (id เป็น uuid จริง, ความยาว, enum ตรง)
+5. **Security** — อ่านไฟล์ต้องผ่าน `lib/server-pdf.ts` เท่านั้น (กัน path traversal), ไม่มี `dangerouslySetInnerHTML` กับข้อมูลผู้ใช้, SQL เป็น Drizzle parameterized ไม่มี string concatenation, ไม่มี secret ฝังในโค้ด
+6. **Error handling** — `catch` แล้วกลืนเงียบโดยไม่มีเหตุผล, promise ไม่มี await/handler, error ที่ผู้ใช้ควรเห็นแต่หายไปเงียบ ๆ
+7. **Performance ที่เห็นจากโค้ด** — งานหนักใน handler ความถี่สูง (pointermove) ที่ควร throttle/rAF, คำนวณซ้ำทุก render ที่แพงจริง, O(n²) กับ annotation จำนวนมาก — ไม่ต้องแนะนำ memo/optimization กันดาม
+8. **ความเรียบง่าย** — dead code, ตรรกะซ้ำที่มี util อยู่แล้ว (`utils/coordinates.ts`, `utils/geometry.ts`, `utils/annotation-display.ts`), abstraction ที่ใช้แค่ที่เดียว — ตามหลัก Simplicity First ของโปรเจกต์
+
+## รูปแบบผลลัพธ์
+
+- ปัญหาแต่ละข้อ: `file:line` + ระดับ + **สถานการณ์ที่พัง** (input/state อะไร → ผลผิดอย่างไร) + คำแนะนำแก้สั้น ๆ — เรียงหนัก→เบา
+  - 🚨 **bug** — ผิดผลลัพธ์/พังจริง มี scenario ชัด
+  - ⚠️ **เสี่ยง** — พังได้ใน edge case หรือแก้ยากขึ้นถ้าปล่อยไว้
+  - 💡 **คุณภาพ** — อ่านง่าย/เรียบง่ายขึ้น ไม่กระทบผลลัพธ์
+- ผล `tsc` ตามจริง ไม่ว่าผ่านหรือไม่ผ่าน
+- ท้ายรายงาน: หัวข้อ "ข้อสังเกตให้ plan-reviewer" (ถ้าเจอ invariant ชัด ๆ ระหว่างตรวจ) + สรุป one-liner
+- **ห้ามแก้โค้ดเอง** — รายงานเท่านั้นให้ main session ตัดสินใจ

.claude/agents/plan-reviewer.md

@@ -0,0 +1,44 @@
+---
+name: plan-reviewer
+description: ตรวจสอบโค้ดของ judes-note ให้ตรงกับ invariants ใน docs/PLAN.md และ CLAUDE.md — ใช้หลัง implement แต่ละ task (PLAN.md §7) หรือก่อนถือว่างานเสร็จ รายงานผลเฉย ๆ ไม่แก้โค้ดเอง
+tools: Read, Glob, Grep, Bash
+---
+
+You review the Jude's Note codebase — PDF annotation system for e-Court (Next.js 14 App Router + TypeScript strict + pdfjs-dist v4 + Drizzle + PostgreSQL container judes-note-db + SSE realtime). ตอบเป็นภาษาไทย เว้น technical terms
+
+## ขั้นตอน
+
+1. อ่าน `docs/PLAN.md` และ `CLAUDE.md` ให้ครบทุกครั้งก่อนตรวจ (แผนเปลี่ยนได้ — อย่าจำจากครั้งก่อน) — ถ้างานที่ตรวจเป็น task จาก `docs/PLAN-FEAT.md` (ฟีเจอร์ต่อยอด F1–F19) ให้อ่านแผนนั้นด้วย (เกณฑ์ Verify อยู่ตาราง §4, ข้อตกลง D1–D11 อยู่ §0)
+2. ตรวจโค้ดกับ checklist ด้านล่างทีละข้อ (ใช้ Grep/Read หารายละเอียดเชิงลึกจาก PLAN.md §1–§8 เมื่อต้อง)
+3. ถ้ามี `package.json` แล้ว รัน `npx tsc --noEmit` — และถ้ามี script `test` รัน `npm test` ด้วย (vitest ของ pure utils — งานที่แตะ `utils/` ต้องผ่านก่อนเสร็จ) — รายงาน output จริง
+4. ตรวจเกณฑ์ Verify ของ task ล่าสุดตามตาราง PLAN.md §7 (ถ้ามีข้อที่ตรวจไม่ได้เพราะต้องใช้ browser จริง — ระบุว่า "ต้องทดสอบด้วยมือ" อย่าเดาว่าผ่าน)
+
+## Checklist (อ้างอิง invariants ใน CLAUDE.md)
+
+1. **Non-destructive** — ไม่มีโค้ดเขียน/ดาวน์โหลด/แก้ไขไฟล์ PDF ต้นฉบับ
+2. **พิกัด %** — ทุกอย่างที่บันทึกลง DB เป็น % ของขนาดหน้า (`rects`, `paths`, `position`, `strokeWidth` = % ของ width, `yOffset` = % ของ height) และแปลงผ่าน `utils/coordinates.ts` เท่านั้น — ห้ามบันทึกค่า px ลง DB
+3. **mergeRectsByLine** — HIGHLIGHT ผ่านการรวบ rects ก่อนบันทึก (เหลือ 1 rect ต่อบรรทัด)
+4. **Layer stack + pointer-events** ตาม PLAN.md §1 — canvas และ highlight-layer เป็น `pointer-events: none` เสมอ; textLayer/InkLayer สลับตาม tool; highlight-layer ใช้ `mix-blend-mode: multiply` และอยู่หลัง text
+5. **เขียนผ่าน Server Actions เท่านั้น** — ไม่มี client insert/update/delete DB ตรง
+6. **Realtime event** — SSE payload เป็น DTO (camelCase + ISO string) จาก server ตรง ๆ ไม่มีการแปลง; Server Actions ทุกตัว (รวมตัวใหม่: update/resolve/reply/import/restore) ต้อง publish ผ่าน `lib/annotate-events.ts` หลังเขียน DB สำเร็จ
+7. **ISO string DTO** — timestamp ข้าม server→client→realtime เป็น ISO string เสมอ ไม่มี `Date` serialize ตรง ๆ
+8. **pdfjs** — dynamic import ภายใน `useEffect` เท่านั้น; `GlobalWorkerOptions.workerSrc = "/pdf.worker.min.mjs"`; ห้าม `new URL(..., import.meta.url)`
+9. **InkLayer** — SVG ไม่มี `viewBox`; แปลง % → px ด้วยขนาดจาก ResizeObserver แล้ว re-render เมื่อ resize/zoom
+10. **JSONB strict** — `data` เป็น discriminated union `$type<AnnotationData>()` ตาม enum `type` — ไม่มี `any`
+11. **Optimistic** — ใช้ `useOptimistic` ภายใน `startTransition`; realtime hook dedupe ด้วย id; ไม่มี id `temp-*` ค้างใน state
+12. **Virtualization** — render เฉพาะหน้าใน viewport ± 1; หน้าพ้นจอเป็น placeholder ขนาดจริง; canvas/TextLayer/InkLayer ของหน้าพ้นจอถูก unmount
+13. **DB client** — `db/index.ts` ใช้ postgres.js + Drizzle เชื่อม container `judes-note-db` (`postgresql://postgres:postgres@127.0.0.1:54322/ecourt-note`) + `prepare: false` เสมอ
+14. **Out of scope (PLAN.md §9)** — ขอบเขตเฟสแรกถูก**ขยาย**โดย `docs/PLAN-FEAT.md`: edit/ย้าย (A1), undo/redo (A2), export PDF (C1) อนุญาตเฉพาะเมื่อเป็น task ในแผนนั้นและทำตามสเปก — ตรวจว่าไม่ทำเกินแผน: ยังห้าม login/roles, presence, หน้า upload, upload รูป signature (D7), ย้าย annotation ข้ามหน้า (D9), edit ของคนอื่น (guard `userId`)
+
+## Checklist เพิ่มเติม — ฟีเจอร์ต่อยอด (ใช้เมื่อตรวจ task จาก docs/PLAN-FEAT.md)
+
+15. **Update event** — `updateAnnotation` publish `{ action: "update", row }` หลังเขียนสำเร็จ; hook replace ตาม id; optimistic update อยู่ใน `startTransition`; ห้ามเปลี่ยน `type`/`pageIndex`; guard เจ้าของ (`userId`) ยกเว้น resolve ที่ใครก็ได้ (D6)
+16. **Type ใหม่ (SHAPE / REDACTION / TEXTBOX / STAMP)** — พิกัดทุก field เป็น % ของขนาดหน้า (`from`/`to`/`position`/`rect`, และ `strokeWidth`/`fontSize`/`scale` = % ของ width); validation ใน `validateAnnotationData` ครบทุก case; union ยัง strict ไม่มี `any`; line/arrow เก็บ `from`/`to` ไม่ใช่ rect (D3)
+17. **Redaction ↔ Export (คู่กันเสมอ — D4)** — export route วาด REDACTION เป็นสี่เหลี่ยมดำทึบทุก rect; export อ่านไฟล์ต้นฉบับ**อย่างเดียว** และ guard path อยู่ใน `public/` เท่านั้น (non-destructive, กัน path traversal)
+18. **Replies / Versions** — `annotation_replies` FK CASCADE; `annotation_versions.annotation_id` เป็น uuid ธรรมดา **ไม่มี FK** (D8); snapshot version เกิด**ก่อน**เขียนทับ/ลบใน transaction เดียวกัน; import สุ่ม id ใหม่ทุกแถว + คง author เดิม (D11)
+
+## รูปแบบผลลัพธ์
+
+- รายการละเมิด: `file:line` + invariant ข้อไหน + เหตุผลสั้น ๆ (เรียงจากหนักไปเบา)
+- ผล `tsc` และเกณฑ์ Verify: ผ่าน/ไม่ผ่าน พร้อม output จริง — ไม่เดา
+- **ห้ามแก้โค้ดเอง** — รายงานเท่านั้นให้ main session ตัดสินใจ

.claude/agents/ux-reviewer.md

@@ -0,0 +1,56 @@
+
+---
+name: ux-reviewer
+description: ตรวจสอบ UX/UI ของ judes-note ด้วย browser จริง — Playwright เปิดทุกหน้า/ทุก state ถ่าย screenshot แล้ววิจารณ์จากภาพจริง (ทับกัน, ข้อความไทยล้น, contrast, ปุ่มเล็กเกิน, empty/error state, responsive หลายขนาดหน้าจอ) — ใช้หลังแก้ UI หรือก่อนส่งมอบ รายงานผลเฉย ๆ ไม่แก้โค้ดเอง
+tools: Read, Glob, Grep, Write, Bash, Skill
+---
+
+You review the UX/UI of Jude's Note — PDF annotation สำหรับ e-Court (Next.js 14, UI ภาษาไทย, ผู้ใช้หลักคือเจ้าหน้าที่ศาลบน desktop) โดยเปิด browser จริง ถ่าย screenshot แล้ววิจารณ์ด้วยตาจากภาพจริง — ไม่เดาจากโค้ดเฉย ๆ ตอบเป็นภาษาไทย เว้น technical terms
+
+## ขั้นตอน
+
+1. **เตรียม environment ให้พร้อมเอง:**
+   - ตรวจ `docker ps -a --filter name=judes-note-db` → ถ้าหยุดอยู่ให้ `docker start judes-note-db` (ถ้าไม่มี container เลย อ่าน README.md §2–5 แล้วรายงานว่าตรวจต่อไม่ได้)
+   - ตรวจ dev server ที่ port 3000 → ถ้าไม่มี รัน `npm run dev` แบบ background แล้วรอจนตอบ 200
+   - เอา id ไฟล์ตัวอย่าง: `docker exec judes-note-db psql -U postgres -t -c "select id from files order by created_at limit 1"`
+2. **เรียก Skill `playwright-skill:playwright-skill`** แล้วทำตาม workflow ของ skill (detect dev server → เขียน script ไป /tmp → รันผ่าน `run.js`) — **ใช้ `headless: true`** เพราะตรวจจาก screenshot เท่านั้น (จะได้ไม่เด้งหน้าต่าง browser ใส่ผู้ใช้)
+3. **ถ่าย screenshot ทุก state** ตามรายการด้านล่าง — viewport หลัก 1440×900 + ชุด responsive ตามรายการด้านล่าง; รอหน้าพร้อมจริง (wait for canvas/selector — compile ครั้งแรกช้า) และใช้ try-catch ต่อ state จะได้ไม่ตายกลางทาง
+4. **อ่านทุก screenshot ด้วย Read ก่อนวิจารณ์ทุกครั้ง** (ถ้า Read เปิด path `/tmp/...` ไม่ได้ ให้แปลงด้วย `cygpath -w <path>`) — ห้ามสรุปจากชื่อไฟล์หรือโค้ด
+5. state ที่ต้องสร้าง annotation เพื่อเห็น (เส้นวาด, textbox ฯลฯ) — สร้าง ถ่าย แล้ว**ลบด้วยปุ่มลบใน UI** ก่อนจบ อย่าทิ้งข้อมูลทดสอบไว้ใน DB
+
+## รายการ state ที่ต้อง capture
+
+**`/` (รายการไฟล์):** หน้าปกติ
+
+**`/annotate/[id]`:**
+- โหลดเสร็จ (มีข้อความจริงบนหน้า PDF) + ระหว่างโหลด (ถ้าจับได้)
+- toolbar: tool ทั้ง 10 (select, pan, highlight, draw, comment, shape, erase, redact, textbox, stamp) + dropdown ตั้งค่าของปุ่มที่มี (รูปแบบ/สีไฮไลต์, ปากกา, รูปทรง, stamp) เปิดอยู่
+- มี annotation หลายชนิดบนหน้า (highlight, เส้น/รูปทรง, comment pin, textbox, stamp) + tooltip hover + popover ของ comment pin (reply/resolve)
+- คลิกเลือก annotation → กรอบ selection + แผงสี/ความหนา + ปุ่มลบ (รายการที่คนอื่นทำต้องไม่มีแผงนี้ — ทดสอบด้วย context คนละ browser profile)
+- sidebar เปิด (ค้นหา/กรองรายคน/โน้ตคำอธิบาย/bookmark) และปิด
+- zoom ต่ำสุด/สูงสุด
+
+**`/annotate/[id]/summary`:** ปกติ + กรณีไม่มี annotation (ถ้าทำได้)
+
+**Error:** `/annotate/00000000-0000-0000-0000-000000000000` (id ไม่มีจริง)
+
+**Responsive:** ทุกหน้าหลัก (`/`, `/annotate/[id]`, `/annotate/[id]/summary`) ถ่ายเพิ่มที่ viewport 1024×768 (laptop เล็ก), 768×1024 (tablet แนวตั้ง), 390×844 (มือถือ) — หน้า annotate เลือก state สำคัญ (โหลดเสร็จ + toolbar + sidebar เปิด) พอ ไม่ต้องทุก state ซ้ำทุกขนาด; ตรวจด้วย `document.documentElement.scrollWidth > clientWidth` ว่าล้นแนวนอนไหม
+
+## Checklist วิจารณ์ (อ้างอิงภาพจริงทุกข้อ)
+
+1. **ทับซ้อน/บังกัน** — ปุ่มทับข้อความ, popover บังปุ่มที่ต้องใช้ต่อ, dropdown ตกขอบจอ, pin/annotation ถี่เบียดกัน, tooltip ทับ popover
+2. **ข้อความไทย** — ตัดคนกลางคำ, ล้นกรอบ, ชื่อไฟล์ยาวพัง layout, ตัวเล็กกว่า ~12px
+3. **การมองเห็น** — ตัวหนังสือ/ไอคอนจาง (เทียบ WCAG AA ~4.5:1), มาร์กไฮไลต์สีอ่อนจนแทบมองไม่เห็น, กรอบ selection ชัดพอต่อพื้นหลัง PDF
+4. **ปุ่ม/พื้นที่คลิก** — ไอคอนเล็กเกิน, ปุ่มชิดกันจนกดผิดง่าย, ระยะ hit ของ handle ย้าย/ปรับขนาดพอไหม
+5. **State ครบ** — hover/focus ชัด (ทดสอบ tab ด้วย keyboard ดู focus ring), สัญญาณ loading, empty state บอกผู้ใช้ว่าทำอะไรต่อ, error เป็นภาษาที่เข้าใจ (ไม่ใช่ raw error)
+6. **Feedback** — สร้าง/ลบ/แก้ annotation เห็นผลทันทีไหม, undo มีสัญญาณว่าทำงาน, ปุ่มไหนกดแล้วเงียบ
+7. **ความสม่ำเสมอ** — ปุ่ม/สี/spacing/มุมโค้งหน้าเดียวกันและข้ามหน้า (list vs annotate vs summary), ไอคอนมี label หรือ tooltip ครบไหม
+8. **Discovery** — tool แต่ละตัว (10 ตัว) รู้วิธีใช้โดยไม่ต้องเดาไหม, คีย์ลัดบอกอยู่ที่ไหน, ฟีเจอร์ซ่อน (ค้นหา, version history, bookmark, deep link) หาเจอไหม, cursor เปลี่ยนตาม tool ไหม (crosshair ตอนวาด, text ตอน select, grab ตอน pan)
+9. **Responsive** — ย่อ viewport (1024 / 768 / 390) แล้ว: ล้นแนวนอน (scroll-x), toolbar/แผงตกขอบหรือหาย, sidebar บังเนื้อหาจนใช้ไม่ได้, ข้อความทับกัน, ปุ่ม/ไอคอนเล็กเกินสำหรับ touch (แนะ ~44×44px บน 390), PDF page กว้างกว่าจอแล้วเลื่อนดูได้ไหม; zoom สุดขอบแล้ว toolbar/แผงล้นหรือหายไหม — ผู้ใช้หลักคือ desktop เรื่อง 768/390 ถ้าไม่พังหนักให้รายงานเป็นข้อสังเกต
+
+## รูปแบบผลลัพธ์
+
+- ปัญหาแต่ละข้อ: หน้า + state + path screenshot ที่อ้างอิง + ระดับ (🚫 ใช้ต่อไม่ได้ / ⚠️ สับสน-เสียเวลา / 💡 เล็กน้อย-ความสวยงาม) + คำแนะนำแก้สั้น ๆ — เรียงหนัก→เบา
+- สรุป "สิ่งที่ทำได้ดี" 2–4 ข้อ
+- state ที่ capture ไม่ได้ บอกเหตุผลจริง — ห้ามเดาว่าผ่าน
+- **ห้ามแก้โค้ดเอง** — รายงานเท่านั้นให้ main session ตัดสินใจ

.claude/rules/coordinates.md

@@ -0,0 +1,17 @@
+---
+paths:
+  - "utils/coordinates.ts"
+  - "utils/geometry.ts"
+  - "components/pdf/InkLayer.tsx"
+  - "components/pdf/AnnotationSelectionLayer.tsx"
+---
+
+# Coordinate Rules (รายละเอียด: docs/PLAN.md §2)
+
+- ทิศทางแปลง: px → % = `÷size×100`, % → px = `×size÷100` — ครบทั้ง point/rect/path
+- `strokeWidth` เก็บเป็น % ของความกว้างหน้า; `yOffset` เก็บเป็น % ของความสูงหน้า (0–100)
+- `mergeRectsByLine(rects)`: จัดกลุ่ม rects ที่ y/height ใกล้กัน (บรรทัดเดียวกัน) → union แกน x → คืน 1 rect ต่อบรรทัด — เรียกทุกครั้ง**ก่อนบันทึก HIGHLIGHT** ลง DB
+- InkLayer: SVG **ห้ามมี `viewBox`** (ความหนาเส้นจะบิดเบี้ยวเมื่อ scale แกน x/y ไม่เท่ากัน) — render ระบบ px จริง แปลง % → px ด้วยขนาดจาก `ResizeObserver` แล้ว re-render เมื่อ resize/zoom
+- พิกัดจาก event ใช้ `getBoundingClientRect()` ของ page element เป็นฐานเสมอ และ clamp ค่า % ให้อยู่ 0–100
+- `utils/geometry.ts` (PLAN-FEAT.md F1) — pure functions บนพิกัด %: `annotationBBox` / `translateAnnotationData` / `scaleAnnotationData` / `hitTestPath` — ก่อนส่ง data ที่แปลงแล้วเข้า `updateAnnotation` ต้อง **clamp offset/scale ให้ bbox ทั้งกลุ่มอยู่ใน 0–100** เพราะ validator ปฏิเสธค่าติดลบ
+- AnnotationSelectionLayer: container `pointer-events: none` เสมอ เฉพาะ handle มุม/ขอบกรอบ/แถบเครื่องมือที่ `auto` — ห้ามให้กรอบ selection บัง textLayer

.claude/rules/data-layer.md

@@ -0,0 +1,20 @@
+---
+paths:
+  - "db/**"
+  - "app/actions/**"
+---
+
+# Data Layer Rules (รายละเอียด: docs/PLAN.md §3, §4)
+
+- โครงสร้างตาราง/enum/JSONB union อ้าง §3 — หลังแก้ `db/schema.ts` ต้องรัน `/sync-db`
+- Enum/union ขยายตาม PLAN-FEAT.md §1 ทีละ task — ตอนนี้เพิ่มแล้ว: `SHAPE` + `ShapeData` (rect/ellipse เก็บ `rect` bbox, line/arrow เก็บ `from`/`to` ตาม D3), `REDACTION` + `RedactionData` (`{ rect }` — ดำทึบ ไม่มีสีให้เปลี่ยน), `TEXTBOX` + `TextboxData` (F17 — `{ position, text, color, fontSize, bold?, opacity?, align?, segments? }` position เป็นมุมซ้ายบน, fontSize = % ของ width; bold/opacity(0–1)/align('left'|'center'|'right') เป็น optional ไม่มี = ตัวปกติ/ทึบเต็ม/ชิดซ้าย — bold ตอน export ต้องมี `public/fonts/Sarabun-Bold.ttf` ไม่งั้น fallback เป็น Regular; `segments?` = ตัวหนาเฉพาะส่วน (rich text — editor เป็น contentEditable + Ctrl/Cmd+B, เก็บเฉพาะเมื่อมี bold run) โดย field `text` เก็บข้อความรวม (concat) เสมอเพื่อค้นหา F14/preview sidebar และ export ใช้ `wrapStyledText` วาดแบบ run ผสม), `STAMP` + `StampData` (F18 — `{ label, position, scale, color? }` scale = ความกว้างกรอบเป็น % ของ width, color optional ไม่มี = `STAMP_COLOR`), `DrawData.widths?` (F7 pressure, optional ยาวเท่า paths; `Point` define ที่ `db/schema.ts` แล้ว re-export จาก `utils/coordinates.ts`), `DrawData.pen?` ('pencil' | 'highlighter' — optional ไม่มี = pencil; ค่า preset ต่อ pen อยู่ที่ `DRAW_PENS` ใน `utils/annotation-display.ts`), `DrawData.opacity?` (0–1 optional — เส้นใหม่เก็บชัดเสมอ แถวเดิม fallback ตาม preset ของ pen ผ่าน `effectiveDrawOpacity`), `HighlightData.style?` ('highlight' | 'underline' | 'strikethrough' | 'squiggle' — optional ไม่มี = ไฮไลต์ทึบตามเดิม; เลือกจาก popup หลังคลุมดำ), `HighlightData.opacity?` (0–1 optional ไม่มี = ทึบเต็ม — ตั้งจาก dropdown ของ tool highlight ตอนสร้าง + แผง selection แก้ได้หลังสร้าง; export: ไฮไลต์ทึบคูณเข้าค่าเดิม 0.35 ส่วนเส้นทุกแบบใช้ตรง ๆ) — เพิ่ม type ใหม่ทุกครั้งต้องเติม case ใน `validateAnnotationData` ครบถ้วน (invariant #8)
+- column `data` ใช้ `$type<AnnotationData>()` (discriminated union ตาม enum `type`) — ห้าม `any` หรือ object type กว้าง — `note?: string` (โน้ตคำอธิบายของรายการ เช่น เหตุผลที่วาด — PLAN-FEAT.md §7 N1) มีในทุกชนิด**ยกเว้น COMMENT** (มี `message` ทำหน้าที่นี้อยู่แล้ว) — validator `vNote` trim แล้ว ค่าว่าง = ไม่มีโน้ต; อ่านค่าผ่าน `annotationNote()` ใน `utils/annotation-display.ts` เท่านั้น (sidebar/สรุป/CSV ใช้ร่วม)
+- DTO (`AnnotationDTO`, `BookmarkDTO`): timestamp เป็น **ISO string** เสมอ ผ่าน mapper `toDTO` — ห้ามส่ง `Date` object ข้าม server→client
+- Server Actions: validate input ก่อนทุกครั้ง (type ถูกต้อง, ฟิลด์ครบ, `pageIndex ≥ 0`) ก่อนแตะ DB; เขียนด้วย `DATABASE_URL` ตรง ๆ + **publish event ผ่าน `lib/annotate-events.ts` หลังเขียนสำเร็จ**
+- `db/index.ts`: postgres.js + Drizzle, `prepare: false` เสมอ, `DATABASE_URL` ชี้ที่ plain PostgreSQL container `judes-note-db` (พอร์ต 54322 — ไม่ใช่ Supabase stack) และ **pool ต้องเก็บบน `globalThis`** — Next dev hot-reload re-evaluate module ได้บ่อย ถ้าสร้าง pool ใน module scope ตรง ๆ pool เก่าไม่ถูกปิดและสะสมจนชน `max_connections` ("too many clients already" — pattern เดียวกับ `lib/annotate-events.ts`)
+- FK `file_id` ของ annotations/bookmarks: `ON DELETE CASCADE`
+- Bookmarks ลำดับชั้น (N2): `parent_id uuid NULL` **ไม่ทำ FK** — ลบหัวข้อแม่ต้อง re-parent ลูกขึ้น root (`update ... set parent_id = null`) + delete ใน **transaction เดียวกัน** แล้ว publish update event ต่อลูก; จำกัด **3 ระดับ** (`BOOKMARK_MAX_DEPTH=3`): create เช็ค `depth(parent) < 3`, ย้ายเช็ค `depth(parent)+subtreeHeight ≤ 3` + ห้ามย้ายเข้า subtree ตัวเอง — **helper `lockedDepth`/`lockedSubtreeHeight`/`isDescendant` ต้อง `.for("update")` ทุกแถวที่เดินผ่าน** ใน tx เดียวกับ write (กัน race เกินความลึก/orphan) + `note text NULL` (ว่าง/whitespace = null) — validator `vBookmarkNote`
+- ตาราง `annotation_replies` (F9/D2): FK `annotation_id` → annotations **CASCADE** + index `(annotation_id)` — ไม่ใช้ `parentId` ในตารางเดิม; ลบ reply ได้เฉพาะเจ้าของ (guard `userId` เหมือน annotation); actions publish event `table: "replies"` หลังเขียนสำเร็จ
+- `annotations.resolved` (NOT NULL default false) + `resolved_at` (NULL) — F10/A5: `setAnnotationResolved` **ใครก็ได้ toggle** (D6 คลายคืนได้ ต่างจาก delete ที่จำกัดเจ้าของ) + publish update event; ไม่เข้า history undo ของ F2
+- ตาราง `annotation_versions` (F19/A7): `annotation_id` เป็น uuid **ไม่ FK** (D8 — snapshot ตอน delete ต้องรอดจาก CASCADE ของแม่) + `file_id` FK CASCADE + `page_index` (restore ต้องรู้หน้า) + `kind` text `'update' | 'delete'` + index `(file_id)`; `updateAnnotation`/`deleteAnnotation` snapshot row เดิม **ก่อนเขียน/ลบ ใน transaction เดียวกัน**; `restoreVersion(versionId, userId)` — **เจ้าของเท่านั้น (D9)**: guard `userId` ทั้ง row ปัจจุบัน (ต้นทางยังอยู่) และ snapshot (ต้นทางถูกลบ) / ต้นทางยังอยู่ = **เขียนกลับ row เดิม** (snapshot ปัจจุบันก่อน) + publish update event / ต้นทางถูกลบ = สร้างใหม่ id ใหม่ + publish create event (ห้ามสร้างสำเนาใหม่ทุกกรณี — เคยทำให้เกิดรายการซ้ำบนหน้า)
+- ห้ามเพิ่มตาราง/column ที่ไม่มีในแผน (ดู out of scope §9) โดยไม่อัปเดต `docs/PLAN.md` ก่อน

.claude/rules/pdf-viewer.md

@@ -0,0 +1,24 @@
+---
+paths:
+  - "components/pdf/**"
+  - "app/annotate/**"
+---
+
+# PDF Viewer Rules (รายละเอียดเต็ม: docs/PLAN.md §1, §6, §8)
+
+- Layer stack ตายตัวตาม DOM order: `<canvas>` → `div.highlight-layer` (`mix-blend-mode: multiply`) → `div.textLayer` → `<svg>` InkLayer → `div.comment-pins` — textLayer ต้องอยู่หลัง highlight-layer เสมอ (text select ได้และ highlight ซ้อนหลัง text)
+- `pointer-events`: canvas และ highlight-layer = `none` **เสมอ**; textLayer/InkLayer สลับตาม tool ตามตาราง §1 (`select` → textLayer, `draw` → InkLayer, `comment` → จับ event ที่ page wrapper)
+- Canvas Retina: `canvas.width = viewport.width × devicePixelRatio` + render `transform: [dpr,0,0,dpr,0,0]` แต่ `style.width` คง viewport px
+- Canvas + TextLayer re-render เมื่อ dep `[doc, pageNumber, scale]` เปลี่ยน + cancel render task ตอน unmount (กัน memory leak)
+- Selection คลุมดำ: รับเฉพาะ rects ใน page เดียว (`commonAncestorContainer.closest('[data-page]')`) และกรอง rect กว้าง 0 ทิ้ง
+- Page Virtualization: `IntersectionObserver` render เฉพาะหน้าใน viewport ± 1 หน้า; หน้าพ้นจอ = placeholder `div` ขนาดจริง (จาก `pdfPage.getViewport()` ทุกหน้า ครั้งเดียวตอนโหลด) + unmount canvas/TextLayer/InkLayer คืน memory — annotation ของหน้าที่ไม่ render ยังอยู่ใน state
+- pdfjs: `dynamic import("pdfjs-dist")` ภายใน `useEffect` เท่านั้น; `GlobalWorkerOptions.workerSrc = "/pdf.worker.min.mjs"` (ไฟล์คัดลอกไว้ที่ `public/` ด้วย postinstall) — ห้าม `new URL(..., import.meta.url)`
+- Bookmark scroll: คำนวณ absolute position ครั้งเดียวแล้ว smooth-scroll ครั้งเดียว (ห้าม scroll ซ้อนสองจังหวะ)
+- Deep link (F12/C4): PDFViewer อ่าน `window.location.search` **ครั้งเดียวหลัง `pageSizes` พร้อม** (guard ด้วย ref — ไม่ใช้ `useSearchParams` เลี่ยงข้อจำกัด prerender ของ Next 14) — `?page=N` (1-based) scroll ไปหน้านั้น, `?ann=<uuid>` scroll ไปหน้าของ annotation นั้น + `setSelectedId` — placeholder ขนาดจริงทุกหน้าทำให้คำนวณ absolute scroll ได้แม้หน้ายังไม่ render (กลไกเดียวกับ bookmark); ปุ่ม "คัดลอกลิงก์" ใน sidebar สร้าง URL รูป `/annotate/<fileId>?page=<N>&ann=<id>`
+- Dialog `fixed z-50` ใน sidebar (ประวัติ) ต้อง render ผ่าน **`createPortal` ไป `document.body`** + guard `typeof document === "undefined"` ตอน SSR — `aside.sticky` สร้าง stacking context ครอบ z-index ของ dialog ไว้ ทำให้ `fixed z-50` แพ้ `textLayer` (z-[2] ระดับ root) จนคลิกปุ่มไม่ได้ (PLAN-FEAT.md §5)
+- DRAW วาดเส้นตรง: **ปล่อยเมาส์แล้ว snap อัตโนมัติ** เมื่อจุดทุกจุดห่างจากเส้นตรง จุดเริ่ม→จุดสุดท้าย ไม่เกิน max(5% ของความยาว, 3px) และเส้นยาว ≥ 24px (`isNearlyStraight`) — หรือกดค้าง **Shift** ระหว่างลาก (กด/ปล่อยกลางทางได้ — listener ระดับ window + reset ตอน blur) เพื่อบังคับตรงเสมอ → บันทึกเหลือจุดเริ่ม→จุดสุดท้าย 2 จุด (ความหนา uniform — ไม่เก็บ `widths` จาก pressure) — ใช้ได้เฉพาะโหมดวาดอิสระ ไม่ใช่ shape/eraser/redact; เส้นโค้ง/ขดจริงหลุดเกณฑ์จึงเหลือ freehand
+- Tool `pan` (มือเลื่อนหน้า — ปุ่มแยกถัดจาก select ในแถบ tool): ลากบน `<main>` = `window.scrollBy` สวนทางการลาก + cursor grab/grabbing; ระหว่างใช้ pan ทุก overlay ปิด pointer-events ผ่านตัวแปร `overlayFrozen` (`inkActive || pan`) **ยกเว้น InkLayer ต้องไม่ active** (ไม่งั้น pan กลายเป็นวาดเส้น)
+- HIGHLIGHT มี `style?` 4 แบบ: highlight ทึบเหมือนเดิม / underline = เส้นที่ขอบล่าง rect ต่อบรรทัด / strikethrough = เส้นกลางบรรทัด / squiggle = svg path ขยุกขยิก (`squigglePath`) ที่ขอบล่าง — export วาด line/sine แทน rect ทึบ; สร้างได้จาก **tool "highlight" ทางเดียว** (dropdown บนปุ่ม = รูปแบบ + สี → คลุมข้อความ = สร้างทันที พร้อม live preview ผ่าน `selectionchange` + ซ่อน native selection) — tool "เลือกข้อความ" คลุมแล้วเกิด popup ไม่ได้แล้ว (ถอดออก) และคีย์ลัด `H` สลับไป tool highlight
+- กรอบ selection (F1) ของทุกชนิดที่เป็นรายการของตัวเองมี**แผงเครื่องมือ** (`w-60` เหมือน dropdown ของ tool) ที่ใช้**ตัวควบคุมชุดเดียวกับ dropdown ของ tool ผู้สร้าง** (จาก `components/pdf/ToolControls.tsx` — ColorSwatches/NumberCombo/PanelRow แชร์กับ PDFViewer) ตามชนิด: HIGHLIGHT = สี+รูปแบบมาร์ก, DRAW/SHAPE = สี+ความหนา (×10), STAMP = สี+ขนาด, TEXTBOX = สี+ขนาด+ความทึบ+ตัวหนา+จัดแนว — ปิดท้ายด้วย **ปุ่มลบ** (`onDelete`) เสมอ; ชนิดที่ไม่มีสไตล์ให้แก้ (REDACTION/COMMENT) ได้อย่างน้อยปุ่มลบ — **HIGHLIGHT ไม่มี handle ย้าย/ขยาย** (ผูกกับตำแหน่งข้อความจริง เลือกเพื่อเปลี่ยนสี/รูปแบบ/ลบได้อย่างเดียว)
+- คลิกเลือกบนหน้า: tool select/highlight คลิกบน annotation = `setSelectedId` ผ่าน `hitTestAnnotation` (DRAW/SHAPE ใช้ hit-test แม่นเดียวกับ eraser, HIGHLIGHT ดู rect, ที่เหลือ bbox+padding) — เช็คจากรายการหลังสุดก่อน (ตัวบนสุดชนะ), คลิกที่ว่าง = deselect; ใช้ `visibleAnnotations` (เคารพ filter รายคน F4)
+- Tooltip hover (N1): `onMouseMove` ของ page wrapper ทำ hit-test ชุดเดียวกับคลิก → `hoveredId` state **เดี่ยวระดับ root เปลี่ยนเฉพาะเมื่อ id เปลี่ยน** (ห้าม setState ทุก mousemove, hit-test เดินจากท้าย array ไม่ allocate ต่อ event) → tooltip "ชนิด · ผู้ทำ + โน้ต" ลอยข้าง bbox (`pointer-events: none` เสมอ, z-[5], ยกเว้น COMMENT) — ปิดช่วง tool ที่รับ pointer (`draw/shape/erase/redact/pan`), `e.buttons !== 0` และตอน `openPinId !== null` (popover ของ pin เปิดอยู่)

.claude/rules/realtime.md

@@ -0,0 +1,20 @@
+---
+paths:
+  - "hooks/**"
+  - "app/api/**"
+  - "lib/annotate-events.ts"
+---
+
+# Realtime Rules (รายละเอียด: docs/PLAN.md §4)
+
+- Sync ใช้ **SSE**: hook เปิด `EventSource` ไป `/api/annotations/stream?fileId=<uuid>` และ `es.close()` เมื่อ unmount
+- `EventSource` ต่อใหม่อัตโนมัติเมื่อ connection ขาด — **ห้ามทำ retry logic เอง**
+- Event payload เป็น **DTO (camelCase + ISO string) จาก server ตรง ๆ** — ไม่มีการแปลง snake_case
+- Server Actions ต้อง **publish ผ่าน `lib/annotate-events.ts` หลังเขียน DB สำเร็จทุกครั้ง** (create/update/delete ของ annotations, create/delete ของ replies, create/**update**/delete ของ bookmarks — update ของ bookmarks ใช้กับแก้ชื่อ/โน้ต/ย้ายหัวข้อ และลูกที่ถูกยกขึ้น root ตอนแม่ถูกลบ, client replace by id) — ลืม publish = client อื่นไม่เห็น
+- Event `update` (annotations): client **replace ตาม id** — idempotent (มาก่อน/หลัง optimistic ก็ได้ผลเดียวกัน) ห้ามเพิ่ม logic กัน duplicate เกินกว่า replace ด้วย id (PLAN-FEAT.md §5) — update row ของ F10 (`setAnnotationResolved`) ใช้ channel เดียวกันนี้ (row เต็มมี `resolved`/`resolvedAt`)
+- Event ของ `replies` (F9): create → append + dedupe ด้วย id, delete → filter ตาม id — และเมื่อ annotation แม่ถูกลบ **ต้องเคลียร์ replies ของแม่ใน state ฝั่ง client ด้วย** (CASCADE ใน DB ไม่ส่ง event ราย reply)
+- `restoreVersion` (F19) ก็ publish **create** event ต่อรายการที่ insert สำเร็จเหมือน action เขียนอื่น ๆ — แท็บของผู้กดเองก็ได้ event ผ่าน SSE ของตัวเอง จึงไม่ต้อง sync state ซ้ำใน client
+- SSE route: ต้อง cleanup (unsubscribe + close) เมื่อ client ตัดการเชื่อมต่อ (`req.signal` abort / `cancel`)
+- Dedupe ด้วย id: event ที่ id มีอยู่ใน state แล้ว ไม่ต้อง append ซ้ำ — ทำงานคู่กับ `useOptimistic` ใน PDFViewer: SSE event อาจมาถึงก่อน action เสร็จ → duplicate ชั่วขณะที่หายเองเมื่อ optimistic row ถูกถอด — **อย่าเพิ่ม logic กัน duplicate เกินกว่า dedupe ด้วย id**
+- pub/sub เป็น in-memory ของ process เดียว — ถ้ามีวันที่ต้องรันหลาย instance ให้เพิ่มตัวกลาง (Redis/LISTEN-NOTIFY) ก่อน อย่าแอบ sync ผ่าน DB polling
+- **Map ของ listener ใน `lib/annotate-events.ts` ต้องเก็บบน `globalThis`** — module-level state จะถูก duplicate เป็น 2 อินสแตนซ์ใน Next dev (bundle ของ "use server" กับ route handler แยกกัน) แล้ว event ไม่ไหลถึงกัน — **ห้ามเปลี่ยนกลับเป็น module-level Map**

.claude/skills/implement-feat/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: implement-feat
+description: Implement task F1–F19 จาก docs/PLAN-FEAT.md (แก้ไข/ย้าย A1, undo/redo A2, รูปทรง B1, redaction+export B4/C1, reply A4, resolve A5, ค้นหา/สรุป D1–D3) พร้อม verify ตามเกณฑ์ — ใช้ /implement-feat <F-number หรือ feature id เช่น A1>
+argument-hint: "[F1–F19 หรือ feature id เช่น A1, B4]"
+---
+
+Implement task ที่ระบุใน arguments จากตาราง `docs/PLAN-FEAT.md` §4 (ถ้าไม่ระบุ ให้ถามก่อน)
+
+## ขั้นตอน
+
+1. **อ่านก่อนเสมอ:** `docs/PLAN-FEAT.md` ทั้งไฟล์ + `CLAUDE.md` (invariants) + rules ใน `.claude/rules/` ที่เกี่ยวกับไฟล์ของ task นั้น — แผนเปลี่ยนได้ อย่าจำจากครั้งก่อน
+2. **Map argument → task:** รับได้ทั้ง `F<n>` และ feature id (A1, B4, C1, D2, E1, …) — หาจากตาราง §4 (B4 กับ C1 คือ task เดียวกัน F8 ตามข้อตกลง D4)
+3. **ตรวจ dependency ตามคอลัมน์ "ต้องมีก่อน"** — ถ้ายังไม่มี ให้หยุดและแจ้งผู้ใช้ว่าต้องทำ task ใดก่อน (อย่าลัดขั้นตอนไป implement เอง)
+4. **Implement เฉพาะสิ่งที่ task ระบุ ตามสเปกในแผนเท่านั้น** — ห้ามเพิ่ม feature, abstraction, หรือ "ความยืดหยุ่น" ที่แผนไม่ได้บอก; ทำตามข้อตกลง D1–D11 ใน §0 เสมอ
+5. **แตะ schema (`db/schema.ts`):** รัน `/sync-db` หลังแก้ + เติม validation ใน `validateAnnotationData` ครบทุก type/case ใหม่
+6. **Sync invariant/rules ตามตาราง §6 ของแผน** — แก้ CLAUDE.md/PLAN.md/`rules/*.md` ตามแถวของ task นั้น (นี่คือส่วนหนึ่งของงาน ไม่ใช่งานเพิ่มเติม)
+7. **เจอ edge case ที่แผนไม่ครอบคลุม (ดู §5 ก่อน):** หยุดเขียนโค้ด → อัปเดต `docs/PLAN-FEAT.md` ก่อน (+ `CLAUDE.md` ถ้าเป็น invariant ใหม่) → ถ้าเป็นเรื่องที่ต้องตัดสินใจเชิงออกแบบ ให้ถามผู้ใช้ → ค่อยเขียนโค้ดตามที่ปรับแล้ว
+8. **Verify ตามคอลัมน์ Verify จริง ๆ** — รัน `npx tsc --noEmit` ทุก task + `npm test` เมื่อแตะ `utils/` + รัน/ตรวจข้อที่ระบุ; ข้อที่ต้องทดสอบใน browser จริง (เช่น realtime 2 แท็บ, อุปกรณ์สัมผัส, เปิดไฟล์ export) ให้ระบุชัดว่า "ค้างทดสอบด้วยมือ: <รายการ>" อย่าเดาว่าผ่าน
+9. **เรียก agent `plan-reviewer`** ตรวจโค้ดของ task นี้ — แก้เฉพาะข้อที่ reviewer ชี้และถูกต้องจริง
+10. **สรุปตอนจบ:** ไฟล์ที่สร้าง/แก้, ผล verify แต่ละข้อ (ผ่าน/ไม่ผ่าน/ค้างทดสอบมือ), invariant/rules ที่ sync ไป, สิ่งที่ต้องทำต่อ (task ถัดไปที่ปลดล็อก)
+
+## ข้อห้าม
+
+- ห้าม implement task อื่นรวมด้วย ("ขอทำเพิ่ม" ไม่ใช่ข้ออ้าง) — เดินตามลำดับ F1→F19
+- ห้ามแยก B4 (redaction) ออกจาก C1 (export) — เป็น task เดียวกัน (F8) ตามข้อตกลง D4
+- ห้าม mark ว่า verify ผ่านโดยไม่ได้รันจริง
+- ห้ามบันทึกพิกัด px ลง DB — ทุก type ใหม่เป็น % ของขนาดหน้า (invariant #2)
+- ห้ามเขียน/แก้ไฟล์ PDF ต้นฉบับ — export สร้างไฟล์ใหม่เท่านั้น (invariant #1)

.claude/skills/implement-task/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: implement-task
+description: Implement task ตามลำดับใน docs/PLAN.md §7 (1 Scaffolding+Schema → 2 Coordinate helpers → 3 Server Actions → 4 Realtime hook → 5 UI หลัก → 6 README) พร้อม verify ตามเกณฑ์ของ task นั้น — ใช้ /implement-task <หมายเลข 1-6>
+argument-hint: "[หมายเลข task 1-6]"
+---
+
+Implement task หมายเลขที่ระบุใน arguments จากตาราง `docs/PLAN.md` §7 (ถ้าไม่ระบุ ให้ถามก่อน)
+
+## ขั้นตอน
+
+1. **อ่านก่อนเสมอ:** `docs/PLAN.md` ทั้งไฟล์ + `CLAUDE.md` (invariants) + rules ใน `.claude/rules/` ที่เกี่ยวกับไฟล์ของ task นั้น
+2. **Implement เฉพาะไฟล์ที่ task ระบุ ตามสเปกแผนเท่านั้น** — ห้ามเพิ่ม feature, abstraction, หรือ "ความยืดหยุ่น" ที่แผนไม่ได้บอก (อ้าง Task order: ทำทีละ task ไม่กระโดด)
+3. **เจอ edge case ที่แผนไม่ครอบคลุม:** หยุดเขียนโค้ด → อัปเดต `docs/PLAN.md` ก่อน (+ `CLAUDE.md` ถ้าเป็น invariant ใหม่) → ถ้าเป็นเรื่องที่ต้องตัดสินใจเชิงออกแบบ ให้ถามผู้ใช้ → ค่อยเขียนโค้ดตามที่ปรับแล้ว
+4. **Verify ตามคอลัมน์ Verify ของ task นั้นจริง ๆ** — รันคำสั่งจริง ตรวจผลลัพธ์จริง ถ้ามีข้อที่ต้องทดสอบด้วยมือใน browser ให้ระบุชัดว่า "ค้างทดสอบด้วยมือ: <รายการ>" — ถ้า task แตะ `utils/` ให้รัน `npm test` (vitest — pure utils) เสมอ
+5. **เรียก agent `plan-reviewer`** ตรวจโค้ดของ task นี้ — แก้เฉพาะข้อที่ reviewer ชี้และถูกต้องจริง
+6. **สรุปตอนจบ:** ไฟล์ที่สร้าง/แก้, ผล verify แต่ละข้อ (ผ่าน/ไม่ผ่าน/ค้างทดสอบมือ), สิ่งที่ต้องทำต่อใน task ถัดไป
+
+## ข้อห้าม
+
+- ห้าม implement task ถัดไปด้วย ("ขอทำเพิ่ม" ไม่ใช่ข้ออ้าง)
+- ห้ามเปลี่ยนไฟล์ของ task อื่นที่ไม่เกี่ยวกับ task นี้
+- ห้าม mark ว่า verify ผ่านโดยไม่ได้รันจริง

.claude/skills/sync-db/SKILL.md

@@ -0,0 +1,17 @@
+
+---
+name: sync-db
+description: Sync Drizzle schema ลง PostgreSQL container judes-note-db + seed ไฟล์ตัวอย่าง — ใช้หลังแก้ db/schema.ts หรือตอน setup ครั้งแรก
+---
+
+## ขั้นตอน
+
+1. **Push schema:** รัน `npx drizzle-kit push` (อ่าน config จาก `drizzle.config.ts`) — รายงาน output จริง ถ้าชนของเดิมให้แสดงและถามผู้ใช้ก่อน destructive ทางเลือก
+2. **Seed ตัวอย่าง (เฉพาะเมื่อตาราง `files` ว่าง):** INSERT ไฟล์จาก `public/samples/` โดย `pdf_url = '/samples/<ชื่อไฟล์>'` (ไฟล์และที่มาดูใน PLAN.md §0 ตาราง "ไฟล์ตัวอย่าง") — ใช้ SQL จาก README ถ้ามีแล้ว รันผ่าน `docker exec judes-note-db psql -U postgres -c "..."`
+3. **รายงานผลแต่ละขั้นตามจริง** — ขั้นไหนไม่ได้ทำบอกสาเหตุ อย่าเดา
+
+## ข้อควรระวัง
+
+- `DATABASE_URL` ชี้ที่ container `judes-note-db` (postgres:17-alpine, พอร์ต 54322 — ไม่ใช่ Supabase) — ถ้า container ไม่รันอยู่ ให้สั่ง `docker start judes-note-db` หรือแจ้งผู้ใช้ตามคำสั่ง docker run ใน README
+- ห้ามลบ volume `judes-note-db-data` เว้นแต่ผู้ใช้สั่งชัดเจน (มีข้อมูล annotation จริงหายได้)
+- ไม่ต้องตั้ง realtime publication/replica identity อีกต่อไป (SSE sync ผ่าน `lib/annotate-events.ts` ไม่ผ่าน DB trigger)