# NPX Install Guide - lintasAI Kit

## Untuk Siapa

Panduan ini ditujukan untuk **staff IT non-programmer** yang mau install lintasAI Kit ke project menggunakan `npx` (lebih cepat dari `git clone`, tidak perlu paham git, dan otomatis dapat versi terbaru).

Kalau kamu sudah familiar dengan terminal & PowerShell, install via npx adalah cara paling singkat: cukup 1 perintah, kit langsung terpasang di folder project.

---

## Cara Install (1 perintah)

1. Buka **PowerShell** (bukan CMD).
2. Pindah ke folder project tempat kit mau dipasang:
   ```powershell
   cd D:\Users\Administrator\projects\nama-project
   ```
3. Jalankan perintah install:
   ```powershell
   npx @ojokesusu/lintasai init
   ```
4. Tunggu sampai muncul pesan `Kit installed successfully`. Biasanya 30 detik - 2 menit tergantung koneksi.

Setelah selesai, folder `.claude-kit/` + `AGENTS.md` akan otomatis dibuat di project root.

---

## v1.3.0 Popup Mode (Claude Code-First UX)

Setup baru v1.3.0 pakai popup native Windows + minimal typing. **Staff non-programmer TIDAK perlu buka PowerShell/CMD manual.**

### Flow staff non-programmer (~5 menit total setup)

1. Owner DM 1-line command: `cd <project>; npx @ojokesusu/lintasai@1.3.0 init`
2. Staff paste → Enter (1x typing)
3. Popup [AGENTS.md] - `[1] Skip RECOMMENDED` default, tekan Enter
4. Popup [Email kamu?] - ketik email work (1x typing seumur hidup)
5. Popup [Buka VS Code?] - klik [Yes]
6. VS Code auto-buka, starter prompt sudah di clipboard
7. Popup [Tip Ctrl+V] - klik [OK], lalu Ctrl+V + Enter di Claude Code chat
8. Phase 1-6 Guided di Claude Code (~90 menit, mouse-click sebagian besar)

### Apa yang Berubah dari v1.2.2

| Aspek | v1.2.2 (typing) | v1.3.0 (popup) |
|-------|------------------|------------------|
| AGENTS.md | Ketik [1]/[2]/[3] | Popup [Skip] default |
| Git identity | Manual `git config` 4 baris | 1 popup email, nama auto-derive |
| Buka VS Code | Manual Cmd+Shift+P | Auto-launch + clipboard |
| Total typing seumur hidup | ~30 baris | ~10 detik (1x email) |

### Power User / CI: --NoGui Mode

Untuk headless / Server Core / SSH session / automation:

```powershell
npx @ojokesusu/lintasai@1.3.0 init -NoGui
```

Semua popup → console prompt dengan default value. Auto-detect headless juga via `[Environment]::UserInteractive` - kalau false, auto-fallback ke console mode.

### Backward Compat

Semua v1.2.2 commands tetap work: init, update, uninstall, doctor, version, status, diff, rollback. -ProjectRoot param tetap honored.

---

## Verify Install Berhasil

Cek status kit:
```powershell
npx @ojokesusu/lintasai status
```

Output yang **benar** harus menampilkan:
- `Kit version: v1.x.x`
- `AGENTS.md present: yes`
- `Manifest signed: yes`
- `Files: <jumlah> / <jumlah> OK`

Kalau ada `MISSING` atau `MODIFIED` di output, lihat section Troubleshooting di bawah.

---

## Troubleshooting

### Error: "node tidak ditemukan" / "'npx' is not recognized"

**Penyebab**: Node.js belum terinstall di PC.

**Fix**:
1. Download Node.js LTS dari https://nodejs.org/ (versi LTS, BUKAN Current).
2. Install dengan opsi default. Pastikan checkbox `Add to PATH` aktif.
3. Tutup & buka ulang PowerShell.
4. Cek versi: `node --version` (harus muncul `v20.x.x` atau lebih baru).
5. Ulangi perintah `npx @ojokesusu/lintasai init`.

### Error: "EACCES" atau "EPERM" di Windows

**Penyebab**: Permission ditolak. Biasanya karena Node.js terinstall di `Program Files` (perlu admin), atau folder project read-only.

**Fix (pilih salah satu)**:
- **Opsi A (cepat)**: Klik kanan PowerShell -> `Run as Administrator`, lalu ulangi perintah init.
- **Opsi B (rekomendasi)**: Uninstall Node.js dari Program Files, install ulang di user folder (`C:\Users\<username>\nodejs\`). Ini menghindari masalah permission permanen.
- **Opsi C**: Pastikan folder project tidak read-only. Klik kanan folder -> Properties -> uncheck `Read-only`.

### Error: "ExecutionPolicy" PowerShell block

**Penyebab**: Windows default block menjalankan script PowerShell yang tidak signed.

**Fix**:
1. Buka PowerShell sebagai user biasa (tidak perlu admin).
2. Jalankan:
   ```powershell
   Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
   ```
3. Pilih `Y` saat ditanya konfirmasi.
4. Ulangi perintah init.

Catatan: `RemoteSigned` aman - hanya allow local script + script remote yang ber-signature. Tidak membuka full security risk.

### Error: Behind corporate proxy / firewall

**Penyebab**: Kantor pakai proxy yang block koneksi npm registry langsung.

**Fix**:
1. Tanya admin IT kantor untuk URL proxy (biasanya `http://proxy.company.local:8080`).
2. Set npm config:
   ```powershell
   npm config set proxy http://proxy.company.local:8080
   npm config set https-proxy http://proxy.company.local:8080
   ```
3. Kalau proxy butuh auth, format jadi: `http://username:password@proxy.company.local:8080`.
4. Ulangi perintah init.

Kalau masih gagal, coba registry mirror: `npm config set registry https://registry.npmmirror.com/`.

### Error: "Kit tidak lengkap" / "File hilang"

**Penyebab**: Download terputus di tengah jalan, atau cache npm corrupt.

**Fix**:
1. Clear cache npm:
   ```powershell
   npm cache clean --force
   ```
2. Hapus folder `.claude-kit/` yang sudah ada (kalau sebagian terinstall):
   ```powershell
   Remove-Item -Recurse -Force .\.claude-kit\
   ```
3. Retry:
   ```powershell
   npx @ojokesusu/lintasai@latest init
   ```

### Error: "Root proyek" salah deteksi (npm cache path)

**Penyebab**: Bug di versi kit **pre-v1.1.3** - kit salah deteksi root project ke folder npm cache, bukan ke folder project user.

**Tanda**: Folder `.claude-kit/` muncul di `C:\Users\<username>\AppData\Roaming\npm-cache\...` bukan di project folder.

**Fix**:
1. Hapus install yang salah:
   ```powershell
   npx @ojokesusu/lintasai uninstall
   ```
2. Upgrade ke versi terbaru (v1.2.0+):
   ```powershell
   npx @ojokesusu/lintasai@latest init
   ```
3. Versi v1.2.0+ sudah fix deteksi root via `process.cwd()` (folder PowerShell aktif).

---

## Rollback ke Versi Sebelumnya

Kalau update terbaru bermasalah, rollback ke versi sebelumnya:

```powershell
npx @ojokesusu/lintasai rollback
```

Perintah ini akan restore file dari snapshot otomatis yang dibuat saat last update. Snapshot disimpan di `.claude-kit/.snapshots/`.

---

## Uninstall

Hapus kit dari project secara aman (sambil keep file user-custom):

```powershell
npx @ojokesusu/lintasai uninstall
```

Perintah ini akan:
- Hapus folder `.claude-kit/`.
- Hapus `AGENTS.md` (kalau belum dimodifikasi user).
- **TIDAK** hapus `docs/`, `src/`, atau file project user lain.

Kalau `AGENTS.md` sudah dimodifikasi, kit akan tanya konfirmasi sebelum hapus.

---

## Cara Update Kit

Update ke versi terbaru:

```powershell
npx @ojokesusu/lintasai update
```

Perintah ini akan:
1. Buat snapshot dari versi current.
2. Download versi terbaru dari npm.
3. Merge file yang dimodifikasi user (kalau ada).
4. Update manifest signature.

Kalau ada konflik merge, kit akan tampilkan diff & tanya pilihan: `keep mine`, `take theirs`, atau `manual merge`.

---

## Cara Cek Apakah Kit Saya Up-to-date

Cek status + versi:
```powershell
npx @ojokesusu/lintasai status
```

Lihat file yang berubah dari versi original:
```powershell
npx @ojokesusu/lintasai diff
```

Output `diff` akan tampilkan:
- File yang **MODIFIED** (diubah user setelah install).
- File yang **MISSING** (terhapus).
- File yang **ADDED** (file baru di luar manifest).

Untuk lihat versi terbaru yang tersedia di npm:
```powershell
npm view @ojokesusu/lintasai version
```

Bandingkan dengan `Kit version` di output `status`. Kalau beda, jalankan `update`.

---

## Kontak Support

- **Discord channel**: `#lintasai-support` (link invite di internal docs tim).
- **Owner**: testing@gmail.com - gunakan Signal/Telegram untuk hal sensitif (kredensial, API key bocor, security incident).
- **Bug report**: buka issue di GitHub repo `@ojokesusu/lintasai` (link di npm page).

Untuk error yang **tidak** ada di troubleshooting di atas:
1. Jalankan `npx @ojokesusu/lintasai status --verbose` (output lengkap).
2. Screenshot output + share di Discord channel.
3. Jangan paste output yang berisi password / API key - mask dulu.