refactor: gate the AI assistant behind Experimental settings, not a feature flag

Author: nicoecheza

ONBOARDING.md

@@ -0,0 +1,70 @@
+# Creator Hub — Onboarding
+
+Creator Hub is Decentraland's desktop app (Electron) for building SDK7 scenes. It's an npm-workspaces monorepo:
+
+- **`@dcl/asset-packs`** — curated 3D assets + Smart Items.
+- **`@dcl/inspector`** — the web-based 3D scene editor (Babylon.js + Redux/Redux-Saga), embedded as an iframe.
+- **`creator-hub`** — the Electron app (main / preload / renderer) that wraps the inspector.
+
+Deps flow `asset-packs → inspector → creator-hub` (each linked via `file:`).
+
+## Get set up
+
+```bash
+make init          # clean, install, protoc, build all
+make build         # build all packages (asset-packs → inspector → creator-hub)
+cd packages/creator-hub && npm run start   # run the app in watch mode
+make test          # unit tests (vitest)   ·  make typecheck  ·  make lint
+```
+
+Node 22+. Read **`CLAUDE.md`** (architecture + hard-won gotchas), **`docs/coding-standards.md`**, and **`docs/testing-standards.md`** before touching code — they override defaults.
+
+---
+
+## The AI Scene Agent
+
+An in-editor AI chat panel that drives the user's **own installed `claude` / `codex` CLI** to build scenes — read the scene, write SDK7 code, mutate the scene graph, and run + drive the preview. It bills against the user's subscription (API keys are stripped by default), so there are no metered keys to manage.
+
+**Turn it on** (it's behind a feature flag, off by default): in a dev build set
+`localStorage['creator-hub:feature-flags'] = '{"creatorhub-ai-chat":true}'`. The 🤖 "Toggle AI assistant" button then appears in the editor header.
+
+### Mental model
+
+Four moving parts, one per process boundary:
+
+1. **Chat panel** (renderer) — `renderer/src/components/AiChatPanel`, a flex sibling of the inspector iframe in `EditorPage`. Redux slice `renderer/src/modules/store/ai`. It only sends prompts and renders streamed events.
+2. **Agent runner** (main) — `main/src/modules/ai.ts` raw-spawns the user's CLI, one child per turn, and parses its NDJSON stdout into events streamed back over the `ai.*` IPC channels. System prompt in `ai-prompt.ts`.
+3. **Scene MCP server** (main) — `main/src/modules/scene-mcp.ts`. A localhost, token-gated, **stateful** MCP server (streamable HTTP, one transport per session) handed to the CLI as its tool source. Read tools read the scene's `main.composite` straight from disk; **mutations, metrics, and selection go main → renderer → inspector-iframe over the SceneRpc bridge**, where the inspector runs its real operations on the live engine — so the viewport updates and undo + autosave come for free.
+4. **Explorer gateway** (main) — `main/src/modules/explorer-gateway.ts`. On `launch_preview` it starts the Decentraland preview with its `unity-explorer-mcp` server on, connects to it as an MCP *client*, and republishes the Explorer's runtime tools as dynamic `explorer_*` tools (screenshot, walk, click, logs, perf). The stateful server is what lets it push `tools/list_changed` so those tools appear/disappear live.
+
+### The tools the agent gets
+
+Read: `get_project_info`, `scene_state`, `entity_detail`, `get_selection`, `get_scene_metrics`, `editor_screenshot`.
+Mutate (all live + undoable): `create_entity`, `remove_entity`, `set_parent`, `set_component`, `remove_component`, `search_catalog`, `place_smart_item`, `attach_script`.
+Preview: `launch_preview`, `preview_status`, `stop_preview`, `explorer_call` + the dynamic `explorer_*` set.
+
+Each turn's mutations are counted, so a one-click **"Undo AI changes"** reverts a whole turn. Conversations persist per project (transcript in the renderer, `--resume` ids in main) and survive a restart.
+
+### Where the code lives
+
+| Layer | Files |
+|---|---|
+| main | `modules/ai.ts` (spawn/stream/env), `ai-prompt.ts`, `scene-mcp.ts` (server + tools + bridge), `explorer-gateway.ts`, `skills.ts` (sdk-skills) |
+| preload | `modules/ai.ts` |
+| renderer | `components/AiChatPanel`, `components/EditorPage` (the `SCENE_OP_HANDLERS` bridge + effects), `modules/store/ai` (slice, `persistence.ts`, `labels.ts`) |
+| inspector | `src/lib/rpc/scene/server.ts` — the `SceneServer`: every read/mutation handler runs here on the live engine |
+| shared | `types/ai.ts`, `types/ipc.ts` |
+
+### How to test it
+
+- **Unit:** `npm run test:unit` (main/preload/renderer/shared) and, in `packages/inspector`, `npm run test`. The load-bearing suites are `main/tests/{ai,scene-mcp,explorer-gateway}.test.ts` and `inspector` `scene.spec.ts`.
+- **Live (needs a real GPU window):** the viewport, mutations, metrics, and the gateway only work with real WebGL, which Playwright's `_electron.launch` does **not** give you. Launch a raw `electron .` with `--remote-debugging-port` and attach via `chromium.connectOverCDP`. Enable the flag (temp-patch `overrides.ts` or DEV localStorage), and open a scene that **already has `node_modules`** — the unpackaged `electron .` can't npm-install on open.
+
+### Gotchas
+
+- **The engine owns the scene graph.** Never write `main.composite`, `scene.json`, or `main.crdt` on disk — the inspector's autosave clobbers external edits within ~100 ms. Change the scene only through the tools.
+- **Stateful MCP server on purpose.** One transport per `Mcp-Session-Id`. That's the correct fix for the original "Server already initialized" bug (which came from sharing one transport) and it's what enables `tools/list_changed`. Don't revert to a shared/stateless transport.
+- **Redux freeze.** Deep-clone (`structuredClone`) any Redux-sourced payload before passing it to an in-place mutating helper, or it throws.
+- **Providers.** Claude and Codex both get the full tool suite (Codex via `-c mcp_servers…` overrides). Gemini isn't wired yet.
+
+Deeper design notes and the full test/harness recipes live in `CLAUDE.md` and `docs/`.

packages/creator-hub/renderer/src/components/EditorPage/component.tsx

@@ -34,7 +34,6 @@ import EditorPng from '/assets/images/editor.png';
 import { ai } from '#preload';
 import { useDispatch, useSelector } from '#store';
 import { useFeatureFlags } from '/@/hooks/useFeatureFlags';
-import { FeatureFlag } from '/@/modules/store/featureFlags';
 import { actions as snackbarActions } from '/@/modules/store/snackbar';
 import { actions as editorActions } from '/@/modules/store/editor';
 import { createGenericNotification } from '/@/modules/store/snackbar/utils';
@@ -131,8 +130,10 @@ export function EditorPage() {
   } = useEditor();
   const { settings, updateAppSettings } = useSettings();
   const { updatePackages } = useWorkspace();
-  const { flags: featureFlags, isEnabled } = useFeatureFlags();
-  const aiChatEnabled = isEnabled(FeatureFlag.AI_CHAT);
+  const { flags: featureFlags } = useFeatureFlags();
+  // The AI assistant is an experimental opt-in (Settings → Experimental), like the Bevy
+  // renderer — not a remote feature flag.
+  const aiChatEnabled = settings.aiAssistant;
   const { executeDeployment, getDeployment } = useDeploy();
   const deployment = project ? getDeployment(project.path) : undefined;
 

packages/creator-hub/renderer/src/components/Modals/AppSettings/Tabs/EditorTab/component.tsx

@@ -74,17 +74,25 @@ const EditorTab: React.FC<EditorTabProps> = ({
 
   const handleExperimentalChange = useCallback(
     (checked: boolean) => {
-      // Turning experimental off returns to the stable default renderer so an
-      // experimental renderer can't stay active while the picker is hidden.
+      // Turning experimental off returns to the stable defaults so no experimental feature
+      // stays active while its controls are hidden (renderer back to Babylon, AI off).
       updateSettings({
         ...settings,
         experimental: checked,
         renderer: checked ? settings.renderer : RENDERER.BABYLON,
+        aiAssistant: checked ? settings.aiAssistant : false,
       });
     },
     [settings, updateSettings],
   );
 
+  const handleAiAssistantChange = useCallback(
+    (checked: boolean) => {
+      updateSettings({ ...settings, aiAssistant: checked });
+    },
+    [settings, updateSettings],
+  );
+
   // MCP server connection details, fetched only while the toggle is on. Not persisted:
   // the URL/token are runtime values (a fresh port + token per app launch), so they're
   // read on demand rather than stored in settings.
@@ -258,6 +266,17 @@ const EditorTab: React.FC<EditorTabProps> = ({
                 {t('modal.app_settings.fields.renderer.bevy')}
               </MenuItem>
             </Select>
+            <FormControlLabel
+              control={
+                <Checkbox
+                  checked={!!settings.aiAssistant}
+                  onChange={(event: React.ChangeEvent<HTMLInputElement>) =>
+                    handleAiAssistantChange(event.target.checked)
+                  }
+                />
+              }
+              label={t('modal.app_settings.fields.ai_assistant.label')}
+            />
           </Box>
         )}
       </FormGroup>

packages/creator-hub/renderer/src/modules/store/featureFlags/types.ts

@@ -6,6 +6,4 @@
 export enum FeatureFlag {
   /** The Analytics section. Off until the analytics API is deployed. */
   ANALYTICS = 'creatorhub-analytics',
-  /** The in-editor AI scene assistant chat panel. Dark until turned on. */
-  AI_CHAT = 'creatorhub-ai-chat',
 }

packages/creator-hub/renderer/src/modules/store/translation/locales/en.json

@@ -417,6 +417,9 @@
         "experimental": {
           "label": "Experimental features"
         },
+        "ai_assistant": {
+          "label": "AI scene assistant"
+        },
         "mcp_server": {
           "label": "Expose AI assistant MCP server",
           "help": "Let an AI agent running outside Creator Hub control the open scene. Paste this into the agent's MCP configuration.",

packages/creator-hub/renderer/src/modules/store/translation/locales/es.json

@@ -417,6 +417,9 @@
         "experimental": {
           "label": "Funciones experimentales"
         },
+        "ai_assistant": {
+          "label": "Asistente de escena con IA"
+        },
         "mcp_server": {
           "label": "Exponer el servidor MCP del asistente de IA",
           "help": "Permite que un agente de IA externo a Creator Hub controle la escena abierta. Pega esto en la configuración MCP del agente.",

packages/creator-hub/renderer/src/modules/store/translation/locales/zh.json

@@ -417,6 +417,9 @@
         "experimental": {
           "label": "实验性功能"
         },
+        "ai_assistant": {
+          "label": "AI 场景助手"
+        },
         "mcp_server": {
           "label": "公开 AI 助手 MCP 服务器",
           "help": "让 Creator Hub 之外运行的 AI 代理控制打开的场景。将此内容粘贴到该代理的 MCP 配置中。",

packages/creator-hub/renderer/src/modules/store/workspace/slice.ts

@@ -36,6 +36,7 @@ const initialState: Async<Workspace> = {
     optimizedAssetsByPath: {},
     experimental: false,
     renderer: DEFAULT_RENDERER,
+    aiAssistant: false,
     exposeMcpServer: false,
     useApiKeyFromEnv: false,
   },

packages/creator-hub/shared/types/config.ts

@@ -49,6 +49,7 @@ export const DEFAULT_CONFIG: Config = {
     optimizedAssetsByPath: {},
     experimental: false,
     renderer: DEFAULT_RENDERER,
+    aiAssistant: false,
     exposeMcpServer: false,
     useApiKeyFromEnv: false,
   },

packages/creator-hub/shared/types/settings.ts

@@ -52,6 +52,9 @@ export type AppSettings = {
   experimental: boolean;
   // Which engine the inspector uses to render the scene in the editor viewport.
   renderer: RENDERER;
+  // Experimental: the in-editor AI scene assistant chat panel. Opt-in under Experimental
+  // features (like the renderer picker); off by default and reset when experimental is off.
+  aiAssistant: boolean;
   // Opt-in: expose the Creator Hub MCP server's URL + token in settings so an AI agent
   // running OUTSIDE the app (e.g. a studio agent) can register it and drive the open scene.
   // The in-app assistant uses that server regardless; this only reveals its connection