# 485Tech.com — AI Engineering Handoff

## Mission

รักษา 485Tech.com ให้เป็นแพลตฟอร์ม Free Online Tools ที่ใช้งานได้จริง, local-first, privacy-first, accessible และดูแลต่อได้โดยคนและ AI. ทุก change ต้องลดความไม่แน่นอนของระบบ ไม่สร้าง claim ที่เกิน implementation และต้องมี validation ที่ตรวจซ้ำได้.

## Read first

ก่อนแก้ code ให้ตรวจ `git status --short --branch` แล้วอ่านเอกสารตามลำดับนี้:

| Order | File | ใช้ตอบคำถาม |
|---:|---|---|
| 1 | `AGENTS.md` | working agreement และ safety boundary |
| 2 | `docs/project-architecture.md` | system map, build/runtime/data flow |
| 3 | `docs/code-commenting-standard.md` | comment, JSDoc, privacy และ handoff rules |
| 4 | `docs/tool-authoring-standard.md` | เพิ่ม/แก้ tool และ capability contract |
| 5 | `docs/release-checklist.md` | test, commit, push และ production verification |
| 6 | `docs/release-gate-final.md` | ผล release ล่าสุดและ known blockers |
| 7 | `docs/cloudflare-deployment-audit.md` | Cloudflare source-of-truth และ live status |

จากนั้นอ่าน source และ test เฉพาะส่วนที่จะเปลี่ยน. ห้ามสมมติว่า adapter ขนาดสั้นเป็น placeholder; trace registration ไปยัง `mega-tools.js`, `pro-tools.js` หรือ `pro-tools-extra.js` ก่อน.

## Non-negotiable rules

1. **Do not reset or revert user changes.** ถ้าพบ working tree ไม่สะอาดให้แยก scope และรักษาไฟล์เดิม.
2. **Source over generated output.** แก้ `src/`, `public/scripts/`, `scripts/` หรือ config ที่เป็น source แล้วรัน `npm run build`; อย่าแก้ generated standalone page เพียงหน้าเดียว.
3. **Privacy claims must be evidence-based.** ห้ามเรียก feature ว่า fully offline, encrypted, private หรือ AI ถ้า code/test ไม่รองรับ. Browser-side inference ที่ดาวน์โหลด model จาก CDN ต้องประกาศว่า first-use network dependency.
4. **No raw input upload by default.** อย่าเพิ่ม fetch/upload ของ user input โดยไม่อัปเดต threat model, consent, capability contract, privacy copy และ tests.
5. **No secrets in code/docs/logs.** ห้าม commit API keys, JWTs, cookies, credentials หรือ personal data. ใช้ placeholder เฉพาะใน docs ที่ระบุชัดว่าเป็นตัวอย่าง.
6. **Shared runtime has broad blast radius.** แก้ `tools-core.js`, `tools-app.js`, `mega-tools.js`, `pro-tools*.js`, Worker หรือ build pipeline ต้องรัน shared regression ครบ.
7. **Tests must assert behavior.** อย่าแก้ flaky test ด้วย timeout อย่างเดียว; รอ state/event ที่ตรวจได้และ comment เหตุผลของ fixture.
8. **Cloudflare changes are sensitive.** Read-only inspection ทำได้เมื่อผู้ใช้ขอ. ห้าม create/update/delete build config, trigger, binding หรือ deploy production โดยเดาเอง; ต้องมี authorization และตรวจ source of truth ก่อน.
9. **Use one deployment source of truth.** เลือก Workers Builds หรือ GitHub Actions สำหรับ deploy production อย่างใดอย่างหนึ่ง ไม่ตั้งซ้อนกันโดยไม่มีเหตุผลและ rollback plan.
10. **Do not claim production success from local tests.** ต้องมี Cloudflare build/deployment evidence และ live route smoke หลัง push.

## Change protocol

ก่อนเริ่มเขียนให้ระบุ intent, affected layer, data boundary, acceptance criteria และ test plan ใน working notes หรือ issue. ระหว่างแก้ให้คอมเมนต์เฉพาะเหตุผล, invariant, lifecycle และ trade-off ตาม `docs/code-commenting-standard.md`.

หลังแก้ให้ทำตามลำดับนี้:

```text
1. npm run build
2. npm run validate:tools
3. node scripts/validate_syntax.mjs
4. focused test ของ feature ที่แก้
5. shared regression ที่ blast radius ครอบคลุม
6. git diff --check
7. review generated diff และ staged diff
8. commit หนึ่ง intent ต่อหนึ่ง commit
9. push เมื่อผู้ใช้อนุญาตและ gate ผ่าน
10. verify remote HEAD และ production read-only status
```

หากขั้นใดล้มเหลว ให้หยุดสรุปสาเหตุและแก้ที่ root cause ไม่ซ่อน failure. ถ้าต้องส่งมอบทั้งที่มี blocker ให้เขียน `known limitations`, impact, workaround และ owner/next acceptance criteria.

## Comment contract for AI

เมื่อเปลี่ยน module สำคัญ ให้เพิ่มหรือปรับ module header ที่ระบุ `@module`, `@description`, `@ai-handoff`, `@human-handoff`, inputs, outputs, side effects, invariants และ failure behavior. Comment ต้องเป็นจริงจาก code และ test ใน commit เดียวกัน. ห้ามใส่ instruction ที่เปลี่ยนพฤติกรรมของ AI แบบลับ ๆ; เอกสารนี้เป็น engineering contract แบบเปิดเผยสำหรับ maintainers.

## Project facts

- Stack เป็น vanilla HTML/CSS/JS, Node ESM build scripts และ Cloudflare Worker + ASSETS binding.
- Catalog ปัจจุบันมี 159 live tools; generated standalone page อยู่ที่ `public/tools/<id>/index.html`.
- Shared browser workspace ใช้ IndexedDB; snapshots schema v2 มี per-value cap 5 MB และ total snapshot budget 25 MB.
- Capability schema v2 source อยู่ที่ `src/tool-capabilities.json`; validator ต้องผ่านทั้ง catalog.
- `bg-remover`, `diagram` และ `excel-chat` เป็น network-dependent ในระดับ first-use asset/library ตาม metadata; อย่าเรียกเป็น fully offline.
- D1/KV/auth เป็น optional ตาม Wrangler environment; การทดสอบไม่มี binding ต้องคาดหวัง 503/unauthorized อย่างถูกต้อง.
- `wrangler.toml` ชื่อ Worker คือ `home`; production pipeline ยังต้องตรวจจาก Cloudflare dashboard/API.

## Handoff format

ทุก handoff หรือ PR summary ต้องตอบให้ครบในย่อหน้า/ตารางสั้น ๆ: intent, changed files, runtime/data contract, user-visible behavior, tests and exact results, known limitations, deployment status และ next step. ลิงก์ไปยัง evidence ใน `docs/` แทนการเขียนว่า “ผ่านแล้ว” โดยไม่มีตัวเลข.