@ojokesusu/lintasai 1.1.2

package/templates/STACK_MIGRATION_GUIDE.md

@@ -0,0 +1,154 @@
+# templates/STACK_MIGRATION_GUIDE.md — Panduan Migrasi Stack (Advanced)
+
+> Versi 1 · 2026-06-03
+> **POST-LAUNCH ADVANCED.** Default tim pakai Vercel — file ini cuma untuk fase migrasi spesifik (cost Vercel over-budget, butuh background worker persistent, atau butuh WebSocket long-lived).
+
+---
+
+## 1. Pengantar
+
+File ini = **pendamping `STACK_GUIDE.md`** untuk fase migrasi vendor hosting.
+
+**JANGAN baca file ini di Day 0–1.** Staff IT non-programmer fase awal cukup pakai Vercel + Supabase sesuai `STACK_GUIDE.md` section 3.
+
+**Baru relevan kalau:**
+
+- Bill Vercel sudah lewat budget (umumnya >$100/bulan untuk satu project) DAN owner sudah verifikasi penyebabnya bukan misconfiguration (mis. ISR revalidate kekecilan, image optimization mati).
+- Butuh **background worker persistent** (Vercel function = serverless, mati setelah HTTP response selesai → tidak cocok untuk job antrian panjang, polling DB terus-menerus, dll.).
+- Butuh **WebSocket / Server-Sent Events long-lived connection** (Vercel Edge punya batasan koneksi durasi pendek).
+- Owner sudah baca Decision Matrix di `STACK_GUIDE.md` section 9 dan memutuskan pindah.
+
+> *Background worker* = proses yang jalan terus-menerus di server (bukan response per request HTTP). Contoh: pengirim email batch, scraper jadwal, queue processor.
+
+---
+
+## 2. Railway Migration Guide
+
+Kapan pilih Railway:
+
+- Butuh background worker persistent + cron native gratis.
+- Mau tetap pakai stack Docker-portable (tidak vendor-lock seperti Vercel Edge).
+- Tim sudah familiar Nixpacks atau Dockerfile.
+
+### 2.1. Provision
+
+1. https://railway.app → New Project → Deploy from GitHub.
+2. Add PostgreSQL plugin (klik **+ New** → Database → PostgreSQL).
+3. Connection string auto-inject ke service via `${{ Postgres.DATABASE_URL }}`.
+
+### 2.2. Env Vars
+
+Service → Variables → tambah satu per satu, atau import dari `.env`.
+
+```text
+DATABASE_URL = ${{ Postgres.DATABASE_URL }}
+NEXT_PUBLIC_SITE_URL = https://akses.up.railway.app
+```
+
+### 2.3. Dockerfile vs Nixpacks
+
+- **Nixpacks** (default) — auto-detect Next.js, no config. Pilih ini dulu.
+- **Dockerfile** — kalau butuh dependency native (ImageMagick, FFmpeg, Chromium).
+
+Contoh Dockerfile Next.js minimal:
+
+```dockerfile
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine AS runner
+WORKDIR /app
+COPY --from=builder /app/.next/standalone ./
+COPY --from=builder /app/.next/static ./.next/static
+COPY --from=builder /app/public ./public
+EXPOSE 3000
+CMD ["node", "server.js"]
+```
+
+Note: aktifkan `output: 'standalone'` di `next.config.js`.
+
+### 2.4. Background Worker + Cron Native
+
+Railway dukung worker service terpisah dari web. Add **+ New Service** → pilih repo yang sama, set start command beda:
+
+```text
+Web service:    npm run start    (= next start)
+Worker service: npm run worker   (= node dist/worker.js)
+```
+
+Cron: pakai package `node-cron` di worker service, atau Railway **Cron Job** (klik service → Settings → Cron Schedule).
+
+### 2.5. Healthcheck Endpoint
+
+Railway monitor `GET /api/health` (configurable). Bikin route:
+
+```ts
+// app/api/health/route.ts
+export async function GET() {
+  return Response.json({ status: 'ok', ts: Date.now() })
+}
+```
+
+---
+
+## 3. Render Migration Guide (Alternative)
+
+Mirip Railway, tapi UI beda + pricing model beda. Pilih Render kalau:
+
+- Mau spending limit ketat (Render lebih predictable per service).
+- Tim sudah familiar Render (mis. pakai untuk proyek lain).
+
+### 3.1. Web Service + DB Terpisah
+
+1. https://render.com → New → **PostgreSQL** → pilih region + plan.
+2. New → **Web Service** → connect GitHub repo.
+3. Connection string DB di-copy manual ke env var `DATABASE_URL`.
+
+### 3.2. Build / Start Command
+
+```text
+Build Command: npm ci && npm run build
+Start Command: npm run start
+```
+
+Untuk Next.js standalone:
+
+```text
+Start Command: node .next/standalone/server.js
+```
+
+### 3.3. Background Worker + Cron
+
+- **Background Worker**: New → Background Worker → set start command sama dengan worker proyek (mis. `npm run worker`).
+- **Cron Job**: New → Cron Job → schedule pakai sintaks cron (`0 */6 * * *` = tiap 6 jam) + command (`npm run cron:cleanup`).
+
+---
+
+## 4. Checklist Pre-Migration (Sebelum Pindah dari Vercel)
+
+Sebelum eksekusi migrasi, pastikan:
+
+- [ ] Sudah verifikasi bill Vercel bukan akibat misconfiguration (cek `Project → Usage`, bandingkan dengan optimasi: ISR revalidate, image optimization, function region).
+- [ ] Sudah baca `STACK_GUIDE.md` section 9 (Decision Matrix) dan paham trade-off vendor lock-in.
+- [ ] Backup DB Supabase aktif (Settings → Database → Backups).
+- [ ] Rollback plan siap: kalau migrasi gagal, balik ke Vercel via DNS switch (TTL DNS ≤5 menit sebelum cutover).
+- [ ] Custom domain SSL siap di vendor baru (Railway/Render auto-handle, tapi propagation DNS bisa 1–24 jam).
+- [ ] Env vars sensitif sudah di-copy ke vendor baru dan di-mark Sensitive/Secret.
+- [ ] Tim yang punya akses Vercel sudah diberi akses Railway/Render (least privilege).
+
+---
+
+## 5. Referensi Eksternal
+
+- Railway docs: https://docs.railway.app
+- Render docs: https://render.com/docs
+- Decision Matrix vendor: `templates/STACK_GUIDE.md` section 9
+- Default workflow (sebelum migrasi): `templates/STACK_GUIDE.md` section 3 (Vercel Setup)
+
+---
+
+> **Update file ini** tiap kali ada perubahan flow Railway/Render (UI dashboard, pricing tier, atau best practice). Catat di `CHANGELOG.md` kit + bump versi.

package/templates/STACK_VERSIONS.md

@@ -0,0 +1,31 @@
+# Stack Versions Reference - lintasAI
+
+> Single source of truth untuk version requirement.
+> Update file ini saat upgrade major version framework.
+> Konsumen: STACK_GUIDE.md, FRONTEND.md, STACK_DETECTION_PATTERN.md, dst.
+> Last updated: 2026-06-05
+
+## Required Versions (Minimum Supported)
+
+| Stack | Minimum | Recommended | Tested |
+|---|---|---|---|
+| Node.js | 18.x | 20.x LTS | 20.x |
+| Next.js | 14.x | 16.x | 16.2.3 |
+| React | 18.x | 19.x | 19.2.4 |
+| Prisma | 5.x | 7.x | 7.7.0 |
+| Tailwind | 3.x | 4.x | 4.x |
+| TypeScript | 5.x | 5.x | 5.x |
+| NextAuth | v4 | v4 | 4.24.13 |
+
+## Version Compatibility Matrix
+
+| lintasAI version | Next.js | Prisma | Notes |
+|---|---|---|---|
+| v1.0.0 | 14-16 | 5-7 | Default akses stack |
+| v1.1.0+ | 17+ | 8+ | Future |
+
+## Update Policy
+
+- Patch bumps (Next 16.2 → 16.3): auto-supported
+- Minor bumps (Next 16 → 17): test in staging dulu
+- Major bumps: kit version bump + migration guide

package/templates/UPDATE_GUIDE.md

@@ -0,0 +1,246 @@
+# docs/UPDATE_GUIDE.md — Cara Update Kit lintasAI (untuk Staff IT Non-Programmer)
+
+> Versi 1 · 2026-06-04 · auto-deployed oleh setup-pola-b.ps1
+
+---
+
+## 1. Untuk siapa & kapan baca dokumen ini
+
+Dokumen ini untuk **staff IT non-programmer** yang pakai kit `lintasAI` di proyek harian. Baca kalau:
+
+- Kamu lihat notifikasi/chat "lintasAI versi baru rilis" dan bingung harus apa.
+- AI di Claude Code bilang "kit kamu ketinggalan, update dulu".
+- Kamu mau tahu apakah update versi baru aman atau bikin file lama berantakan.
+- Kamu mau rollback (balik ke versi lama) karena update terasa "aneh".
+
+Kalau kamu programmer senior dan butuh detail teknis sha256/manifest diff, langsung loncat ke `./.claude-kit/CHANGELOG.md` + baca source `update-kit.ps1`.
+
+---
+
+## 2. TL;DR (baca ini dulu kalau buru-buru)
+
+Kit `lintasAI` di-update dengan **1 perintah** — entah lewat chat AI ("lintasAI v1.2.0 rilis, update") atau jalanin `kit.ps1 update` di PowerShell. Sistem otomatis re-clone versi terbaru, backup file kamu yang ter-modifikasi, lalu AI **auto-pakai aturan baru** di sesi berikutnya. Mirip kayak **WhatsApp auto-update di Play Store** — kamu tinggal tap, fitur baru langsung jalan, chat lama tidak hilang.
+
+---
+
+## 3. 4-Tier Update Strategy (level keparahan update)
+
+Tidak semua update sama besarnya. Kit `lintasAI` punya **4 level**, dari yang paling ringan sampai yang butuh perhatian khusus:
+
+| Tier | Label CHANGELOG | Contoh isi update | Analogi tools digital | Aksi staff |
+|------|-----------------|-------------------|----------------------|------------|
+| **1 — Silent** | (tanpa label) | Typo, perbaikan kalimat, fix link rusak | **WhatsApp 2.23.10 → 2.23.11** auto-update di background, kamu bahkan tidak sadar | Cukup 1 perintah `kit.ps1 update`. Selesai. |
+| **2 — AI auto-sync** | (tanpa label) | Aturan baru ditambahin, template baru, prompt baru | **iPhone iOS 17.3 → 17.4** minor — ada fitur baru tapi semua app lama tetap jalan normal | 1 perintah update. AI di sesi berikutnya auto-pakai aturan baru. Tidak perlu setup ulang. |
+| **3 — [BREAKING]** | `[BREAKING]` | Struktur file/folder berubah, format CLAUDE.md ganti, nama file di-rename | **iPhone iOS 16 → iOS 17** major — sebelum upgrade muncul layar "backup dulu ya", beberapa setting harus dicek ulang | Baca **"Migration Steps"** inline di CHANGELOG.md untuk versi itu. Biasanya 2-5 langkah PowerShell. AI bisa bantu jalanin step-by-step. |
+| **4 — [SCAN-REQUIRED]** | `[SCAN-REQUIRED]` | Logic bulk-bootstrap berubah, rule scan dokumen lama ganti | **Tokopedia Seller ganti algoritma kategori** — produk lama harus di-remap ulang biar tetap muncul di pencarian | Paste ulang isi `JALANKAN_KIT.md` ke chat AI baru. AI scan ulang proyek pakai rule baru, lalu apply. |
+
+**Cara baca label:** buka `./.claude-kit/CHANGELOG.md`, lihat entry versi terbaru. Kalau ada `[BREAKING]` atau `[SCAN-REQUIRED]` di judul, naik tier. Kalau cuma "fix typo di template X", itu Tier 1.
+
+---
+
+## 4. Dual-Mode Update — pilih yang nyaman
+
+Ada **2 cara** update kit. Sama-sama valid, tapi pas konteks beda:
+
+### Mode A — AI Chat (RECOMMENDED untuk harian)
+
+Buka Claude Code, chat:
+
+> "lintasAI v1.2.0 rilis, update dong"
+
+AI akan:
+1. Fetch `CHANGELOG.md` versi baru dari GitHub `ojokesusu/lintasAI`.
+2. Parse label tier (Tier 1/2/3/4).
+3. Compose ringkasan Bahasa Indonesia: "ada 3 perubahan, 1 typo + 1 fitur baru + 1 BREAKING (rename folder X → Y)".
+4. Tanya konfirmasi: "lanjut update?" — kamu jawab "ya".
+5. Jalanin `./.claude-kit/kit.ps1 update` otomatis.
+6. Kalau Tier 3/4, AI bacain "Migration Steps" satu per satu sambil tunggu kamu OK.
+
+**Analogi:** kayak **Tokopedia Seller** yang push notif "ada update aturan baru ongkir, mau lihat?" — kamu tap, dia jelasin pakai bahasa biasa, kamu tinggal setuju.
+
+### Mode B — PowerShell Script (fallback / CI / advanced)
+
+Buka PowerShell di folder proyek, jalanin:
+
+```powershell
+./.claude-kit/kit.ps1 update
+```
+
+Script otomatis classify tier dan kasih output terstruktur di terminal:
+
+```
+[OK] Fetched lintasAI v1.2.0 (was: v1.1.3)
+[INFO] 3 changes: 1 Tier-1, 1 Tier-2, 1 Tier-3 [BREAKING]
+[ACTION REQUIRED] Tier-3 migration needed:
+  - Step 1: Rename folder docs/old/ -> docs/legacy/
+  - Step 2: Update reference di AGENTS.md line 42
+[BACKUP] 2 files user-modified -> .claude-kit/CLAUDE_universal_v1.md.bak-20260604-1530
+```
+
+Mode ini dipakai kalau:
+- Kamu CI/CD pipeline (no AI in the loop).
+- Sambungan internet AI lagi lemot, mau update offline lebih cepat.
+- Kamu programmer dan suka lihat output mentah.
+
+**Analogi:** kayak `git pull` manual vs pakai GitHub Desktop GUI — sama hasilnya, beda interface.
+
+---
+
+## 5. Skenario sehari-hari — kapan tiap tier muncul
+
+**Skenario A: Tier 1 — Hari Senin pagi**
+> Owner kit fix typo "ANALAGI" → "ANALOGI" di `ANALOGI_LIBRARY.md`. Kamu chat "update", AI bilang "cuma typo, aman 100%, update otomatis". Kamu lanjut kerja. Tidak ada yang berubah di workflow kamu.
+
+**Skenario B: Tier 2 — Hari Rabu sore**
+> Owner kit tambah 5 prompt baru di `PROMPT_LIBRARY.md` untuk handle task "code review". Kamu update. Sesi AI besok pagi, kamu tanya "review PR ini", AI auto-pakai prompt baru tanpa kamu sadar. Mirip **Excel kasih function baru `XLOOKUP`** — formula lama (`VLOOKUP`) tetap jalan, function baru tinggal dipakai kalau mau.
+
+**Skenario C: Tier 3 [BREAKING] — Hari Jumat siang**
+> Owner kit rename `CLAUDE_universal_v1.md` → `LINTAS_AI_RULES.md`. CHANGELOG kasih Migration Steps:
+> 1. Tutup semua sesi Claude Code.
+> 2. Jalanin `kit.ps1 update`.
+> 3. AI auto-update referensi di `AGENTS.md` kamu.
+> 4. Buka sesi baru, verifikasi AI baca file baru.
+>
+> Analogi: kayak **BCA mobile minta re-login pakai biometric** setelah update major — sedikit ribet, tapi sekali doang.
+
+**Skenario D: Tier 4 [SCAN-REQUIRED] — Hari Senin pagi setelah weekend**
+> Owner kit ubah logic scan: dulu cuma baca `docs/`, sekarang juga baca `prisma/schema.prisma`. Kamu paste ulang `JALANKAN_KIT.md` ke chat AI baru. AI bilang "saya scan ulang proyek pakai rule baru ya", lalu propose update di beberapa file lama. Kamu approve. Analogi: **Tokopedia minta seller re-kategorisasi produk** setelah ganti algoritma — sekali kerjaan, manfaat panjang.
+
+---
+
+## 6. Cara execute update — langkah konkret
+
+### Cara 1 (RECOMMENDED): Chat ke AI
+
+1. Buka Claude Code di folder proyek (mis. `D:\Users\Administrator\projects\akses`).
+2. Ketik di chat: `lintasAI v1.2.0 rilis, update`.
+   (Ganti `1.2.0` dengan versi yang kamu lihat di chat tim / di GitHub.)
+3. Tunggu AI ringkas perubahan dalam Bahasa Indonesia.
+4. Jawab `ya` kalau setuju.
+5. AI eksekusi + verifikasi + lapor "selesai, versi sekarang v1.2.0".
+
+### Cara 2 (advanced): PowerShell
+
+1. Buka PowerShell.
+2. `cd` ke folder proyek.
+3. Jalanin:
+   ```powershell
+   ./.claude-kit/kit.ps1 update
+   ```
+4. Baca output, ikuti `[ACTION REQUIRED]` kalau ada.
+5. Kalau Tier 3/4, buka `./.claude-kit/CHANGELOG.md` baca section "Migration Steps" versi itu.
+
+---
+
+## 7. Apa yang ter-backup otomatis
+
+Update kit pakai **atomic re-clone** (kit lama dihapus, kit baru di-clone fresh). Tapi file yang **kamu modifikasi sendiri** tidak hilang — dilindungi pakai logic sha256 di `update-kit.ps1`:
+
+- Sebelum re-clone, script hitung sha256 tiap file kit.
+- Bandingkan dengan manifest versi awal install.
+- File yang sha256-nya **beda** (= kamu pernah edit) → di-backup ke `.bak-YYYYMMDD-HHmm`.
+- File yang sha256-nya **sama** (= tidak pernah disentuh) → langsung ditimpa fresh.
+
+**Contoh:**
+```
+./.claude-kit/CLAUDE_universal_v1.md          ← tidak pernah kamu edit, di-overwrite
+./.claude-kit/CLAUDE_universal_v1.md.bak-20260604-1530  ← (tidak dibuat, file aman)
+
+./.claude-kit/templates/INDEX.md              ← kamu edit kemarin
+./.claude-kit/templates/INDEX.md.bak-20260604-1530      ← BACKUP versi kamu disini
+./.claude-kit/templates/INDEX.md              ← versi baru kit di-install di sini
+```
+
+Setelah update, kamu bisa **diff manual** antara file baru vs `.bak` kamu, lalu merge perubahan yang masih relevan. AI bisa bantu kalau kamu chat "merge backup INDEX.md kemarin ke versi baru".
+
+**Analogi:** mirip **Google Drive kasih versioning otomatis** — file lama tidak hilang, tinggal buka "Version History".
+
+---
+
+## 8. Auto-cleanup backup (30 hari + max 3 versi)
+
+Biar folder `.claude-kit/` tidak penuh sampah `.bak`, `update-kit.ps1` punya auto-cleanup:
+
+- **Aturan 1:** file `.bak` yang umurnya > **30 hari** dihapus otomatis tiap kali update.
+- **Aturan 2:** kalau ada > **3 versi backup** untuk file yang sama, versi paling lama dihapus (keep 3 terbaru).
+
+**Contoh:**
+```
+INDEX.md.bak-20260301-1200   ← 95 hari lalu, DIHAPUS
+INDEX.md.bak-20260520-0900   ← keep (3 terbaru)
+INDEX.md.bak-20260601-1430   ← keep
+INDEX.md.bak-20260604-1530   ← keep (paling baru)
+```
+
+**Analogi:** kayak **WhatsApp auto-delete chat backup di Google Drive setelah 1 tahun** — sistem self-clean, tidak perlu kamu pikirin.
+
+> Catatan: TIDAK ada folder `migrations/` per breaking change (over-engineering). Migration instructions ditulis **inline** di CHANGELOG entry per versi, supaya satu tempat aja yang dibaca.
+
+---
+
+## 9. Rollback kalau update bermasalah
+
+Kalau setelah update terasa "aneh" (mis. AI bingung, file hilang, error import), rollback:
+
+### Cara 1: kit.ps1 rollback
+
+```powershell
+./.claude-kit/kit.ps1 rollback
+```
+
+Script otomatis cari snapshot pre-update terakhir dan restore.
+
+### Cara 2: git restore (kalau kit di-track git)
+
+```powershell
+git restore --source=HEAD~1 -- .claude-kit/
+```
+
+Balik ke versi commit sebelumnya. Cocok kalau kamu sudah commit kit ke repo proyek.
+
+### Cara 3: chat AI
+
+> "rollback update lintasAI tadi, kayanya bermasalah"
+
+AI auto-jalanin Cara 1 + verifikasi.
+
+**Analogi:** kayak **iPhone "Restore from iCloud Backup"** — kalau update iOS bermasalah, restore ke snapshot sebelumnya, semua data balik.
+
+---
+
+## 10. FAQ untuk staff non-programmer
+
+**Q1: Saya tidak update selama 2 bulan, aman?**
+Aman, kit lama tetap jalan. Tapi AI mungkin tidak tahu fitur/aturan baru. Best practice: update minimal 1× per 2 minggu, atau tiap kali owner kit announce versi baru di chat tim.
+
+**Q2: Update bisa bikin file `docs/` proyek saya hilang?**
+**TIDAK.** Update cuma sentuh folder `./.claude-kit/`. File proyek (mis. `docs/`, `prisma/`, `app/`) tidak ke-touch sama sekali. Kit dan proyek terpisah, kayak **app WhatsApp vs chat history kamu** — update app tidak hapus chat.
+
+**Q3: Saya pernah edit `CLAUDE_universal_v1.md`, edit-an saya hilang setelah update?**
+Tidak. File user-modified auto-backup ke `.bak-YYYYMMDD-HHmm`. Bisa kamu cek + merge manual. AI bisa bantu.
+
+**Q4: Versi kit terbaru di mana saya lihat?**
+Buka `github.com/ojokesusu/lintasAI` → file `CHANGELOG.md`. Atau chat AI: "versi terbaru lintasAI berapa?".
+
+**Q5: Sesi AI besok pagi otomatis tahu aturan baru, atau saya perlu setting ulang?**
+Auto. Tiap kali AI start sesi, dia baca `./.claude-kit/CLAUDE_universal_v1.md` fresh. Jadi setelah update, sesi berikutnya = pakai aturan baru tanpa setting ulang. Analogi: **Notion update template** → besok kamu buka Notion, template baru langsung ada.
+
+**Q6: Saya CI/CD, update di pipeline gimana?**
+Pakai Mode B (PowerShell). Tambahin step `./.claude-kit/kit.ps1 update --non-interactive` di pipeline. Exit code non-zero kalau ada Tier 3/4 yang butuh manual review.
+
+**Q7: Kalau saya cuma 1 orang (solo project), perlu update juga?**
+Perlu. Owner kit terus improve aturan, prompt, dan analogi. Update = AI kamu makin pintar. Solo project lebih gampang lagi karena tidak perlu koordinasi tim.
+
+---
+
+## 11. Cross-reference
+
+- **Istilah teknis** (mis. "sha256", "manifest", "atomic re-clone") → buka `./.claude-kit/templates/ANALOGI_LIBRARY.md` untuk analogi sehari-hari.
+- **Detail per versi** (apa berubah di v1.2.0 vs v1.3.0) → buka `./.claude-kit/CHANGELOG.md`.
+- **Audit setelah update besar** → ikuti pattern di `./.claude-kit/CLAUDE_universal_v1.md` section 4.4 "Audit Post-Setup".
+- **Aturan umum kerja AI-first** → `./.claude-kit/CLAUDE_universal_v1.md` (wajib baca tiap sesi).
+- **Kalau bingung, chat AI**: "saya mau update lintasAI tapi tidak paham langkahnya" — AI guide step-by-step.
+
+---
+
+> Dokumen ini bagian dari kit `lintasAI` v1.0.0 (commit d7284b1). Update guide ini sendiri ikut tier classification — kalau owner kit ubah strategy update, versi guide ini naik ke v2 dengan `[BREAKING]` label.

package/templates/_EXAMPLE.md

@@ -0,0 +1,110 @@
+# docs/_EXAMPLE.md — Contoh Format `.md` Pendamping (REFERENSI)
+
+> Versi 1 · 2026-05-31 · generic untuk semua proyek tim
+> File ini SISTEM (prefix `_`) — referensi format, **jangan dihapus**.
+
+## Pengantar
+
+File ini = **contoh konkret 1 file `.md` pendamping** yang ditulis sesuai format standar tim (`_PATTERNS.md` seksi 3). Pakai sebagai reference saat kamu (atau AI) buat `.md` pendamping baru — copy struktur, ganti isi sesuai modul aktual.
+
+**Contoh di bawah = fiksional** (`users.ts` adalah file imajiner). Ini cuma reference format, bukan bagian dari proyekmu. Hapus atau biarkan — tidak akan mengganggu.
+
+---
+
+## CONTOH (mulai dari sini, copy & adapt)
+
+```markdown
+# users.md — Modul User Management (CRUD + RBAC)
+
+> Versi 1 · 2026-05-31 · auto-generated
+
+## Tujuan
+Modul `users.ts` adalah **fasad CRUD untuk entitas user** di proyek ini. Tujuan utama: centralisasi semua operasi user (create / read / update / soft-delete) supaya validasi + audit log konsisten lintas endpoint. Cegah duplikasi query Prisma di banyak handler.
+
+Konsumen: handler API (`/api/users/*`), background job (mis. cleanup user inactive), CLI seeding (`scripts/seed-users.ts`).
+
+## Cara Pakai
+
+`​`​`ts
+import { createUser, getUserById, updateUser, softDeleteUser } from "@/lib/users";
+
+// Create — validasi schema + hash password + audit log otomatis
+const user = await createUser({
+  email: "alice@example.com",
+  password: "plain-text-here", // di-hash di dalam, jangan hash sendiri
+  role: "MEMBER",
+});
+
+// Read — return null kalau tidak ada (jangan throw)
+const u = await getUserById("user_123");
+
+// Update — partial update, validasi schema, audit log delta
+await updateUser("user_123", { role: "ADMIN" });
+
+// Soft delete — set deletedAt, JANGAN hard delete (audit retention 90 hari)
+await softDeleteUser("user_123", { actorId: currentUser.id });
+`​`​`
+
+## Input / Output
+
+- **`createUser(input: CreateUserInput): Promise<User>`**
+  - Input: `{ email: string, password: string, role: Role }`
+  - Output: `User` (tanpa field `password`)
+  - Throws: `ValidationError` kalau email duplicate / format invalid / password lemah
+
+- **`getUserById(id: string): Promise<User | null>`**
+  - Input: `id` (string, format `user_<cuid>`)
+  - Output: `User` atau `null` (BUKAN throw kalau tidak ada)
+
+- **`updateUser(id: string, patch: Partial<UserPatch>): Promise<User>`**
+  - Input: ID + partial patch object
+  - Output: User setelah update
+  - Throws: `NotFoundError` kalau ID tidak ada, `ValidationError` kalau patch invalid
+
+- **`softDeleteUser(id: string, opts: { actorId: string }): Promise<void>`**
+  - Input: ID + actorId untuk audit
+  - Output: void
+  - Side effect: set `deletedAt = now()`, insert row `audit_log`
+
+## Dependensi
+
+- **Library**:
+  - `@prisma/client` — query DB user table
+  - `bcrypt` — password hash (cost factor 12)
+  - `zod` — schema validation
+- **Env**:
+  - `BCRYPT_COST` (opsional, default 12) — biaya bcrypt
+- **File terkait**:
+  - `prisma.ts` — singleton Prisma client
+  - `audit.ts` — `logAction()` untuk write ke `audit_log` table
+  - `permissions.ts` — `requireRole()` kalau caller perlu RBAC check di luar
+  - DB: tabel `users`, `audit_log`
+
+## Catatan
+
+- **Password hashing**: SELALU pakai `bcrypt.hash(password, BCRYPT_COST)` di dalam modul. JANGAN expose raw password compare ke caller — pakai `verifyPassword(plain, hash)` helper. Cegah timing attack: bcrypt sudah constant-time.
+- **Soft delete bukan hard delete**: aturan compliance — semua user record retain 90 hari dengan `deletedAt` set. Hard delete cuma di cleanup job khusus (lihat `scripts/cleanup-deleted-users.ts`).
+- **Email case-insensitive**: lookup pakai `.toLowerCase()` di query Prisma. Cegah Alice@x.com vs alice@x.com jadi 2 record.
+- **Audit log wajib untuk mutation**: create/update/softDelete WAJIB insert ke `audit_log` table dengan `actorId` (siapa lakukan), `targetUserId` (siapa terdampak), `action` (string enum), `delta` (JSON diff).
+- **Race condition email duplicate**: pakai DB unique constraint di kolom `email` + catch `PrismaClientKnownRequestError` code `P2002`. Jangan check-then-insert (race).
+- Source code: `src/lib/users.ts:1` (entry), `src/lib/users.validation.ts:1` (zod schema).
+```
+
+---
+
+## Aturan saat copy contoh ini
+
+1. **Ganti `users.md` jadi nama modul aktual** (mis. `auth.md`, `invoices.md`).
+2. **Ganti semua placeholder fiksional** — `users.ts`, `User`, env var, dll.
+3. **Update `Versi` + tanggal** sesuai kenyataan.
+4. **Source code path WAJIB nyata** — jangan biarkan `src/lib/users.ts:1` kalau file aktual beda.
+5. **Pastikan max ~80 baris** (file ini contoh = lebih panjang karena ada explanation, tapi `.md` pendamping aktual cukup ringkas).
+6. **Update `architecture_auto.md`** setelah create — tambah 1 baris baru.
+
+---
+
+## Kenapa file ini ada?
+
+Tim profesional = consistent format. Tanpa contoh konkret, tiap dev/AI bikin format beda → docs jadi messy + AI kebingungan saat baca. File `_EXAMPLE.md` ini = anchor format. Saat AI generate `.md` pendamping baru, AI baca file ini dulu sebagai reference.
+
+Boleh dihapus kalau tim sudah hafal format. Default: **biarkan** — biaya 0, value tinggi untuk anggota baru.