KotaKata.AI

Imported from fadhly-permata/KotaKata.AI (AGENTS.md). Install upstream with npx skills add fadhly-permata/KotaKata.AI. Copyright stays with the author.

CodeGraph

In repositories indexed by CodeGraph (a .codegraph/ directory exists at the repo root), reach for it BEFORE grep/find or reading files when you need to understand or locate code:

• Shell (always works): codegraph explore "<symbol names or question>" prints the relevant symbols' verbatim source plus the call paths between them — including dynamic-dispatch hops grep can't follow. Name a file or symbol in the query to read its current line-numbered source.
• Useful companions: codegraph query <symbol> (search symbols), codegraph callers <symbol>, codegraph callees <symbol>, codegraph impact <symbol> (blast radius), codegraph status (index freshness).

If there is no .codegraph/ directory, skip CodeGraph entirely — indexing is the user's decision.

Aturan Proyek (wajib dipatuhi)

Aturan-aturan ini mengikat untuk semua sesi kerja di repository ini:

1. Jangan pernah push/build ke Expo & EAS kecuali diminta eksplisit

• JANGAN pernah menjalankan eas build, eas submit, eas update, expo prebuild (atau perintah apa pun yang mengunggah/mempublikasikan ke expo.dev / EAS) tanpa perintah eksplisit dari pemilik repo pada sesi itu.
• Push ke repo GitHub (git push) adalah hal yang wajar; push/build ke Expo (expo.dev / EAS) adalah hal yang TERPISAH dan hanya boleh dilakukan jika pemilik repo memintanya secara eksplisit.
• Jika perlu, beri tahu pemilik bahwa build EAS butuh persetujuan mereka, jangan langsung menjalankannya.

2. Atribusi commit: hanya nama pemilik repo

• JANGAN pernah menambahkan trailer Co-Authored-By: ... atau atribusi pihak lain (mis. agen AI) ke pesan commit. Semua commit harus tercatat atas nama pemilik repo (Fadhly Permata) saja.
• JANGAN menambahkan baris watermark/atribusi otomatis (mis. "Generated with ...") ke body pesan commit.

2b. Rilis GitHub WAJIB atas nama Fadhly Permata (dilarang pakai identitas lain)

• Setiap perintah gh di workspace ini berjalan dengan kredensial GitHub App yang dikelola platform (bukan akun personal Fadhly Permata) — satu-satunya identitas yang tersedia untuk API GitHub. Akibatnya, release yang dibuat lewat gh release create dari workspace ini tercatat atas nama app tersebut, BUKAN atas nama Fadhly Permata (commit tidak terpengaruh: memakai user.name/user.email git = Fadhly Permata).
• KARENA ITU: JANGAN PERNAH membuat (atau menghapus) GitHub Release dari workspace ini. Kalau pemilik minta rilis:
  1. Siapkan SEMUANYA di sini: bump versi app.json (version/buidNumber), catatan rilis lengkap (RELEASE_NOTES), nama tag vX.Y.Z.
  2. Jangan jalankan gh release create / gh release delete — berikan instruksi singkat dan MINTA Fadhly Permata publish dari akun GitHub-nya sendiri (UI GitHub atau gh pribadinya), supaya penulis release = Fadhly Permata.
• Dilarang mencantumkan identitas selain Fadhly Permata sebagai author release, author commit, atau kredit di file repo (kecuali nama command tooling platform yang memang harus dipakai, mis. freebuff-preview).

3. STOP preview dulu sebelum menyentuh file (aturan dari pemilik repo)

• Selama mode preview SEDANG JALAN, file-file (mis. .env / .env.local) bisa terkunci sehingga akses terminal ke file itu diblokir/ditutup. Ini BUKAN karena izin hilang — itu efek preview yang sedang berjalan.
• SEBELUM melakukan perubahan apa pun yang menyentuh file (termasuk operasi yang membaca/menulis .env*, script DB yang baca .env.local, dll): freebuff-preview stop dulu, kerjakan, lalu freebuff-preview start lagi kalau preview memang sedang dibutuhkan.
• Jangan pernah pakai kill/pkill untuk mematikan preview — selalu lewat freebuff-preview stop (tool resmi platform).

4. Langsung commit & push setelah setiap perubahan (aturan dari pemilik repo)

• SETELAH satu revisi/pekerjaan selesai (kode, fix bug, dokumen, meta-aturan) dan verifikasinya lolos (tsc / test / lint bila relevan): LANGSUNG git add file yang relevan → git commit → git push origin main, tanpa menunggu diminta lagi.
• Pesan commit mengikuti gaya repo & aturan #2 (atas nama pemilik saja, tanpa atribusi pihak lain). Jangan biarkan perubahan menumpuk tidak ter-commit.
• Bila beberapa pekerjaan selesai dalam satu sesi, gabungkan per batch yang jelas (mis. satu commit per plan/revisi).

5. Revisi baru: CATAT DULU, jangan langsung dikerjakan (aturan dari pemilik repo)

• SAAT menerima revisi/permintaan baru (fitur, perubahan, atau laporan bug): JANGAN langsung mengerjakan. Cukup catat dulu:
  1. Buat/masukkan ke dokumen plan PLAN-NNN di .agents/plans/ dengan status pending (langkahnya belum di-checklist) — satu plan per revisi, judul ringkas & jelas, isi deskripsi revisi apa adanya.
  2. Lapor ke pemilik: revisi sudah dicatat (sebut nomor plan-nya) + jawaban singkat kalau pemilik bertanya (mis. analisis penyebab bug, tanpa mengubah kode).
  3. Pekerjaan DIMULAI hanya setelah pemilik menyuruh mengerjakannya (mis. "kerjakan", "kerjakan semuanya", "kerjakan satu per satu", atau "kerjakan yang ini dulu"). Saat itu, susun daftar revisi pending & tanyakan caranya: SEMUANYA sekaligus / SATU PER SATU (selesai satu → lapor → lanjut) / pilih yang mana dulu.
• Pengecualian yang boleh langsung dikerjakan tanpa menunggu perintah: permintaan meta/aturan repo itu sendiri (mis. menambah/mengubah aturan di AGENTS.md) — revisi lain tetap dicatat dulu.
• JANGAN cross-check ke kode saat membuat plan. Cukup simpan catatan revisinya apa adanya — menelusuri/memverifikasi kode di fase pencatatan buang waktu. Analisis kode & penyebab baru dilakukan SAAT pemilik menyuruh mengerjakan (di awal pengerjaan plan, sebelum solve).

5b. FIXING WAJIB JAGA PLATFORM LAIN (aturan permanen dari pemilik repo)

• Aplikasi ini berjalan di LEBIH DARI SATU platform: Web (browser) dan Native (Android/iOS via Hermes/React Native). Fix di satu platform TIDAK BOLEH merusak platform lain.
• SEBELUM menulis perbaikan, identifikasi dulu dampaknya ke semua platform:
  • API web-only (window.addEventListener, CustomEvent, document, localStorage, matchMedia, dll.) HARUS di-guard dengan pengecekan FUNGSI-nya secara eksplisit (mis. typeof window?.addEventListener === "function") — BUKAN cukup typeof window !== "undefined", karena di Hermes objek window ADA tetapi fungsi browser-nya TIDAK ada (pernah menyebabkan layar blank/error di APK, lihat PLAN-076).
  • Sebaliknya, API native-only juga harus punya jalur fallback web.
• SETELAH fix, verifikasi lintas platform sebelum mengklaim selesai: typecheck + test + (bila menyentuh UI/startup) pastikan jalur startup aman untuk KEDUA platform. Kalau perlu, cari pemakaian serupa lainnya di seluruh repo dan perbaiki sekalian (grep pattern yang sama).
• Pelajaran dari kasus nyata: memperbaiki bug di satu platform lalu diam-diam merusak platform lain adalah REGRESI. Regresi lebih buruk daripada bug awalnya — jadi setiap fix wajib disertai pertimbangan eksplisit: "apakah perubahan ini aman di web DAN di native APK?"

6a. KATA VULGAR ITU HARAM (aturan permanen dari pemilik repo)

• KotaKata.AI adalah permainan aman anak. Setiap kata/soal yang vulgar, kasar, makian, alat kelamin, tindakan seksual, pelecehan, hinaan, diskriminatif, atau terkait narkoba TIDAK BOLEH muncul — baik sebagai jawaban maupun di dalam clue (c1/c2/c3) — di tier mana pun (1–10), di Mode AI, maupun di konten apa pun yang dipakai aplikasi.
• Setiap pekerjaan yang menyentuh kosakata WAJIB menjalankan scanner node scripts/vocab/vulgar-words.mjs dan memastikan 0 hit di kelompok VULGAR & ANSWER-ONLY (kelompok KONTEKSTUAL ditinjau manual per hit — jika konteksnya kasar/melecehkan, harus diganti).
• Scanner anti-vulgar ini adalah jaring pengaman permanen (PLAN-041): jangan pernah menghapus/menonaktifkannya; kalau ada kata baru yang terlewat, tambahkan ke daftar di scripts/vocab/vulgar-words.mjs.
• Verifikasi DB setelah push: node scripts/db/check-vulgar-db.mjs harus melaporkan 0 kata vulgar di Supabase.

6. Setiap revisi selesai → LANGSUNG deploy web ke expo.dev (aturan dari pemilik repo)

• Setiap kali satu batch revisi/pekerjaan SELESAI dan verifikasinya lolos (tsc / test / lint), wajib langsung build & deploy versi WEB ke expo.dev (node scripts/expo-deploy-web.mjs --prod atau npm deploy:web) — bagian dari alur standar, TIDAK perlu menunggu izin lagi.
• Ini adalah PENGECUALIAN khusus untuk deploy web (EAS Hosting) dari aturan #1. Aturan #1 tetap berlaku untuk build NATIVE (APK/AAB via eas build / scripts/expo-build.mjs): build native tetap butuh perintah eksplisit pemilik tiap sesi.
• Urutan standar satu batch: kerjakan → verifikasi (tsc/test/lint) → git commit + git push origin main → deploy web ke expo.dev → laporkan hasil (URL produksi + status deploy) ke pemilik.
• Kalau deploy web gagal, perbaiki penyebabnya (jangan biarkan gagal menggantung), lalu coba lagi sampai berhasil atau laporkan kendalanya.

7. Wajib Try-Catch + Logging di Setiap Operasi Asinkron (aturan permanen)

Semua kode yang menjalankan operasi asinkron (fetch, DB query, storage, navigasi, dll.) WAJIB dibungkus try-catch dengan logging menggunakan fungsi logger dari src/utils/logger.ts:

• loggerError(msg, err) — untuk error yang menggagalkan operasi (HTTP 500, DB error, auth gagal). Selalu sertakan error object supaya stacktrace tersimpan di log DB.
• loggerWarn(msg, err) — untuk error yang ditangani gracefully (offline, fallback ke cache, gagal sync tapi app tetap jalan).
• loggerInfo(msg, err) — untuk info penting yang perlu di-track (board selesai, user login, config tersimpan).
• loggerDebug(msg) — untuk debug verbose (hanya di DEV).

Aturan penulisan:

// ✅ BENAR: try-catch + logging dengan context yang jelas
try {
  const data = await supabase.from("table").select("*");
  // ...proses data...
} catch (err) {
  loggerError("Gagal mengambil data dari tabel", err);
  // fallback / re-throw sesuai kebutuhan
}

// ❌ SALAH: catch tanpa logging
try {
  await doSomething();
} catch {
  // error hilang, debugging jadi sulit
}

// ❌ SALAH: catch tanpa err object
try {
  await doSomething();
} catch (err) {
  loggerError("Gagal", "unknown"); // stacktrace hilang
}

LogViewerScreen (keamanan):

• UI TIDAK PERNAH menampilkan stack field (stacktrace/inner exception).
• details field di-sanitize sebelum ditampilkan (mask API key, token, base64 secret) lewat sanitizeForDisplay().
• Stacktrace & detail lengkap HANYA tersimpan di log DB untuk debugging developer — bukan untuk user.

Pengecualian (boleh tanpa logger):

• Catch block yang memang sengaja menelan error untuk operasi non-kritis (mis. play("tap").catch(() => {}) untuk suara).
• Tapi tetap harus pakai komentar // abaikan — [alasan].

8. Konsistensi Error Handling di Repository Layer

Repository (src/data/repositories/) sudah menggunakan pola:

const { data, error } = await supabase.from("table").select("*");
if (error) throw new Error(`Gagal [aksi]: ${error.message}`);

Panggilan ke repository di screen/hook tetap harus dibungkus try-catch

• logging di LEVEL PEMANGGIL (screen/component), bukan di repository. Repository melempar error → pemanggil menangkap + logging.

9. WAJIB JAGA KONSISTENSI KODE & RENCANA YANG SUDAH ADA (aturan keras dari pemilik repo)

Latar belakang: sudah 2× regresi karena perubahan tidak mengecek kondisi existing (fix hooks ResolutionSimulator justru crash native — PLAN-110; simpan provider AI menimpa seluruh config cloud yang sudah ada). Pola "perbaiki A, diam-diam merusak B" TIDAK BOLEH berulang.

SEBELUM mengubah kode apa pun, wajib melakukan pemeriksaan konsistensi:

1. Baca implementasi existing dulu, jangan mengarang ulang alurnya. Pahami fungsi/pemanggil/alur yang sudah ada (grep callers/callees, baca file terkait) sebelum menulis kode. Perubahan harus MENYAMBUNG dengan desain yang sudah jalan — bukan menggantinya diam-diam.
2. Data & storage format: petakan SEMUA pembaca/penulis sebelum menyentuh bentuk datanya. Kalau sebuah kolom DB / key storage / JSON punya lebih dari satu penulis atau pembaca (termasuk migrasi format lama), perubahan HARUS memakai API tulis yang utuh (mis. saveAll*, bukan overwrite single-object) dan semua jalur baca harus tetap mendukung format lama + baru. Grep dulu semua pemakaian kolom/key tersebut.
3. Fix tidak boleh melahirkan bug baru. Setiap kali memindahkan/mengubah kode untuk memperbaiki sesuatu (mis. pindahkan hook, ubah guard, refactor kecil), jejak ulang SEMUA jalur eksekusi hasil perubahan itu — termasuk jalur di platform lain (lihat aturan #5b) dan jalur yang tadinya aman.
4. Cek dokumen rencana yang relevan (.agents/plans/PLAN-*.md yang menyentuh fitur tersebut + RELEASE_NOTES.md) supaya konteks keputusan desain sebelumnya tidak dilanggar tanpa sadar. Kalau memang perlu mengubah keputusan desain lama, sebut eksplisit di laporan.
5. Setelah selesai, jalankan verifikasi standar (tsc + test) DAN kalau perubahannya luas, jalankan npm run audit:bugs -- --quiet pada file yang disentuh sebagai jaring pengaman kedua.
6. Kalau ragu antara "cara cepat" vs "cara yang konsisten dengan existing": pilih yang konsisten, lalu laporkan trade-off-nya ke pemilik.