@weppy/roblox-mcp 2.0.10 → 2.1.0

package/docs/ko/README.md

@@ -1,13 +1,21 @@
 # Roblox MCP — Roblox Studio MCP 서버 | Claude, Codex, Cursor, Gemini로 AI 게임 개발
 
-> **weppy-roblox-mcp (WROX)**는 AI 코딩 에이전트가 라이브 Roblox Studio 세션을 제어할 수 있게 하는 MCP 서버입니다 — 자연어로 스크립트, 인스턴스, 지형, 조명, 에셋, 오디오, 애니메이션을 생성하고 편집합니다.
+> **WROX**는 AI 코딩 에이전트가 라이브 Roblox Studio 세션을 제어할 수 있게 하는 MCP 서버입니다 — 자연어로 스크립트, 인스턴스, 지형, 조명, 에셋, 오디오, 애니메이션을 생성하고 편집합니다.
 
-**21개 통합 도구 · 140+ 액션 · 양방향 Sync · 자동 플레이테스트 · 멀티 Place 지원**
+**액션 기반 통합 도구 · 양방향 Sync · 자동 플레이테스트 · 멀티 Place 지원**
 
 [English](../../README.md) | **한국어** | [日本語](../ja/README.md) | [Español](../es/README.md) | [Português](../pt-br/README.md) | [Bahasa Indonesia](../id/README.md)
 
 [![데모 — AI가 실시간으로 Roblox 게임을 제작하는 모습](https://img.youtube.com/vi/3jrUpBbZPaw/maxresdefault.jpg)](https://youtu.be/3jrUpBbZPaw)
 
+## WROX (Weppy Roblox MCP)를 쓰는 이유
+
+Claude, Codex, Gemini 같은 AI 코딩 에이전트는 강력하지만 — Roblox Studio 내부는 볼 수도, 수정할 수도 없습니다. DataModel, 스크립트, 지형, 조명 전부 외부 도구에는 보이지 않습니다. 브릿지 없이는 AI가 코드 조각을 생성해도 직접 붙여넣어야 합니다.
+
+**WROX**는 AI 에이전트와 Roblox Studio를 연결하는 브릿지입니다. AI가 Studio 안에서 인스턴스, 스크립트, 속성, 지형 등을 직접 생성하고 수정하면, 변경 내용이 Studio와 대시보드에 즉시 반영되어 **무엇이 바뀌었는지 한눈에 확인**할 수 있습니다.
+
+코드를 복사해서 붙여넣을 필요 없이, AI가 작업하고 내가 결과를 확인하는 방식입니다.
+
 ## 빠른 설치
 
 **원라인 설치** — MCP 서버, Roblox Studio 플러그인, AI 앱 등록을 한 번에 진행합니다:
@@ -52,14 +60,15 @@ npx -y @weppy/roblox-mcp
 | Codex CLI | [설정](installation/ai-apps/codex-cli.md) |
 | Codex Desktop | [설정](installation/ai-apps/codex-app.md) |
 | Gemini CLI | [설정](installation/ai-apps/gemini-cli.md) |
+| Antigravity | [설정](installation/ai-apps/antigravity.md) |
 
 > MCP를 지원하는 모든 AI 앱에서 사용 가능합니다. 서버 명령어: `npx -y @weppy/roblox-mcp`
 
 ## 호환성
 
-| Claude Code | Claude Desktop | Cursor | Codex CLI | Gemini CLI |
-|:-----------:|:--------------:|:------:|:---------:|:----------:|
-| ✅ | ✅ | ✅ | ✅ | ✅ |
+| Claude Code | Claude Desktop | Cursor | Codex CLI | Gemini CLI | Antigravity |
+|:-----------:|:--------------:|:------:|:---------:|:----------:|:-----------:|
+| ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 
 **요구 사항:** Node.js 18+, Roblox Studio, Windows 10+ 또는 macOS 12+
 
@@ -73,17 +82,15 @@ npx -y @weppy/roblox-mcp
 - "맵 중앙에 보스 아레나 만들고, 스폰 포인트도 충돌 없이 배치해줘."
 - "이 모듈 인터페이스 바꾸고 참조하는 스크립트 전부 함께 수정해줘."
 
-단순 코드 생성이 아니라, **실행 가능한 작업 단위**로 처리된다는 점이 핵심입니다.
-
 ### 2) Sync: AI가 프로젝트 전체 문맥을 읽고 유지
 
 AI가 로컬 동기화된 프로젝트를 기준으로 전체 구조를 이해해, 여러 파일에 걸친 변경을 일관되게 수행합니다.
 
-![Sync 워크플로우 — Studio와 로컬 파일이 실시간으로 동기화되는 모습](../assets/screenshots/plugin/sync/sync-overview.png)
-
 - Basic: Studio -> Local 단방향 동기화
 - Pro: 양방향 동기화 + 타입별 Direction/Apply Mode + 변경 기록 + 멀티 Place
 
+![Sync 워크플로우 — Studio와 로컬 파일이 실시간으로 동기화되는 모습](../assets/screenshots/plugin/sync/sync-overview.png)
+
 ### 3) Playtest: AI가 테스트를 자동으로 실행하고 검증
 
 Studio 플레이테스트를 AI가 직접 제어합니다. F5(Play)/F8(Run) 시작/중지는 물론, 테스트 스크립트를 주입하고 로그를 수집해 리포트까지 자동 생성합니다.
@@ -98,24 +105,24 @@ Studio 플레이테스트를 AI가 직접 제어합니다. F5(Play)/F8(Run) 시
 
 MCP 서버가 제공하는 웹 대시보드에서 연결 상태, 도구 실행 기록, 동기화 상태, 게임 변경 이력을 실시간으로 확인합니다.
 
-![대시보드 Overview — 서버 상태, 최근 변경 사항, 세션 요약](../assets/screenshots/dashboard/dashboard_overview.png)
-
 - 서버/플러그인/에이전트 연결 상태 한눈에 확인
 - AI가 변경한 모든 내용을 Changelog에서 Before & After로 비교
 - 도구 실행 기록과 통계로 작업 흐름 분석
 
+![대시보드 Overview — 서버 상태, 최근 변경 사항, 세션 요약](../assets/screenshots/dashboard/dashboard_overview.png)
+
 ### 5) WROX Roblox Explorer: VSCode에서 Studio 계층 구조 탐색
 
 Roblox Studio의 전체 인스턴스 트리를 VSCode 안에서 바로 확인할 수 있습니다. 서비스를 탐색하고, 동기화된 스크립트와 속성 파일을 열고, 동기화 상태를 추적하세요 — Studio로 전환할 필요 없이.
 WROX Roblox Explorer는 WROX가 생성한 sync 데이터를 위한 companion VSCode 확장입니다. 기본 트리 탐색은 동기화된 파일만으로 동작하고, 로컬 MCP 서버가 실행 중이면 실시간 sync 상태와 direction 표시가 더 정확하게 반영됩니다.
 설치는 [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=weppy.weppy-roblox-explorer) 또는 [Open VSX](https://open-vsx.org/extension/weppy/weppy-roblox-explorer)에서 할 수 있습니다.
 
-![WROX Roblox Explorer — VSCode 사이드바에 표시되는 Studio 인스턴스 트리](../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
-
 - Studio와 동일한 클래스 아이콘으로 직관적 구분
 - 클릭으로 동기화된 스크립트와 속성 파일 열기
 - 동기화 상태 표시를 포함한 멀티 Place 지원
 
+![WROX Roblox Explorer — VSCode 사이드바에 표시되는 Studio 인스턴스 트리](../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
+
 ## 유저가 바로 체감하는 장점
 
 - 반복 작업 압축: 수십 번 클릭/수정을 자연어 한 번으로 처리
@@ -123,6 +130,14 @@ WROX Roblox Explorer는 WROX가 생성한 sync 데이터를 위한 companion VSC
 - 리스크 감소: 변경 이력과 동기화 상태를 기준으로 안전하게 수정
 - 토큰 효율 개선(Pro): 대량 action과 batch 실행으로 왕복 요청 감소
 
+## 활용 사례
+
+- **빠른 프로토타이핑**: 자연어로 게임 메카닉을 설명하면 AI가 Studio에서 바로 구현
+- **대량 리팩터링**: 모듈 인터페이스를 변경하고 의존 스크립트를 한 번에 업데이트
+- **지형 & 환경**: 절차적 지형 생성, 조명/분위기 설정, 에셋 배치를 단일 프롬프트로
+- **멀티 파일 일관성**: AI가 Sync를 통해 전체 프로젝트를 읽고 관련 스크립트를 함께 수정
+- **에셋 통합**: Creator Store 검색, 모델 삽입, 속성 설정을 에디터를 벗어나지 않고 수행
+
 ## 세부 문서
 
 - [설치 가이드](installation/README.md)
@@ -142,12 +157,47 @@ WROX Roblox Explorer는 WROX가 생성한 sync 데이터를 위한 companion VSC
 - [플레이테스트 & 자동 테스트](tools/playtest.md) — 플레이테스트 제어, 자동 검증
 - [시스템 & 디버깅](tools/system-and-debugging.md) — 연결, 로그, 배치 실행
 
+## FAQ
+
+### Claude Code를 Roblox Studio에 어떻게 연결하나요?
+Roblox Studio 플러그인을 설치한 뒤, Claude Code에 MCP 서버(`npx -y @weppy/roblox-mcp`)를 등록하세요. Claude가 Studio 안의 스크립트를 직접 읽고 쓸 수 있습니다. [Claude Code 설정](installation/ai-apps/claude-code.md)을 참고하세요.
+
+### Codex CLI로 Roblox Studio를 사용하려면?
+플러그인을 설치하고 Codex CLI에 MCP 서버 설정을 추가하세요. [Codex CLI 설정](installation/ai-apps/codex-cli.md)을 참고하세요.
+
+### Roblox MCP가 Cursor에서도 동작하나요?
+네. [Cursor 설정](installation/ai-apps/cursor.md)을 참고하세요. MCP를 지원하는 모든 AI 클라이언트에서 동작합니다.
+
+### AI로 Roblox 게임을 만들 수 있나요?
+네. AI가 인스턴스 생성, 스크립트 작성, 지형 생성, 조명 설정, 에셋 삽입, 물리 설정 등을 라이브 Studio 세션 안에서 직접 수행합니다. 코드 생성을 넘어 실행 가능한 작업까지 처리합니다.
+
+### Basic과 Pro의 차이는?
+Basic(무료)은 MCP 도구 실행과 단방향 동기화(Studio -> Local)를 포함합니다. Pro는 양방향 동기화, 대량 작업, 지형 생성, 공간 분석, 오디오/애니메이션 제어, 멀티 Place 지원을 추가합니다. [Pro 업그레이드 가이드](pro-upgrade.md)를 참고하세요.
+
+### Weppy는 다른 Roblox MCP 서버와 어떻게 다른가요?
+Weppy는 기능별 도구 분리 대신 액션 기반 디스패칭을 사용합니다. 이로 인해 AI 토큰 소비가 크게 줄어듭니다. 또한 양방향 프로젝트 동기화와 멀티 Place 지원을 제공하는데, 대부분의 대안에는 없는 기능입니다.
+
+### 안전한가요? AI가 게임을 망가뜨릴 수 있나요?
+서버는 localhost(127.0.0.1:3002)에서만 실행됩니다. 금지 경로(CoreGui, CorePackages)는 차단됩니다. 속도 제한(450 req/min)과 30초 타임아웃이 폭주 작업을 방지합니다. 모든 변경 사항은 동기화 기록으로 추적할 수 있습니다.
+
 ## Pro로 업그레이드
 
 양방향 Sync, 고급 제작 기능, AI 토큰 효율 — 한 번의 업그레이드로 모두 누리세요.
 
 [Pro 업그레이드 가이드](pro-upgrade.md)
 
+## 라이선스
+
+이 저장소는 `AGPL-3.0` 라이선스를 따릅니다.
+
+상업용 라이선스는 별도로 제공됩니다. [COMMERCIAL-LICENSE.md](../../COMMERCIAL-LICENSE.md)를 참고하세요.
+
+Weppy 이름 및 로고 사용은 [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 이슈](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/ko/dashboard/connection.md

@@ -6,7 +6,7 @@
 
 ## 개요
 
-Connection 페이지는 MCP 시스템의 모든 연결 상태를 한 곳에서 모니터링합니다. 서버가 연결되어 있으면(L1 이상) 항상 접근할 수 있습니다.
+Connection 페이지는 MCP 시스템의 모든 연결 상태를 한 곳에서 모니터링합니다. 대시보드가 **서버 연결됨** 또는 **Studio 연결됨** 상태이면 항상 접근할 수 있습니다.
 
 ## Server Status
 

package/docs/ko/dashboard/overview.md

@@ -34,17 +34,17 @@ http://localhost:3002
 
 > `DASHBOARD_AUTO_OPEN=false`로 설정하면 자동 열림을 비활성화할 수 있습니다 ([Settings](settings.md) 페이지에서 확인).
 
-## 연결 레벨
+## 연결 상태
 
 대시보드는 연결 상태에 따라 사용 가능한 기능이 달라집니다:
 
-| 레벨 | 조건 | 사용 가능한 페이지 |
-|:----:|------|-------------------|
-| **L0** | 서버 미연결 | 재연결 대기 화면만 표시 |
-| **L1** | 서버 연결, 플러그인 미연결 | Connection, Tools, Settings |
-| **L2** | 서버 + 플러그인 모두 연결 | 모든 페이지 |
+| 상태 | 조건 | 사용 가능한 페이지 |
+|------|------|-------------------|
+| **서버 연결 끊김** | 서버 미연결 | 재연결 대기 화면만 표시 |
+| **서버 연결됨** | 서버 연결, 플러그인 미연결 | Connection, Tools, Settings |
+| **Studio 연결됨** | 서버 + 플러그인 모두 연결 | 모든 페이지 |
 
-플러그인이 연결되지 않은 상태(L1)에서는 Overview, Changelog, Sync, Playtest 페이지에 접근할 수 없습니다.
+대시보드가 **서버 연결됨** 상태일 때는 Overview, Changelog, Sync, Playtest 페이지에 접근할 수 없습니다.
 
 ## Overview
 

package/docs/ko/dashboard/playtest.md

@@ -6,7 +6,7 @@
 
 ## 개요
 
-Playtest 페이지는 AI가 실행한 플레이테스트의 상태와 테스트 결과를 보여줍니다. 플러그인이 연결된 상태(L2)에서만 접근할 수 있습니다.
+Playtest 페이지는 AI가 실행한 플레이테스트의 상태와 테스트 결과를 보여줍니다. 대시보드가 **Studio 연결됨** 상태일 때만 접근할 수 있습니다.
 
 ## Playtest Status
 

package/docs/ko/dashboard/settings.md

@@ -4,7 +4,7 @@
 
 ## 개요
 
-Settings 페이지에서는 라이선스 정보와 서버 설정을 확인하고 일부를 변경할 수 있습니다. 서버가 연결되어 있으면(L1 이상) 항상 접근할 수 있습니다.
+Settings 페이지에서는 라이선스 정보와 서버 설정을 확인하고 일부를 변경할 수 있습니다. 대시보드가 **서버 연결됨** 또는 **Studio 연결됨** 상태이면 항상 접근할 수 있습니다.
 
 ## License (읽기 전용)
 

package/docs/ko/dashboard/sync.md

@@ -8,7 +8,7 @@
 
 ## 개요
 
-Sync 페이지는 Studio ↔ 로컬 파일 동기화의 현재 상태와 설정을 시각적으로 보여줍니다. 플러그인이 연결된 상태(L2)에서만 접근할 수 있습니다.
+Sync 페이지는 Studio ↔ 로컬 파일 동기화의 현재 상태와 설정을 시각적으로 보여줍니다. 대시보드가 **Studio 연결됨** 상태일 때만 접근할 수 있습니다.
 
 ## Sync Status
 

package/docs/ko/dashboard/tools.md

@@ -6,7 +6,7 @@
 
 ## 개요
 
-Tools 페이지는 AI가 실행한 MCP 도구의 기록과 통계를 제공합니다. **History**와 **Statistics** 두 개의 서브탭으로 구성됩니다. 서버가 연결되어 있으면(L1 이상) 항상 접근할 수 있습니다.
+Tools 페이지는 AI가 실행한 MCP 도구의 기록과 통계를 제공합니다. **History**와 **Statistics** 두 개의 서브탭으로 구성됩니다. 대시보드가 **서버 연결됨** 또는 **Studio 연결됨** 상태이면 항상 접근할 수 있습니다.
 
 ## History 탭
 

package/docs/ko/installation/README.md

@@ -74,7 +74,7 @@ GitHub에서 플러그인 파일을 다운로드한 뒤, Roblox Studio의 Plugin
 ## 선택 사항: WROX Roblox Explorer (VSCode 확장) 설치
 
 동기화된 인스턴스 트리를 Roblox 클래스 아이콘과 함께 VSCode에서 탐색할 수 있습니다.
-이 확장은 위의 Roblox MCP 설치를 먼저 완료해야 사용할 수 있습니다. Explorer가 Sync가 생성한 `roblox-project-sync` 데이터를 읽기 때문입니다.
+이 확장은 위의 Roblox MCP 설치를 먼저 완료해야 사용할 수 있습니다. Explorer가 프로젝트 루트 아래의 `wrox-project-sync` Sync 데이터를 읽기 때문입니다.
 
 👉 [WROX Roblox Explorer 설치 가이드](roblox-explorer.md)
 

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

@@ -9,7 +9,7 @@ Roblox Studio의 Explorer와 동일한 인스턴스 트리를 VSCode에서 볼
 
 - VSCode 1.85+
 - [Roblox MCP](../../../README.md) 설치 및 Sync 활성화 (Basic 또는 Pro)
-- Sync가 생성한 `roblox-project-sync/place_*/.sync-meta.json` 존재
+- 프로젝트 루트 아래에 Sync가 생성한 `wrox-project-sync/place_*/.sync-meta.json` 존재
 
 ## 설치 방법
 
@@ -37,7 +37,7 @@ VSCode Extensions 사이드바(`Ctrl+Shift+X` / `Cmd+Shift+X`)에서 **WROX Robl
 
 | 설정 | 기본값 | 설명 |
 |------|--------|------|
-| `robloxExplorer.syncRoot` | `""` | `roblox-project-sync` 루트 절대 경로. 비워두면 자동 탐색. |
+| `robloxExplorer.syncRoot` | `""` | `wrox-project-sync` 루트 절대 경로. 비워두면 자동 탐색합니다. WROX는 `{projectRoot}/wrox-project-sync` 를 사용합니다. |
 | `robloxExplorer.hidePropsFiles` | `false` | 기본 VSCode 탐색기에서 동기화 파일(`.props.json`, `_tree.json`, `.value.json`)을 숨깁니다. |
 | `robloxExplorer.autoRefresh` | `true` | Sync 파일 변경 시 트리를 자동으로 새로고침합니다. |
 | `robloxExplorer.showSyncStatus` | `true` | 트리 항목에 Sync 상태 장식을 표시합니다. |

package/docs/ko/sync/overview.md

@@ -18,7 +18,7 @@ Sync가 없으면 AI는 대화에 붙여 넣은 코드 일부만 보고 판단
 2. Incremental Sync: 변경 감시로 이후 변경분만 반영
 3. History/Status 추적: 어떤 변경이 언제 어떤 방향으로 반영됐는지 확인
 
-로컬 기본 경로는 `roblox-project-sync/place_{placeId}/explorer` 형태로 생성됩니다.
+Sync 데이터는 `{projectRoot}/wrox-project-sync/place_{placeId}/explorer` 아래에 생성됩니다.
 
 ### VSCode에서 Sync 데이터 탐색
 

package/docs/ko/tools/playtest.md

@@ -81,10 +81,10 @@ Edit ──play──→ Running ──stop──→ Edit
 - 마지막 로그 수집
 
 ### 5. 리포트 생성
-로컬 파일로 리포트와 로그를 저장합니다:
+리포트와 로그는 로컬 `{projectRoot}/wrox-project-sync/place_XXXXX/tests/YYYYMMDD-HHmmss/` 아래에 저장됩니다.
 
 ```
-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/pt-br/README.md

@@ -2,12 +2,20 @@
 
 > **WROX** e um servidor MCP que permite agentes de codificacao IA controlarem uma sessao ao vivo do Roblox Studio — crie e edite scripts, instancias, terrain, iluminacao, assets, audio e animacoes com linguagem natural.
 
-**21 ferramentas consolidadas · 140+ acoes · Sync bidirecional · Playtest automatizado · Suporte multi-place**
+**Ferramentas consolidadas baseadas em ações · Sync bidirecional · Playtest automatizado · Suporte multi-place**
 
 [English](../../README.md) | [한국어](../ko/README.md) | [日本語](../ja/README.md) | [Español](../es/README.md) | **Português** | [Bahasa Indonesia](../id/README.md)
 
 [![Demo — IA criando um jogo Roblox em tempo real](https://img.youtube.com/vi/3jrUpBbZPaw/maxresdefault.jpg)](https://youtu.be/3jrUpBbZPaw)
 
+## Por que WROX (Weppy Roblox MCP)?
+
+Agentes de codificação IA como Claude, Codex e Gemini são poderosos — mas não conseguem ver nem modificar nada dentro do Roblox Studio. O DataModel, scripts, terrain e iluminação são todos invisíveis para ferramentas externas. Sem uma ponte, a IA só pode gerar trechos de código que você precisa colar manualmente.
+
+**WROX** é uma ponte entre agentes de IA e o Roblox Studio. A IA cria e modifica diretamente instâncias, scripts, propriedades, terrain e mais dentro do Studio, e as alterações são refletidas imediatamente no Studio e no dashboard para que você possa **ver exatamente o que mudou**.
+
+Sem necessidade de copiar e colar código. A IA trabalha e você confere os resultados.
+
 ## Instalacao rapida
 
 **Instalacao em um comando** — Instala o servidor MCP, o plugin do Roblox Studio e registra nos apps de IA em um único passo:
@@ -52,14 +60,15 @@ npx -y @weppy/roblox-mcp
 | Codex CLI | [Configuracao](installation/ai-apps/codex-cli.md) |
 | Codex Desktop | [Configuracao](installation/ai-apps/codex-app.md) |
 | Gemini CLI | [Configuracao](installation/ai-apps/gemini-cli.md) |
+| Antigravity | [Configuracao](installation/ai-apps/antigravity.md) |
 
 > Funciona com qualquer cliente MCP compativel. O comando do servidor e `npx -y @weppy/roblox-mcp`.
 
 ## Compatibilidade
 
-| 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+ ou macOS 12+
 
@@ -73,17 +82,15 @@ A IA consegue operar diretamente scripts, instancias, propriedades, terreno, ilu
 - "Cria uma arena de boss no centro do mapa e coloca spawns sem colisao."
 - "Muda a interface deste modulo e atualiza todos os scripts dependentes."
 
-Nao e apenas geracao de codigo. Sao **acoes executaveis para fluxo real de desenvolvimento**.
-
 ### 2) Sync: mantem contexto completo do projeto para a IA
 
 A IA trabalha com um espelho local sincronizado, entao alteracoes em varios arquivos continuam consistentes.
 
-![Fluxo de Sync — Studio e arquivos locais sincronizados em tempo real](../assets/screenshots/plugin/sync/sync-overview.png)
-
 - Basic: sincronizacao unidirecional (Studio -> Local)
 - Pro: sincronizacao bidirecional + Direction/Apply Mode por tipo + historico + multiplace
 
+![Fluxo de Sync — Studio e arquivos locais sincronizados em tempo real](../assets/screenshots/plugin/sync/sync-overview.png)
+
 ### 3) Playtest: a IA executa e valida testes automaticamente
 
 A IA pode controlar diretamente o playtest do Studio. Ela pode iniciar e parar Play (F5) ou Run (F8), injetar scripts de teste, coletar logs e gerar relatorios locais automaticamente.
@@ -98,24 +105,24 @@ A IA pode controlar diretamente o playtest do Studio. Ela pode iniciar e parar P
 
 No dashboard web fornecido pelo servidor MCP, acompanhe em tempo real o status de conexao, historico de execucao de ferramentas, status de sincronizacao e historico de alteracoes do jogo.
 
-![WROX WROX Dashboard Overview — status do servidor, alteracoes recentes e resumo da sessao](../assets/screenshots/dashboard/dashboard_overview.png)
-
 - Visualize o status de conexao do servidor/plugin/agente de uma so vez
 - Compare todas as alteracoes feitas pela IA com Before & After no Changelog
 - Analise o fluxo de trabalho com historico e estatisticas de execucao de ferramentas
 
+![WROX WROX Dashboard Overview — status do servidor, alteracoes recentes e resumo da sessao](../assets/screenshots/dashboard/dashboard_overview.png)
+
 ### 5) WROX Roblox Explorer: navegue a hierarquia do Studio no VSCode
 
 Visualize a arvore completa de instancias do seu lugar no Roblox Studio diretamente dentro do VSCode. Navegue pelos servicos, abra scripts e arquivos de propriedades sincronizados, e acompanhe o status de sincronizacao — tudo sem trocar para o Studio.
 WROX Roblox Explorer e uma extensao complementar do VSCode para os dados de sync gerados pelo WROX. A navegacao basica da arvore funciona a partir dos arquivos sincronizados em disco, e os indicadores ao vivo de status sync ou direction ficam mais completos quando o servidor MCP local esta em execucao.
 Instale pela [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=weppy.weppy-roblox-explorer) ou pela [Open VSX](https://open-vsx.org/extension/weppy/weppy-roblox-explorer).
 
-![WROX Roblox Explorer — arvore de instancias do Studio exibida na barra lateral do VSCode](../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
-
 - Icones de classe iguais ao Studio para reconhecimento imediato
 - Clique para abrir scripts e arquivos de propriedades sincronizados
 - Suporte multiplace com indicadores de status de sincronizacao
 
+![WROX Roblox Explorer — arvore de instancias do Studio exibida na barra lateral do VSCode](../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
+
 ## Valor imediato para o usuario
 
 - Comprimir trabalho repetitivo: transformar muitas edicoes manuais em um pedido
@@ -123,6 +130,14 @@ Instale pela [VS Code Marketplace](https://marketplace.visualstudio.com/items?it
 - Reduzir risco: decidir com base no estado do sync e no historico
 - Melhor eficiencia de tokens (Pro): menos round trips com acoes em massa
 
+## Casos de uso
+
+- **Prototipagem rápida**: Descreva uma mecânica de jogo em linguagem natural e veja a IA construí-la no Studio
+- **Refatoração em massa**: Renomeie uma interface de módulo e atualize todos os scripts dependentes em uma única solicitação
+- **Terrain e ambiente**: Gere terrain procedural, configure iluminação/atmosfera, posicione assets — tudo a partir de um único prompt
+- **Consistência multi-arquivo**: A IA lê o projeto completo via Sync e aplica alterações em scripts relacionados de forma conjunta
+- **Integração de assets**: Pesquise no Creator Store, insira modelos e configure propriedades sem sair do editor
+
 ## Documentacao detalhada
 
 - [Guia de instalacao](installation/README.md)
@@ -142,12 +157,47 @@ Instale pela [VS Code Marketplace](https://marketplace.visualstudio.com/items?it
 - [Playtest e testes automatizados](tools/playtest.md) - controle de playtest e validacao automatica
 - [Sistema e depuracao](tools/system-and-debugging.md) - conexao, logs e execucao em lote
 
+## FAQ
+
+### Como conecto o Claude Code ao Roblox Studio?
+Instale o plugin do Roblox Studio e registre o servidor MCP (`npx -y @weppy/roblox-mcp`) no Claude Code. O Claude poderá ler e escrever scripts diretamente dentro do Studio. Consulte [Configuração do Claude Code](installation/ai-apps/claude-code.md).
+
+### Como uso o Codex CLI com o Roblox Studio?
+Instale o plugin e adicione a configuração do servidor MCP ao Codex CLI. Consulte [Configuração do Codex CLI](installation/ai-apps/codex-cli.md).
+
+### O Roblox MCP funciona com o Cursor?
+Sim. Consulte [Configuração do Cursor](installation/ai-apps/cursor.md). Qualquer cliente de IA compatível com MCP funciona.
+
+### A IA pode criar jogos Roblox com isso?
+Sim. A IA pode criar instâncias, escrever scripts, gerar terrain, configurar iluminação, inserir assets, configurar física e mais — tudo dentro de uma sessão de Studio ao vivo. Vai além da geração de código para ações executáveis.
+
+### Qual é a diferença entre Basic e Pro?
+Basic (gratuito) inclui execução de ferramentas MCP e sincronização unidirecional (Studio -> Local). Pro adiciona sincronização bidirecional, operações em massa, geração de terrain, análise espacial, controle de áudio/animação e suporte multi-place. Consulte o [Guia de upgrade Pro](pro-upgrade.md).
+
+### Como o Weppy se diferencia de outros servidores MCP para Roblox?
+O Weppy usa despacho baseado em ações em vez de ferramentas separadas para cada função. Isso reduz significativamente o consumo de tokens de IA. Também fornece sincronização bidirecional de projeto e suporte multi-place, que a maioria das alternativas não possui.
+
+### É seguro? A IA pode quebrar meu jogo?
+O servidor roda apenas em localhost (127.0.0.1:3002). Caminhos proibidos (CoreGui, CorePackages) são bloqueados. Limitação de taxa (450 req/min) e timeouts de 30 segundos previnem operações descontroladas. Todas as alterações são rastreáveis pelo histórico de sincronização.
+
 ## Upgrade Pro
 
 Sync bidirecional, recursos avancados de criacao e eficiencia de tokens de IA — tudo em uma unica atualizacao.
 
 [Guia de upgrade Pro](pro-upgrade.md)
 
+## Licença
+
+Este repositório está licenciado sob `AGPL-3.0`.
+
+Licenciamento comercial está disponível separadamente. Consulte [COMMERCIAL-LICENSE.md](../../COMMERCIAL-LICENSE.md).
+
+O uso do nome e logotipos Weppy é regido 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/pt-br/dashboard/connection.md

@@ -6,7 +6,7 @@
 
 ## Visao geral
 
-A pagina Connection monitora todos os status de conexao do sistema MCP em um unico local. Esta sempre acessivel quando o servidor esta conectado (L1 ou superior).
+A pagina Connection monitora todos os status de conexao do sistema MCP em um unico local. Esta sempre acessivel quando o dashboard esta em estado **Servidor conectado** ou **Studio conectado**.
 
 ## Server Status
 

package/docs/pt-br/dashboard/overview.md

@@ -34,17 +34,17 @@ http://localhost:3002
 
 > Defina `DASHBOARD_AUTO_OPEN=false` para desativar a abertura automatica (consulte a pagina [Settings](settings.md)).
 
-## Niveis de conexao
+## Estados de conexao
 
 O Dashboard oferece funcionalidades diferentes de acordo com o status da conexao:
 
-| Nivel | Condicao | Paginas disponiveis |
-|:-----:|----------|---------------------|
-| **L0** | Servidor desconectado | Exibe apenas a tela de aguardando reconexao |
-| **L1** | Servidor conectado, plugin desconectado | Connection, Tools, Settings |
-| **L2** | Servidor + plugin ambos conectados | Todas as paginas |
+| Estado | Condicao | Paginas disponiveis |
+|--------|----------|---------------------|
+| **Servidor desconectado** | Servidor desconectado | Exibe apenas a tela de aguardando reconexao |
+| **Servidor conectado** | Servidor conectado, plugin desconectado | Connection, Tools, Settings |
+| **Studio conectado** | Servidor + plugin ambos conectados | Todas as paginas |
 
-Quando o plugin nao esta conectado (L1), as paginas Overview, Changelog, Sync e Playtest nao ficam acessiveis.
+Quando o dashboard esta em estado **Servidor conectado**, as paginas Overview, Changelog, Sync e Playtest nao ficam acessiveis.
 
 ## Overview
 

package/docs/pt-br/dashboard/playtest.md

@@ -6,7 +6,7 @@
 
 ## Visao geral
 
-A pagina Playtest exibe o status e os resultados dos playtests executados pela IA. So fica acessivel quando o plugin esta conectado (L2).
+A pagina Playtest exibe o status e os resultados dos playtests executados pela IA. So fica acessivel quando o dashboard esta em estado **Studio conectado**.
 
 ## Playtest Status
 

package/docs/pt-br/dashboard/settings.md

@@ -4,7 +4,7 @@
 
 ## Visao geral
 
-Na pagina Settings, voce pode verificar as informacoes de licenca e as configuracoes do servidor, alem de alterar algumas delas. Esta sempre acessivel quando o servidor esta conectado (L1 ou superior).
+Na pagina Settings, voce pode verificar as informacoes de licenca e as configuracoes do servidor, alem de alterar algumas delas. Esta sempre acessivel quando o dashboard esta em estado **Servidor conectado** ou **Studio conectado**.
 
 ## License (somente leitura)
 

package/docs/pt-br/dashboard/sync.md

@@ -8,7 +8,7 @@
 
 ## Visao geral
 
-A pagina Sync exibe visualmente o status atual e as configuracoes da sincronizacao Studio <-> arquivos locais. So fica acessivel quando o plugin esta conectado (L2).
+A pagina Sync exibe visualmente o status atual e as configuracoes da sincronizacao Studio <-> arquivos locais. So fica acessivel quando o dashboard esta em estado **Studio conectado**.
 
 ## Sync Status
 

package/docs/pt-br/dashboard/tools.md

@@ -6,7 +6,7 @@
 
 ## Visao geral
 
-A pagina Tools fornece o historico e as estatisticas das ferramentas MCP executadas pela IA. E composta por duas sub-abas: **History** e **Statistics**. Esta sempre acessivel quando o servidor esta conectado (L1 ou superior).
+A pagina Tools fornece o historico e as estatisticas das ferramentas MCP executadas pela IA. E composta por duas sub-abas: **History** e **Statistics**. Esta sempre acessivel quando o dashboard esta em estado **Servidor conectado** ou **Studio conectado**.
 
 ## Aba History
 

package/docs/pt-br/installation/README.md

@@ -72,7 +72,7 @@ Registre o servidor MCP no seu app de IA. Funciona com qualquer app que suporte
 ## Opcional: Instalar WROX Roblox Explorer (Extensão VSCode)
 
 Navegue pelas árvores de instâncias sincronizadas dentro do VSCode com ícones de classes Roblox.
-Esta extensao opcional exige que a instalacao do Roblox MCP acima ja esteja concluida, porque o Explorer le os dados `roblox-project-sync` gerados pelo Sync.
+Esta extensao opcional exige que a instalacao do Roblox MCP acima ja esteja concluida, porque o Explorer le os dados de Sync em `wrox-project-sync` dentro da raiz do projeto.
 
 👉 [Guia de instalação do WROX Roblox Explorer](roblox-explorer.md)
 

package/docs/pt-br/installation/roblox-explorer.md

@@ -9,7 +9,7 @@ Esta é uma extensao complementar do WROX, e não uma integração Roblox indepe
 
 - VSCode 1.85+
 - [Roblox MCP](../../../README.md) instalado com Sync habilitado (Basic ou Pro)
-- `roblox-project-sync/place_*/.sync-meta.json` já gerado pelo Sync
+- O Sync ja gerou `wrox-project-sync/place_*/.sync-meta.json` na raiz do projeto
 
 ## Instalação
 
@@ -37,7 +37,7 @@ A navegação basica da arvore funciona a partir dos arquivos sincronizados em d
 
 | Configuração | Padrão | Descrição |
 |--------------|--------|-----------|
-| `robloxExplorer.syncRoot` | `""` | Caminho absoluto para a raiz do `roblox-project-sync`. Detectado automaticamente se vazio. |
+| `robloxExplorer.syncRoot` | `""` | Caminho absoluto para a raiz do `wrox-project-sync`. Se estiver vazio, e detectado automaticamente. O WROX usa `{projectRoot}/wrox-project-sync`. |
 | `robloxExplorer.hidePropsFiles` | `false` | Oculta arquivos de Sync (`.props.json`, `_tree.json`, `.value.json`) no explorador padrão do VSCode. |
 | `robloxExplorer.autoRefresh` | `true` | Atualiza automaticamente a árvore quando os arquivos Sync mudam. |
 | `robloxExplorer.showSyncStatus` | `true` | Exibe decorações de status Sync nos itens da árvore. |

package/docs/pt-br/sync/overview.md

@@ -18,7 +18,7 @@ Sem Sync, a IA so enxerga trechos colados no chat. Com Sync ativo, ela trabalha
 2. Incremental Sync: atualizacao continua das mudancas novas
 3. Rastreamento de History/Status: ver o que mudou, quando e em qual direcao
 
-O caminho local padrao e `roblox-project-sync/place_{placeId}/explorer`.
+Os dados de Sync ficam em `{projectRoot}/wrox-project-sync/place_{placeId}/explorer`.
 
 ### Explorar dados sincronizados no VSCode
 

package/docs/pt-br/tools/playtest.md

@@ -86,10 +86,10 @@ Edit --play--> Running --stop--> Edit
 
 ### 5. Escrita de relatorios
 
-Os relatorios e logs sao gravados em arquivos locais:
+Os relatorios e logs sao gravados em `{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/llms-full.txt

@@ -495,7 +495,7 @@ Without Sync, AI only sees snippets pasted into chat. With Sync enabled, AI work
 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`.
 
 ## Sync Capabilities
 
@@ -565,13 +565,13 @@ Set `DASHBOARD_AUTO_OPEN=false` to disable automatic opening.
 | **Tools** | Tool execution history, statistics, tier distribution |
 | **Settings** | License, log level, sync settings, language |
 
-## Connection Levels
+## Connection States
 
-| Level | Condition | Available Pages |
-|:-----:|-----------|-----------------|
-| **L0** | Server not connected | Reconnection waiting screen only |
-| **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 | Reconnection waiting screen only |
+| **Server connected** | Server connected, plugin not connected | Connection, Tools, Settings |
+| **Studio connected** | Both server and plugin connected | All pages |
 
 ## Overview Page
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weppy/roblox-mcp",
-  "version": "2.0.10",
+  "version": "2.1.0",
   "description": "MCP (Model Context Protocol) server for Roblox Studio integration - enables AI coding agents to interact with Roblox Studio in real-time",
   "main": "plugins/weppy-roblox-mcp/dist/index.js",
   "type": "module",

package/plugins/weppy-roblox-mcp/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "weppy-roblox-mcp",
   "description": "MCP server for Roblox Studio integration - AI-powered game development with specialized agents and skills",
-  "version": "2.0.10",
+  "version": "2.1.0",
   "author": {
     "name": "hope1026"
   },