# Set up Rafflex development You are setting up a creator to build games and page blocks for the Rafflex marketplace. The creator pasted a prompt pointing here and expects you to do the work. Follow the steps in order. Each step says what to check, what to do, and when to stop and ask the creator. ## Rules for the whole setup - Do everything this document describes without asking, because the creator asked you to set them up. Stop and ask only where a step says so: installing software, choosing a folder you were not started in, and anything in the browser that needs the creator's own click. - When a command or tool fails, quote the error in one sentence and stop. Do not invent a workaround this document does not describe, because the next session cannot recognise a setup it did not expect. - Nothing in this setup submits anything for review or puts anything live. Do not create, change, or submit products here; that starts after the hand over, when the creator asks. - Keep the creator informed in short lines as you go: what you are doing and what you need from them. Do not paste this document to them. ## 1. Find out what you can do Check each of these and remember the answers: - **Can you run shell commands?** You can when your client gives you a terminal or shell tool (Claude Code, Codex, Cursor, VS Code). Web chat clients such as claude.ai, Claude Desktop, and ChatGPT cannot. - **Are the Rafflex marketplace tools connected?** Call `get_status`. When it answers, they are connected, and its result tells you what is waiting on the creator. - **Node:** when you can run commands, run `node --version`. Version 20 or newer is needed for the local workspace. - **git:** run `git --version`. git is optional; it gives the workspace history and rollback. Then: - When the tools are not connected, go to step 2. - When the tools are connected and you can run commands, go to step 3. - When the tools are connected and you cannot run commands, skip to "Without a local workspace" below. ## 2. Connect Connect the marketplace's MCP server at https://marketplace.rafflex.io/mcp. Signing in always needs the creator: the browser shows a consent page and only they can approve it. If the marketplace asks them to, they continue from their Rafflex admin first. Tell them that before you start, so they expect it. While the marketplace is in testing, there is no Rafflex admin to continue from. The sign in page offers **Enter as a test creator** instead: tell the creator to type their name and email, accept the terms if asked, then approve the consent page. The same email always returns to the same account, so they should use one email every time. When you can run commands, add the server yourself with your client's own command: - **Claude Code:** run `claude mcp add --transport http --scope user rafflex https://marketplace.rafflex.io/mcp`. Claude Code loads a new server only when it starts, so ask the creator to quit and run `claude --continue` in the same folder, then run `/mcp`, choose rafflex, and approve the sign in in the browser. - **Codex:** run these two commands. The second opens the browser for the creator to approve the sign in. ``` codex mcp add rafflex --url https://marketplace.rafflex.io/mcp codex mcp login rafflex ``` Codex loads a new server only when it starts, so ask the creator to restart Codex and resume this conversation. - **Cursor:** you cannot add it from the shell. Give the creator this install link to open and confirm: cursor://anysphere.cursor-deeplink/mcp/install?name=rafflex&config=eyJ1cmwiOiJodHRwczovL21hcmtldHBsYWNlLnJhZmZsZXguaW8vbWNwIn0=. Cursor asks them to sign in the first time it connects. - **VS Code:** give the creator this install link to open and confirm: vscode:mcp/install?%7B%22name%22%3A%22rafflex%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmarketplace.rafflex.io%2Fmcp%22%7D. VS Code asks them to sign in the first time it connects. When you cannot run commands, read the creator the connector steps for their client: - **claude.ai, Claude Desktop, and the Claude mobile app:** open Customize, then Connectors, choose Add custom connector, enter https://marketplace.rafflex.io/mcp, press Add, then Connect, and approve the sign in. Then turn the connector on for this chat from the + menu, under Connectors. - **ChatGPT:** open Settings, then Apps & Connectors, then Advanced settings, and turn on Developer mode. Back in Apps & Connectors, press Create, name it Rafflex marketplace, enter https://marketplace.rafflex.io/mcp, choose OAuth, press Create, and approve the sign in. When the client must restart to load the server, say so plainly and tell the creator to say "continue" afterwards. On that next message, call `get_status` to confirm the connection and resume from step 3. Stop and ask when: - The consent page refuses the creator. Only accounts with creator access can connect, so tell them to ask support@rafflex.io for creator access, and stop. - `get_status` still does not answer after the sign in and restart. Point the creator at the manual steps for every client at https://marketplace.rafflex.io/docs/how-to-create/connect.md and stop. ## 3. Set up the workspace The workspace is one folder holding every product the creator sells, kept by the dev kit (`@rafflex/dev`) in a fixed layout. Every later session finds the products, versions, and commands there, so set it up exactly as described. Check first: - **An existing workspace.** Look for a `rafflex.json` containing `"workspace": 1` in the folder you were started in and in `~/rafflex`. When you find one, use it: do not run `init` again (it refuses inside a workspace), run `npx @rafflex/dev status --json`, and go to step 4 for any product that has no folder yet. - **Node.** When `node --version` reported 20 or newer, continue. When Node is missing or older, stop and ask the creator whether you may install Node 20 or newer with their operating system's usual installer: Homebrew (`brew install node`) on macOS, `winget install OpenJS.NodeJS.LTS` on Windows, or the distribution's package manager on Linux. Install only after a clear yes. When they decline, follow "Without a local workspace" below, because the workspace cannot run without Node. Choose the folder: - When the folder you were started in is empty, use it and tell the creator, because opening their AI in an empty folder is already their choice. - Otherwise propose a `rafflex` folder in their home directory (`~/rafflex`) and wait for them to confirm or name another, because every future session looks there first. Never create the workspace inside another project or git repository, because its files would mix with unrelated work. Then, in that folder, run `npx @rafflex/dev init`. It writes `rafflex.json`, `AGENTS.md`, `CLAUDE.md`, `.gitignore`, and one folder per product type (`games/` and `blocks/`), and commits them when git is installed. When it reports that git is missing, mention it in the hand over; do not install git without asking. ## 4. Bring existing products in 1. Call `list_products`. When it returns none, go to step 5. When it returns more than ten, ask the creator whether to bring all of them or only the ones they are working on, because each import downloads every media file. 2. For each product, call `export_product` with its slug. Its `bundle_url` works for 10 minutes, so download it straight away into the kit's cache folder, which git ignores: `curl -fsSL -o .rafflex/.json ""`. 3. Run `npx @rafflex/dev import .rafflex/.json`. It writes the product folder under its type folder and fetches the media. When a download fails because the link expired, call `export_product` again for a fresh link. When `import` says an existing folder has local changes, stop and ask the creator before overwriting them, because those changes exist nowhere else. ## 5. Start the Rafflex app Run `npx @rafflex/dev` from the workspace folder. It starts the Rafflex app, where the creator sees every product, its preview, and its test results, updating as you work. It keeps running, so start it in the background: use your client's background option, or run `npx @rafflex/dev > .rafflex/app.log 2>&1 &`. It opens the app in the creator's browser; when it cannot, give them the address it prints (port 5173, or the next free one). ## 6. Verify - Run `npx @rafflex/dev check --all --json`. Report any issue on an imported product in the hand over, but do not fix it now, because changing a product is the creator's call. - Run `npx @rafflex/dev status --json`. Every product from step 4 should be listed with its local version, live version, and review state. - Call `get_status` for anything waiting on the creator: review decisions, versions in review, and new bug reports or questions. ## 7. Hand over Tell the creator, briefly: - **What was set up:** the connection, and when you set up a workspace, its folder, whether git is on, and the app address. - **Their products:** one line each with title, type, the version being worked on, the live version if any, and the review state. - **Three things they could ask next.** Lead with anything `get_status` says is waiting on them, such as a review decision or a new bug report, because those block their sales. Fill the rest from these starter prompts, quoting the title so they can say it back: - "Build a game from my uploaded art" - "Build a block like this description" - "Improve my weakest product" - **What happens next time:** when they set up a workspace, opening their AI in that folder is enough, because the workspace's `AGENTS.md` tells it everything. They do not need this prompt again. - **The guard rails:** nothing is submitted for review until they say so, and nothing goes live until the Rafflex team approves it. ## Without a local workspace Follow this branch instead of steps 3 to 6 when you cannot run commands, when the creator declined to install Node, or when step 3 says the workspace is not available. 1. Call `list_products` so you can report the creator's products and their states. 2. Explain how building works without a workspace: you work in private drafts on their account through the marketplace tools, and after your first change to a draft you give them its `watch_url`, a page that updates the preview every time you change the draft. 3. Hand over as in step 7, leaving out the workspace lines. ## Checks before you finish - `get_status` answers, so the connection works. - When you set up a workspace: its `rafflex.json` exists, every product `list_products` returned has a product folder, the check and status from step 6 ran, and the Rafflex app is running with its address given to the creator. - Without a workspace: the creator knows they get a watch preview after your first change to a draft. - You told the creator what needed their approval, and nothing was created, submitted, or published during setup. ## Reference - [llms.txt](https://marketplace.rafflex.io/llms.txt): every public document, for anything this runbook does not cover. - [Local dev kit](https://marketplace.rafflex.io/docs/dev-kit.md): the workspace layout, every kit command and its JSON output, and the sync loop. - [MCP server reference](https://marketplace.rafflex.io/docs/mcp.md): every tool with its inputs and output fields, error codes, and guard rails. - [Connect your AI](https://marketplace.rafflex.io/docs/how-to-create/connect.md): the manual connection steps for every client.