@weppy/roblox-mcp 1.0.1 → 1.0.3

package/docs/es/tools/overview.md

@@ -1,99 +1,259 @@
-# Funciones de Roblox MCP
+# Herramientas de Roblox MCP
 
-Conecta la IA con Roblox Studio para automatizar diversas tareas. A continuacion se presenta lo que puedes hacer por categoria.
+Para parametros detallados, consulte las definiciones de herramientas MCP directamente.
 
-Politica de Sync:
-- Basic: Studio -> Local (una via)
-- Pro: Sync bidireccional + funcionalidades avanzadas mas amplias (mejor eficiencia de tokens IA con operaciones masivas)
-
----
-
-## Basic (Gratis)
-
-### Gestion de Objetos
-
-Crea, clona, elimina y mueve objetos del juego como partes, modelos y carpetas. Tareas como "Crea una parte roja" o "Clona este modelo y ponlo al lado" son posibles.
-
-### Propiedades
-
-Lee y cambia todas las propiedades de los objetos como tamano, color, posicion y material. Puedes cambiar varias propiedades a la vez o ajustarlas relativamente segun los valores actuales.
-
-### Scripts
-
-Crea nuevos scripts, lee el codigo existente y modificalo. Puedes editar lineas especificas, buscar texto dentro de scripts o identificar dependencias para ver que modulos se referencian.
-
-### Seleccion
-
-Verifica los objetos seleccionados, cambia la seleccion y limpia la seleccion. Esencial para entender y controlar con que estas trabajando en Studio.
-
-### Busqueda
-
-Encuentra objetos en tu juego por nombre o clase (tipo).
-
-### Etiquetas
-
-Agrega o quita etiquetas de objetos y encuentra todos los objetos con una etiqueta especifica de una vez. Util para gestionar grupos de objetos similares.
-
-### Camara
-
-Mueve la camara a objetos o posiciones especificas. Conveniente para ver rapidamente el area en la que estas trabajando.
-
-### Registros
-
-Consulta logs de salida y errores ocurridos durante la ejecucion del juego. Ayuda a encontrar y corregir bugs.
-
-### Conexion
-
-Verifica el estado de conexion y uso entre el servidor MCP y Roblox Studio.
-
----
-
-## Pro
-
-Si necesitas funciones mas potentes, puedes actualizar a Pro.
+Documentacion relacionada:
+- [Guia detallada de Sync](../sync/overview.md)
 
-### Seleccion Avanzada
-
-Obtien el contexto detallado de la seleccion con propiedades y codigo fuente, explora la jerarquia de seleccion, agrega/elimina elementos de la seleccion, y consulta informacion del Place y servicios del juego. Util para flujos de trabajo avanzados y automatizacion.
-
-### Scripts Avanzados
-
-Reemplaza contenido en multiples scripts de una vez o ejecuta codigo Luau instantaneamente. Util para modificaciones repetitivas de codigo o pruebas rapidas.
-
-### Busqueda Avanzada
-
-Explora el arbol de archivos completo o busca objetos por propiedad o etiqueta. Obtien una vista completa de la estructura del proyecto y consulta todos los descendientes o ancestros de objetos especificos.
-
-### Operaciones Masivas
-
-Crea, elimina, modifica o duplica cientos de objetos a la vez. Maneja rapidamente tareas a gran escala como plantar arboles en un mapa, cambiar el color de todas las partes o colocar objetos segun patrones.
-
-### Assets
-
-Busca modelos gratuitos en Roblox Creator Store e insertarlos instantaneamente. Agrega assets mediante conversacion como "Busca un modelo de castillo medieval" o "Inserta un modelo de arma".
-
-### Entorno
-
-Configura iluminacion, cielo, niebla, propiedades del terreno y hora del dia con lenguaje natural. Solicitudes como "Cambia a ambiente de atardecer" o "Pon la hora a medianoche" son posibles.
-
-### Gestion de Estado
-
-Guarda el estado actual del Workspace como snapshot y consulta cambios recientes y el estado del viewport. Ayuda a entender el estado actual durante tareas complejas.
-
-### Analisis Espacial
-
-Determina con precision el tamano y posicion de objetos, encuentra espacios vacios y verifica colisiones. Tambien puedes alinear objetos a una cuadricula.
-
-### Raycast
-
-Lanza rayos invisibles para encontrar puntos de colision con terreno u objetos. Esencial para el diseno de niveles: encontrar posiciones del suelo, verificar si se pueden colocar objetos, buscar ubicaciones de spawn y analizar areas transitables.
-
-### Terreno
-
-Rellena, talla y suaviza terreno con diversas formas como bloques, esferas, cilindros y cunas. Cambia materiales y colores, o genera proceduralmente terreno natural con montanas y rios.
-
-### Visualizacion
-
-Muestra areas, marcadores y lineas en pantalla para confirmar visualmente el espacio de trabajo. Util para debugging y revision de diseno de niveles.
-
-👉 [Guia de actualizacion a Pro](../pro-upgrade.md)
+Politica de Sync:
+- Basic: Studio -> Local sincronizacion unidireccional
+- Pro: Sincronizacion bidireccional + cobertura de acciones avanzadas mas amplia (mejor eficiencia de tokens IA con flujos masivos)
+
+## Query Instances (Mixto)
+
+| Accion | Descripcion | Tier |
+|--------|-------------|------|
+| `get` | Obtener propiedades de instancia por ruta | Basic |
+| `children` | Obtener hijos inmediatos o todos los descendientes | Basic |
+| `find_child` | Buscar primer hijo por nombre y filtro de clase opcional | Basic |
+| `find_descendant` | Buscar primer descendiente por nombre | Basic |
+| `wait_for_child` | Esperar a que aparezca un hijo (con timeout) | Basic |
+| `class_info` | Obtener informacion de clase y propiedades validas | Basic |
+| `search_name` | Buscar instancias por patron de nombre (soporta comodines) | Basic |
+| `search_class` | Buscar instancias por nombre de clase | Basic |
+| `file_tree` | Obtener estructura de arbol de archivos desde la raiz | Pro |
+| `project_structure` | Obtener estructura completa del proyecto | Pro |
+| `descendants` | Obtener todos los descendientes de una instancia | Pro |
+| `ancestors` | Obtener todos los ancestros de una instancia | Pro |
+| `search_property` | Buscar instancias por valor de propiedad | Pro |
+| `search_tag` | Buscar instancias por etiqueta | Pro |
+
+## Mutate Instances (Mixto)
+
+| Accion | Descripcion | Tier |
+|--------|-------------|------|
+| `create` | Crear una nueva instancia | Basic |
+| `create_with_props` | Crear instancia con propiedades iniciales | Basic |
+| `delete` | Eliminar una instancia | Basic |
+| `clone` | Clonar una instancia | Basic |
+| `move` | Mover instancia a nuevo padre | Basic |
+| `rename` | Renombrar una instancia | Basic |
+| `pivot` | Establecer posicion pivot o CFrame | Basic |
+| `create_tree` | Crear arbol jerarquico de instancias | Pro |
+| `mass_create` | Crear multiples instancias a la vez | Pro |
+| `mass_delete` | Eliminar multiples instancias | Pro |
+| `mass_duplicate` | Duplicar multiples instancias | Pro |
+| `smart_duplicate` | Duplicar con espaciado y cantidad | Pro |
+
+## Manage Properties (Mixto)
+
+| Accion | Descripcion | Tier |
+|--------|-------------|------|
+| `get` | Obtener valor de una propiedad | Basic |
+| `set` | Establecer valor de una propiedad | Basic |
+| `get_all` | Obtener todas las propiedades de una instancia | Basic |
+| `set_multiple` | Establecer multiples propiedades a la vez | Basic |
+| `get_attr` | Obtener valor de atributo | Basic |
+| `set_attr` | Establecer valor de atributo | Basic |
+| `get_all_attrs` | Obtener todos los atributos | Basic |
+| `delete_attr` | Eliminar un atributo | Basic |
+| `add_tag` | Agregar etiqueta a instancia | Basic |
+| `remove_tag` | Eliminar etiqueta de instancia | Basic |
+| `check_tag` | Verificar si instancia tiene una etiqueta | Basic |
+| `get_tags` | Obtener todas las etiquetas de una instancia | Basic |
+| `get_tagged` | Obtener todas las instancias con una etiqueta especifica | Basic |
+| `set_calculated` | Establecer propiedad usando expresion matematica | Pro |
+| `set_relative` | Establecer propiedad relativa al valor actual | Pro |
+| `mass_set` | Establecer propiedad en multiples instancias | Pro |
+| `mass_get` | Obtener propiedad de multiples instancias | Pro |
+| `modify_children` | Modificar todos los hijos de un padre | Pro |
+
+## Manage Scripts (Mixto)
+
+| Accion | Descripcion | Tier |
+|--------|-------------|------|
+| `get_source` | Obtener codigo fuente del script | Basic |
+| `set_source` | Establecer codigo fuente del script | Basic |
+| `create` | Crear un nuevo script | Basic |
+| `delete` | Eliminar un script | Basic |
+| `edit_replace` | Reemplazar lineas especificas del script | Basic |
+| `edit_insert` | Insertar lineas en posicion | Basic |
+| `edit_delete` | Eliminar lineas especificas | Basic |
+| `search` | Buscar texto en script | Basic |
+| `get_dependencies` | Obtener dependencias del script | Basic |
+| `replace` | Reemplazo masivo en scripts | Pro |
+
+## Manage Lighting (Pro)
+
+| Accion | Descripcion | Tier |
+|--------|-------------|------|
+| `lighting` | Establecer propiedades del servicio Lighting | Pro |
+| `atmosphere` | Establecer propiedades de Atmosphere | Pro |
+| `sky` | Establecer propiedades de Sky | Pro |
+| `terrain_props` | Establecer propiedades visuales/agua de Terrain | Pro |
+| `time` | Establecer hora del dia | Pro |
+
+## Manage Selection (Mixto)
+
+| Accion | Descripcion | Tier |
+|--------|-------------|------|
+| `get` | Obtener seleccion actual | Basic |
+| `set` | Reemplazar seleccion actual | Basic |
+| `clear` | Limpiar seleccion | Basic |
+| `cached` | Obtener seleccion en cache sin ida y vuelta | Basic |
+| `context` | Obtener contexto detallado con fuente y propiedades | Pro |
+| `details` | Obtener detalles jerarquicos con ancestros/descendientes | Pro |
+| `add` | Agregar elementos a la seleccion | Pro |
+| `remove` | Eliminar elementos de la seleccion | Pro |
+| `watch` | Monitorear cambios de seleccion | Pro |
+
+## Manage Camera (Basic)
+
+| Accion | Descripcion | Tier |
+|--------|-------------|------|
+| `info` | Obtener posicion, rotacion, FOV y tamano del viewport | Basic |
+| `focus_path` | Mover camara para enfocar instancia | Basic |
+| `focus_position` | Mover camara para enfocar posicion | Basic |
+| `suggest` | Obtener vista de camara sugerida para objetivo | Basic |
+
+## Manage Tween (Pro)
+
+| Accion | Descripcion | Tier |
+|--------|-------------|------|
+| `create` | Crear tween con propiedades objetivo | Pro |
+| `play` | Reproducir un tween creado | Pro |
+| `pause` | Pausar un tween en ejecucion | Pro |
+| `cancel` | Cancelar un tween | Pro |
+
+## Manage Audio (Pro)
+
+| Accion | Descripcion | Tier |
+|--------|-------------|------|
+| `play` | Reproducir sonido (crea Sound si es necesario) | Pro |
+| `stop` | Detener un sonido en reproduccion | Pro |
+| `pause` | Pausar un sonido en reproduccion | Pro |
+| `resume` | Reanudar un sonido pausado | Pro |
+| `set_listener` | Establecer tipo/objetivo del listener de audio | Pro |
+
+## Manage Animation (Pro)
+
+| Accion | Descripcion | Tier |
+|--------|-------------|------|
+| `load` | Cargar animacion en Humanoid/AnimationController | Pro |
+| `play` | Reproducir pista de animacion cargada | Pro |
+| `stop` | Detener animacion en reproduccion | Pro |
+| `get_tracks` | Listar todas las pistas de animacion cargadas | Pro |
+
+## Manage Physics (Pro)
+
+| Accion | Descripcion | Tier |
+|--------|-------------|------|
+| `register_group` | Registrar grupo de colision | Pro |
+| `set_collidable` | Establecer si dos grupos pueden colisionar | Pro |
+| `get_groups` | Listar todos los grupos de colision registrados | Pro |
+
+## Manage Effects (Pro)
+
+| Accion | Descripcion | Tier |
+|--------|-------------|------|
+| `emit` | Emitir particulas desde ParticleEmitter | Pro |
+| `clear` | Limpiar todas las particulas | Pro |
+| `toggle` | Activar o desactivar efecto | Pro |
+
+## Manage Terrain (Pro)
+
+| Accion | Descripcion | Tier |
+|--------|-------------|------|
+| `fill_block` | Rellenar terreno en forma de bloque | Pro |
+| `fill_ball` | Rellenar terreno en forma de esfera | Pro |
+| `fill_cylinder` | Rellenar terreno en forma de cilindro | Pro |
+| `fill_wedge` | Rellenar terreno en forma de cuna | Pro |
+| `clear_region` | Limpiar terreno en region | Pro |
+| `clear_bounds` | Limpiar terreno en limites | Pro |
+| `replace_material` | Reemplazar material en region | Pro |
+| `colors_get` | Obtener colores de material | Pro |
+| `colors_set` | Establecer colores de material | Pro |
+| `read_voxel` | Leer datos de voxel individual | Pro |
+| `read_voxels` | Leer datos de voxels masivo | Pro |
+| `write_voxels` | Escribir datos de voxels masivo | Pro |
+| `generate` | Generar terreno procedural | Pro |
+| `smooth` | Suavizar terreno | Pro |
+
+## Spatial Query (Pro)
+
+| Accion | Descripcion | Tier |
+|--------|-------------|------|
+| `raycast` | Lanzar un solo rayo | Pro |
+| `find_ground` | Encontrar posicion del suelo debajo del punto | Pro |
+| `check_placement` | Verificar si la colocacion esta libre de colisiones | Pro |
+| `multi_raycast` | Lanzar multiples rayos en lote | Pro |
+| `scan_area` | Generar mapa de alturas del area | Pro |
+| `find_flat` | Encontrar areas planas para construccion | Pro |
+| `find_spawn` | Encontrar posiciones de spawn adecuadas | Pro |
+| `analyze_walkable` | Analizar cuadricula de transitabilidad | Pro |
+| `spatial_map` | Obtener todas las posiciones de BasePart | Pro |
+| `find_space` | Encontrar espacio vacio para objeto | Pro |
+| `bounds` | Obtener caja delimitadora de instancias | Pro |
+| `snap_grid` | Ajustar posicion a cuadricula | Pro |
+| `collision` | Verificar colision AABB | Pro |
+
+## Manage Assets (Pro)
+
+| Accion | Descripcion | Tier |
+|--------|-------------|------|
+| `insert` | Insertar modelo por ID de asset | Pro |
+| `info` | Obtener metadatos del asset | Pro |
+| `search` | Buscar en Creator Store | Pro |
+| `search_insert` | Buscar e insertar primera coincidencia | Pro |
+| `insert_free` | Insertar modelo gratuito | Pro |
+| `insert_package` | Insertar paquete | Pro |
+| `export` | Exportar seleccion actual | Pro |
+
+## Manage Sync (Pro)
+
+| Accion | Descripcion | Tier |
+|--------|-------------|------|
+| `status` | Obtener estado de sincronizacion de un Place | Pro |
+| `config` | Obtener configuracion de sincronizacion | Pro |
+| `history` | Obtener historial de cambios | Pro |
+| `directions` | Obtener direcciones de sincronizacion por tipo | Pro |
+| `read_file` | Leer un archivo sincronizado | Pro |
+| `write_file` | Escribir en un archivo sincronizado | Pro |
+| `progress` | Obtener progreso de sincronizacion en tiempo real y ancho de banda | Pro |
+
+## Workspace State (Pro)
+
+| Accion | Descripcion | Tier |
+|--------|-------------|------|
+| `sync` | Obtener estado actual del Workspace | Pro |
+| `snapshot` | Obtener estructura completa del arbol de instancias | Pro |
+| `changes` | Obtener cambios recientes | Pro |
+| `viewport` | Obtener informacion de camara y viewport | Pro |
+
+## Manage Logs (Basic)
+
+| Accion | Descripcion | Tier |
+|--------|-------------|------|
+| `get` | Obtener logs filtrados | Basic |
+| `clear` | Limpiar buffer de logs | Basic |
+| `errors` | Obtener solo errores recientes | Basic |
+
+## System Info (Mixto)
+
+| Accion | Descripcion | Tier |
+|--------|-------------|------|
+| `ping` | Probar conexion | Basic |
+| `connection` | Obtener info de conexion servidor/plugin | Basic |
+| `usage` | Obtener tier actual (basic/pro) | Basic |
+| `place_info` | Obtener Place ID, nombre, creador | Pro |
+| `services` | Listar todos los servicios de Roblox | Pro |
+| `studio_settings` | Obtener preferencias de Studio | Pro |
+| `run_command` | Ejecutar comando de Studio | Pro |
+
+## Batch Execute (Pro)
+
+Ejecuta multiples comandos en un solo lote. Cada comando especifica un nombre de herramienta y argumentos. Los comandos se ejecutan secuencialmente con comportamiento opcional de continuar en caso de error.
+
+## Execute Luau (Pro)
+
+Ejecuta codigo Luau arbitrario en el sandbox de Roblox Studio. Servicios bloqueados: HttpService, DataStoreService, MessagingService. No puede acceder a CoreGui/CorePackages.

package/docs/id/README.md

@@ -6,67 +6,40 @@
 
 [![Demo](https://img.youtube.com/vi/3jrUpBbZPaw/maxresdefault.jpg)](https://youtu.be/3jrUpBbZPaw)
 
-## Yang Bisa Kamu Lakukan
+## Fitur utama
 
-### Dari Satu Ide ke Game yang Bisa Dimainkan
+### 1) MCP Tool: eksekusi langsung di Studio dari bahasa alami
 
-"Buatkan game survival gaya Minecraft dengan siklus siang/malam, penambangan, crafting, dan wave defense." — Satu kalimat dan AI merancang struktur game, membangun map, membuat objek, serta menulis semua scriptnya.
+Pilar pertama Roblox MCP adalah **eksekusi MCP Tool**.
+AI bisa langsung menangani script, instance, properti, terrain, lighting, asset, audio, dan animasi di dalam Studio.
 
-> **Tip**: Minta "buat rencana dulu" lalu review dan katakan "jalankan" untuk hasil lebih baik.
+- "Tambahkan partikel + suara + cooldown saat player melompat."
+- "Buat arena boss di tengah map dan pasang spawn point yang aman dari tabrakan."
+- "Ubah interface modul ini dan perbarui semua script yang bergantung padanya."
 
-### AI yang Sudah Membaca Seluruh Proyekmu
+Ini bukan sekadar generate kode. Ini adalah **aksi yang benar-benar bisa dieksekusi**.
 
-AI menyinkronkan proyek Roblox kamu ke file lokal dan mempelajari setiap script, objek, dan struktur. Puluhan file dipahami sekaligus, dimodifikasi secara konsisten.
+### 2) Sync: menjaga konteks penuh proyek untuk AI
 
-- "Temukan semua tempat yang menggunakan RemoteEvents dan petakan alur pemanggilannya."
-- "Refaktor semua script AI musuh untuk menggunakan state machine yang terpadu."
-- "Rangkum hanya perubahan berisiko yang terjadi sejak kemarin."
+Pilar kedua adalah **Project Sync**.
+AI bekerja dari mirror lokal yang tersinkron, jadi perubahan lintas banyak file tetap konsisten.
 
-Kelola beberapa Place secara bersamaan. Lacak seluruh riwayat perubahan.
+- Basic: sinkronisasi satu arah (Studio -> Local)
+- Pro: sinkronisasi dua arah + Direction/Apply Mode per tipe + riwayat + multiplace
 
-### Script: Tulis, Refaktor, Debug — File Terkait Sekaligus
+Dengan begitu sumber kebenaran tetap jelas dan konteks perubahan tidak hilang.
 
-Bukan hanya file yang kamu tunjuk. AI menangani seluruh rantai dependensi.
+## Nilai yang langsung terasa
 
-- "Saat player jump, tambahkan partikel + suara + cooldown."
-- "Temukan semua koneksi event yang bisa menyebabkan memory leak dan perbaiki dengan aman."
-- "Ubah interface modul ini dan perbarui semua script yang mereferensikannya."
+- Ringkas pekerjaan berulang: banyak edit manual jadi satu perintah
+- Ubah file terkait sekaligus: bukan hanya satu file target
+- Risiko lebih rendah: putuskan perubahan dari status sync dan riwayat
+- Efisiensi token lebih baik (Pro): kurangi bolak-balik dengan aksi massal
 
-### Buat dan Tempatkan Objek — Ratusan dengan Satu Perintah
+## Dokumen detail
 
-"Jajarkan 50 lampu jalan sepanjang jalan ini", "Tempatkan 20 rumah bata di seluruh distrik dengan rotasi acak" — AI langsung membuatnya di Studio. Perbarui properti di sejumlah objek manapun dengan satu perintah.
-
-### Pencahayaan, Cuaca, dan Atmosfer dalam Satu Kalimat
-
-"Ubah jadi padang pasir berdebu saat matahari terbenam", "Buat malam badai di mana kilat sesekali menerangi area" — satu kalimat dan pencahayaan, langit, atmosfer, serta fog semuanya berubah sekaligus.
-
-### Pahatan Terrain Melalui Percakapan
-
-"Pegunungan tebing di utara, sungai di tengah, dataran terbuka di selatan" — hasilkan lanskap apapun melalui percakapan. Kontrol material, warna, ketinggian, dan penghalusan. Bangun seluruh map tanpa menyentuh terrain editor.
-
-### Cari di Creator Store dan Langsung Pasang
-
-"Temukan model kastil abad pertengahan, taruh di tengah map, dan perbesar 1.5x" — cari asset gratis dan masukkan langsung ke proyekmu.
-
-### Kecerdasan Spasial untuk Level Design
-
-"Cari ruang kosong untuk arena bos baru", "Tampilkan hanya area yang benar-benar bisa dipatroli monster" — AI menangani penalaran spasial kompleks dan logika penempatan.
-
-### Animasi, Fisika, dan Audio sebagai Sistem yang Terhubung
-
-- "Selama animasi dash diputar, ubah aturan tabrakan player-musuh."
-- "Fade in BGM bos saat ultimate aktif, dan kembali dengan mulus saat selesai."
-
-Karakter, tabrakan, dan suara bekerja bersama sebagai sistem game, bukan alat terpisah.
-
-### Jalankan Kode Roblox Apapun Secara Langsung
-
-Ketika tools bawaan tidak cukup, AI mengeksekusi Luau sembarang di Studio.
-
-- "Temukan semua Part di Workspace dengan Anchored=false dan listkan."
-- "Perbarui objek yang cocok secara massal dan catat setiap perubahan."
-
-> [Lihat daftar lengkap](tools/overview.md)
+- [Cakupan tool (Tools Overview)](tools/overview.md)
+- [Panduan detail Sync](sync/overview.md)
 
 ## Mulai
 

package/docs/id/sync/overview.md

@@ -0,0 +1,104 @@
+# Panduan detail Sync Roblox MCP
+
+Sync menghubungkan status Roblox Studio dan file lokal agar AI bisa membaca dan memodifikasi konteks proyek secara utuh dan stabil.
+
+## Kenapa Sync penting
+
+Tanpa Sync, AI hanya melihat potongan kode yang ditempel di chat. Dengan Sync aktif, AI bekerja dari keseluruhan proyek.
+
+- Terapkan refactor lintas banyak script secara konsisten
+- Tinjau perubahan berisiko lebih cepat lewat riwayat
+- Jaga sumber kebenaran antara Studio dan file lokal tetap jelas
+
+## Cara kerjanya
+
+1. Full Sync: mirror awal dari tree/instance Studio ke lokal
+2. Incremental Sync: perubahan baru terus disinkronkan
+3. Pelacakan History/Status: cek apa yang berubah, kapan, dan ke arah mana
+
+Path lokal default adalah `roblox-project-sync/place_{placeId}/explorer`.
+
+## Basic vs Pro
+
+| Item | Basic | Pro |
+|------|------|-----|
+| Arah sync | Studio -> Local | Dua arah |
+| Direction per tipe | Tidak didukung | Didukung (Scripts / Values / Containers / Data / Services) |
+| Apply Mode per tipe | Tidak didukung | Didukung (Auto / Manual) |
+| API status/riwayat | Tidak didukung | Didukung (`status`, `history`, `progress`) |
+| Tool `manage_sync` | Tidak didukung | Didukung |
+| Sync multiplace | Tidak didukung | Didukung (hingga 3 place) |
+
+## Target sync dan aturan eksklusi default
+
+Layanan yang disinkronkan secara default:
+
+- `Workspace`
+- `Lighting`
+- `ReplicatedStorage`
+- `ServerStorage`
+- `ServerScriptService`
+- `StarterGui`
+- `StarterPlayer`
+- `StarterPack`
+- `ReplicatedFirst`
+- `SoundService`
+- `Chat`
+- `LocalizationService`
+
+Eksklusi default:
+
+- Kelas: `Terrain`, `Camera`
+- Path terlarang demi keamanan: `CoreGui`, `CorePackages`, `RobloxScript`, `RobloxScriptSecurity`
+
+## Direction dan Apply Mode
+
+### Direction (arah sync per tipe)
+
+- `forward`: Studio -> Local
+- `reverse`: Local -> Studio
+- `bidirectional`: dua arah
+
+Tipe dikelola terpisah: `scripts`, `values`, `containers`, `data`, `services`.
+
+### Apply Mode (cara menerapkan perubahan reverse)
+
+- `manual`: user konfirmasi sebelum diterapkan ke Studio
+- `auto`: perubahan terdeteksi diterapkan otomatis
+
+Di Pro, Direction dan Apply Mode bisa diatur per tipe.
+
+## Panduan aksi `manage_sync` (Pro)
+
+| Aksi | Deskripsi | Parameter utama |
+|------|------|-----------|
+| `status` | Cek status sync saat ini untuk place | `placeId` |
+| `config` | Ambil konfigurasi sync | `placeId` |
+| `history` | Ambil riwayat perubahan | `placeId`, `query.limit`, `query.offset` |
+| `directions` | Ambil Direction per tipe | `placeId` |
+| `read_file` | Baca file yang sudah tersinkron | `placeId`, `instancePath` |
+| `write_file` | Tulis file yang sudah tersinkron | `placeId`, `instancePath`, `content` |
+| `progress` | Lihat progres/throughput sync realtime | `placeId` |
+
+## Workflow yang disarankan
+
+### 1) Mulai dengan aman
+
+- Selesaikan Full Sync dulu sebagai baseline
+- Awali dengan mode `manual` untuk menurunkan risiko
+
+### 2) Bekerja dengan AI
+
+- "Cek status sync, lalu rangkum hanya perubahan berisiko dari riwayat terbaru"
+- "Refactor dulu script di `ServerScriptService` dan sertakan catatan riwayat"
+
+### 3) Pemulihan saat dibutuhkan
+
+- Lacak perubahan terbaru dengan `history`
+- Periksa file target dengan `read_file`
+- Pulihkan konten dengan `write_file`, lalu verifikasi status di Studio
+
+## Dokumen terkait
+
+- [Cakupan tool (Tools Overview)](../tools/overview.md)
+- [Panduan Upgrade Pro](../pro-upgrade.md)