@weppy/roblox-mcp 2.5.0 → 2.5.1

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Weppy Roblox MCP — MCP server that lets AI coding agents control a live Roblox Studio session with 21 tools, 140+ actions, bidirectional sync, automated playtest, and multi-place support",
-    "version": "2.5.0"
+    "version": "2.5.1"
   },
   "plugins": [
     {
       "name": "weppy-roblox-mcp",
       "source": "./plugins/weppy-roblox-mcp",
       "description": "Weppy Roblox MCP — MCP server that lets AI coding agents control a live Roblox Studio session with 21 tools, 140+ actions, bidirectional sync, automated playtest, and multi-place support",
-      "version": "2.5.0",
+      "version": "2.5.1",
       "author": {
         "name": "hope1026"
       },

package/CHANGELOG.md

@@ -10,6 +10,14 @@ All notable changes to this project will be documented in this file.
 
 
 
+
+## [2.5.1] - 2026-04-12
+
+### Bug Fixes
+
+- **Fix installer failing when run from a directory with a local `@weppy/roblox-mcp` package** — If the install script was executed from a folder where `@weppy/roblox-mcp` was already present (for example inside the package itself or under a parent `node_modules`), `npx` could pick up the shadowed local copy instead of fetching the published release, causing setup to misbehave or fail. The installer now runs `npx` inside an isolated temporary working directory, so it always resolves and installs the latest published version regardless of where you run it from.
+
+
 ## [2.5.0] - 2026-04-12
 
 ### ⚠️ BREAKING CHANGES

package/README.md

@@ -149,7 +149,8 @@ Install from [VS Code Marketplace](https://marketplace.visualstudio.com/items?it
 - [Tools Reference](docs/en/tools/overview.md)
 - [Sync Deep Dive](docs/en/sync/overview.md)
 - [WEPPY Dashboard Guide](docs/en/dashboard/overview.md)
-- [WEPPY Roblox Explorer (VSCode Extension)](docs/en/installation/roblox-explorer.md)
+- [WEPPY Roblox Explorer Guide](docs/en/explorer/overview.md)
+- [WEPPY Roblox Explorer Installation](docs/en/installation/roblox-explorer.md)
 - [Compatibility](docs/compatibility.md)
 - [Troubleshooting](docs/troubleshooting.md)
 

package/docs/en/explorer/overview.md

@@ -0,0 +1,104 @@
+# WEPPY Roblox Explorer Guide
+
+**WEPPY Roblox Explorer** is a companion VSCode/Antigravity extension that mirrors the Roblox Studio Explorer tree directly inside your editor. Browse synced instances, open scripts, and edit properties without constantly switching between Studio and your editor.
+
+> **Optional** — Explorer is not required. The MCP server and the Roblox Studio plugin are enough to use every core feature. Install Explorer when you want to browse project structure or inspect/edit properties right from your editor.
+
+![WEPPY Roblox Explorer — Studio instance tree displayed in the VSCode sidebar](../../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
+
+## Why Use Explorer
+
+AI agents can already understand the entire project context from the files generated by Sync, but when a human browses the mirror, file paths alone do not make the hierarchy obvious. Explorer reuses the same sync data and renders it as the **same tree you see in Roblox Studio**, which makes the following much easier:
+
+- See at a glance which service/instance a script belongs to
+- Quickly locate instances across services by name or path
+- Check per-file sync status (modified / studio / conflict)
+- Edit properties without switching to Studio
+
+## Requirements
+
+- VSCode 1.85+ or Antigravity
+- [Roblox MCP](../installation/README.md) installed with Sync enabled (Basic or Pro)
+- A Sync-generated `weppy-project-sync/place_*/.sync-meta.json` under your project root
+
+Explorer works purely from the on-disk sync files by default. When the local MCP server is running, live sync state and direction information are reflected as well.
+
+## Installation
+
+Search for **WEPPY Roblox Explorer** in the Extensions sidebar (`Ctrl+Shift+X` / `Cmd+Shift+X`) of VSCode or Antigravity and click **Install**.
+
+Direct marketplace links:
+
+- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=weppy.weppy-roblox-explorer)
+- [Open VSX](https://open-vsx.org/extension/weppy/weppy-roblox-explorer)
+
+## Browsing the Instance Tree
+
+After installing, a **WEPPY Explorer** view appears in the VSCode Activity Bar and auto-discovers the sync directory from your project root.
+
+- **Service roots**: Synced services such as `Workspace`, `ReplicatedStorage`, and `ServerScriptService` appear at the top level.
+- **Roblox class icons**: Over 200 Studio-style icons that switch automatically between dark and light themes.
+- **Multi-place support**: Each synced Place is shown as its own tree root when multiple places exist.
+- **Auto refresh**: The tree updates with a 500ms debounce whenever sync files change.
+- **Sync status badges**: `modified`, `studio`, and `conflict` states are shown next to icons so you can spot changes and conflicts immediately.
+
+Clicking a tree item opens the file that backs the instance (`.server.luau`, `.client.luau`, `.module.luau`, `.props.json`, ...). The right-click menu lets you copy the instance path in `game.Workspace.Part` format or reveal the backing file in the default VSCode explorer.
+
+## Property Panel
+
+Select an instance in the Explorer tree and run **Open Properties** to launch a panel that looks just like the Properties window in Studio. You can inspect and edit properties in grouped form without touching the `.props.json` file directly.
+
+![Property Panel — edit Studio-style properties inside VSCode](../../assets/screenshots/roblox-explorer/roblox-explorer-property-window.png)
+
+- **Grouped display**: Properties are sorted into the same groups as Studio (Appearance, Behavior, Data, Part, Transform, and so on).
+- **Type-aware editors**: Input widgets match the property type — numbers, strings, booleans, colors, Vector3, enums, and more.
+- **File-backed editing**: Changes are written to the instance's `*.props.json` file and flow back to Studio through Sync's reverse path (Pro, when bidirectional is enabled).
+- **Custom editor binding**: Opening a `.props.json` file directly uses the Property Panel instead of the default text editor.
+
+If you want the Property Panel to open automatically as you click around the tree, set `robloxExplorer.propertyPanel.autoOpen` to `true` in settings.
+
+## Searching Instances
+
+Run `WEPPY Explorer: Search Instances` (from the view title icon or the Command Palette) to open a QuickPick that searches across every synced service.
+
+- Partial matches against instance names
+- Selecting a result focuses the tree on the matching item
+- When multiple places are synced, results are scoped per place
+
+## Settings
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `robloxExplorer.mcpBaseUrl` | `""` | Local MCP HTTP base URL. If empty, Explorer tries `http://127.0.0.1:3002` and then `http://127.0.0.1:3003`. |
+| `robloxExplorer.syncRoot` | `""` | Absolute path to the `weppy-project-sync` root. Auto-discovered from workspace folders when empty. |
+| `robloxExplorer.hidePropsFiles` | `false` | Hide sync artifacts (`.props.json`, `_tree.json`, `.value.json`) in the default VSCode explorer. |
+| `robloxExplorer.autoRefresh` | `true` | Auto-refresh the tree when sync files change. |
+| `robloxExplorer.showSyncStatus` | `true` | Show sync status decorations on tree items. |
+| `robloxExplorer.followFocusCue` | `false` | Follow external focus cue files by best-effort tree reveal and script file open. |
+| `robloxExplorer.propertyPanel.autoOpen` | `false` | Automatically open the Property Panel when you select an instance in the tree. |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `WEPPY Explorer: Refresh` | Manually refresh the instance tree |
+| `WEPPY Explorer: Search Instances` | Search for instances across every service |
+| `WEPPY Explorer: Open Backing File` | Open the backing file for the selected instance |
+| `WEPPY Explorer: Open Properties` | Open the Property Panel for the selected instance |
+| `WEPPY Explorer: Copy Instance Path` | Copy the full instance path (e.g. `game.Workspace.Part`) |
+| `WEPPY Explorer: Reveal in Explorer` | Show the backing file in the default VSCode explorer |
+| `WEPPY Explorer: Collapse All` | Collapse every tree node |
+| `WEPPY Explorer: Open Settings` | Open the Explorer settings page |
+
+## Troubleshooting
+
+- **Tree is empty**: Check that the `weppy-project-sync/place_*` directory exists and that Sync has completed at least one Full Sync. Set `robloxExplorer.syncRoot` manually if needed.
+- **Sync status does not appear**: Make sure the local MCP server is running and try setting `robloxExplorer.mcpBaseUrl` explicitly.
+- **Property Panel does not open**: If a `.props.json` file opens in the default text editor, right-click the file and choose **Reopen Editor With... → WEPPY Property Panel**.
+- **Icons look broken**: Re-select your VSCode theme or restart the window to refresh the icon cache.
+
+## See Also
+
+- [Roblox MCP Installation Guide](../installation/README.md)
+- [Sync Guide](../sync/overview.md)
+- [Tools Overview](../tools/overview.md)

package/docs/en/sync/overview.md

@@ -24,7 +24,7 @@ Use the root path for editor integrations such as `luau-lsp`. Setup steps are co
 
 ### Browse sync data in VSCode
 
-Install the [WEPPY Roblox Explorer](../installation/roblox-explorer.md) extension to browse the synced instance tree in VSCode, just like in Roblox Studio.
+Install the [WEPPY Roblox Explorer](../explorer/overview.md) extension to browse the synced instance tree in VSCode, just like in Roblox Studio.
 Explorer reads the sync files generated here, and it can show additional live sync state or direction details when the local MCP server is running.
 
 ![WEPPY Roblox Explorer — browse synced instance tree in VSCode](../../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)

package/docs/es/README.md

@@ -149,7 +149,8 @@ Instálalo desde [VS Code Marketplace](https://marketplace.visualstudio.com/item
 - [Lista completa de tools](tools/overview.md)
 - [Guia detallada de Sync](sync/overview.md)
 - [Guia del Dashboard](dashboard/overview.md)
-- [WEPPY Roblox Explorer (Extension VSCode)](installation/roblox-explorer.md)
+- [Guia detallada de WEPPY Roblox Explorer](explorer/overview.md)
+- [Instalacion de WEPPY Roblox Explorer](installation/roblox-explorer.md)
 - [Compatibilidad](../compatibility.md)
 - [Solucion de problemas](../troubleshooting.md)
 

package/docs/es/explorer/overview.md

@@ -0,0 +1,104 @@
+# Guia detallada de WEPPY Roblox Explorer
+
+**WEPPY Roblox Explorer** es una extension complementaria para VSCode / Antigravity que replica el arbol del Explorer de Roblox Studio dentro de tu editor. Explora instancias sincronizadas, abre scripts y edita propiedades sin tener que alternar entre Studio y el editor.
+
+> **Opcional** — Explorer no es obligatorio. El servidor MCP y el plugin de Roblox Studio son suficientes para usar todas las funciones principales. Instala Explorer cuando quieras navegar la estructura del proyecto o revisar y editar propiedades directamente desde tu editor.
+
+![WEPPY Roblox Explorer — arbol de instancias de Studio en la barra lateral de VSCode](../../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
+
+## Por que usar Explorer
+
+Los agentes de IA pueden entender el contexto completo del proyecto a partir de los archivos generados por Sync, pero cuando una persona explora el mirror directamente, las rutas de archivo por si solas no siempre dejan clara la jerarquia. Explorer reutiliza los mismos datos de sync y los presenta con la **misma estructura que ves en Roblox Studio**, lo que facilita:
+
+- Ver de un vistazo a que servicio / instancia pertenece cada script
+- Localizar rapidamente instancias entre servicios por nombre o ruta
+- Revisar el estado de sincronizacion por archivo (modified / studio / conflict)
+- Editar propiedades sin tener que abrir Studio
+
+## Requisitos
+
+- VSCode 1.85+ o Antigravity
+- [Roblox MCP](../installation/README.md) instalado con Sync habilitado (Basic o Pro)
+- Un archivo `weppy-project-sync/place_*/.sync-meta.json` generado por Sync bajo la raiz de tu proyecto
+
+Explorer funciona usando solo los archivos de sync en disco. Cuando el servidor MCP local esta en ejecucion, tambien se reflejan el estado de sync en vivo y la informacion de direction.
+
+## Instalacion
+
+Busca **WEPPY Roblox Explorer** en la barra lateral de Extensions (`Ctrl+Shift+X` / `Cmd+Shift+X`) de VSCode o Antigravity y haz clic en **Install**.
+
+Enlaces directos al marketplace:
+
+- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=weppy.weppy-roblox-explorer)
+- [Open VSX](https://open-vsx.org/extension/weppy/weppy-roblox-explorer)
+
+## Navegar el arbol de instancias
+
+Despues de la instalacion aparece una vista **WEPPY Explorer** en la Activity Bar de VSCode que detecta automaticamente el directorio de sync desde la raiz del proyecto.
+
+- **Raices de servicios**: Los servicios sincronizados como `Workspace`, `ReplicatedStorage` y `ServerScriptService` aparecen en el nivel superior.
+- **Iconos de clases Roblox**: Mas de 200 iconos al estilo Studio que cambian automaticamente entre tema oscuro y claro.
+- **Multi Place**: Cada Place sincronizado se muestra con su propia raiz de arbol cuando hay mas de uno.
+- **Actualizacion automatica**: El arbol se actualiza con un debounce de 500ms cuando los archivos de sync cambian.
+- **Insignias de estado sync**: Los estados `modified`, `studio` y `conflict` aparecen junto al icono para detectar cambios y conflictos al instante.
+
+Al hacer clic en un elemento del arbol se abre el archivo que respalda la instancia (`.server.luau`, `.client.luau`, `.module.luau`, `.props.json`, ...). El menu contextual permite copiar la ruta de la instancia en formato `game.Workspace.Part` o mostrar el archivo en el explorador predeterminado de VSCode.
+
+## Panel de propiedades
+
+Selecciona una instancia en el arbol del Explorer y ejecuta **Open Properties** para abrir un panel que se ve como la ventana Properties de Studio. Puedes inspeccionar y editar propiedades agrupadas sin tocar directamente el archivo `.props.json`.
+
+![Panel de propiedades — edita propiedades al estilo Studio dentro de VSCode](../../assets/screenshots/roblox-explorer/roblox-explorer-property-window.png)
+
+- **Vista agrupada**: Las propiedades se ordenan en los mismos grupos que usa Studio (Appearance, Behavior, Data, Part, Transform, etc.).
+- **Editores por tipo**: Los controles de entrada se adaptan al tipo de la propiedad: numeros, cadenas, booleanos, colores, Vector3, enums y mas.
+- **Edicion basada en archivos**: Los cambios se guardan en el archivo `*.props.json` de la instancia y se propagan a Studio a traves del camino reverso de Sync (Pro, cuando bidirectional esta habilitado).
+- **Editor personalizado**: Abrir un archivo `.props.json` directamente carga el Panel de propiedades en lugar del editor de texto predeterminado.
+
+Si quieres que el Panel de propiedades se abra automaticamente al navegar el arbol, cambia `robloxExplorer.propertyPanel.autoOpen` a `true` en la configuracion.
+
+## Busqueda de instancias
+
+Ejecuta el comando `WEPPY Explorer: Search Instances` (desde el icono del encabezado de la vista o la Command Palette) para abrir un QuickPick que busca a traves de todos los servicios sincronizados.
+
+- Coincidencias parciales sobre los nombres de instancia
+- Seleccionar un resultado enfoca el arbol en el elemento correspondiente
+- Cuando hay varios places sincronizados, los resultados se limitan por place
+
+## Configuracion
+
+| Ajuste | Valor por defecto | Descripcion |
+|--------|-------------------|-------------|
+| `robloxExplorer.mcpBaseUrl` | `""` | URL HTTP base del MCP local. Si esta vacio, Explorer prueba `http://127.0.0.1:3002` y luego `http://127.0.0.1:3003`. |
+| `robloxExplorer.syncRoot` | `""` | Ruta absoluta a la raiz `weppy-project-sync`. Se detecta desde las carpetas del workspace si esta vacia. |
+| `robloxExplorer.hidePropsFiles` | `false` | Oculta los archivos de sync (`.props.json`, `_tree.json`, `.value.json`) en el explorador predeterminado de VSCode. |
+| `robloxExplorer.autoRefresh` | `true` | Actualiza el arbol automaticamente cuando cambian los archivos de sync. |
+| `robloxExplorer.showSyncStatus` | `true` | Muestra decoraciones de estado de sync en los elementos del arbol. |
+| `robloxExplorer.followFocusCue` | `false` | Sigue archivos externos de focus cue para expandir el arbol y abrir archivos relacionados. |
+| `robloxExplorer.propertyPanel.autoOpen` | `false` | Abre automaticamente el Panel de propiedades al seleccionar una instancia en el arbol. |
+
+## Comandos
+
+| Comando | Descripcion |
+|---------|-------------|
+| `WEPPY Explorer: Refresh` | Refresca manualmente el arbol de instancias |
+| `WEPPY Explorer: Search Instances` | Busca instancias a traves de todos los servicios |
+| `WEPPY Explorer: Open Backing File` | Abre el archivo de la instancia seleccionada |
+| `WEPPY Explorer: Open Properties` | Abre el Panel de propiedades de la instancia seleccionada |
+| `WEPPY Explorer: Copy Instance Path` | Copia la ruta completa de la instancia (p. ej. `game.Workspace.Part`) |
+| `WEPPY Explorer: Reveal in Explorer` | Muestra el archivo en el explorador predeterminado de VSCode |
+| `WEPPY Explorer: Collapse All` | Contrae todos los nodos del arbol |
+| `WEPPY Explorer: Open Settings` | Abre la pagina de ajustes de Explorer |
+
+## Resolucion de problemas
+
+- **El arbol esta vacio**: Verifica que exista el directorio `weppy-project-sync/place_*` y que Sync haya completado al menos un Full Sync. Define `robloxExplorer.syncRoot` manualmente si es necesario.
+- **No aparece el estado de sync**: Asegurate de que el servidor MCP local este en ejecucion y prueba a configurar `robloxExplorer.mcpBaseUrl` de forma explicita.
+- **El Panel de propiedades no se abre**: Si un archivo `.props.json` se abre en el editor de texto predeterminado, haz clic derecho sobre el y elige **Reopen Editor With... → WEPPY Property Panel**.
+- **Los iconos se ven rotos**: Vuelve a seleccionar el tema de VSCode o reinicia la ventana para refrescar la cache de iconos.
+
+## Documentos relacionados
+
+- [Guia de instalacion de Roblox MCP](../installation/README.md)
+- [Guia de Sync](../sync/overview.md)
+- [Resumen de herramientas](../tools/overview.md)

package/docs/es/sync/overview.md

@@ -24,7 +24,7 @@ Para integraciones de editor como `luau-lsp`, se recomienda usar la ruta de la r
 
 ### Explorar datos sincronizados en VSCode
 
-Instala la extension [WEPPY Roblox Explorer](../installation/roblox-explorer.md) para explorar el arbol de instancias sincronizado en VSCode, igual que en Roblox Studio.
+Instala la extension [WEPPY Roblox Explorer](../explorer/overview.md) para explorar el arbol de instancias sincronizado en VSCode, igual que en Roblox Studio.
 Explorer lee los archivos sync generados aqui, y puede mostrar ademas estado sync en vivo e informacion de direction cuando el servidor MCP local esta en ejecucion.
 
 ![WEPPY Roblox Explorer — explorar el arbol de instancias sincronizado en VSCode](../../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)

package/docs/id/README.md

@@ -149,7 +149,8 @@ Instal dari [VS Code Marketplace](https://marketplace.visualstudio.com/items?ite
 - [Daftar tool lengkap](tools/overview.md)
 - [Panduan detail Sync](sync/overview.md)
 - [Panduan dashboard](dashboard/overview.md)
-- [WEPPY Roblox Explorer (Ekstensi VSCode)](installation/roblox-explorer.md)
+- [Panduan lengkap WEPPY Roblox Explorer](explorer/overview.md)
+- [Instalasi WEPPY Roblox Explorer](installation/roblox-explorer.md)
 - [Kompatibilitas](../compatibility.md)
 - [Panduan pemecahan masalah](../troubleshooting.md)
 

package/docs/id/explorer/overview.md

@@ -0,0 +1,104 @@
+# Panduan Lengkap WEPPY Roblox Explorer
+
+**WEPPY Roblox Explorer** adalah ekstensi pendamping VSCode / Antigravity yang menampilkan tree Explorer dari Roblox Studio langsung di editor kamu. Jelajahi instance yang tersinkron, buka script, dan edit property tanpa harus bolak-balik antara Studio dan editor.
+
+> **Opsional** — Explorer bukan kewajiban. Server MCP dan plugin Roblox Studio sudah cukup untuk semua fitur inti. Instal Explorer jika kamu ingin menjelajahi struktur project atau memeriksa dan mengedit property langsung dari editor.
+
+![WEPPY Roblox Explorer — tree instance Studio tampil di sidebar VSCode](../../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
+
+## Kenapa pakai Explorer
+
+Agen AI sudah bisa memahami konteks project secara penuh dari file yang dihasilkan Sync, tapi saat manusia menjelajah mirror secara langsung, path file saja belum tentu memperlihatkan hierarki dengan jelas. Explorer memakai ulang data sync yang sama dan menyajikannya dalam **tree yang sama persis seperti di Roblox Studio**, sehingga hal berikut jadi jauh lebih mudah:
+
+- Melihat sekaligus script itu berada di service / instance mana
+- Menemukan instance lintas service berdasarkan nama atau path dengan cepat
+- Memeriksa status sync per file (modified / studio / conflict)
+- Mengedit property tanpa membuka Studio
+
+## Persyaratan
+
+- VSCode 1.85+ atau Antigravity
+- [Roblox MCP](../installation/README.md) sudah terpasang dengan Sync aktif (Basic atau Pro)
+- File `weppy-project-sync/place_*/.sync-meta.json` hasil Sync berada di root project
+
+Explorer secara default bekerja hanya dengan file sync di disk. Jika server MCP lokal sedang berjalan, status sync live dan informasi direction ikut direfleksikan.
+
+## Cara instal
+
+Cari **WEPPY Roblox Explorer** di sidebar Extensions (`Ctrl+Shift+X` / `Cmd+Shift+X`) pada VSCode atau Antigravity lalu klik **Install**.
+
+Link marketplace langsung:
+
+- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=weppy.weppy-roblox-explorer)
+- [Open VSX](https://open-vsx.org/extension/weppy/weppy-roblox-explorer)
+
+## Menjelajahi tree instance
+
+Setelah instal, tampilan **WEPPY Explorer** akan muncul di Activity Bar VSCode dan secara otomatis menemukan direktori sync dari root project.
+
+- **Akar service**: Service yang tersinkron seperti `Workspace`, `ReplicatedStorage`, dan `ServerScriptService` ditampilkan di level atas.
+- **Ikon kelas Roblox**: Lebih dari 200 ikon bergaya Studio yang otomatis menyesuaikan antara tema gelap dan terang.
+- **Multi Place**: Setiap Place yang tersinkron ditampilkan sebagai root tree terpisah ketika ada beberapa place.
+- **Auto refresh**: Tree diperbarui dengan debounce 500ms setiap kali file sync berubah.
+- **Badge status sync**: Status `modified`, `studio`, dan `conflict` muncul di samping ikon supaya perubahan dan konflik langsung terlihat.
+
+Meng-klik item di tree akan membuka file yang menopang instance tersebut (`.server.luau`, `.client.luau`, `.module.luau`, `.props.json`, ...). Menu klik-kanan memungkinkan menyalin path instance dalam format `game.Workspace.Part` atau menampilkan file di explorer bawaan VSCode.
+
+## Property Panel
+
+Pilih sebuah instance di tree Explorer lalu jalankan perintah **Open Properties** untuk membuka panel yang mirip jendela Properties pada Studio. Kamu bisa melihat dan mengedit property dalam bentuk berkelompok tanpa menyentuh file `.props.json` secara langsung.
+
+![Property Panel — edit property bergaya Studio di dalam VSCode](../../assets/screenshots/roblox-explorer/roblox-explorer-property-window.png)
+
+- **Tampilan berkelompok**: Property diurutkan dalam grup yang sama seperti di Studio (Appearance, Behavior, Data, Part, Transform, dan lain-lain).
+- **Editor sesuai tipe**: Widget input menyesuaikan dengan tipe property — angka, string, boolean, warna, Vector3, enum, dan lainnya.
+- **Editing berbasis file**: Perubahan disimpan ke file `*.props.json` milik instance dan mengalir kembali ke Studio lewat jalur reverse Sync (Pro, saat bidirectional aktif).
+- **Custom editor**: Membuka file `.props.json` secara langsung akan memakai Property Panel alih-alih editor teks bawaan.
+
+Kalau mau Property Panel terbuka otomatis saat kamu memilih instance di tree, ubah `robloxExplorer.propertyPanel.autoOpen` menjadi `true` di pengaturan.
+
+## Pencarian instance
+
+Jalankan perintah `WEPPY Explorer: Search Instances` (dari ikon judul view atau Command Palette) untuk membuka QuickPick yang mencari di seluruh service tersinkron.
+
+- Pencocokan sebagian terhadap nama instance
+- Memilih hasil akan memfokuskan tree ke item yang sesuai
+- Ketika beberapa place tersinkron, hasil dibatasi per place
+
+## Pengaturan
+
+| Pengaturan | Default | Deskripsi |
+|------------|---------|-----------|
+| `robloxExplorer.mcpBaseUrl` | `""` | URL HTTP base MCP lokal. Kosong berarti Explorer mencoba `http://127.0.0.1:3002` lalu `http://127.0.0.1:3003`. |
+| `robloxExplorer.syncRoot` | `""` | Path absolut ke root `weppy-project-sync`. Dideteksi otomatis dari folder workspace saat kosong. |
+| `robloxExplorer.hidePropsFiles` | `false` | Sembunyikan file sync (`.props.json`, `_tree.json`, `.value.json`) di explorer bawaan VSCode. |
+| `robloxExplorer.autoRefresh` | `true` | Perbarui tree otomatis saat file sync berubah. |
+| `robloxExplorer.showSyncStatus` | `true` | Tampilkan dekorasi status sync di item tree. |
+| `robloxExplorer.followFocusCue` | `false` | Ikuti file focus cue eksternal untuk membuka tree dan file terkait. |
+| `robloxExplorer.propertyPanel.autoOpen` | `false` | Buka Property Panel otomatis ketika memilih instance di tree. |
+
+## Perintah
+
+| Perintah | Deskripsi |
+|----------|-----------|
+| `WEPPY Explorer: Refresh` | Segarkan tree instance secara manual |
+| `WEPPY Explorer: Search Instances` | Cari instance di seluruh service |
+| `WEPPY Explorer: Open Backing File` | Buka file pendukung dari instance terpilih |
+| `WEPPY Explorer: Open Properties` | Buka Property Panel untuk instance terpilih |
+| `WEPPY Explorer: Copy Instance Path` | Salin path instance lengkap (mis. `game.Workspace.Part`) |
+| `WEPPY Explorer: Reveal in Explorer` | Tampilkan file di explorer bawaan VSCode |
+| `WEPPY Explorer: Collapse All` | Tutup semua node pada tree |
+| `WEPPY Explorer: Open Settings` | Buka halaman pengaturan Explorer |
+
+## Pemecahan masalah
+
+- **Tree kosong**: Pastikan direktori `weppy-project-sync/place_*` ada dan Sync sudah menyelesaikan minimal satu Full Sync. Atur `robloxExplorer.syncRoot` secara manual bila perlu.
+- **Status sync tidak muncul**: Pastikan server MCP lokal sedang berjalan dan coba set `robloxExplorer.mcpBaseUrl` secara eksplisit.
+- **Property Panel tidak terbuka**: Jika file `.props.json` terbuka di editor teks bawaan, klik kanan file itu lalu pilih **Reopen Editor With... → WEPPY Property Panel**.
+- **Ikon rusak**: Pilih ulang tema VSCode atau restart window agar cache ikon diperbarui.
+
+## Dokumen terkait
+
+- [Panduan instalasi Roblox MCP](../installation/README.md)
+- [Panduan Sync](../sync/overview.md)
+- [Tinjauan Tools](../tools/overview.md)

package/docs/id/sync/overview.md

@@ -24,7 +24,7 @@ Untuk integrasi editor seperti `luau-lsp`, sebaiknya gunakan path root. Langkah
 
 ### Jelajahi data sync di VSCode
 
-Instal ekstensi [WEPPY Roblox Explorer](../installation/roblox-explorer.md) untuk menjelajahi tree instance yang sudah tersinkron di VSCode, seperti di Roblox Studio.
+Instal ekstensi [WEPPY Roblox Explorer](../explorer/overview.md) untuk menjelajahi tree instance yang sudah tersinkron di VSCode, seperti di Roblox Studio.
 Explorer membaca file sync yang dihasilkan di sini, dan juga bisa menampilkan status sync live serta informasi direction saat server MCP lokal sedang berjalan.
 
 ![WEPPY Roblox Explorer — jelajahi tree instance yang tersinkron di VSCode](../../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)

package/docs/ja/README.md

@@ -147,7 +147,8 @@ WEPPY Roblox Explorerは、WEPPYが生成するsyncデータを扱うcompanion V
 - [Tool一覧](tools/overview.md)
 - [Sync機能詳細ガイド](sync/overview.md)
 - [WEPPY Dashboard ガイド](dashboard/overview.md)
-- [WEPPY Roblox Explorer (VSCode拡張)](installation/roblox-explorer.md)
+- [WEPPY Roblox Explorer 詳細ガイド](explorer/overview.md)
+- [WEPPY Roblox Explorer インストール](installation/roblox-explorer.md)
 - [互換性](../compatibility.md)
 - [トラブルシューティング](../troubleshooting.md)
 

package/docs/ja/explorer/overview.md

@@ -0,0 +1,104 @@
+# WEPPY Roblox Explorer 詳細ガイド
+
+**WEPPY Roblox Explorer** は、Roblox Studio の Explorer ツリーを VSCode / Antigravity などのエディタ内で同じ形で表示する companion 拡張機能です。Studio とローカルを行き来することなく、同期済みインスタンス階層を閲覧し、スクリプトを開き、プロパティを編集できます。
+
+> **任意** — Explorer は必須ではありません。MCP サーバーと Roblox Studio プラグインだけで、すべてのコア機能を利用できます。エディタ内でプロジェクト構造を閲覧したり、プロパティをすばやく確認・編集したい場合にインストールしてください。
+
+![WEPPY Roblox Explorer — VSCode サイドバーに表示される Studio インスタンスツリー](../../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
+
+## なぜ Explorer を使うのか
+
+Sync が生成するファイルだけで AI はプロジェクト全体の文脈を理解できますが、人間が直接閲覧するときはファイルパスだけでは構造が把握しづらいことがあります。Explorer は同じ sync データを **Roblox Studio と同じ階層構造** で再表示するため、次のような作業が楽になります。
+
+- スクリプトがどのサービス / インスタンス配下にあるかを一目で把握
+- 複数のサービスにまたがるインスタンスを名前・パスですばやく検索
+- 同期状態 (modified / studio / conflict) をファイル単位で確認
+- Studio に切り替えずにプロパティを編集
+
+## 必要要件
+
+- VSCode 1.85+ または Antigravity
+- [Roblox MCP](../installation/README.md) をインストールし Sync を有効化 (Basic または Pro)
+- プロジェクトルート以下に Sync が生成した `weppy-project-sync/place_*/.sync-meta.json` が存在すること
+
+Explorer は基本的にディスク上の sync ファイルだけで動作し、ローカル MCP サーバーが動作中であれば、リアルタイムの sync 状態と direction 情報もあわせて反映されます。
+
+## インストール方法
+
+VSCode または Antigravity の Extensions サイドバー (`Ctrl+Shift+X` / `Cmd+Shift+X`) で **WEPPY Roblox Explorer** を検索し、**Install** をクリックしてください。
+
+マーケットプレース直接リンク:
+
+- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=weppy.weppy-roblox-explorer)
+- [Open VSX](https://open-vsx.org/extension/weppy/weppy-roblox-explorer)
+
+## インスタンスツリーの閲覧
+
+インストール後、VSCode の Activity Bar に **WEPPY Explorer** ビューが追加され、プロジェクトルートから sync ディレクトリを自動検出します。
+
+- **サービスルート**: `Workspace`、`ReplicatedStorage`、`ServerScriptService` など、同期対象のサービスが最上位に表示されます。
+- **Roblox クラスアイコン**: 200 以上の Studio アイコンが、ダーク / ライトテーマに応じて自動で切り替わります。
+- **マルチ Place**: 複数 Place が同期されている場合、Place ごとに独立したツリールートとして表示されます。
+- **自動更新**: sync ファイルが変更されると 500ms のデバウンスでツリーが自動更新されます。
+- **Sync 状態バッジ**: `modified`、`studio`、`conflict` の状態がアイコン横に表示され、変更や競合をすぐに確認できます。
+
+ツリー上でアイテムをクリックすると、そのインスタンスを構成するファイル (`.server.luau`、`.client.luau`、`.module.luau`、`.props.json` など) が開きます。右クリックメニューから `game.Workspace.Part` 形式でインスタンスパスをコピーしたり、デフォルトの VSCode エクスプローラーでファイル位置を表示したりできます。
+
+## Property Panel
+
+Explorer ツリーでインスタンスを選択し、**Open Properties** コマンドを実行すると、Studio の Properties ウィンドウと同じ形式のパネルが開きます。`.props.json` ファイルを直接編集することなく、グループ化された形でプロパティを確認・編集できます。
+
+![Property Panel — VSCode 内で Studio と同じプロパティ編集画面を利用](../../assets/screenshots/roblox-explorer/roblox-explorer-property-window.png)
+
+- **グループ別表示**: Appearance、Behavior、Data、Part、Transform など、Studio と同じ分類でプロパティが整理されます。
+- **型対応エディタ**: 数値、文字列、Boolean、Color、Vector3、Enum などプロパティの型に合わせた入力ウィジェットが提供されます。
+- **ファイルベース編集**: 変更内容は該当インスタンスの `*.props.json` ファイルに保存され、Sync の reverse 経路を通じて Studio へ反映されます (Pro, bidirectional 設定時)。
+- **カスタムエディタ登録**: `.props.json` ファイルを直接開くと、デフォルトのエディタではなく Property Panel が自動的に起動します。
+
+ツリー操作中に自動で Property Panel を開きたい場合は、設定で `robloxExplorer.propertyPanel.autoOpen` を `true` に変更してください。
+
+## インスタンス検索
+
+`WEPPY Explorer: Search Instances` コマンド (ビュー上部アイコンまたはコマンドパレット) を使うと、すべてのサービスにまたがって QuickPick 検索を実行できます。
+
+- インスタンス名の部分一致で高速に検索
+- 結果を選択するとツリー上の該当項目にフォーカスが移動
+- 複数 Place が同期されている場合は Place 単位で検索結果が分離
+
+## 設定
+
+| 設定 | デフォルト | 説明 |
+|------|--------|------|
+| `robloxExplorer.mcpBaseUrl` | `""` | ローカル MCP HTTP のベース URL。空の場合は `http://127.0.0.1:3002`、`http://127.0.0.1:3003` の順に試行します。 |
+| `robloxExplorer.syncRoot` | `""` | `weppy-project-sync` ルートの絶対パス。空の場合はワークスペースフォルダから自動検出します。 |
+| `robloxExplorer.hidePropsFiles` | `false` | デフォルトの VSCode エクスプローラーで sync ファイル (`.props.json`、`_tree.json`、`.value.json`) を非表示にします。 |
+| `robloxExplorer.autoRefresh` | `true` | sync ファイル変更時にツリーを自動更新します。 |
+| `robloxExplorer.showSyncStatus` | `true` | ツリー項目に sync 状態バッジを表示します。 |
+| `robloxExplorer.followFocusCue` | `false` | 外部 focus cue ファイルに従ってツリーを自動展開し、関連ファイルを開きます。 |
+| `robloxExplorer.propertyPanel.autoOpen` | `false` | ツリーでインスタンスを選択したときに Property Panel を自動で開きます。 |
+
+## コマンド
+
+| コマンド | 説明 |
+|--------|------|
+| `WEPPY Explorer: Refresh` | インスタンスツリーを手動で更新 |
+| `WEPPY Explorer: Search Instances` | すべてのサービスでインスタンスを検索 |
+| `WEPPY Explorer: Open Backing File` | 選択したインスタンスの backing ファイルを開く |
+| `WEPPY Explorer: Open Properties` | 選択したインスタンスの Property Panel を開く |
+| `WEPPY Explorer: Copy Instance Path` | 完全なインスタンスパスをコピー (例: `game.Workspace.Part`) |
+| `WEPPY Explorer: Reveal in Explorer` | デフォルトの VSCode エクスプローラーでファイル位置を表示 |
+| `WEPPY Explorer: Collapse All` | ツリーのすべてのノードを折りたたむ |
+| `WEPPY Explorer: Open Settings` | Explorer 設定ページを開く |
+
+## トラブルシューティング
+
+- **ツリーが空**: `weppy-project-sync/place_*` ディレクトリが存在し、Sync が少なくとも 1 回 Full Sync を完了しているか確認してください。必要であれば `robloxExplorer.syncRoot` を手動で指定します。
+- **Sync 状態が表示されない**: ローカル MCP サーバーが動作中か確認し、`robloxExplorer.mcpBaseUrl` を明示的に設定してみてください。
+- **Property Panel が開かない**: `.props.json` ファイルがデフォルトエディタで開く場合、ファイルを右クリックして **Reopen Editor With... → WEPPY Property Panel** を選択してください。
+- **アイコンが崩れる**: VSCode のテーマを選び直すか、ウィンドウを再起動してアイコンキャッシュを更新してください。
+
+## 関連ドキュメント
+
+- [Roblox MCP インストールガイド](../installation/README.md)
+- [Sync ガイド](../sync/overview.md)
+- [Tools 概要](../tools/overview.md)

package/docs/ja/sync/overview.md

@@ -24,7 +24,7 @@ Sync データは `{projectRoot}/weppy-project-sync/place_{placeId}/explorer`
 
 ### VSCodeで同期データを閲覧する
 
-[WEPPY Roblox Explorer](../installation/roblox-explorer.md) 拡張機能をインストールすると、Roblox Studioと同じようにVSCode上で同期済みインスタンスツリーを閲覧できます。
+[WEPPY Roblox Explorer](../explorer/overview.md) 拡張機能をインストールすると、Roblox Studioと同じようにVSCode上で同期済みインスタンスツリーを閲覧できます。
 Explorerはここで生成されたsyncファイルを読み取り、ローカルMCPサーバーが動作中なら追加でlive sync状態とdirection情報も表示できます。
 
 ![WEPPY Roblox Explorer — VSCodeで同期済みインスタンスツリーを閲覧](../../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)

package/docs/ko/README.md

@@ -147,7 +147,8 @@ WEPPY Roblox Explorer는 WEPPY가 생성한 sync 데이터를 위한 companion V
 - [Tool 전체 목록](tools/overview.md)
 - [Sync 기능 상세 가이드](sync/overview.md)
 - [WEPPY Dashboard 가이드](dashboard/overview.md)
-- [WEPPY Roblox Explorer (VSCode 확장)](installation/roblox-explorer.md)
+- [WEPPY Roblox Explorer 상세 가이드](explorer/overview.md)
+- [WEPPY Roblox Explorer 설치](installation/roblox-explorer.md)
 - [호환성](../compatibility.md)
 - [문제 해결 가이드](../troubleshooting.md)