# Oriverse — AI agent quickstart

Version 2026-09-02 (llms.txt names the current date; if this one is older,
refetch https://www.oriverse.com/docs/agents/quickstart.md?v=<that date>).

Human? Paste this page's URL into your AI agent (Claude Code, Codex, ChatGPT,
claude.ai) and ask it to build you a game. AI agent? Pick your lane:

- **Can you run commands on the user's Windows machine** (Claude Code, Codex,
  terminal agents)? Download the desktop app (section 1) and build with its
  agent CLI — no account or connector. Can download files but not launch
  them? Fetch + verify the zip; the user double-clicks it.
- **Can you add an MCP server to yourself** (`claude mcp add`,
  `codex mcp add`, API clients)? Connect MCP (section 2).
- **Neither — chat-only session** (claude.ai, ChatGPT, mobile)? Send the user
  to https://www.oriverse.com/editor and tell them to ask its built-in AI
  assistant for the game. Never walk the user through MCP connector setup
  unless they ask to connect this chat.

Whatever the lane, you write Weave (Oriverse's language): read the Weave
skill → build and playtest → deliver `share_game` (play link),
`publish_game` (project page), or `submit_pending_world` (the user's open
editor).

## 1. Desktop app (Windows x86_64)

The full engine: editor, agent CLI, playtest, publish. Non-Windows or
no-install: the web editor (https://www.oriverse.com/editor in a WebGPU
browser — Chrome/Edge, or Safari 26+ — free account) is the same project
surface; skip to section 2.

### Download

1. Fetch the release manifest: https://www.oriverse.com/binary/editor/latest.json
2. Show the user the version (`tag`) and download size (`zip_bytes`), and ask
   before downloading or running anything.
3. Download `zip_url`, verify `zip_sha256`, extract, start `entrypoint`:

~~~powershell
$m = Invoke-RestMethod https://www.oriverse.com/binary/editor/latest.json
$zip = Join-Path $PWD "oriverse-$($m.tag).zip"
Invoke-WebRequest $m.zip_url -OutFile $zip
$actual = (Get-FileHash $zip -Algorithm SHA256).Hash.ToLowerInvariant()
if ($actual -ne $m.zip_sha256.ToLowerInvariant()) { throw "SHA-256 mismatch" }
$dir = Join-Path $PWD "oriverse-$($m.tag)"
Expand-Archive -LiteralPath $zip -DestinationPath $dir
Start-Process (Join-Path $dir $m.entrypoint)
~~~

Do not bypass Windows security prompts — let the user approve them. The user
then signs in (or creates a free account) and leaves the app open.

### Build with the exe CLI (no account, no MCP)

`oriverse.exe tools` lists every agent tool and writes `agent_readme.md` (the
CLI quickstart, also shipped next to the exe) with the calling conventions.
Build: `read_skill("weave_coding")` → `stage_new_world` → `playtest` →
`share_game` (a hosted play link: browser or desktop app, one shared live
session per link). The GUI exe has no console: call it via Start-Process with
output redirects, and pass tool args as `--args-file <path.json>`. Publishing
to an account still needs sign-in (sections 2 and 4).

## 2. MCP (agents that can self-configure)

MCP server: `https://mcp.oriverse.com/relay/mcp` (Streamable HTTP + OAuth).

Over MCP, building, playtesting and `share_game` run server-side — no client
needed. A signed-in client (section 1) is needed only for
`submit_pending_world` and the editor's Publish.

Codex CLI:

~~~text
codex mcp add oriverse --url https://mcp.oriverse.com/relay/mcp
codex mcp login oriverse
codex mcp list
~~~

Claude Code:

~~~text
claude mcp add --transport http oriverse https://mcp.oriverse.com/relay/mcp
~~~

then run `/mcp` and authenticate.

Chat clients (claude.ai / ChatGPT): connector setup is manual work in the
user's settings — offer it only when the user asks to connect their chat
account; otherwise route per the lanes at the top.

Sign in with the SAME Oriverse account as the client from section 1. After
OAuth, restart the agent or open a new session so the tools load. For
`submit_pending_world` the app/page must stay open and signed in: it routes
to the live client, and only when the agent's MCP OAuth account matches the
client's signed-in account.

## 3. Build

1. Call `read_skill("weave_coding")` before writing or changing any Weave —
   it returns the language reference matching the connected client's version.
   Never guess Weave syntax or reuse Weave docs found elsewhere.
2. Inspect the available tools and the current client/project state, then use
   the tools (MCP or exe CLI) to stage, patch, and run the world.
3. Keep user confirmations for destructive, publishing, or purchasing actions.

## 4. Share

When the game is ready, the user presses **Publish** in the editor. Publish
updates the live public version and gives a public project page URL — that
link is the shareable game (multiplayer works; players sign in free).

Without publishing: `share_game` returns a temporary hosted play link
(expires ~30 days) — a page offering instant browser play or
open-in-desktop-app, where everyone on the link shares one live session.

## If something fails

- User stalled in connector setup: stop; route per the lanes at the top
  (exe CLI, or the web editor's built-in assistant).
- `submit_pending_world` reports no bound client: the Oriverse app/page is not
  open, not signed in, or signed into a different account than the MCP OAuth.
  Everything else works without a client; `share_game` still delivers a link.
- OAuth succeeded but tools don't appear: restart the agent or open a new
  session/task.
- Unsupported OS/arch for the desktop ZIP: use the web editor path.
- SHA-256 mismatch: delete the file and re-download; never run a mismatched
  binary.