@weppy/roblox-mcp 2.0.9 → 2.1.0

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.0.9"
+    "version": "2.1.0"
   },
   "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.0.9",
+      "version": "2.1.0",
       "author": {
         "name": "hope1026"
       },

package/CHANGELOG.md

@@ -21,6 +21,45 @@ All notable changes to this project will be documented in this file.
 
 
 
+
+
+## [2.1.0] - 2026-03-29
+
+### ⚠️ BREAKING CHANGES
+
+- **Sync directory renamed**: `roblox-project-sync/` → `wrox-project-sync/`. All existing sync data will be stored under the new directory. The old `roblox-project-sync/` directory is no longer used.
+- **App data directory renamed**: `~/.weppy-roblox-mcp` → `~/.wrox-data`. The old `~/.weppy-roblox-mcp` directory is no longer recognized.
+- **Project sync resets from Studio**: After upgrading, project sync data is re-initialized from Studio as the source of truth. Any local-only changes not yet synced back to Studio will be lost — ensure your Studio state is up to date before upgrading.
+- **License downgrade requires plugin action**: If your license changes from Pro to Basic, you **must** click "Refresh" in the plugin UI or deactivate and reactivate the plugin for the tier change to take effect. Without this step, the plugin may continue to report the previous tier.
+
+### Features
+
+- **Dashboard project root switching**: Added the ability to change the project root directory directly from the Dashboard overview page, with restart and path migration support.
+- **Dashboard Place UI improvements**: Redesigned the Place summary display for better visual clarity and usability.
+- Dashboard place summary API and persistence for active project state
+- Sync root switch flow with configurable overrides and path migration
+
+### Bug Fixes
+
+- Harden sync-root switching with error handling and fallback resolution
+- Preserve and surface dashboard sync-root restart errors
+- Normalize observability sync roots and honor override root in runtime paths
+- Cover remaining wrox runtime paths
+
+### Documentation
+
+- Expand documentation with project rationale, use cases, FAQ, and license details across all locales
+- Update sync data path documentation to reflect project-root-based storage
+
+
+## [2.0.10] - 2026-03-28
+
+### Improved
+
+- Improved sync logic with play mode detection, suppression, and post-play reconciliation.
+- Enhanced plugin UI for sync collision resolution.
+
+
 ## [2.0.9] - 2026-03-27
 
 ### Improved

package/README.md

@@ -8,13 +8,13 @@
 
 [![Demo — AI building a Roblox game in real time](https://img.youtube.com/vi/3jrUpBbZPaw/maxresdefault.jpg)](https://youtu.be/3jrUpBbZPaw)
 
-## Why WROX?
+## Why WROX (Weppy Roblox MCP)?
 
 AI coding agents like Claude, Codex, and Gemini are powerful — but they cannot see or modify anything inside Roblox Studio. The DataModel, scripts, terrain, and lighting are all invisible to external tools. Without a bridge, AI can only generate code snippets that you must paste manually.
 
-**WROX** provides a real-time bridge between AI agents and the Roblox Studio DataModel. It exposes the full Roblox API surface as executable MCP tools, so AI can **directly create, read, modify, and delete** instances, scripts, properties, terrain, and more — inside a live Studio session.
+**WROX** is a bridge between AI agents and Roblox Studio. AI directly creates and modifies instances, scripts, properties, terrain, and more inside Studio, and the changes are reflected immediately in Studio and the dashboard so you can **see exactly what changed**.
 
-This is not just code generation. It is **executable, production-oriented actions** running directly in Studio.
+No copy-pasting code. AI does the work, you review the results.
 
 ## Quick Install
 
@@ -88,11 +88,11 @@ AI can directly handle scripts, instances, properties, terrain, lighting, assets
 
 AI works from a synchronized local mirror, so multi-file updates stay consistent.
 
-![Sync workflow — Studio and local files synchronized in real time](docs/assets/screenshots/sync.png)
-
 - Basic: one-way sync (Studio -> Local)
 - Pro: bidirectional sync + per-type Direction/Apply Mode + history + multi-place
 
+![Sync workflow — Studio and local files synchronized in real time](docs/assets/screenshots/plugin/sync/sync-overview.png)
+
 ### 3) Playtest: Let AI run and verify tests automatically
 
 AI can control Roblox Studio playtests directly. It can start and stop Play (F5) or Run (F8), inject test scripts, collect logs, and generate local reports automatically.
@@ -101,28 +101,30 @@ AI can control Roblox Studio playtests directly. It can start and stop Play (F5)
 - "Write a test that verifies the SpawnLocation is above the ground and run it."
 - "Validate that the script I just changed runs without errors in playtest."
 
+![WROX Playtest Dashboard — Test history and detailed report](docs/assets/screenshots/dashboard/dashboard_playtest.png)
+
 ### 4) WROX Dashboard: Monitor AI work in real time
 
 The MCP server provides a web dashboard where you can check connection status, tool execution history, sync state, and game change logs in real time.
 
-![WROX WROX Dashboard Overview — Server status, recent changes, and session summary](docs/assets/screenshots/dashboard/dashboard_overview.png)
-
 - Server/Plugin/Agent connection status at a glance
 - Compare every change the AI made via Before & After in Changelog
 - Analyze workflow with tool execution history and statistics
 
+![WROX WROX Dashboard Overview — Server status, recent changes, and session summary](docs/assets/screenshots/dashboard/dashboard_overview.png)
+
 ### 5) WROX Roblox Explorer: Browse Studio hierarchy in VSCode
 
 View the full instance tree of your Roblox Studio place directly inside VSCode. Navigate services, open synced scripts and property files, and track sync status — all without switching to Studio.
 WROX Roblox Explorer is a companion VSCode extension for sync data generated by WROX. Tree browsing works from synced files, and live sync state or direction indicators are enhanced when the local MCP server is running.
 Install from [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=weppy.weppy-roblox-explorer) or [Open VSX](https://open-vsx.org/extension/weppy/weppy-roblox-explorer).
 
-![WROX Roblox Explorer — Studio instance tree displayed in VSCode sidebar](docs/assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
-
 - Class icons matching Studio for instant recognition
 - Click to open synced scripts and property files
 - Multi-place support with sync status indicators
 
+![WROX Roblox Explorer — Studio instance tree displayed in VSCode sidebar](docs/assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
+
 ## Use Cases
 
 - **Rapid prototyping**: Describe a game mechanic in natural language and watch AI build it in Studio

package/docs/en/dashboard/connection.md

@@ -6,7 +6,7 @@
 
 ## Overview
 
-The Connection page lets you monitor all connection states of the MCP system in one place. It is accessible whenever the server is connected (L1 or above).
+The Connection page lets you monitor all connection states of the MCP system in one place. It is accessible whenever the dashboard is in the **Server connected** or **Studio connected** state.
 
 ## Server Status
 

package/docs/en/dashboard/overview.md

@@ -34,17 +34,17 @@ http://localhost:3002
 
 > Set `DASHBOARD_AUTO_OPEN=false` to disable automatic opening (see the [Settings](settings.md) page).
 
-## Connection Levels
+## Connection States
 
 The features available in the dashboard depend on the connection state:
 
-| Level | Condition | Available Pages |
-|:-----:|-----------|-----------------|
-| **L0** | Server not connected | Only the reconnection waiting screen is displayed |
-| **L1** | Server connected, plugin not connected | Connection, Tools, Settings |
-| **L2** | Both server and plugin connected | All pages |
+| State | Condition | Available Pages |
+|-------|-----------|-----------------|
+| **Server disconnected** | Server not connected | Only the reconnection waiting screen is displayed |
+| **Server connected** | Server connected, plugin not connected | Connection, Tools, Settings |
+| **Studio connected** | Both server and plugin connected | All pages |
 
-When the plugin is not connected (L1), the Overview, Changelog, Sync, and Playtest pages are inaccessible.
+When the dashboard is in the **Server connected** state, the Overview, Changelog, Sync, and Playtest pages are inaccessible.
 
 ## Overview
 

package/docs/en/dashboard/playtest.md

@@ -6,7 +6,7 @@
 
 ## Overview
 
-The Playtest page shows the status and test results of playtests run by the AI. It is accessible only when the plugin is connected (L2).
+The Playtest page shows the status and test results of playtests run by the AI. It is accessible only when the dashboard is in the **Studio connected** state.
 
 ## Playtest Status
 

package/docs/en/dashboard/settings.md

@@ -4,7 +4,7 @@
 
 ## Overview
 
-The Settings page lets you view license information and server settings, and modify some of them. It is accessible whenever the server is connected (L1 or above).
+The Settings page lets you view license information and server settings, and modify some of them. It is accessible whenever the dashboard is in the **Server connected** or **Studio connected** state.
 
 ## License (Read-Only)
 

package/docs/en/dashboard/sync.md

@@ -8,7 +8,7 @@
 
 ## Overview
 
-The Sync page provides a visual overview of the current state and settings for Studio <-> local file synchronization. It is accessible only when the plugin is connected (L2).
+The Sync page provides a visual overview of the current state and settings for Studio <-> local file synchronization. It is accessible only when the dashboard is in the **Studio connected** state.
 
 ## Sync Status
 

package/docs/en/dashboard/tools.md

@@ -6,7 +6,7 @@
 
 ## Overview
 
-The Tools page provides the execution history and statistics of MCP tools run by the AI. It consists of two sub-tabs: **History** and **Statistics**. It is accessible whenever the server is connected (L1 or above).
+The Tools page provides the execution history and statistics of MCP tools run by the AI. It consists of two sub-tabs: **History** and **Statistics**. It is accessible whenever the dashboard is in the **Server connected** or **Studio connected** state.
 
 ## History Tab
 

package/docs/en/installation/README.md

@@ -74,7 +74,7 @@ Register the MCP server with your AI app. You can use it with any AI app that su
 ## Optional: Install WROX Roblox Explorer (VSCode Extension)
 
 Browse synced instance trees inside VSCode with Roblox class icons.
-This optional extension requires the Roblox MCP setup above, because it reads `roblox-project-sync` data generated by Sync.
+This optional extension requires the Roblox MCP setup above, because it reads sync data from `wrox-project-sync` under your project root.
 
 👉 [WROX Roblox Explorer Installation Guide](roblox-explorer.md)
 

package/docs/en/installation/roblox-explorer.md

@@ -9,7 +9,7 @@ This is a companion extension for WROX, not a standalone Roblox integration.
 
 - VSCode 1.85+
 - [Roblox MCP](../../../README.md) installed with Sync enabled (Basic or Pro)
-- `roblox-project-sync/place_*/.sync-meta.json` already generated by Sync
+- Sync has already generated `wrox-project-sync/place_*/.sync-meta.json` under your project root
 
 ## Installation
 
@@ -37,7 +37,7 @@ Core tree browsing works from synced files on disk. Live sync state, direction i
 
 | Setting | Default | Description |
 |---------|---------|-------------|
-| `robloxExplorer.syncRoot` | `""` | Absolute path to `roblox-project-sync` root. Auto-discovered if empty. |
+| `robloxExplorer.syncRoot` | `""` | Absolute path to the `wrox-project-sync` root. If empty, it is auto-discovered. WROX uses `{projectRoot}/wrox-project-sync`. |
 | `robloxExplorer.hidePropsFiles` | `false` | Hide sync artifact files (`.props.json`, `_tree.json`, `.value.json`) in the default VSCode explorer. |
 | `robloxExplorer.autoRefresh` | `true` | Auto-refresh tree when sync files change. |
 | `robloxExplorer.showSyncStatus` | `true` | Show sync status decorations on tree items. |

package/docs/en/installation/roblox-plugin.md

@@ -18,7 +18,7 @@ Note:
 2. Click the **Plugins** tab in the top menu
 3. Click the **Plugins Folder** button
 
-![Open Plugins Folder](../../assets/screenshots/plugins_menu.png)
+![Open Plugins Folder](../../assets/screenshots/plugin/installation/plugins-menu.png)
 
 4. **Copy** the `WeppyRobloxMCP.rbxm` file from the extracted folder into the opened Plugins folder
 5. **Restart Roblox Studio**
@@ -27,7 +27,7 @@ Note:
 
 After restarting, the **WROX** button will appear in the Plugins tab.
 
-![WROX Button](../../assets/screenshots/weppy_plugin_toolbar.png)
+![WROX Button](../../assets/screenshots/plugin/installation/toolbar-button.png)
 
 ## 4. Connect to AI Agent
 
@@ -52,13 +52,13 @@ The MCP server must be installed. Complete the guide for your AI app first:
 3. Click the **Connect** button in the plugin window
 4. Once **"Connected"** status is displayed, you're ready
 
-![Plugin Main Screen](../../assets/screenshots/plugin_main.png)
+![Plugin Main Screen](../../assets/screenshots/plugin/installation/main-screen.png)
 
 ## 5. Settings (Optional)
 
 Click the settings button in the top right of the plugin to change options.
 
-![Settings Screen](../../assets/screenshots/settings.png)
+![Settings Screen](../../assets/screenshots/plugin/installation/settings-screen.png)
 
 - **Auto Connect**: Automatically connect to MCP server when Studio starts
 - **Auto Reconnect**: Automatically attempt to reconnect when connection is lost

package/docs/en/pro-upgrade.md

@@ -48,7 +48,7 @@ You only need to activate the license once, either in the plugin or in the dashb
 5. If the status does not update immediately, click **Refresh**.
 6. When activation succeeds, the status changes from Basic to Pro and Pro features become available.
 
-![WROX Plugin license activation screen](../assets/screenshots/license/license-plugin.png)
+![WROX Plugin license activation screen](../assets/screenshots/plugin/license/plugin-license-screen.png)
 
 ### Activate in the dashboard
 
@@ -58,7 +58,7 @@ You only need to activate the license once, either in the plugin or in the dashb
 4. Click **Activate License** to activate the license.
 5. If needed, use **Refresh License** to fetch the latest status.
 
-![WROX Dashboard license activation screen](../assets/screenshots/license/license-dashboard.png)
+![WROX Dashboard license activation screen](../assets/screenshots/plugin/license/dashboard-license-screen.png)
 
 ### After activation
 

package/docs/en/sync/overview.md

@@ -12,13 +12,13 @@ Without Sync, AI only sees snippets pasted into chat. With Sync enabled, AI work
 
 ## How it works
 
-![Sync workflow — Studio tree mirrored to local files](../../assets/screenshots/sync.png)
+![Sync workflow — Studio tree mirrored to local files](../../assets/screenshots/plugin/sync/sync-overview.png)
 
 1. Full Sync: initial mirror from Studio tree/instances to local files
 2. Incremental Sync: continuous update of new changes
 3. History/Status tracking: inspect what changed, when, and in which direction
 
-Default local path is `roblox-project-sync/place_{placeId}/explorer`.
+Sync data is stored under `{projectRoot}/wrox-project-sync/place_{placeId}/explorer`.
 
 ### Browse sync data in VSCode
 
@@ -109,7 +109,7 @@ In Pro, Direction and Apply Mode can be controlled per type.
 
 When changes are detected on both Studio and local sides during bidirectional sync, a conflict resolution dialog appears.
 
-![Local Changes Detected — conflict resolution options (Studio Priority / Local Priority / Per-File)](../../assets/screenshots/sync_conflict.png)
+![Local Changes Detected — conflict resolution options (Studio Priority / Local Priority / Per-File)](../../assets/screenshots/plugin/sync/sync-conflict.png)
 
 - **Studio Priority**: overwrite with Studio state as the source of truth
 - **Local Priority**: apply local files to Studio

package/docs/en/tools/playtest.md

@@ -86,10 +86,10 @@ Edit --play--> Running --stop--> Edit
 
 ### 5. Write reports
 
-Reports and logs are written to local files:
+Reports and logs are written under `{projectRoot}/wrox-project-sync/place_XXXXX/tests/YYYYMMDD-HHmmss/`.
 
 ```text
-roblox-project-sync/place_XXXXX/tests/YYYYMMDD-HHmmss/
+{projectRoot}/wrox-project-sync/place_XXXXX/tests/YYYYMMDD-HHmmss/
 ├── test-report.md
 └── test-log.txt
 ```

package/docs/es/README.md

@@ -2,12 +2,20 @@
 
 > **WROX** es un servidor MCP que permite a los agentes de codificacion IA controlar una sesion en vivo de Roblox Studio — crea y edita scripts, instancias, terrain, iluminacion, assets, audio y animaciones con lenguaje natural.
 
-**21 herramientas consolidadas · 140+ acciones · Sync bidireccional · Playtest automatizado · Soporte multi-place**
+**Herramientas consolidadas basadas en acciones · Sync bidireccional · Playtest automatizado · Soporte multi-place**
 
 [English](../../README.md) | [한국어](../ko/README.md) | [日本語](../ja/README.md) | **Español** | [Português](../pt-br/README.md) | [Bahasa Indonesia](../id/README.md)
 
 [![Demo — IA creando un juego Roblox en tiempo real](https://img.youtube.com/vi/3jrUpBbZPaw/maxresdefault.jpg)](https://youtu.be/3jrUpBbZPaw)
 
+## ¿Por qué WROX (Weppy Roblox MCP)?
+
+Los agentes de codificación IA como Claude, Codex y Gemini son potentes — pero no pueden ver ni modificar nada dentro de Roblox Studio. El DataModel, los scripts, el terrain y la iluminación son invisibles para las herramientas externas. Sin un puente, la IA solo puede generar fragmentos de código que debes pegar manualmente.
+
+**WROX** es un puente entre los agentes de IA y Roblox Studio. La IA crea y modifica directamente instancias, scripts, propiedades, terrain y más dentro de Studio, y los cambios se reflejan de inmediato en Studio y en el dashboard para que puedas **ver exactamente qué cambió**.
+
+No necesitas copiar ni pegar código. La IA trabaja y tú verificas los resultados.
+
 ## Instalacion rapida
 
 **Instalacion en un solo comando** — Instala el servidor MCP, el plugin de Roblox Studio y registra tus apps de IA en un solo paso:
@@ -52,14 +60,15 @@ npx -y @weppy/roblox-mcp
 | Codex CLI | [Configuracion](installation/ai-apps/codex-cli.md) |
 | Codex Desktop | [Configuracion](installation/ai-apps/codex-app.md) |
 | Gemini CLI | [Configuracion](installation/ai-apps/gemini-cli.md) |
+| Antigravity | [Configuracion](installation/ai-apps/antigravity.md) |
 
 > Funciona con cualquier cliente MCP compatible. El comando del servidor es `npx -y @weppy/roblox-mcp`.
 
 ## Compatibilidad
 
-| Claude Code | Claude Desktop | Cursor | Codex CLI | Gemini CLI |
-|:-----------:|:--------------:|:------:|:---------:|:----------:|
-| ✅ | ✅ | ✅ | ✅ | ✅ |
+| Claude Code | Claude Desktop | Cursor | Codex CLI | Gemini CLI | Antigravity |
+|:-----------:|:--------------:|:------:|:---------:|:----------:|:-----------:|
+| ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 
 **Requisitos:** Node.js 18+, Roblox Studio, Windows 10+ o macOS 12+
 
@@ -73,17 +82,15 @@ La IA puede manejar directamente scripts, instancias, propiedades, terreno, ilum
 - "Crea una arena de boss en el centro del mapa y coloca spawns sin colision."
 - "Cambia la interfaz de este modulo y actualiza todos los scripts dependientes."
 
-No es solo generacion de codigo. Son **acciones ejecutables orientadas a produccion**.
-
 ### 2) Sync: mantiene el contexto completo del proyecto
 
 La IA trabaja sobre un espejo local sincronizado, asi que los cambios en multiples archivos se mantienen consistentes.
 
-![Flujo de Sync — Studio y archivos locales sincronizados en tiempo real](../assets/screenshots/sync.png)
-
 - Basic: sincronizacion unidireccional (Studio -> Local)
 - Pro: sincronizacion bidireccional + Direction/Apply Mode por tipo + historial + multiplace
 
+![Flujo de Sync — Studio y archivos locales sincronizados en tiempo real](../assets/screenshots/plugin/sync/sync-overview.png)
+
 ### 3) Playtest: la IA ejecuta y verifica pruebas automaticamente
 
 La IA puede controlar directamente el playtest de Studio. Puede iniciar y detener Play (F5) o Run (F8), inyectar scripts de prueba, recopilar logs y generar reportes locales automaticamente.
@@ -92,28 +99,30 @@ La IA puede controlar directamente el playtest de Studio. Puede iniciar y detene
 - "Escribe y ejecuta una prueba para confirmar que el SpawnLocation esta sobre el suelo."
 - "Valida con playtest que el script que acabo de cambiar funciona sin errores."
 
+![WROX Playtest Dashboard — historial de pruebas y reporte detallado](../assets/screenshots/dashboard/dashboard_playtest.png)
+
 ### 4) WROX Dashboard: monitorea el trabajo de la IA en tiempo real
 
 El Dashboard web proporcionado por el servidor MCP permite consultar en tiempo real el estado de conexion, el historial de ejecucion de herramientas, el estado de sincronizacion y el historial de cambios del juego.
 
-![WROX WROX Dashboard Overview — estado del servidor, cambios recientes y resumen de sesion](../assets/screenshots/dashboard/dashboard_overview.png)
-
 - Estado de conexion del servidor/plugin/agente de un vistazo
 - Compara todos los cambios realizados por la IA con Before & After en el Changelog
 - Analiza el flujo de trabajo con el historial de ejecucion de herramientas y estadisticas
 
+![WROX WROX Dashboard Overview — estado del servidor, cambios recientes y resumen de sesion](../assets/screenshots/dashboard/dashboard_overview.png)
+
 ### 5) WROX Roblox Explorer: explora la jerarquia de Studio en VSCode
 
 Visualiza el arbol completo de instancias de tu lugar en Roblox Studio directamente dentro de VSCode. Navega los servicios, abre scripts y archivos de propiedades sincronizados, y rastrea el estado de sincronizacion — todo sin cambiar a Studio.
 WROX Roblox Explorer es una extension complementaria de VSCode para los datos de sync generados por WROX. El arbol base funciona con los archivos sincronizados en disco, y los indicadores en vivo de estado sync o direction se enriquecen cuando el servidor MCP local esta en ejecucion.
 Instálalo desde [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=weppy.weppy-roblox-explorer) o [Open VSX](https://open-vsx.org/extension/weppy/weppy-roblox-explorer).
 
-![WROX Roblox Explorer — arbol de instancias de Studio mostrado en la barra lateral de VSCode](../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
-
 - Iconos de clase iguales a Studio para reconocimiento inmediato
 - Clic para abrir scripts y archivos de propiedades sincronizados
 - Soporte multiplace con indicadores de estado de sincronizacion
 
+![WROX Roblox Explorer — arbol de instancias de Studio mostrado en la barra lateral de VSCode](../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
+
 ## Valor inmediato para el usuario
 
 - Comprime trabajo repetitivo: convierte muchas ediciones manuales en una sola instruccion
@@ -121,6 +130,14 @@ Instálalo desde [VS Code Marketplace](https://marketplace.visualstudio.com/item
 - Menor riesgo: decide cambios con estado de sync e historial
 - Mejor eficiencia de tokens (Pro): menos idas y vueltas con acciones masivas
 
+## Casos de uso
+
+- **Prototipado rápido**: Describe una mecánica de juego en lenguaje natural y observa cómo la IA la construye en Studio
+- **Refactorización masiva**: Renombra una interfaz de módulo y actualiza todos los scripts dependientes en una sola solicitud
+- **Terrain y entorno**: Genera terrain procedural, configura iluminación/atmósfera, coloca assets — todo desde un solo prompt
+- **Consistencia multi-archivo**: La IA lee el proyecto completo vía Sync y aplica cambios en scripts relacionados de forma conjunta
+- **Integración de assets**: Busca en el Creator Store, inserta modelos y configura propiedades sin salir de tu editor
+
 ## Documentacion detallada
 
 - [Guia de instalacion](installation/README.md)
@@ -140,12 +157,47 @@ Instálalo desde [VS Code Marketplace](https://marketplace.visualstudio.com/item
 - [Playtest y pruebas automatizadas](tools/playtest.md) - control de playtest y validacion automatica
 - [Sistema y depuracion](tools/system-and-debugging.md) - conexion, logs y ejecucion por lotes
 
+## FAQ
+
+### ¿Cómo conecto Claude Code a Roblox Studio?
+Instala el plugin de Roblox Studio y luego registra el servidor MCP (`npx -y @weppy/roblox-mcp`) en Claude Code. Claude podrá leer y escribir scripts directamente dentro de Studio. Consulta [Configuración de Claude Code](installation/ai-apps/claude-code.md).
+
+### ¿Cómo uso Codex CLI con Roblox Studio?
+Instala el plugin y agrega la configuración del servidor MCP a Codex CLI. Consulta [Configuración de Codex CLI](installation/ai-apps/codex-cli.md).
+
+### ¿Roblox MCP funciona con Cursor?
+Sí. Consulta [Configuración de Cursor](installation/ai-apps/cursor.md). Cualquier cliente de IA compatible con MCP funciona.
+
+### ¿Puede la IA crear juegos de Roblox con esto?
+Sí. La IA puede crear instancias, escribir scripts, generar terrain, configurar iluminación, insertar assets, configurar física y más — todo dentro de una sesión de Studio en vivo. Va más allá de la generación de código hacia acciones ejecutables.
+
+### ¿Cuál es la diferencia entre Basic y Pro?
+Basic (gratuito) incluye ejecución de herramientas MCP y sincronización unidireccional (Studio -> Local). Pro agrega sincronización bidireccional, operaciones masivas, generación de terrain, análisis espacial, control de audio/animación y soporte multi-place. Consulta la [Guía de actualización Pro](pro-upgrade.md).
+
+### ¿Cómo se diferencia Weppy de otros servidores MCP para Roblox?
+Weppy usa despacho basado en acciones en lugar de herramientas separadas para cada función. Esto reduce significativamente el consumo de tokens de IA. También proporciona sincronización bidireccional de proyecto y soporte multi-place, que la mayoría de las alternativas no tienen.
+
+### ¿Es seguro? ¿Puede la IA romper mi juego?
+El servidor se ejecuta solo en localhost (127.0.0.1:3002). Las rutas prohibidas (CoreGui, CorePackages) están bloqueadas. La limitación de velocidad (450 req/min) y los tiempos de espera de 30 segundos previenen operaciones fuera de control. Todos los cambios son rastreables a través del historial de sincronización.
+
 ## Upgrade Pro
 
 Sync bidireccional, capacidades de creacion avanzadas y eficiencia de tokens de IA — todo en una sola actualizacion.
 
 [Guia de actualizacion Pro](pro-upgrade.md)
 
+## Licencia
+
+Este repositorio está licenciado bajo `AGPL-3.0`.
+
+Las licencias comerciales están disponibles por separado. Consulta [COMMERCIAL-LICENSE.md](../../COMMERCIAL-LICENSE.md).
+
+El uso del nombre y los logotipos de Weppy se rige por [TRADEMARKS.md](../../TRADEMARKS.md).
+
 ---
 
+[![npm version](https://img.shields.io/npm/v/@weppy/roblox-mcp)](https://www.npmjs.com/package/@weppy/roblox-mcp) [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/) [![Smithery](https://smithery.ai/badge/@hope1026/weppy-roblox-mcp)](https://smithery.ai/server/@hope1026/weppy-roblox-mcp)
+
+[![Roblox MCP on Glama](https://glama.ai/mcp/servers/hope1026/roblox-mcp/badges/card.svg)](https://glama.ai/mcp/servers/hope1026/roblox-mcp)
+
 [GitHub Issues](https://github.com/hope1026/weppy-roblox-mcp/issues) · [Discussions](https://github.com/hope1026/weppy-roblox-mcp/discussions) · [npm](https://www.npmjs.com/package/@weppy/roblox-mcp)

package/docs/es/dashboard/connection.md

@@ -6,7 +6,7 @@
 
 ## Descripcion general
 
-La pagina Connection permite monitorear todos los estados de conexion del sistema MCP en un solo lugar. Es accesible siempre que el servidor este conectado (L1 o superior).
+La pagina Connection permite monitorear todos los estados de conexion del sistema MCP en un solo lugar. Es accesible siempre que el dashboard este en estado **Servidor conectado** o **Studio conectado**.
 
 ## Server Status
 

package/docs/es/dashboard/overview.md

@@ -34,17 +34,17 @@ http://localhost:3002
 
 > Configura `DASHBOARD_AUTO_OPEN=false` para desactivar la apertura automatica (consulta la pagina de [Settings](settings.md)).
 
-## Niveles de conexion
+## Estados de conexion
 
 El Dashboard ofrece diferentes funciones segun el estado de conexion:
 
-| Nivel | Condicion | Paginas disponibles |
-|:-----:|-----------|---------------------|
-| **L0** | Servidor no conectado | Solo se muestra la pantalla de espera de reconexion |
-| **L1** | Servidor conectado, plugin no conectado | Connection, Tools, Settings |
-| **L2** | Servidor + plugin ambos conectados | Todas las paginas |
+| Estado | Condicion | Paginas disponibles |
+|--------|-----------|---------------------|
+| **Servidor desconectado** | Servidor no conectado | Solo se muestra la pantalla de espera de reconexion |
+| **Servidor conectado** | Servidor conectado, plugin no conectado | Connection, Tools, Settings |
+| **Studio conectado** | Servidor + plugin ambos conectados | Todas las paginas |
 
-Cuando el plugin no esta conectado (L1), no se puede acceder a las paginas Overview, Changelog, Sync y Playtest.
+Cuando el dashboard esta en estado **Servidor conectado**, no se puede acceder a las paginas Overview, Changelog, Sync y Playtest.
 
 ## Overview
 

package/docs/es/dashboard/playtest.md

@@ -6,7 +6,7 @@
 
 ## Descripcion general
 
-La pagina Playtest muestra el estado de los playtests ejecutados por la IA y los resultados de las pruebas. Solo es accesible cuando el plugin esta conectado (L2).
+La pagina Playtest muestra el estado de los playtests ejecutados por la IA y los resultados de las pruebas. Solo es accesible cuando el dashboard esta en estado **Studio conectado**.
 
 ## Playtest Status
 

package/docs/es/dashboard/settings.md

@@ -4,7 +4,7 @@
 
 ## Descripcion general
 
-En la pagina Settings puedes consultar la informacion de licencia y la configuracion del servidor, y modificar algunos parametros. Es accesible siempre que el servidor este conectado (L1 o superior).
+En la pagina Settings puedes consultar la informacion de licencia y la configuracion del servidor, y modificar algunos parametros. Es accesible siempre que el dashboard este en estado **Servidor conectado** o **Studio conectado**.
 
 ## License (solo lectura)
 

package/docs/es/dashboard/sync.md

@@ -8,7 +8,7 @@
 
 ## Descripcion general
 
-La pagina Sync muestra visualmente el estado actual y la configuracion de la sincronizacion Studio <-> archivos locales. Solo es accesible cuando el plugin esta conectado (L2).
+La pagina Sync muestra visualmente el estado actual y la configuracion de la sincronizacion Studio <-> archivos locales. Solo es accesible cuando el dashboard esta en estado **Studio conectado**.
 
 ## Sync Status
 

package/docs/es/dashboard/tools.md

@@ -6,7 +6,7 @@
 
 ## Descripcion general
 
-La pagina Tools proporciona el historial de ejecucion y las estadisticas de las herramientas MCP ejecutadas por la IA. Se compone de dos sub-pestanas: **History** y **Statistics**. Es accesible siempre que el servidor este conectado (L1 o superior).
+La pagina Tools proporciona el historial de ejecucion y las estadisticas de las herramientas MCP ejecutadas por la IA. Se compone de dos sub-pestanas: **History** y **Statistics**. Es accesible siempre que el dashboard este en estado **Servidor conectado** o **Studio conectado**.
 
 ## Pestana History
 

package/docs/es/installation/README.md

@@ -67,7 +67,7 @@ Configura el servidor MCP en tu app de IA para que pueda comunicarse con Roblox
 ## Opcional: Instalar WROX Roblox Explorer (Extensión VSCode)
 
 Explora los árboles de instancias sincronizados dentro de VSCode con iconos de clases Roblox.
-Esta extensión opcional requiere completar antes la instalación de Roblox MCP, porque Explorer lee los datos `roblox-project-sync` generados por Sync.
+Esta extension opcional requiere completar antes la instalacion de Roblox MCP, porque Explorer lee los datos de Sync desde `wrox-project-sync` dentro de la raiz del proyecto.
 
 👉 [Guía de instalación de WROX Roblox Explorer](roblox-explorer.md)
 

package/docs/es/installation/roblox-explorer.md

@@ -9,7 +9,7 @@ Esta es una extensión complementaria para WROX, no una integración de Roblox i
 
 - VSCode 1.85+
 - [Roblox MCP](../../../README.md) instalado con Sync habilitado (Basic o Pro)
-- `roblox-project-sync/place_*/.sync-meta.json` ya generado por Sync
+- Sync ya genero `wrox-project-sync/place_*/.sync-meta.json` dentro de la raiz del proyecto
 
 ## Instalación
 
@@ -37,7 +37,7 @@ La navegación básica del árbol funciona con los archivos sincronizados en dis
 
 | Configuración | Valor por defecto | Descripción |
 |---------------|-------------------|-------------|
-| `robloxExplorer.syncRoot` | `""` | Ruta absoluta a la raíz de `roblox-project-sync`. Se detecta automáticamente si está vacío. |
+| `robloxExplorer.syncRoot` | `""` | Ruta absoluta a la raiz de `wrox-project-sync`. Si esta vacia, se detecta automaticamente. WROX usa `{projectRoot}/wrox-project-sync`. |
 | `robloxExplorer.hidePropsFiles` | `false` | Oculta los archivos de Sync (`.props.json`, `_tree.json`, `.value.json`) en el explorador predeterminado de VSCode. |
 | `robloxExplorer.autoRefresh` | `true` | Actualiza automáticamente el árbol cuando cambian los archivos Sync. |
 | `robloxExplorer.showSyncStatus` | `true` | Muestra decoraciones de estado Sync en los elementos del árbol. |