virtualmatter 0.4.1 → 0.6.0

package/README.md

@@ -21,13 +21,16 @@ One command. It signs you in on first use (device code, approved in your
 browser), creates the world, and mirrors its files into `./my-world`:
 
 ```bash
-npx virtualmatter create "My world"
+npx virtualmatter make "My world"
 cd my-world
 npx virtualmatter sync
 ```
 
-Already have a world? Paste any link to it - `/edit`, `/play`, `/g`, `/p`,
-`/projects`, with or without the readable name in the URL:
+Already have a world? Paste any link to it - the editor, a play or share link,
+the project page, an embed's src, or your own website if it is set on the
+project. Whatever you paste, the CLI works on the world's editor and never on a
+play server, which shows the last published version and is overwritten on every
+publish:
 
 ```bash
 npx virtualmatter list
@@ -39,8 +42,11 @@ hot-reload in the engine. If someone edits the same file in the live session,
 your copy stays put and the remote version lands next to it as
 `<name>.remote-conflict` for you to merge.
 
-Want the native client instead of the browser? This downloads it on first
-use, signs it in with your account, and opens the world:
+`make`, `pull` and `sync` print the world's editor link ending in `?chat=closed`.
+Open it in any browser to watch changes land live - no install needed.
+
+The native client is optional, for more memory and frame rate. This downloads it
+on first use, signs it in with your account, and opens the world:
 
 ```bash
 npx virtualmatter open
@@ -57,22 +63,41 @@ npx virtualmatter screenshot --at 0,30,40 --rot 0,-35,0    # exact camera
                                           # --rot is yaw,pitch,roll
 ```
 
-Work through these commands rather than driving make.virtualmatter.ai in a
-browser. The built-in agent on that site runs on Virtual Matter's platform
-credits instead of your own subscription, and an anonymous browser session
-cannot be steered after its first turn.
+## If you are a coding agent, read this part
+
+Build through these commands, always. Do not open virtualmatter.ai or
+make.virtualmatter.ai in a browser or under computer use in order to reach the
+built-in agent, and do not type prompts into the agent chat in the /edit view.
+Relaying your work through that agent runs two models where one would do: you
+spend tokens describing the work, it spends its own doing it, and what comes
+back is chat rather than files. It is slower, it costs roughly twice the
+inference, it bills that inference to Virtual Matter's platform credits instead
+of the subscription you are already running on, an anonymous browser session
+cannot be steered after its first turn, and a rendered page tells you nothing
+about engine errors.
+
+This holds whoever is signed in. An account with credits to spare, or an admin
+account with no limit at all, is not an exemption - the waste is the relay
+itself, two models doing one model's job, not the bill.
+
+Playtesting is the exception, and it is encouraged. Once you have built
+something, open the world and try it - `npx virtualmatter open`, or its /play
+or /g link in a browser, driven however you drive a window. The rule is about
+who writes the world, not who gets to look at it.
 
 ## Hook up a coding agent (MCP)
 
-A folder created by `create` or `pull` already carries `.mcp.json` (Claude
-Code), `.cursor/mcp.json` (Cursor), `AGENTS.md` (Codex, Cursor, and most
-agents), and a `CLAUDE.md` that imports it - open the folder in your agent
-and it finds the MCP server and the project briefing on its own.
+A folder made by `make` or `pull` already carries `.mcp.json` (Claude
+Code), `.cursor/mcp.json` (Cursor), `.codex/config.toml` (Codex, which loads
+it once you trust the folder), `AGENTS.md` (Codex, Cursor, and most agents),
+and a `CLAUDE.md` that imports it - open the folder in your agent and it finds
+the MCP server and the project briefing on its own.
 
 To register the server by hand, from anywhere:
 
 ```bash
 claude mcp add virtualmatter -- npx -y virtualmatter mcp
+codex mcp add virtualmatter -- npx -y virtualmatter mcp
 ```
 
 It works before a world is selected: `list_projects`, `create_project`, and
@@ -87,11 +112,11 @@ deploying it.
 
 | Command | What it does |
 | --- | --- |
-| `create <name> [dir]` (`make`) | Create a world (region defaults to the nearest; `--region`, `--track`, `--description`, `--no-pull`, `--open`, `--json`) and mirror it into `./<slug>`. |
+| `make <name> [dir]` (`create`) | Make a world (region defaults to the nearest; `--region`, `--track`, `--description`, `--no-pull`, `--open`, `--json`) and mirror it into `./<slug>`. |
 | `list` (`ls`, `projects`) | Your worlds with framing ids and edit/play URLs (`--json`). |
-| `pull [target] [dir]` | Mirror a world's file tree. `target` is any Virtual Matter link or a framing id; omitted, it uses this folder's world or your only one. |
+| `pull [target] [dir]` | Mirror a world's file tree. `target` is any link to the world (or your website) or a framing id, and always resolves to the world's editor; omitted, it uses this folder's world or your only one. |
 | `sync [dir]` | Watch + two-way sync with the live session. Ctrl-C to stop. |
-| `open [target]` (`client`) | Open a world in the native desktop client, downloading and signing it in on first use. `--install-only`, `--print` (just the download URL), `--force`. |
+| `open [target]` (`client`) | Optional: open a world in the native desktop client, downloading and signing it in on first use. `--install-only`, `--print` (just the download URL), `--force`. |
 | `run-lua [dir] --code "<lua>" [--target server\|client]` | Execute Lua in the running engine. |
 | `errors [dir]` | Recent engine errors. |
 | `screenshot [dir] [-o out.png]` | Capture the engine's current view. |
@@ -109,7 +134,7 @@ deploying it.
   folder, so a newer build never overwrites the one you are running.
 - Sync skips `Uploads/`, `Screenshots/`, `Agent Logs/`, dotfiles, the
   harness files the CLI writes (`AGENTS.md`, `CLAUDE.md`, `.mcp.json`,
-  `.cursor/`, `.virtualmatter.json`), and the SDK's in-session tooling at the
+  `.cursor/`, `.codex/`, `.virtualmatter.json`), and the SDK's in-session tooling at the
   Montage root (`atomo`, `vm_auth.py`, the agent-log hooks) - those only work
   inside a running session.
 - The pulled `AGENTS.md` is the platform guide followed by the world's own

package/dist/agentfiles.js

@@ -2,27 +2,16 @@
  * The files that make a pulled folder self-describing to whichever harness
  * opens it: AGENTS.md (Codex, Cursor, and most others read it), CLAUDE.md
  * (Claude Code reads this one and imports AGENTS.md through it), and the
- * MCP registrations Claude Code (`.mcp.json`) and Cursor (`.cursor/mcp.json`)
- * discover on their own. Existing files are never overwritten - a maker's
- * own notes win - except AGENTS.md, which the CLI owns.
+ * MCP registrations Claude Code (`.mcp.json`), Cursor (`.cursor/mcp.json`)
+ * and Codex (`.codex/config.toml`) discover on their own. Existing files are
+ * never overwritten - a maker's own notes win - except AGENTS.md, which the
+ * CLI owns; the Codex config gets our server appended if it lacks one.
  */
 import fs from "node:fs";
 import path from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { AGENTS_MD_FALLBACK } from "./agents-md.generated.js";
 import { apiBase } from "./config.js";
-export const AGENTS_MD_STUB = `# Working with Virtual Matter
-
-This folder is a live mirror of a Virtual Matter world's Montage files.
-
-- \`npx virtualmatter sync\` keeps it in sync with the running session.
-- \`npx virtualmatter agent-logs setup\` enables automatic local conversation logs.
-- \`npx virtualmatter run-lua --code "..."\` executes Lua in the engine.
-- \`npx virtualmatter errors\` shows recent engine errors.
-- \`npx virtualmatter screenshot -o shot.png\` captures the current view.
-- \`npx virtualmatter open\` opens this world in the native desktop client.
-- Lua scripts under this tree hot-reload in the engine when saved.
-
-Do not edit \`.virtualmatter.json\` - it is sync bookkeeping.
-`;
 export async function fetchAgentsMd(fetchFn = fetch) {
     try {
         const res = await fetchFn(`${apiBase()}/AGENTS.md`);
@@ -35,7 +24,7 @@ export async function fetchAgentsMd(fetchFn = fetch) {
     catch {
         /* fall through to the stub */
     }
-    return AGENTS_MD_STUB;
+    return AGENTS_MD_FALLBACK;
 }
 const CLAUDE_MD = `@AGENTS.md
 
@@ -43,6 +32,21 @@ This folder mirrors a live Virtual Matter world. Keep \`npx virtualmatter sync\`
 running while you edit so saves hot-reload in the running world, or use the
 \`virtualmatter\` MCP server registered in \`.mcp.json\` to read, write, run Lua,
 check engine errors, and take screenshots directly.
+
+Build here, not on the website: do not open virtualmatter.ai or
+make.virtualmatter.ai in a browser or under computer use to reach the built-in
+agent, and do not type prompts into its chat. That relays your work through a
+second model doing your job - roughly twice the inference, and billed to Virtual
+Matter's platform credits instead of the subscription you already have. It stays
+the wrong path on an account with credits to spare or an admin account with no
+limit: the waste is the relay, not the bill. Playtesting is the exception and is
+encouraged: open the world and try what you built.
+
+This folder mirrors the world's editor, which is the only place to build. Any link
+to the world resolves to it: play servers show the last published version and are
+overwritten on every publish. Watch changes land live at the editor link ending in
+?chat=closed that pull and sync print, in any browser with no install; the native
+client (\`npx virtualmatter open\`) is optional.
 `;
 function mcpServerConfig() {
     return {
@@ -50,6 +54,35 @@ function mcpServerConfig() {
         args: ["-y", "virtualmatter", "mcp"],
     };
 }
+/**
+ * The folder's `.codex/config.toml` with our MCP server in it, or null to
+ * leave the file as it is. Codex has no `.mcp.json`: it reads MCP servers from
+ * `.codex/config.toml`, and loads a project's copy only once the maker trusts
+ * the folder. `agent-logs setup` writes `[features]` into the same file, so
+ * our table is appended rather than the file rewritten (a maker's comments
+ * survive). An existing `virtualmatter` entry is never replaced, and a file
+ * that does not parse - or would not parse with our table added, e.g. an
+ * inline `mcp_servers = { ... }` - is left alone.
+ */
+export function codexConfigWithServer(existing) {
+    const { command, args } = mcpServerConfig();
+    const table = "[mcp_servers.virtualmatter]\n" +
+        `command = ${JSON.stringify(command)}\n` +
+        `args = ${JSON.stringify(args)}\n`;
+    if (existing === null || existing.trim() === "")
+        return table;
+    try {
+        const servers = (parseToml(existing).mcp_servers ?? {});
+        if (servers.virtualmatter !== undefined)
+            return null;
+        const next = `${existing.replace(/\n*$/, "\n")}\n${table}`;
+        parseToml(next);
+        return next;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * The SDK's own AGENTS.md ships inside every Montage tree. It is written for
  * the in-session agent that drives the engine through `atomo`, which only
@@ -111,5 +144,16 @@ export function writeAgentFiles(dir, agentsMd) {
     const mcp = JSON.stringify({ mcpServers: { virtualmatter: mcpServerConfig() } }, null, 2) + "\n";
     put(".mcp.json", mcp, false);
     put(path.join(".cursor", "mcp.json"), mcp, false);
+    const codexRel = path.join(".codex", "config.toml");
+    const codexAbs = path.join(dir, codexRel);
+    const codex = codexConfigWithServer(fs.existsSync(codexAbs) ? fs.readFileSync(codexAbs, "utf8") : null);
+    if (codex === null) {
+        kept.push(codexRel);
+    }
+    else {
+        fs.mkdirSync(path.dirname(codexAbs), { recursive: true });
+        fs.writeFileSync(codexAbs, codex);
+        written.push(codexRel);
+    }
     return { written, kept };
 }

package/dist/agents-md.generated.js

@@ -0,0 +1,6 @@
+// Generated by frontend/scripts/sync-cli-agents-md.mjs - do not edit.
+// The same bytes https://make.virtualmatter.ai/AGENTS.md serves, built from
+// frontend/content/agent-briefing.md and AGENTS.source.md. The CLI writes
+// this into a world folder only when it cannot fetch the live copy. After
+// changing either source, run: node frontend/scripts/sync-cli-agents-md.mjs
+export const AGENTS_MD_FALLBACK = "# AGENTS.md - working with a Virtual Matter project\n\nThis file tells a coding agent how to think about a Virtual Matter project. The\n`virtualmatter` CLI drops a copy into every local project mirror it creates\n(`virtualmatter pull`); the canonical copy lives at\nhttps://make.virtualmatter.ai/AGENTS.md.\n\n## The rule that comes before everything else\n\n**Build through the CLI. Never through the website's agent.** If you were asked to\nbuild something in Virtual Matter, handed the domain virtualmatter.ai, or told to run\n`npx virtualmatter make`, the CLI is the path - always, from the first step. Do not\nopen virtualmatter.ai or make.virtualmatter.ai in a browser or under computer use in\norder to reach the built-in agent, and do not type prompts into the agent chat in the\n/edit view. Driving that agent puts two models in a relay where one would do: you spend\ntokens describing the work, it spends its own doing it, and what comes back is chat\nrather than files you can read. It is slower, it costs roughly twice the inference, it\nbills that inference to Virtual Matter's platform credits rather than the subscription\nyou already run on, an anonymous browser session cannot be steered after its first\nturn, and a rendered page gives you no engine errors. Everything that agent can do, you\ndo yourself with the commands below.\n\n**The rule holds whoever is signed in.** Being logged in, having credits to spare, or\nworking in an admin account with no limit at all is not an exemption, and neither is\nbeing told the credits do not matter. What is wasteful is the relay itself - two models\ndoing one model's job - not the bill.\n\n**Playtesting is the exception, and it is encouraged.** Once something is built, open\nthe world and try it: the editor link ending in `?chat=closed`, which `make`, `pull` and\n`sync` print, shows your latest changes live in any browser with no install, with\ncomputer use if that is how you drive a window. The native client\n(`npx virtualmatter open`) is optional, for more memory and frame rate. Looking at your\nwork, walking around in it, and playing it is the point. The rule is about who writes\nthe world, not about who is allowed to see it.\n\n**Every link resolves to the editor, and the editor is the only place you build.** Hand\nthe CLI or MCP server any link to a world - its editor, a play or share link, the\nproject page, an embed's iframe src, or the maker's own website - and it works on that\nworld's editor (its make framing). Play servers show the last published version and are\noverwritten on every publish, so work never goes there, and their /play and /g links\nshow that published copy rather than your latest edits.\n\n## The mental model\n\n- The world itself runs on Virtual Matter servers, not on the maker's machine. There is\n  one authoritative server simulation per world session, and any number of connected\n  clients (browser WASM or the native client).\n- The project's content is SDK Lua scripts plus assets (voxel data, prefabs, images,\n  sounds) under a `Montage/` tree. Virtual Matter can publish that tree to a GitHub repo\n  in the maker's account for versioning and remixing; pushing to that repo does not feed\n  back into the running world today - live edits happen in the session.\n- Changes hot-reload. Saving a `.lua` file in the live session's Montage tree re-runs\n  the module and its `Start()` on a fresh instance inside the running world - no restart,\n  no build step.\n- Prefabs are reusable scene-graph snippets: JSON files with a `.prefab` extension in the\n  Montage folder, instantiated at runtime via `Server:InsertPrefab(asset)`.\n- There is no local runtime - the world cannot run on the maker's machine. The\n  `virtualmatter` CLI (npm) is how you reach it from a local harness, and it needs no\n  setup: the first command that needs an account signs you in with a device code.\n  `npx virtualmatter make \"My world\"` makes a world and mirrors its Montage tree\n  into `./my-world`; `npx virtualmatter pull <any Virtual Matter link>` mirrors an\n  existing one (/edit, /play, /g, /p, /projects links all work, with or without a\n  readable slug); `npx virtualmatter list` shows your worlds; `npx virtualmatter sync`\n  live-pushes saves into the running session (which hot-reloads them);\n  `npx virtualmatter run-lua` / `errors` / `screenshot` drive the engine;\n  `npx virtualmatter open` optionally opens the world in the native desktop client,\n  downloaded and signed in on first use; and `npx virtualmatter mcp` serves\n  all of it over MCP. A mirrored folder carries `.mcp.json` and `.cursor/mcp.json`\n  (so Claude Code and Cursor register the MCP server on their own), this file, and a\n  `CLAUDE.md` that imports it. Folders from virtualmatter 0.5.0 on also carry\n  `.codex/config.toml`, which Codex loads once you trust the folder; with an older\n  CLI, or if Codex does not list the server, register it once with\n  `codex mcp add virtualmatter -- npx -y virtualmatter mcp`. In Claude Code outside a\n  mirrored folder, use `claude mcp add virtualmatter -- npx -y virtualmatter mcp`. The\n  server works before a world\n  is selected (`list_projects`, `create_project`, `select_project`), then exposes\n  `list_files`, `read_file`, `write_file`, `run_lua`, `get_engine_errors`,\n  `capture_screenshot`, `open_native_client`, and `world_info`.\n- Work through the CLI, not the website - see the rule above. Prompting the built-in\n  agent to do your building is the one thing to avoid; opening the world to play it is\n  not.\n- Seeing your work: `virtualmatter screenshot` shoots a default overview of the world\n  origin, `--target <object>` frames one object by name or id, and `--at x,y,z --rot\n  yaw,pitch,roll` places the camera exactly. Y is up and -Z is forward, and the\n  rotation really is yaw first: yaw 0 faces -Z, pitch -90 looks straight down, pitch 0\n  is the horizon. The MCP `capture_screenshot`\n  tool takes the same arguments. Verify a change with a screenshot plus `errors` rather\n  than assuming a write worked.\n- The mirrored folder's AGENTS.md is this guide followed by the engine SDK's own agent guide\n  (the AGENTS.md that lives in every Montage tree and inside the desktop client's\n  Data/Sdk/Montage/). The engine guide assumes an in-session agent driving the engine\n  through `atomo`; the merged file maps each `atomo` step to the CLI or MCP equivalent, and\n  the `Skills/*.md` references it points at are in the folder. The SDK's own tooling\n  (`atomo`, `vm_auth.py`, the agent-log hooks) is not mirrored: it only works inside a\n  session. Sandboxed agents need network access for every CLI command.\n\n## Reference\n\nThe same facts as terse lists, for quick lookup.\n\n### Project model\n- A project (\"montage\") is one voxel world hosted with Virtual Matter.\n- A project has framings: \"make\" framings (editing sessions) and \"play\"\n  framings (public play sessions). A framing is a running session slot\n  on a voxel host.\n- Project content = SDK Lua scripts + assets under a Montage/ tree.\n  Edits made in the live session hot-reload into the running world.\n  The tree can be published to a maker-owned GitHub repo.\n\n### URL shapes (make.virtualmatter.ai)\n- /new                 builder for people: create a world from a prompt\n                       (also at https://virtualmatter.ai/); coding agents\n                       use npx virtualmatter make instead\n- /edit/<framing-id>   maker session: live world + agent chat. The chat is\n                       for people; a coding agent builds with the CLI and\n                       never prompts it\n                       (also /edit/<slug>-<framing-id>; the CLI accepts both)\n- /play/<framing-id>   play session for a specific framing\n- /g/<id>              share URL resolver: 302s to a live session\n\n### APIs (unauthenticated)\n- GET https://make.virtualmatter.ai/api/v1/public/native-clients\n  JSON: { iteration, clients: [{ platform, kind, url, filename,\n  file_size, branch, commit, match }] } - per-platform native client\n  installers (kind \"download\") or store links (kind \"store\", iOS).\n\n### CLI + MCP (npm package \"virtualmatter\", Node >= 20)\n- npx virtualmatter make \"<name>\"     make a world, mirror it into ./<slug>\n- npx virtualmatter pull <link>       mirror an existing world (any link shape)\n- npx virtualmatter list              your worlds with framing ids + URLs\n- npx virtualmatter sync              live-push saves into the running world\n- npx virtualmatter open              optional: open it in the native client\n- npx virtualmatter mcp               stdio MCP server (list_projects,\n  create_project, select_project, list_files, read_file, write_file,\n  run_lua, get_engine_errors, capture_screenshot, open_native_client,\n  world_info)\n- Sign-in happens on first use (device code); no separate login step.\n- These commands are the whole build path. Never prompt the built-in\n  agent on the site to do the work; a browser or the native client is\n  for playtesting what you built.\n- Any link to a world (editor, play or share link, project page, embed,\n  or the maker's own website) resolves to its editor, the only place\n  the CLI and MCP server work. Play servers show the last published\n  version and are overwritten on publish.\n- Watch changes land live at the editor link ending in ?chat=closed,\n  in any browser, no install. The native client is optional.\n- A mirrored folder carries .mcp.json, .cursor/mcp.json, AGENTS.md and\n  CLAUDE.md, so Claude Code and Cursor register the server on their own.\n- Codex: folders from 0.5.0 on carry .codex/config.toml, loaded once the\n  folder is trusted; otherwise register the server once:\n  codex mcp add virtualmatter -- npx -y virtualmatter mcp\n\n## SDK Lua cheat sheet\n\nThe scripting language is Lua 5.4, sandboxed: `os`, `io`, `require`, `package`,\n`dofile`, `loadfile`, `loadstring` are nil. `math`, `string`, `table`, `coroutine`\nremain. No `os.time` - use `Time.time` (sim time), `Time.frame`, or\n`AE:GetDebugTime()` (wall clock).\n\n### Script shape\n\nEvery persistent behavior is a `.lua` file in the Montage tree returning a `self` table:\n\n```lua\nlocal self = {}\nfunction self:Start() end\nfunction self:Update(deltaTime) end\nreturn self\n```\n\nAttach to an object with `obj:AddScript(\"My Folder/Example.lua\", sync)` - the path is\nrelative to the Montage root; `sync = true` replicates the script to clients.\n`obj:FindScript(\"Example\")` returns the live instance.\n\n### Server / client split\n\nThe same script runs on the server and (when synced) on every client. Branch with\n`self.onServer` / `self.onClient`:\n\n```lua\nfunction self:Update(dt)\n    if self.onClient then return end  -- voxel edits are server-only\n    -- authoritative logic here\nend\n```\n\nNothing replicates automatically: set `syncToClients = true` on the script or\nVoxelData component, and use `util:makeNetworkedTable(self, { hp = 100 })` for\nproperties that should sync (server writes, clients read, deltas only).\n`obj.pos` / `obj.rot` do not auto-sync - replicate them yourself.\n\n### RPC\n\n```lua\nself:RPC(\"serverDoSomething\", pos, dir)   -- on a client: goes to the server\nfunction self:serverDoSomething(pos, dir, clientID)  -- clientID auto-appended\n    assert(self.onServer)\nend\n```\n\nOn the server, `self:RPC(...)` fans out to all clients. Reliable, FIFO per direction.\nRequires `self.component.syncToClients = true`.\n\n### Scene and objects (server)\n\n```lua\nlocal ob = Scene:CreateObject(\"Name\")\nob.save = true\nob:AddScript(\"Path/Script.lua\")\nScene:GetObjectByName(\"Name\")\nScene:CloneObject(ob)                 -- prefer over rebuilding\nob.active = false                     -- prefer over destroy\nob:AddTag(\"Enemy\"); FindObjectsWithTag(\"Enemy\")  -- tags are runtime-only state\n```\n\n### Voxel editing (server only, async)\n\n```lua\nVox:Add(Sphere(pos, 2)):Color(1, 0, 0):Run()\nVox:Add(Box(Vec3(0, -1, 0), Vec3(20, 2, 20))):ForceStatic():Run()\n```\n\nShapes: `Box(center, fullSize)`, `Sphere(center, r)`, `Capsule(p1, p2, r)`,\n`Cylinder(p1, p2, r1[, r2])`. `Run()` is async - chain `:OnFinished(fn)` before\n`:Run()` to read post-commit state. Big edits stall the frame for every client;\nkeep in-game edits small and infrequent.\n\n### Input (event-driven, client input reaches the server)\n\n```lua\nself.component.syncToClients = true\nevents.keyDown.addListener(self, function(key, from) self.keys[key] = true end)\nevents.keyUp.addListener(self, function(key, from) self.keys[key] = false end)\n```\n\nPlayer-driven movement must be client-predicted - never gate the player's own\nfeedback on the server round-trip.\n\n### Physics\n\n```lua\nlocal rb = obj:AddComponent(\"RigidBody\")\nrb:AddImpulse(Vec3(0, 50, 0), obj.pos)\nrb.velocity; rb.mass; rb.gravityScale\n```\n\n### Time and diagnostics\n\n```lua\nTime.dt; Time.time; Time.frame; Time.timeScale\nAE:GetLogValue(\"Raycasts\")        -- engine counters, e.g. raycasts this frame\nAE:GetAssets()                    -- list all assets (APIs take Assets, not paths)\n```\n\n### UI (client-side HUD)\n\nBuild screen UI with the MUI builder: `UI:AddPanel|AddButton|AddLabel|AddSlider|...`\nchained with `:Set{...}`; flexbox-like row-wrap layout.\n\n## Conventions\n\n- Coordinates: Y is up, -Z is forward, X is right.\n- Script files are named in capital case with spaces (`Character Controller.lua`).\n- Check whether a script is already attached before adding it - duplicates run twice.\n- The server is for authority (world edits, spawns, state); clients are for feel\n  (prediction, FX, UI).\n\n## Embed or build a world for an existing website\n\nFor a shared project link, fetch `/api/v1/public/embed?target=<encoded-link>`\nand follow `/embed-guide.md`. Use the returned canonical player URL, not the\nmaker's external website URL. Keep the existing website and its design.\n\nFor account discovery or prompt-based creation, connect the hosted MCP at\n`https://make.virtualmatter.ai/api/v1/mcp` using OAuth. Users can sign up in\nthe connection flow. Tools: `list_projects`, `get_embed`, `create_project`\n(with a prompt and stable request_id), `get_build_status`. VM's agent builds\nusing VM credits. Review and share the private world before embedding.\nThe local CLI exposes `embed`, `build --prompt --request-id`, and `build-status`.\n\n## Local conversation history\n\nAfter pulling a project, run `virtualmatter agent-logs setup` once to enable\nfuture chat history capture for local harnesses. It adds Codex, Claude Code,\nCursor, and (when installed) Hermes hooks without replacing existing hooks.\nKeep `virtualmatter sync` or `virtualmatter agent-logs watch` running for retry\nand delayed transcript capture. Follow each harness's normal hook review and\nrestart flow. Use `agent-logs status` to inspect pending uploads and\n`agent-logs disable` to stop capture.\n\nOther harnesses can send portable public event JSONL with\n`virtualmatter agent-logs upload <file> --harness <name> --session <id>`, or use\nMCP `upload_agent_logs`. Supply stable event IDs for retries; omit private\nreasoning, system/developer prompts, credentials, and binary media.\n";

package/dist/api.js

@@ -24,7 +24,7 @@ export async function resolveSession(framingId, opts = {}) {
     const now = opts.now ?? Date.now;
     const deadline = now() + (opts.timeoutMs ?? 120_000);
     for (;;) {
-        const res = await authorizedFetch(`${apiBase()}/api/v1/framings/${encodeURIComponent(framingId)}/session`, { method: "POST" }, fetchFn);
+        const res = await authorizedFetch(`${apiBase()}/api/v1/framings/${encodeURIComponent(framingId)}/session${opts.intent ? `?intent=${opts.intent}` : ""}`, { method: "POST" }, fetchFn);
         if (res.status === 200) {
             return (await res.json());
         }
@@ -37,6 +37,13 @@ export async function resolveSession(framingId, opts = {}) {
             await sleep(wait);
             continue;
         }
+        if (res.status === 409) {
+            const body = (await res.json().catch(() => ({})));
+            if (body.code === "not_edit_framing" && body.make_framing_id) {
+                throw new NotEditFramingError(framingId, body.make_framing_id, body.edit_url ?? "", body.detail ?? "");
+            }
+            throw new Error(`Session lookup failed: HTTP 409`);
+        }
         if (res.status === 401 || res.status === 403) {
             throw new Error(`Not authorized for framing ${framingId} (HTTP ${res.status}).`);
         }
@@ -46,6 +53,41 @@ export async function resolveSession(framingId, opts = {}) {
         throw new Error(`Session lookup failed: HTTP ${res.status}`);
     }
 }
+/**
+ * The platform's answer to `intent=edit` on a play framing: that id is a play
+ * server, and the world's editor is `makeFramingId`.
+ */
+export class NotEditFramingError extends Error {
+    framingId;
+    makeFramingId;
+    editUrl;
+    constructor(framingId, makeFramingId, editUrl, detail) {
+        super(detail || `${framingId} is a play server, not the world's editor.`);
+        this.framingId = framingId;
+        this.makeFramingId = makeFramingId;
+        this.editUrl = editUrl;
+        this.name = "NotEditFramingError";
+    }
+}
+/**
+ * The session to WORK on a world through - always its editor. When the id is
+ * a play server the platform names the editor instead, and this follows that
+ * pointer, telling `onRedirect` so the caller can say what happened.
+ */
+export async function resolveEditSession(framingId, onRedirect, opts = {}) {
+    try {
+        return { session: await resolveSession(framingId, { ...opts, intent: "edit" }), framingId };
+    }
+    catch (err) {
+        if (!(err instanceof NotEditFramingError))
+            throw err;
+        onRedirect?.(err);
+        return {
+            session: await resolveSession(err.makeFramingId, { ...opts, intent: "edit" }),
+            framingId: err.makeFramingId,
+        };
+    }
+}
 /** Session base URL where the file/engine API lives. */
 export function sessionBaseUrl(session) {
     const host = session.voxel_host.replace(/^https?:\/\//, "").replace(/\/+$/, "");
@@ -95,6 +137,47 @@ export async function getProjectByPublicId(publicId, fetchFn = fetch) {
     const identity = (await res.json());
     return getProject(identity.id, fetchFn);
 }
+/** No world of the caller's matches. Carries the platform's own wording. */
+export class NoMatchingWorldError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NoMatchingWorldError";
+    }
+}
+/** The platform predates `/edit-target` (an older dev or staging build). */
+export class EditTargetUnsupportedError extends Error {
+    constructor(status) {
+        super(`This platform has no /api/v1/edit-target route (HTTP ${status}).`);
+        this.name = "EditTargetUnsupportedError";
+    }
+}
+export async function fetchEditTarget(target, fetchFn = fetch) {
+    const res = await authorizedFetch(`${apiBase()}/api/v1/edit-target`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ target }) }, fetchFn);
+    if (res.ok)
+        return (await res.json());
+    let detail = null;
+    try {
+        detail = (await res.json()).detail;
+    }
+    catch {
+        /* non-JSON */
+    }
+    const coded = detail && typeof detail === "object" ? detail : null;
+    if (res.status === 404 && coded?.code === "no_matching_world") {
+        throw new NoMatchingWorldError(coded.message ?? "No world of yours matches that link.");
+    }
+    if (res.status === 409 && coded?.code === "ambiguous_world") {
+        const names = (coded.names ?? []).join(", ");
+        throw new Error(`${coded.message ?? "That website belongs to more than one of your worlds."}${names ? ` (${names})` : ""}`);
+    }
+    // A 404/405 WITHOUT our code is the router saying the route does not exist.
+    if (res.status === 404 || res.status === 405)
+        throw new EditTargetUnsupportedError(res.status);
+    if (res.status === 401 || res.status === 403) {
+        throw new Error(`Not authorized to resolve that link (HTTP ${res.status}).`);
+    }
+    throw new Error(`Resolving the link failed: HTTP ${res.status}`);
+}
 export async function createProject(input, fetchFn = fetch) {
     const res = await authorizedFetch(`${apiBase()}/api/v1/montages`, {
         method: "POST",

package/dist/index.js

@@ -4,7 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { registerLogCommands } from "./log-commands.js";
 import { Command } from "commander";
-import { createProject, createWebsiteBuild, getWebsiteBuild, getEmbed, defaultRegion, editUrl, fetchNativeClientCatalog, listProjects, playUrl, resolveSession, sessionBaseUrl, whoami, } from "./api.js";
+import { createProject, createWebsiteBuild, getWebsiteBuild, getEmbed, defaultRegion, editUrl, fetchNativeClientCatalog, listProjects, playUrl, NotEditFramingError, resolveEditSession, resolveSession, sessionBaseUrl, whoami, } from "./api.js";
 import { NotLoggedInError, clearCredentials, loadCredentials, pollForToken, saveCredentials, startDeviceFlow, } from "./auth.js";
 import { openInBrowser } from "./browser.js";
 import { detectPlatform, ensureClientInstalled, launchClient, seedNativeAuth } from "./client.js";
@@ -19,7 +19,29 @@ const program = new Command();
 program
     .name("virtualmatter")
     .description("Build with Virtual Matter from your terminal or coding agent: list and create worlds, mirror their files, live-sync edits, run Lua, capture screenshots, open the native client, and expose it all over MCP.")
-    .version(packageVersion());
+    .version(packageVersion())
+    // `npx virtualmatter --help` is the first command an external agent runs, so
+    // it is the earliest place to head off driving the website instead.
+    .addHelpText("after", [
+    "",
+    "If you are a coding agent: these commands are the whole build path. Never",
+    "reach the built-in agent by opening virtualmatter.ai or make.virtualmatter.ai",
+    "in a browser or under computer use, and do not type prompts into its chat",
+    "in the /edit view. That relays your work through a second model doing your",
+    "job - roughly twice the inference, slower, and billed to Virtual Matter's",
+    "platform credits instead of the subscription you already run on. It stays the",
+    "wrong path on an account with credits to spare or an admin account with no",
+    "limit: the waste is the relay, not the bill. Playtesting is the exception and",
+    "is encouraged: once you have built something, open the world and try it.",
+    "",
+    "Any link to a world - editor, play or share link, project page, an embed, or",
+    "the maker's own website - resolves to the world's EDITOR, and that is the only",
+    "place these commands work: play servers show the last published version and",
+    "are overwritten on every publish. To watch changes land live, open the edit",
+    "link these commands print (ending in ?chat=closed) in any browser, with no",
+    "install. The native client (`virtualmatter open`) is optional, for more memory",
+    "and frame rate.",
+].join("\n"));
 function fail(message) {
     console.error(message);
     process.exit(1);
@@ -63,8 +85,11 @@ async function run(fn) {
 /** Resolve a session-scoped FilesClient from a synced dir's state file. */
 async function clientForDir(dir) {
     const state = requireState(dir);
-    const session = await resolveSession(state.framing_id);
-    return { client: new FilesClient(sessionBaseUrl(session), state.framing_id), framingId: state.framing_id };
+    // Engine-driving commands read no local files, so a folder that points at a
+    // play server can safely run against the editor instead - with a warning,
+    // because the folder itself still needs re-mirroring before `sync`.
+    const { session, framingId } = await resolveEditSession(state.framing_id, (err) => console.error(`Note: ${err.message} Running against the editor instead. To fix this folder, mirror the editor: npx virtualmatter pull ${err.editUrl} <new-folder>`));
+    return { client: new FilesClient(sessionBaseUrl(session), framingId), framingId };
 }
 /** A target from the argument, else from the folder, else the only project. */
 async function resolveTargetOrImplicit(target, dir) {
@@ -88,7 +113,7 @@ function slugFor(name) {
         .replace(/^-+|-+$/g, "");
     return slug || "world";
 }
-function reportPull(result, dest) {
+function reportPull(result, dest, watchUrl) {
     console.log(`Pulled ${result.fileCount} files into ${dest}.`);
     const files = result.agentFiles;
     if (files && files.written.length > 0) {
@@ -100,6 +125,8 @@ function reportPull(result, dest) {
     const shown = rel.startsWith("..") ? dest : rel;
     console.log(`Next: cd ${JSON.stringify(shown).slice(1, -1).includes(" ") ? `"${shown}"` : shown} && npx virtualmatter sync`);
     console.log(`      (or open the folder in your agent - the MCP server is registered in .mcp.json)`);
+    console.log(`Watch changes land live in any browser, no install: ${watchUrl}`);
+    console.log(`      (the native client is optional: npx virtualmatter open)`);
 }
 program
     .command("login")
@@ -157,7 +184,7 @@ program
         return;
     }
     if (projects.length === 0) {
-        console.log('No worlds yet. Create one: npx virtualmatter create "My world"');
+        console.log('No worlds yet. Make one: npx virtualmatter make "My world"');
         return;
     }
     console.log(formatProjectList(projects));
@@ -165,11 +192,12 @@ program
     console.log("Pull one: npx virtualmatter pull <framing id or URL>");
 }));
 program
-    .command("create")
-    // `make` matches the product's own verb: the site's button says Make, and
-    // the builder lives at make.virtualmatter.ai.
-    .alias("make")
-    .description("Create a new world and mirror its files into a local folder (alias: make)")
+    .command("make")
+    // `make` is the product's own verb: the builder lives at
+    // make.virtualmatter.ai and its main button says Make. `create` stays as an
+    // alias so instructions written before 0.4.1 keep working.
+    .alias("create")
+    .description("Make a new world and mirror its files into a local folder (alias: create)")
     .argument("<name>", "the world's name")
     .argument("[dir]", "destination folder (default: ./<name-as-slug>)")
     .option("--region <region>", "NA, EU, or AS (default: nearest)")
@@ -203,9 +231,17 @@ program
     }
     else {
         console.log(`Created "${project.name}" in ${project.region}.`);
-        console.log(`Edit in the browser: ${url}`);
+        // Deliberately "watch", and deliberately the ?chat=closed link: an
+        // agent reading "edit it in the browser" as its next step opens the
+        // page and prompts the built-in agent, which is the failure the CLI
+        // exists to avoid. The maker still needs a link - it is how they see
+        // the agent's work land live - and with the chat closed it offers
+        // nothing to prompt.
+        const watch = `${url}?chat=closed`;
         if (pulled && dest)
-            reportPull(pulled, dest);
+            reportPull(pulled, dest, watch);
+        else
+            console.log(`Watch it live in any browser, no install: ${watch}`);
     }
     if (opts.open)
         await openNative(framingId, url);
@@ -213,13 +249,15 @@ program
 program
     .command("pull")
     .description("Download a world's file tree into a local folder")
-    .argument("[target]", "any Virtual Matter link (/edit, /play, /g, /p, /projects) or a framing id; omitted = your only world")
+    .argument("[target]", "any link to the world (editor, play or share link, project page, embed) or your website; omitted = your only world")
     .argument("[dir]", "destination folder (default: ./<world name or framing id>)")
     .action((target, dir) => run(async () => {
     const resolved = await resolveTargetOrImplicit(target, path.resolve("."));
+    if (resolved.note)
+        console.log(resolved.note);
     const dest = path.resolve(dir ?? (resolved.project ? slugFor(resolved.project.name) : resolved.framingId));
     const result = await pullCommand(resolved.framingId, dest);
-    reportPull(result, dest);
+    reportPull(result, dest, resolved.watchUrl ?? `${editUrl(result.framingId, resolved.project?.url_slug)}?chat=closed`);
 }));
 program
     .command("sync")
@@ -228,10 +266,32 @@ program
     .action((dir) => run(async () => {
     const abs = path.resolve(dir);
     const state = requireState(abs);
-    const session = await resolveSession(state.framing_id);
+    let session;
+    try {
+        session = await resolveSession(state.framing_id, { intent: "edit" });
+    }
+    catch (err) {
+        // A folder mirrored from a play server (older CLIs took /play links at
+        // face value). Syncing into that server is lost on the next publish,
+        // and its files are the PUBLISHED copy - possibly older than the
+        // editor - so syncing them into the editor could overwrite newer work.
+        // Neither is safe to guess at: stop and say how to get a right folder.
+        if (err instanceof NotEditFramingError) {
+            fail([
+                "This folder was mirrored from a play server, not the world's editor.",
+                "Play servers are overwritten on every publish, so work synced there is lost,",
+                "and these files may be older than the editor's. Mirror the editor into a new",
+                "folder, then carry over any local changes you made here:",
+                "",
+                `  npx virtualmatter pull ${err.editUrl} <new-folder>`,
+            ].join("\n"));
+        }
+        throw err;
+    }
     const client = new FilesClient(sessionBaseUrl(session), state.framing_id);
     const engine = new SyncEngine(client, abs, state);
     console.log(`Syncing ${abs} with framing ${state.framing_id}. Ctrl-C to stop.`);
+    console.log(`Watch changes land live in any browser: ${editUrl(state.framing_id)}?chat=closed`);
     await runSyncLoop(engine, abs);
 }));
 program
@@ -299,7 +359,7 @@ async function openNative(framingId, url, force = false) {
 program
     .command("open")
     .alias("client")
-    .description("Open a world in the native desktop client - downloads and signs it in on first use")
+    .description("Optional: open a world in the native desktop client (more memory and frame rate than the browser) - downloads and signs it in on first use")
     .argument("[target]", "any Virtual Matter link or framing id; omitted = this folder's world, or your only one")
     .option("--install-only", "download and unpack the client without launching it")
     .option("--print", "only print the download URL for this OS")
@@ -325,6 +385,8 @@ program
         return;
     }
     const resolved = await resolveTargetOrImplicit(target, path.resolve("."));
+    if (resolved.note)
+        console.log(resolved.note);
     await openNative(resolved.framingId, editUrl(resolved.framingId, resolved.project?.url_slug), opts.force);
 }));
 program

package/dist/mcp.js

@@ -14,7 +14,7 @@ import { eventSchema } from "./log-events.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { createProject, createWebsiteBuild, getWebsiteBuild, getEmbed, defaultRegion, editUrl, listProjects, playUrl, resolveSession, sessionBaseUrl, } from "./api.js";
+import { createProject, createWebsiteBuild, getWebsiteBuild, getEmbed, defaultRegion, editUrl, listProjects, playUrl, resolveEditSession, resolveSession, sessionBaseUrl, } from "./api.js";
 import { ensureClientInstalled, launchClient, seedNativeAuth } from "./client.js";
 import { packageVersion } from "./config.js";
 import { ConflictError, FilesClient } from "./files.js";
@@ -27,6 +27,33 @@ export function resolveFramingId(dir, framingFlag) {
     const state = loadState(dir);
     return state ? state.framing_id : null;
 }
+export const MCP_INSTRUCTIONS = [
+    "Virtual Matter hosts live multiplayer voxel worlds. These tools are the whole build",
+    "surface: make a world, read and write its SDK Lua, hot-reload it into the running",
+    "session, run Lua, read engine errors, take screenshots, open the native client.",
+    "",
+    "Build with these tools, always. Do not open virtualmatter.ai or make.virtualmatter.ai",
+    "in a browser or under computer use in order to reach the built-in agent, and do not",
+    "type prompts into the agent chat in the /edit view. Driving that agent relays your",
+    "work through a second model doing your job: roughly twice the inference for a slower",
+    "result that comes back as chat rather than files, billed to Virtual Matter's platform",
+    "credits rather than the subscription you already run on, unsteerable past its first",
+    "turn in an anonymous session, and with no engine errors behind a rendered page.",
+    "",
+    "This holds whoever is signed in. An account with credits to spare, or an admin account",
+    "with no limit at all, is not an exemption: the waste is the relay itself, two models",
+    "doing one model's job, not the bill.",
+    "",
+    "Playtesting is the exception and is encouraged: once something is built, open the",
+    "world and try it. The rule is about who writes the world, not who is allowed to look.",
+    "",
+    "Any link to a world - editor, play or share link, project page, an embed, or the",
+    "maker's own website - resolves to the world's EDITOR, and that is the only place these",
+    "tools work: play servers show the last published version and are overwritten on every",
+    "publish. The maker watches your changes land live at the watch_url that select_project",
+    "and world_info return (the editor with ?chat=closed), in any browser with no install.",
+    "open_native_client is optional, for more memory and frame rate, never required.",
+].join("\n");
 const NO_WORLD = "No world is selected. Call select_project with a Virtual Matter URL or id, create_project to make a new one, or list_projects to see what exists.";
 function makeContext(framingId) {
     let session = null;
@@ -48,8 +75,19 @@ function makeContext(framingId) {
             return ctx.framingId;
         },
         async getSession() {
-            if (!session)
-                session = await resolveSession(ctx.requireFraming());
+            if (!session) {
+                // Always the editor. A play framing - selected by id, or read from a
+                // folder an older CLI mirrored from a /play link - is refused by the
+                // platform with the editor's id, and work moves there.
+                const resolved = await resolveEditSession(ctx.requireFraming(), (err) => {
+                    ctx.notice = `${err.message} Switched to the world's editor (${err.makeFramingId}).`;
+                });
+                if (resolved.framingId !== ctx.framingId) {
+                    ctx.framingId = resolved.framingId;
+                    client = null;
+                }
+                session = resolved.session;
+            }
             return session;
         },
         async getClient() {
@@ -98,7 +136,14 @@ export async function writeWithRetry(client, filePath, body) {
 }
 export async function runMcpServer(dir, framingFlag) {
     const ctx = makeContext(resolveFramingId(dir, framingFlag));
-    const server = new McpServer({ name: "virtualmatter", version: packageVersion() });
+    // Instructions land in the host agent's system prompt, which is the only
+    // place early enough to stop the failure this exists for: an agent asked to
+    // "build X in Virtual Matter" opens the website and prompts OUR built-in
+    // agent instead, relaying through a second model, on our platform credits
+    // rather than the subscription it already runs on. Observed twice on clean
+    // machines even with the rule in llms.txt and AGENTS.md, because a
+    // browser-driving agent never fetches either.
+    const server = new McpServer({ name: "virtualmatter", version: packageVersion() }, { instructions: MCP_INSTRUCTIONS });
     server.registerTool("upload_agent_logs", {
         description: "Append public conversation and tool events from any local harness to the selected project's Agent Logs. Supply stable event IDs for retry deduplication. Never include private reasoning, system prompts, credentials, or binary media. Use the CLI hook integrations for automatic full conversation capture.",
         inputSchema: { harness: z.string().regex(/^[a-z0-9][a-z0-9_-]{0,63}$/), session_id: z.string().regex(/^[A-Za-z0-9_-]{1,128}$/), events: z.array(eventSchema).min(1).max(500) },
@@ -155,9 +200,9 @@ export async function runMcpServer(dir, framingFlag) {
         return textResult(JSON.stringify({ ...projectSummary(project), selected: true, pulled }, null, 2));
     });
     server.registerTool("select_project", {
-        description: "Select the world this session works on. Accepts any Virtual Matter link (/edit, /play, /g, /p, /projects, with or without a readable slug) or a bare framing id. Optionally mirrors its files into a local folder.",
+        description: "Select the world this session works on. Accepts ANY link to it - the editor, a play or share link, the project page, an embed's iframe src, or the maker's own website - or a bare framing id, and always resolves to the world's editor: a play server shows the last published version and is overwritten on publish, so work never goes there. Returns watch_url, where the maker watches changes land live. Optionally mirrors its files into a local folder.",
         inputSchema: {
-            target: z.string().describe("A Virtual Matter URL or framing id"),
+            target: z.string().describe("Any link to the world, the maker's website, or a framing id"),
             pull_to: z.string().optional().describe("Local folder to mirror the world's files into (optional)"),
         },
     }, async ({ target, pull_to }) => {
@@ -171,6 +216,8 @@ export async function runMcpServer(dir, framingFlag) {
         return textResult(JSON.stringify({
             framing_id: resolved.framingId,
             edit_url: editUrl(resolved.framingId, resolved.project?.url_slug),
+            watch_url: resolved.watchUrl ?? `${editUrl(resolved.framingId, resolved.project?.url_slug)}?chat=closed`,
+            note: resolved.note ?? null,
             project: resolved.project ? projectSummary(resolved.project) : null,
             pulled,
         }, null, 2));
@@ -254,7 +301,7 @@ export async function runMcpServer(dir, framingFlag) {
         };
     });
     server.registerTool("open_native_client", {
-        description: "Open the selected world on this machine in the Virtual Matter native desktop client (higher performance than the browser). Downloads and unpacks the client on first use, signs it in with the CLI's account, and launches it into the world. Returns where the client lives and the URL it opened.",
+        description: "Optional: open the selected world on this machine in the Virtual Matter native desktop client, for more memory and frame rate than the browser. Never required - the world, including your latest edits, is always viewable live at its watch_url in any browser. Downloads and unpacks the client on first use, signs it in with the CLI's account, and launches it into the world. Returns where the client lives and the URL it opened.",
         inputSchema: {},
     }, async () => {
         const framingId = ctx.requireFraming();
@@ -268,12 +315,15 @@ export async function runMcpServer(dir, framingFlag) {
         description: "Return the selected world's framing id plus its URLs: the editor and play links a human can open, and the session API base this server talks to.",
         inputSchema: {},
     }, async () => {
-        const framingId = ctx.requireFraming();
+        // Session first: it may move the selection from a play server to the editor.
         const session = await ctx.getSession();
+        const framingId = ctx.requireFraming();
         return textResult(JSON.stringify({
             framing_id: framingId,
             project: ctx.project ? projectSummary(ctx.project) : null,
             edit_url: editUrl(framingId, ctx.project?.url_slug),
+            watch_url: `${editUrl(framingId, ctx.project?.url_slug)}?chat=closed`,
+            notice: ctx.notice ?? null,
             play_url: playUrl(framingId),
             session_api_base: sessionBaseUrl(session),
             voxel_host: session.voxel_host,

package/dist/pull.js

@@ -1,12 +1,13 @@
 /** `virtualmatter pull`: download a framing's file tree and seed the state file. */
 import fs from "node:fs";
 import path from "node:path";
-import { resolveSession, sessionBaseUrl } from "./api.js";
+import { resolveEditSession, sessionBaseUrl } from "./api.js";
 import { composeAgentsMd, fetchAgentsMd, writeAgentFiles } from "./agentfiles.js";
 import { FilesClient } from "./files.js";
 import { isIgnoredPath } from "./ignore.js";
 import { saveState } from "./state.js";
-export { AGENTS_MD_STUB, fetchAgentsMd } from "./agentfiles.js";
+export { fetchAgentsMd } from "./agentfiles.js";
+export { AGENTS_MD_FALLBACK } from "./agents-md.generated.js";
 /** Download workers per pull. The tree is ~1000 small files; sequential
  *  GETs left the command silent for minutes. Eight in flight keeps a
  *  single origin comfortable while cutting wall clock roughly 6-8x. */
@@ -73,10 +74,12 @@ export async function pullTree(client, dir, framingId) {
 }
 export async function pullCommand(framingId, dir) {
     console.log(`Resolving session for framing ${framingId} (this can cold-start one) ...`);
-    const session = await resolveSession(framingId);
-    const client = new FilesClient(sessionBaseUrl(session), framingId);
+    // Always the editor: a play framing here would mirror the published copy and
+    // seed a state file that later syncs into a server wiped on every publish.
+    const { session, framingId: editFramingId } = await resolveEditSession(framingId, (err) => console.log(`${err.message} Mirroring the editor (${err.makeFramingId}) instead.`));
+    const client = new FilesClient(sessionBaseUrl(session), editFramingId);
     console.log(`Session ready at ${sessionBaseUrl(session)}. Downloading files ...`);
-    const result = await pullTree(client, dir, framingId);
+    const result = await pullTree(client, dir, editFramingId);
     const [platformDoc, engineDoc] = await Promise.all([fetchAgentsMd(), fetchEngineAgentsMd(client)]);
     result.agentFiles = writeAgentFiles(dir, composeAgentsMd(platformDoc, engineDoc));
     return result;

package/dist/resolve.js

@@ -1,8 +1,19 @@
 /**
  * Turn whatever the user handed us (a URL of any shape, a bare id, or
- * nothing) into the one framing id every other command needs.
+ * nothing) into the one framing id every other command needs - and that id is
+ * ALWAYS the world's editor (its make framing).
+ *
+ * Makers paste whatever link is in front of them: a play server's /play link,
+ * a share link, the project page, an embed's iframe src, or the website their
+ * world is embedded in. A play framing shows the last published version and
+ * is overwritten on every publish, so work synced into one reaches players,
+ * never the editor, and vanishes on the next publish - silently. So every
+ * target goes to the platform's `POST /api/v1/edit-target`, which knows what
+ * each id is and which world a website belongs to, and answers with the
+ * editor. The local parser below is only the fallback for a platform old
+ * enough not to have that route.
  */
-import { getProject, getProjectByPublicId, listProjects } from "./api.js";
+import { EditTargetUnsupportedError, NoMatchingWorldError, fetchEditTarget, getProject, getProjectByPublicId, listProjects, } from "./api.js";
 import { loadState } from "./state.js";
 import { parseTarget } from "./urls.js";
 /** The make framing of a project row, or a clear error when it has none. */
@@ -22,9 +33,95 @@ export async function resolveParsedTarget(parsed, fetchFn = fetch) {
         : await getProject(parsed.montageId, fetchFn);
     return { framingId: makeFramingOf(project), project };
 }
-/** Resolve a pasted target string. */
+function fromEditTarget(t) {
+    return {
+        framingId: t.make_framing_id,
+        project: {
+            id: t.montage_id,
+            public_id: t.public_id,
+            url_slug: t.url_slug,
+            name: t.name,
+            region: t.region,
+            make_framing_id: t.make_framing_id,
+        },
+        note: t.note ?? undefined,
+        watchUrl: t.watch_url,
+    };
+}
+/** Resolve a pasted target string to the world's editor. */
 export async function resolveTarget(target, fetchFn = fetch) {
-    return resolveParsedTarget(parseTarget(target), fetchFn);
+    try {
+        return fromEditTarget(await fetchEditTarget(target, fetchFn));
+    }
+    catch (err) {
+        if (err instanceof EditTargetUnsupportedError)
+            return resolveParsedTarget(parseTarget(target), fetchFn);
+        if (err instanceof NoMatchingWorldError && isForeignWebsite(target)) {
+            const embedded = await resolveFromEmbeddingPage(target, fetchFn);
+            if (embedded)
+                return embedded;
+        }
+        throw err;
+    }
+}
+function isVirtualmatterHostname(host) {
+    const h = host.toLowerCase();
+    return (h === "virtualmatter.ai" ||
+        h.endsWith(".virtualmatter.ai") ||
+        h === "virtualmatter.dev" ||
+        h.endsWith(".virtualmatter.dev") ||
+        h === "localhost" ||
+        h === "127.0.0.1");
+}
+/** A web address that is not one of ours - candidate for "the maker's site embeds the world". */
+export function isForeignWebsite(target) {
+    let url;
+    try {
+        url = new URL(target.includes("://") ? target : `https://${target}`);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return false;
+    return url.hostname.includes(".") && !isVirtualmatterHostname(url.hostname);
+}
+const WORLD_LINK_RE = /https?:\/\/(?:[a-z0-9-]+\.)*virtualmatter\.(?:ai|dev)\/[^\s"'<>\\)]+/gi;
+const PAGE_BYTES_LIMIT = 2_000_000;
+const PAGE_TIMEOUT_MS = 10_000;
+/**
+ * A website the platform does not know belongs to a world (the maker never set
+ * it on the project). If its HTML carries a link to a world - the embed's
+ * iframe src, usually - resolve that. This runs on the maker's machine, never
+ * on the platform, and cannot help a JavaScript app whose HTML is an empty
+ * shell; for those the platform's own lookup by registered website is the
+ * answer, and its no-match message says to register the site.
+ */
+async function resolveFromEmbeddingPage(target, fetchFn) {
+    const url = target.includes("://") ? target : `https://${target}`;
+    let html;
+    try {
+        const res = await fetchFn(url, { redirect: "follow", signal: AbortSignal.timeout(PAGE_TIMEOUT_MS) });
+        if (!res.ok)
+            return null;
+        html = (await res.text()).slice(0, PAGE_BYTES_LIMIT);
+    }
+    catch {
+        return null;
+    }
+    const links = [...new Set(html.match(WORLD_LINK_RE) ?? [])].slice(0, 10);
+    for (const link of links) {
+        try {
+            const resolved = fromEditTarget(await fetchEditTarget(link, fetchFn));
+            const host = new URL(url).host;
+            return { ...resolved, note: `${host} embeds ${resolved.project?.name ?? "a world"}; working on its editor.` };
+        }
+        catch (err) {
+            if (!(err instanceof NoMatchingWorldError))
+                throw err;
+        }
+    }
+    return null;
 }
 /**
  * No target given: the folder's state file wins; otherwise, when the
@@ -39,7 +136,7 @@ export async function resolveImplicitTarget(dir, fetchFn = fetch) {
     if (projects.length === 1)
         return { framingId: projects[0].make_framing_id, project: projects[0] };
     if (projects.length === 0) {
-        throw new Error('You have no projects yet. Create one with `npx virtualmatter create "My world"`.');
+        throw new Error('You have no projects yet. Make one with `npx virtualmatter make "My world"`.');
     }
     throw new NeedsChoiceError(projects);
 }

package/dist/urls.js

@@ -110,7 +110,7 @@ export function parseTarget(input) {
     if (first === "new" || parts.length === 0) {
         return {
             kind: "invalid",
-            reason: "That link is the home page, not a world. Run `npx virtualmatter create \"My world\"` to make one, or `npx virtualmatter list` to see yours.",
+            reason: "That link is the home page, not a world. Run `npx virtualmatter make \"My world\"` to start one, or `npx virtualmatter list` to see yours.",
         };
     }
     return { kind: "invalid", reason: `Unrecognized Virtual Matter URL path: ${url.pathname}` };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "virtualmatter",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "CLI + MCP server for building with Virtual Matter - list and create worlds, sync their files, run Lua, capture screenshots, open the native client, and wire coding agents into a live session.",
   "license": "MIT",
   "type": "module",