@weppy/roblox-mcp 1.0.2 → 1.0.3

package/docs/id/tools/overview.md

@@ -1,99 +1,259 @@
-# Fitur Roblox MCP
+# Alat Roblox MCP
 
-Hubungkan AI dengan Roblox Studio dan otomatiskan berbagai pekerjaan. Berikut adalah hal-hal yang bisa kamu lakukan berdasarkan kategori.
+Untuk parameter detail, periksa definisi alat MCP secara langsung.
 
-Kebijakan Sync:
-- Basic: Studio -> Local (satu arah)
-- Pro: Sync dua arah + cakupan fitur lanjutan lebih luas (efisiensi token AI lebih baik lewat operasi massal)
-
----
-
-## Basic (Gratis)
-
-### Manajemen Objek
-
-Buat, duplikat, hapus, dan pindahkan objek game seperti part, model, dan folder. Pekerjaan seperti "Buatkan part merah" atau "Duplikat model ini dan taruh di sebelahnya" bisa dilakukan.
-
-### Properti
-
-Baca dan ubah semua properti objek seperti ukuran, warna, posisi, dan material. Kamu bisa mengubah beberapa properti sekaligus atau menyesuaikan secara relatif berdasarkan nilai saat ini.
-
-### Script
-
-Buat script baru, baca kode yang ada, dan modifikasi. Kamu bisa mengedit baris tertentu, mencari teks di dalam script, atau mengidentifikasi dependensi untuk melihat modul mana yang direferensikan.
-
-### Seleksi
-
-Cek objek yang sedang dipilih, ubah seleksi, dan bersihkan seleksi. Penting untuk memahami dan mengontrol apa yang sedang kamu kerjakan di Studio.
-
-### Pencarian
-
-Temukan objek di game berdasarkan nama atau kelas (tipe).
-
-### Tag
-
-Tambah atau hapus tag dari objek dan temukan semua objek dengan tag tertentu sekaligus. Berguna untuk mengelola grup objek sejenis.
-
-### Kamera
-
-Pindahkan kamera ke objek atau posisi tertentu. Praktis untuk melihat area yang sedang kamu kerjakan dengan cepat.
-
-### Log
-
-Cek output log dan error yang terjadi saat game berjalan. Membantu menemukan dan memperbaiki bug.
-
-### Koneksi
-
-Cek status koneksi dan penggunaan antara server MCP dan Roblox Studio.
-
----
-
-## Pro
-
-Kalau butuh fitur yang lebih kuat, kamu bisa upgrade ke Pro.
+Dokumen terkait:
+- [Panduan detail Sync](../sync/overview.md)
 
-### Seleksi Lanjutan
-
-Dapatkan konteks seleksi detail dengan properti dan source code, jelajahi hierarki seleksi, tambah/hapus item dari seleksi, dan lihat informasi Place serta service game. Berguna untuk workflow lanjutan dan otomasi.
-
-### Script Lanjutan
-
-Ganti konten di beberapa script sekaligus atau jalankan kode Luau secara instan. Berguna untuk modifikasi kode berulang atau pengujian cepat.
-
-### Pencarian Lanjutan
-
-Jelajahi seluruh file tree atau cari objek berdasarkan properti atau tag. Dapatkan gambaran lengkap struktur proyek dan lihat semua descendant atau ancestor dari objek tertentu.
-
-### Operasi Massal
-
-Buat, hapus, modifikasi, atau duplikat ratusan objek sekaligus. Tangani pekerjaan skala besar dengan cepat seperti menanam pohon di map, mengubah warna semua part, atau menempatkan objek sesuai pola.
-
-### Aset
-
-Cari model gratis di Roblox Creator Store dan masukkan langsung. Tambahkan aset lewat percakapan seperti "Carikan model kastil abad pertengahan" atau "Masukkan model senjata".
-
-### Lingkungan
-
-Atur pencahayaan, langit, kabut, properti terrain, dan waktu dengan bahasa alami. Permintaan seperti "Ubah ke suasana senja" atau "Set waktu ke tengah malam" bisa dilakukan.
-
-### Manajemen State
-
-Simpan state Workspace saat ini sebagai snapshot dan cek perubahan terbaru serta status viewport. Membantu memahami state saat ini selama pekerjaan kompleks.
-
-### Analisis Spasial
-
-Tentukan ukuran dan posisi objek secara akurat, temukan ruang kosong, dan cek tabrakan. Kamu juga bisa menyelaraskan objek ke grid.
-
-### Raycast
-
-Tembakkan sinar tak terlihat untuk menemukan titik tabrakan dengan terrain atau objek. Penting untuk desain level game: menemukan posisi tanah, mengecek apakah objek bisa ditempatkan, mencari lokasi spawn, dan menganalisis area yang bisa dilalui.
-
-### Terrain
-
-Isi, pahat, dan haluskan terrain dengan berbagai bentuk seperti blok, bola, silinder, dan baji. Ubah material dan warna, atau buat terrain alam secara prosedural dengan gunung dan sungai.
-
-### Visualisasi
-
-Tampilkan area, marker, dan garis di layar untuk mengonfirmasi ruang kerja secara visual. Berguna untuk debugging dan review desain level.
-
-👉 [Panduan Upgrade Pro](../pro-upgrade.md)
+Kebijakan Sync:
+- Basic: Studio -> Local sinkronisasi satu arah
+- Pro: Sinkronisasi dua arah + cakupan aksi lanjutan lebih luas (efisiensi token AI lebih baik dengan alur kerja massal)
+
+## Query Instances (Campuran)
+
+| Aksi | Deskripsi | Tier |
+|------|-----------|------|
+| `get` | Mendapatkan properti instance berdasarkan path | Basic |
+| `children` | Mendapatkan anak langsung atau semua keturunan | Basic |
+| `find_child` | Mencari anak pertama berdasarkan nama dan filter kelas opsional | Basic |
+| `find_descendant` | Mencari keturunan pertama berdasarkan nama | Basic |
+| `wait_for_child` | Menunggu anak muncul (dengan timeout) | Basic |
+| `class_info` | Mendapatkan informasi kelas dan properti yang valid | Basic |
+| `search_name` | Mencari instance berdasarkan pola nama (mendukung wildcard) | Basic |
+| `search_class` | Mencari instance berdasarkan nama kelas | Basic |
+| `file_tree` | Mendapatkan struktur pohon file dari root | Pro |
+| `project_structure` | Mendapatkan struktur proyek lengkap | Pro |
+| `descendants` | Mendapatkan semua keturunan dari sebuah instance | Pro |
+| `ancestors` | Mendapatkan semua leluhur dari sebuah instance | Pro |
+| `search_property` | Mencari instance berdasarkan nilai properti | Pro |
+| `search_tag` | Mencari instance berdasarkan tag | Pro |
+
+## Mutate Instances (Campuran)
+
+| Aksi | Deskripsi | Tier |
+|------|-----------|------|
+| `create` | Membuat instance baru | Basic |
+| `create_with_props` | Membuat instance dengan properti awal | Basic |
+| `delete` | Menghapus instance | Basic |
+| `clone` | Mengkloning instance | Basic |
+| `move` | Memindahkan instance ke parent baru | Basic |
+| `rename` | Mengganti nama instance | Basic |
+| `pivot` | Mengatur posisi pivot atau CFrame | Basic |
+| `create_tree` | Membuat pohon instance hierarkis | Pro |
+| `mass_create` | Membuat beberapa instance sekaligus | Pro |
+| `mass_delete` | Menghapus beberapa instance | Pro |
+| `mass_duplicate` | Menduplikasi beberapa instance | Pro |
+| `smart_duplicate` | Menduplikasi dengan jarak dan jumlah | Pro |
+
+## Manage Properties (Campuran)
+
+| Aksi | Deskripsi | Tier |
+|------|-----------|------|
+| `get` | Mendapatkan nilai satu properti | Basic |
+| `set` | Mengatur nilai satu properti | Basic |
+| `get_all` | Mendapatkan semua properti dari sebuah instance | Basic |
+| `set_multiple` | Mengatur beberapa properti sekaligus | Basic |
+| `get_attr` | Mendapatkan nilai atribut | Basic |
+| `set_attr` | Mengatur nilai atribut | Basic |
+| `get_all_attrs` | Mendapatkan semua atribut | Basic |
+| `delete_attr` | Menghapus atribut | Basic |
+| `add_tag` | Menambahkan tag ke instance | Basic |
+| `remove_tag` | Menghapus tag dari instance | Basic |
+| `check_tag` | Memeriksa apakah instance memiliki tag | Basic |
+| `get_tags` | Mendapatkan semua tag pada instance | Basic |
+| `get_tagged` | Mendapatkan semua instance dengan tag tertentu | Basic |
+| `set_calculated` | Mengatur properti menggunakan ekspresi matematika | Pro |
+| `set_relative` | Mengatur properti relatif terhadap nilai saat ini | Pro |
+| `mass_set` | Mengatur properti pada beberapa instance | Pro |
+| `mass_get` | Mendapatkan properti dari beberapa instance | Pro |
+| `modify_children` | Memodifikasi semua anak dari sebuah parent | Pro |
+
+## Manage Scripts (Campuran)
+
+| Aksi | Deskripsi | Tier |
+|------|-----------|------|
+| `get_source` | Mendapatkan kode sumber script | Basic |
+| `set_source` | Mengatur kode sumber script | Basic |
+| `create` | Membuat script baru | Basic |
+| `delete` | Menghapus script | Basic |
+| `edit_replace` | Mengganti baris tertentu di script | Basic |
+| `edit_insert` | Menyisipkan baris pada posisi | Basic |
+| `edit_delete` | Menghapus baris tertentu | Basic |
+| `search` | Mencari teks di script | Basic |
+| `get_dependencies` | Mendapatkan dependensi script | Basic |
+| `replace` | Penggantian massal di seluruh script | Pro |
+
+## Manage Lighting (Pro)
+
+| Aksi | Deskripsi | Tier |
+|------|-----------|------|
+| `lighting` | Mengatur properti layanan Lighting | Pro |
+| `atmosphere` | Mengatur properti Atmosphere | Pro |
+| `sky` | Mengatur properti Sky | Pro |
+| `terrain_props` | Mengatur properti visual/air Terrain | Pro |
+| `time` | Mengatur waktu hari | Pro |
+
+## Manage Selection (Campuran)
+
+| Aksi | Deskripsi | Tier |
+|------|-----------|------|
+| `get` | Mendapatkan seleksi saat ini | Basic |
+| `set` | Mengganti seleksi saat ini | Basic |
+| `clear` | Menghapus seleksi | Basic |
+| `cached` | Mendapatkan seleksi dari cache tanpa round-trip | Basic |
+| `context` | Mendapatkan konteks detail dengan sumber dan properti | Pro |
+| `details` | Mendapatkan detail hierarkis dengan leluhur/keturunan | Pro |
+| `add` | Menambahkan item ke seleksi | Pro |
+| `remove` | Menghapus item dari seleksi | Pro |
+| `watch` | Memantau perubahan seleksi | Pro |
+
+## Manage Camera (Basic)
+
+| Aksi | Deskripsi | Tier |
+|------|-----------|------|
+| `info` | Mendapatkan posisi, rotasi, FOV, dan ukuran viewport kamera | Basic |
+| `focus_path` | Memindahkan kamera untuk fokus pada instance | Basic |
+| `focus_position` | Memindahkan kamera untuk fokus pada posisi | Basic |
+| `suggest` | Mendapatkan tampilan kamera yang disarankan untuk target | Basic |
+
+## Manage Tween (Pro)
+
+| Aksi | Deskripsi | Tier |
+|------|-----------|------|
+| `create` | Membuat tween dengan properti target | Pro |
+| `play` | Memutar tween yang dibuat | Pro |
+| `pause` | Menjeda tween yang berjalan | Pro |
+| `cancel` | Membatalkan tween | Pro |
+
+## Manage Audio (Pro)
+
+| Aksi | Deskripsi | Tier |
+|------|-----------|------|
+| `play` | Memutar suara (membuat Sound jika diperlukan) | Pro |
+| `stop` | Menghentikan suara yang diputar | Pro |
+| `pause` | Menjeda suara yang diputar | Pro |
+| `resume` | Melanjutkan suara yang dijeda | Pro |
+| `set_listener` | Mengatur tipe/target listener audio | Pro |
+
+## Manage Animation (Pro)
+
+| Aksi | Deskripsi | Tier |
+|------|-----------|------|
+| `load` | Memuat animasi pada Humanoid/AnimationController | Pro |
+| `play` | Memutar track animasi yang dimuat | Pro |
+| `stop` | Menghentikan animasi yang diputar | Pro |
+| `get_tracks` | Mendaftar semua track animasi yang dimuat | Pro |
+
+## Manage Physics (Pro)
+
+| Aksi | Deskripsi | Tier |
+|------|-----------|------|
+| `register_group` | Mendaftarkan grup tabrakan | Pro |
+| `set_collidable` | Mengatur apakah dua grup bisa bertabrakan | Pro |
+| `get_groups` | Mendaftar semua grup tabrakan terdaftar | Pro |
+
+## Manage Effects (Pro)
+
+| Aksi | Deskripsi | Tier |
+|------|-----------|------|
+| `emit` | Mengeluarkan partikel dari ParticleEmitter | Pro |
+| `clear` | Menghapus semua partikel | Pro |
+| `toggle` | Mengaktifkan atau menonaktifkan efek | Pro |
+
+## Manage Terrain (Pro)
+
+| Aksi | Deskripsi | Tier |
+|------|-----------|------|
+| `fill_block` | Mengisi terrain berbentuk blok | Pro |
+| `fill_ball` | Mengisi terrain berbentuk bola | Pro |
+| `fill_cylinder` | Mengisi terrain berbentuk silinder | Pro |
+| `fill_wedge` | Mengisi terrain berbentuk baji | Pro |
+| `clear_region` | Menghapus terrain di region | Pro |
+| `clear_bounds` | Menghapus terrain di batas | Pro |
+| `replace_material` | Mengganti material di region | Pro |
+| `colors_get` | Mendapatkan warna material | Pro |
+| `colors_set` | Mengatur warna material | Pro |
+| `read_voxel` | Membaca data voxel tunggal | Pro |
+| `read_voxels` | Membaca data voxel massal | Pro |
+| `write_voxels` | Menulis data voxel massal | Pro |
+| `generate` | Menghasilkan terrain prosedural | Pro |
+| `smooth` | Menghaluskan terrain | Pro |
+
+## Spatial Query (Pro)
+
+| Aksi | Deskripsi | Tier |
+|------|-----------|------|
+| `raycast` | Meluncurkan satu sinar | Pro |
+| `find_ground` | Menemukan posisi tanah di bawah titik | Pro |
+| `check_placement` | Memeriksa apakah penempatan bebas tabrakan | Pro |
+| `multi_raycast` | Meluncurkan beberapa sinar sekaligus | Pro |
+| `scan_area` | Menghasilkan peta ketinggian area | Pro |
+| `find_flat` | Menemukan area datar untuk pembangunan | Pro |
+| `find_spawn` | Menemukan posisi spawn yang sesuai | Pro |
+| `analyze_walkable` | Menganalisis grid kemampuan jalan | Pro |
+| `spatial_map` | Mendapatkan semua posisi BasePart | Pro |
+| `find_space` | Menemukan ruang kosong untuk objek | Pro |
+| `bounds` | Mendapatkan kotak pembatas instance | Pro |
+| `snap_grid` | Menyelaraskan posisi ke grid | Pro |
+| `collision` | Memeriksa tabrakan AABB | Pro |
+
+## Manage Assets (Pro)
+
+| Aksi | Deskripsi | Tier |
+|------|-----------|------|
+| `insert` | Menyisipkan model berdasarkan ID aset | Pro |
+| `info` | Mendapatkan metadata aset | Pro |
+| `search` | Mencari di Creator Store | Pro |
+| `search_insert` | Mencari dan menyisipkan kecocokan pertama | Pro |
+| `insert_free` | Menyisipkan model gratis | Pro |
+| `insert_package` | Menyisipkan paket | Pro |
+| `export` | Mengekspor seleksi saat ini | Pro |
+
+## Manage Sync (Pro)
+
+| Aksi | Deskripsi | Tier |
+|------|-----------|------|
+| `status` | Mendapatkan status sinkronisasi sebuah Place | Pro |
+| `config` | Mendapatkan konfigurasi sinkronisasi | Pro |
+| `history` | Mendapatkan riwayat perubahan | Pro |
+| `directions` | Mendapatkan arah sinkronisasi per tipe | Pro |
+| `read_file` | Membaca file yang disinkronkan | Pro |
+| `write_file` | Menulis ke file yang disinkronkan | Pro |
+| `progress` | Mendapatkan progres sinkronisasi real-time dan bandwidth | Pro |
+
+## Workspace State (Pro)
+
+| Aksi | Deskripsi | Tier |
+|------|-----------|------|
+| `sync` | Mendapatkan state Workspace saat ini | Pro |
+| `snapshot` | Mendapatkan struktur pohon instance lengkap | Pro |
+| `changes` | Mendapatkan perubahan terbaru | Pro |
+| `viewport` | Mendapatkan informasi kamera dan viewport | Pro |
+
+## Manage Logs (Basic)
+
+| Aksi | Deskripsi | Tier |
+|------|-----------|------|
+| `get` | Mendapatkan log yang difilter | Basic |
+| `clear` | Menghapus buffer log | Basic |
+| `errors` | Mendapatkan hanya error terbaru | Basic |
+
+## System Info (Campuran)
+
+| Aksi | Deskripsi | Tier |
+|------|-----------|------|
+| `ping` | Menguji koneksi | Basic |
+| `connection` | Mendapatkan info koneksi server/plugin | Basic |
+| `usage` | Mendapatkan tier saat ini (basic/pro) | Basic |
+| `place_info` | Mendapatkan Place ID, nama, kreator | Pro |
+| `services` | Mendaftar semua layanan Roblox | Pro |
+| `studio_settings` | Mendapatkan preferensi Studio | Pro |
+| `run_command` | Menjalankan perintah Studio | Pro |
+
+## Batch Execute (Pro)
+
+Menjalankan beberapa perintah dalam satu batch. Setiap perintah menentukan nama alat dan argumen. Perintah dijalankan secara berurutan dengan perilaku opsional lanjut saat terjadi error.
+
+## Execute Luau (Pro)
+
+Menjalankan kode Luau arbitrer di sandbox Roblox Studio. Layanan yang diblokir: HttpService, DataStoreService, MessagingService. Tidak dapat mengakses CoreGui/CorePackages.

package/docs/ja/README.md

@@ -6,74 +6,47 @@
 
 [![デモ](https://img.youtube.com/vi/3jrUpBbZPaw/maxresdefault.jpg)](https://youtu.be/3jrUpBbZPaw)
 
-## できること
+## 主要機能
 
-### アイデア一つで、プレイ可能なゲームまで
+### 1) MCP Tool: 自然言語の指示をStudioで直接実行
 
-「マインクラフト風サバイバルゲームを作って。昼夜サイクル、採掘、クラフト、ウェーブディフェンスまで。」 — 一文でAIがゲーム構造を設計し、マップ・オブジェクト・スクリプトまで直接作ってくれます。
+Roblox MCPの第一の柱は**MCP Tool実行**です。
+AIがStudio内で、スクリプト、インスタンス、プロパティ、地形、ライティング、アセット、オーディオ、アニメーションを直接処理します。
 
-> **ヒント**: 「まず計画を立てて」とリクエストし、計画を確認してから「実行して」と指示すると、より完成度の高い結果が得られます。
+- 「プレイヤーのジャンプ時に、パーティクル + サウンド + クールタイムを追加して。」
+- 「マップ中央にボスアリーナを作って、衝突しないスポーンポイントを配置して。」
+- 「このモジュールのインターフェースを変えて、依存スクリプトを全部更新して。」
 
-### プロジェクト全体を読み込んだAI
+単なるコード生成ではなく、**実行可能な作業単位**として処理できる点が重要です。
 
-AIがRobloxプロジェクトをローカルに同期して、すべてのスクリプト・オブジェクト・構造を把握します。数十ファイルを一度に理解し、一貫して修正します。
+### 2) Sync: AIがプロジェクト全体の文脈を維持
 
-- 「RemoteEventを使っている場所を全部見つけて呼び出しフローを整理して。」
-- 「敵AIのスクリプト全体を統一したステートマシン構造にリファクタリングして。」
-- 「昨日以降に変更されたファイルの中でリスクの高い変更だけ要約して。」
+第二の柱は**Project Sync**です。
+同期されたローカルミラーを基準にAIが作業するため、複数ファイルにまたがる変更も一貫して適用できます。
 
-複数のPlaceを同時に管理し、変更履歴も追跡できます。
+- Basic: 片方向同期 (Studio -> Local)
+- Pro: 双方向同期 + タイプ別Direction/Apply Mode + 変更履歴 + マルチPlace
 
-### スクリプトの作成・リファクタリング・デバッグ、関連ファイルまとめて
+どちらを正とするかを明確に保ち、変更文脈の取りこぼしを防げます。
 
-指定したファイルだけでなく、依存関係にある全ファイルをまとめて処理します。
+## すぐに実感できる価値
 
-- 「プレイヤーがジャンプしたときにパーティクル + サウンド + クールタイムを追加して。」
-- 「メモリリークの可能性があるイベント接続を全部見つけて安全に修正して。」
-- 「このモジュールのインターフェースを変えて、参照している全スクリプトも一緒に更新して。」
+- 反復作業を圧縮: 多数の手作業を1つの指示に集約
+- 関連ファイルを同時に変更: 単一ファイル修正で終わらない
+- リスク低減: 同期状態と履歴を見ながら安全に変更
+- トークン効率向上 (Pro): バルク処理で往復回数を削減
 
-### オブジェクトの作成と配置 — 数百個も一コマンドで
+## 詳細ドキュメント
 
-「この道に沿って街灯を50本間隔を揃えて立てて」「レンガの家20軒をエリアごとにランダムな向きで配置して」 — AIがStudioに直接作成します。複数オブジェクトのプロパティをまとめて変更するのも一コマンドで済みます。
-
-### 照明・天気・演出を一文で
-
-「夕焼けのほこりっぽい砂漠の雰囲気に変えて」「嵐の夜で、稲妻の瞬間だけ周りが明るくなるようにして」 — 一言で照明、空、大気、霧が一括で自動変更されます。
-
-### 会話で彫刻する自然地形
-
-「マップ北部に断崖の山脈、中央に川、南部に広い平原を作って」 — 山、川、平原、洞窟を会話だけで生成できます。素材、色、高さ、滑らかさを自由に調整し、地形エディタを開かずにマップ全体を完成させられます。
-
-### Creator Storeのアセットを検索してすぐに配置
-
-「中世の城のモデルを見つけてマップ中央に配置して、スケールを1.5倍にして」 — 無料アセットを検索してプロジェクトにすぐ追加できます。
-
-### 空間インテリジェンスでレベルデザインまで
-
-「新しいボスアリーナに使える空きスペースを見つけて」「モンスターが実際にパトロールできるエリアだけ表示して」 — 複雑な空間推論と配置ロジックをAIが処理します。
-
-### アニメーション・物理・オーディオ、ゲームシステムとして連携
-
-- 「ダッシュアニメーション再生中はプレイヤーと敵の衝突ルールを変えて。」
-- 「アルティメット発動時に専用BGMをフェードイン、終了時に自然に戻して。」
-
-キャラクター、衝突、サウンドをバラバラなツールではなくゲームシステムとして連携させます。
-
-### どんなRoblox APIも直接実行
-
-内蔵ツールで足りないときは、AIがStudio内で任意のLuauコードを直接実行します。
-
-- 「Workspace全体からAnchored=falseのパーツだけ見つけてリストにして。」
-- 「条件に合うオブジェクトを一括更新して、変更結果をログに残して。」
-
-> [全機能リスト](tools/overview.md)
+- [Tool対応範囲 (Tools Overview)](tools/overview.md)
+- [Sync機能詳細ガイド](sync/overview.md)
 
 ## はじめに
 
 インストールは2つのステップで完了します:
 
-1. **Roblox Studioプラグインのインストール** — StudioとAIを接続する橋渡しの役割をします
-2. **AIアプリにMCPサーバーを登録** — 使用するAIアプリでRoblox MCPを認識できるように設定します
+1. **Roblox Studioプラグインのインストール** — StudioとAIを接続する橋渡し
+2. **AIアプリにMCPサーバーを登録** — 使用するAIアプリでRoblox MCPを認識
 
 5分で終わります。👉 [インストールガイド](installation/README.md)
 

package/docs/ja/sync/overview.md

@@ -0,0 +1,104 @@
+# Roblox MCP Sync 詳細ガイド
+
+SyncはRoblox Studioの状態とローカルファイルを接続し、AIがプロジェクト全体の文脈を安定して読み取り・変更できるようにする機能です。
+
+## なぜSyncが重要か
+
+Syncがない場合、AIはチャットに貼られた断片だけを見て判断します。Syncを有効にすると、プロジェクト全体を基準に作業できます。
+
+- 複数スクリプトにまたがるリファクタリングを一貫して適用
+- 変更履歴を使って高リスクな変更を素早く確認
+- Studioとローカルのどちらを正とするかを明確化
+
+## 基本の動作
+
+1. Full Sync: Studioツリー/インスタンスをローカルに初期ミラー
+2. Incremental Sync: 以後の変更分のみを継続反映
+3. History/Status追跡: いつ・どの方向で何が変わったかを確認
+
+ローカルの既定パスは `roblox-project-sync/place_{placeId}/explorer` です。
+
+## Basic vs Pro
+
+| 項目 | Basic | Pro |
+|------|------|-----|
+| 同期方向 | Studio -> Local | 双方向 |
+| タイプ別Direction | 非対応 | 対応 (Scripts / Values / Containers / Data / Services) |
+| タイプ別Apply Mode | 非対応 | 対応 (Auto / Manual) |
+| 状態/履歴API | 非対応 | 対応 (`status`, `history`, `progress`) |
+| `manage_sync` ツール | 非対応 | 対応 |
+| マルチPlace Sync | 非対応 | 対応 (最大3 Place) |
+
+## 同期対象と既定の除外ルール
+
+既定の同期対象サービス:
+
+- `Workspace`
+- `Lighting`
+- `ReplicatedStorage`
+- `ServerStorage`
+- `ServerScriptService`
+- `StarterGui`
+- `StarterPlayer`
+- `StarterPack`
+- `ReplicatedFirst`
+- `SoundService`
+- `Chat`
+- `LocalizationService`
+
+既定の除外項目:
+
+- クラス: `Terrain`, `Camera`
+- セキュリティ上アクセス禁止のパス: `CoreGui`, `CorePackages`, `RobloxScript`, `RobloxScriptSecurity`
+
+## Direction と Apply Mode
+
+### Direction（タイプ別同期方向）
+
+- `forward`: Studio -> Local
+- `reverse`: Local -> Studio
+- `bidirectional`: 双方向
+
+タイプは `scripts`, `values`, `containers`, `data`, `services` に分かれて管理されます。
+
+### Apply Mode（reverse変更の適用方法）
+
+- `manual`: Studio反映前にユーザー確認
+- `auto`: 検出された変更を自動適用
+
+ProではタイプごとにDirection/Apply Modeを細かく制御できます。
+
+## `manage_sync` アクションガイド (Pro)
+
+| アクション | 説明 | 主な引数 |
+|------|------|-----------|
+| `status` | Placeの現在の同期状態を確認 | `placeId` |
+| `config` | 同期設定を取得 | `placeId` |
+| `history` | 変更履歴を取得 | `placeId`, `query.limit`, `query.offset` |
+| `directions` | タイプ別Directionを取得 | `placeId` |
+| `read_file` | 同期ファイルを読み取り | `placeId`, `instancePath` |
+| `write_file` | 同期ファイルに書き込み | `placeId`, `instancePath`, `content` |
+| `progress` | リアルタイム進行状況/処理量を取得 | `placeId` |
+
+## 推奨ワークフロー
+
+### 1) 安全に開始
+
+- まずFull Syncを完了して基準点を作る
+- 初期は `manual` 適用でリスクを下げる
+
+### 2) AIと変更作業
+
+- 「Sync状態を確認して、直近履歴からリスクの高い変更だけ要約して」
+- 「`ServerScriptService` のスクリプトを先にリファクタリングして、履歴も残して」
+
+### 3) 問題時の復旧
+
+- `history` で最近の変更を追跡
+- `read_file` で対象ファイルを確認
+- `write_file` で内容を復元してStudio状態を再確認
+
+## 関連ドキュメント
+
+- [Tool対応範囲 (Tools Overview)](../tools/overview.md)
+- [Proアップグレードガイド](../pro-upgrade.md)