# Virtual Matter - context for coding agents

## Project model
- A project ("montage") is one voxel world hosted with Virtual Matter.
- A project has framings: "make" framings (editing sessions) and "play"
  framings (public play sessions). A framing is a running session slot
  on a voxel host.
- Project content = SDK Lua scripts + assets under a Montage/ tree.
  Edits made in the live session hot-reload into the running world.
  The tree can be published to a maker-owned GitHub repo.

## URL shapes (make.virtualmatter.ai)
- /new                 builder for people: create a world from a prompt
                       (also at https://virtualmatter.ai/); coding agents
                       use npx virtualmatter create instead
- /edit/<framing-id>   maker session: live world + agent chat
                       (also /edit/<slug>-<framing-id>; the CLI accepts both)
- /play/<framing-id>   play session for a specific framing
- /g/<id>              share URL resolver: 302s to a live session

## APIs (unauthenticated)
- GET https://make.virtualmatter.ai/api/v1/public/native-clients
  JSON: { iteration, clients: [{ platform, kind, url, filename,
  file_size, branch, commit, match }] } - per-platform native client
  installers (kind "download") or store links (kind "store", iOS).

## CLI + MCP (npm package "virtualmatter", Node >= 20)
- npx virtualmatter create "<name>"   create a world, mirror it into ./<slug>
- npx virtualmatter pull <link>       mirror an existing world (any link shape)
- npx virtualmatter list              your worlds with framing ids + URLs
- npx virtualmatter sync              live-push saves into the running world
- npx virtualmatter open              open the world in the native client
- npx virtualmatter mcp               stdio MCP server (list_projects,
  create_project, select_project, list_files, read_file, write_file,
  run_lua, get_engine_errors, capture_screenshot, open_native_client,
  world_info)
- Sign-in happens on first use (device code); no separate login step.
- A mirrored folder carries .mcp.json, .cursor/mcp.json, AGENTS.md and
  CLAUDE.md, so Claude Code and Cursor register the server on their own.
- Codex reads AGENTS.md but needs the server registered once:
  codex mcp add virtualmatter -- npx -y virtualmatter mcp