@vgai/cli 0.4.1 → 0.5.0-canary.20260719.0

package/README.md

@@ -5,34 +5,47 @@ running editor from the terminal (or from an AI agent — this is the CLI the
 template's `/editor` skill uses).
 
 It talks to the editor dev server's HTTP/SSE control API via
-[`@vgai/editor-sdk`](../editor-sdk/).
+[`@vgai/editor-sdk`](https://www.npmjs.com/package/@vgai/editor-sdk).
 
-## Install
+## Create a game—no global install
 
 ```bash
-cd packages/vgai-cli && npm run build
-npm link                      # puts a global `vgai` on your PATH
-# or, without a global install, invoke the built file directly:
-#   node /path/to/vgai-engine/packages/vgai-cli/dist/index.js <command>
+npx @vgai/cli@latest create my-game
 ```
 
-> `npm link` works: the entry-point guard realpath-resolves `process.argv[1]`
-> before comparing it against `import.meta.url`, so a symlinked `vgai` bin runs
-> correctly. Direct `node dist/index.js` invocation is equally supported.
+This creates a standalone registry-backed project, installs it, opens its
+visual editor, and prints the actual editor URL. Node.js 22 or newer is
+required.
 
-`npm run build` bundles `src/index.ts` (esbuild, `--bundle --platform=node`) to
-`dist/index.js`, inlining the workspace-source dependencies it imports
-(`@vgai/editor-sdk`, `create-vgai-project` — neither ships a build step, so a
-plain `tsc` compile of the CLI alone would leave unresolvable `.ts` imports at
-runtime). The `bin` field points at that built file, so plain Node runs it —
-no bun required. The CLI resolves the engine root from its own file location,
-so it only works from inside a checkout of this monorepo.
+To keep `vgai` available globally:
+
+```bash
+npm install --global @vgai/cli
+vgai create my-game
+```
+
+An installed CLI defaults to versioned registry dependencies. A CLI built
+inside the VGAI source checkout defaults to contributor-oriented `file:`
+links; `--registry` and `--link` override that choice explicitly.
+
+To remix a shipped reference project instead of starting blank:
+
+```bash
+npx @vgai/cli@latest create my-game --example hp-hud
+```
+
+Examples are copied into standalone projects; editing the copy never changes
+the packaged reference or this repository.
 
 ## Commands
 
 ```
-vgai create <name> [location] [--template starter|empty] [--example <id>]   scaffold a project
+vgai create <name> [location] [--template default|2d|react] [--example <id>]
+            [--registry|--link] [--no-edit]
+vgai examples [--json]         list reference projects available to --example
 vgai edit [project-path]        launch the editor for a project (default: cwd)
+vgai inspect [folder] [--json]  read-only Three.js/R3F/PixiJS/React detection
+vgai adapt <folder> [--write]   preview by default; explicitly add only vgai.game.json
 vgai open <path>                switch project in a running editor
 vgai project | projects         show current / list recent projects
 vgai scene <path>               open a scene file
@@ -44,6 +57,8 @@ vgai show <viewport scene|game / inspector / console / build>
 vgai open-asset <path> <kind>
 vgai grid|helpers|stats <on|off> | shading <solid|unlit|wireframe|normals|overdraw>
 vgai status                     print full editor state as JSON
+vgai mcp [folder]               standard stdio tools/resources/prompts for Codex,
+                                Claude Code, Cursor, and other MCP clients
 
 vgai apply-diff <scene> <patch> [--report]   apply a SceneDiff patch to a scene
                                 file, schema-validating the scene, the patch,
@@ -65,6 +80,23 @@ vgai deploy [folder]            build a first-party game folder and direct-uploa
 --port <n> / VGAI_EDITOR_PORT overrides vgai.game.json.editorPort
 ```
 
+Scaffolded projects include this ready-to-use `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "vgai": {
+      "command": "npm",
+      "args": ["run", "vgai", "--", "mcp", "."]
+    }
+  }
+}
+```
+
+The same server can be launched manually with `vgai mcp .`. It binds file and
+editor operations to that exact project; if its editor is not running, live
+tools fail instead of falling through to another project's session.
+
 `vgai play` is verification, not fire-and-forget: it waits for
 `playState === 'playing'`, then polls log entries until at least one frame has
 actually run, and prints any first-frame errors.
@@ -75,15 +107,21 @@ starts a separate editor on the scaffold-generated preference stored in
 opens the printed URL in your browser. Projects without that optional field
 use 5173 as their preference.
 
-## Limitations
+## Source-checkout development
+
+Contributors can build and link the current checkout:
+
+```bash
+npm run build -w @vgai/cli
+(cd packages/vgai-cli && npm link)
+vgai create my-game --link
+```
+
+The bundle inlines the shared private scaffolder, so the public CLI and the
+editor's New Project route use the same `scaffoldProject` implementation.
+Registry projects remain portable without the checkout; link projects are
+deliberately tied to it.
 
-- Monorepo-checkout only (engine root resolved relative to the CLI source).
-- Scaffolded projects reference the engine by a relative `file:` path — this is
-  the deliberate source-vendored model (the engine is meant to be read and
-  edited, not consumed as a black-box package), but it means projects are not
-  portable off the machine without the checkout.
+Learn and manual: https://vgai-learn.pages.dev
 
-`vgai create` scaffolds via the shared `scaffoldProject` library in
-[`create-vgai-project`](../create-vgai-project/) — the same implementation
-`npx create-vgai-project` and the editor dev-server's create-project route
-use (see that package's README for what scaffolding does).
+Hosted editor: https://vgai-editor.pages.dev