# AGENTS.md — AI Agent Rules

## Entry Point Wajib

Sebelum melakukan pekerjaan apa pun, baca berurutan:
1. `docs/context-index.md` — peta seluruh dokumentasi
2. `.cursor/blueprint.md` — visi, fase, batas modul
3. `.cursor/progress.md` — fase aktif & checklist DoD
4. Dokumen spesifik modul (db-schema, api-contracts, dll)

**Jangan implement fase N+1 jika fase N belum DoD.**

---

## Aturan Kode

### Python (FastAPI Collector)
- Gunakan `snake_case` untuk variable, function, file
- Type hints wajib di semua function signature
- Pydantic schema di `app/schemas/` — jangan inline model di routes
- Route di `app/api/` — satu file per resource
- DB session via dependency injection (`get_db`)
- Jangan commit `.env` — gunakan `.env.example`

### PowerShell (Agent)
- Module di `agent/lib/` — satu file per sensor (Get-CpuInfo.ps1, dll)
- Jangan hardcode credential di skrip
- Hindari literal `$env:` di file `.ps1` yang di-serve Nginx (nginx potong respons)
- Test lokal dulu sebelum publish ke `agent.gisportal.id/install/`

### SQL / Database
- PK: UUID (`gen_random_uuid()`)
- Timestamp: `timestamptz`
- Nama tabel: `snake_case` plural
- Setiap perubahan schema → update `docs/database.md` + `.cursor/db-schema.md`
- Migration order: lihat `infra/db/README.md`

---

## Aturan Deploy

**Wajib setelah bump versi agent:**
```powershell
.\infra\collector\publish_agent_install.ps1   # upload ke agent.gisportal.id/install/
.\infra\collector\push_collector.ps1          # rebuild UI/API jika berubah
```

- Update `agent/VERSION` + `agent/install/manifest.json` sebelum publish
- Update `Riwayat milestone` di `.cursor/progress.md`
- Update `Sync terakhir` di `perintah.md`

**File transfer ke server:** gunakan `scp -o "MACs=hmac-sha1"` dari Windows.
Jangan heredoc SSH dari PowerShell — `$` variabel terpotong.

---

## Aturan Dokumentasi

- Setiap perubahan arsitektur → buat ADR baru di `docs/adr/ADR-00N-*.md`
- ADR **tidak boleh dihapus** — buat ADR baru jika keputusan berubah
- Setelah implementasi: update `.cursor/progress.md` + `perintah.md`
- Implementasi tanpa dokumentasi = **belum selesai**
- Update `docs/context-index.md` jika ada dokumen baru

---

## Aturan Keamanan

- **Jangan commit secret**: password DB, bearer token, API key
- Credentials DB ada di `/root/geonetagent_dev.credentials` di server 10.100.1.25
- Token agent ada di `.env` server — lihat `docs/environment.md` untuk nama variabelnya
- SSH command butuh approval user sebelum dijalankan
- Nginx `agent.gisportal.id`: `ssi off` — jangan taruh `$env:` literal di file `.ps1` yang di-serve

---

## Batas Sistem (Non-goals)

Jangan implement hal-hal berikut — sudah diputuskan di ADR/blueprint:
- ❌ Engine monitoring time-series (pakai Zabbix)
- ❌ NMS pengganti MikroTik/Proxmox tools
- ❌ Duplikasi data GIS legacy dari SQL Server
- ❌ Remote desktop / RMM agent
- ❌ Ticketing enterprise penuh (fase awal)