[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6},"actionData","errors","routes/tab",{"_7":8,"_9":10},"tab","guides","pages",[11,12],{"_7":8,"_13":60,"_15":61,"_17":18,"_19":62,"_21":63,"_23":64},{"_7":8,"_13":14,"_15":16,"_17":18,"_19":20,"_21":22,"_23":24},"section","build-a-world-with-an-ai-agent","title","Build a World with an AI Agent","kind","guide","summary","Set up a coding agent like Claude or Codex to author a Voyage V33 world against the wiki's API — folder structure, instruction files, the validate loop, an offline mirror, local models, and what it all costs.","order",2,"blocks",[25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40],{"_41":42,"_43":59},{"_41":42,"_43":58},{"_41":42,"_43":57},{"_41":42,"_43":56},{"_41":42,"_43":55},{"_41":42,"_43":54},{"_41":42,"_43":53},{"_41":42,"_43":52},{"_41":42,"_43":51},{"_41":42,"_43":50},{"_41":42,"_43":49},{"_41":42,"_43":48},{"_41":42,"_43":47},{"_41":42,"_43":46},{"_41":42,"_43":45},{"_41":42,"_43":44},"type","prose","md","## Where to go next\n\n- When you're done, paste `worlds/my-world/world.json` back into the editor's **JSON** toggle — where you copied it from — to play or publish.\n- Full endpoint reference: [API](/tools/api).\n- Check a world in the browser: [Validator](/tools/validator).\n- Section field rules: browse [World](/world), [Mechanics](/mechanics), [AI](/ai), and [Other](/other), or fetch `/api/sections/

.md`.\n- Ready-made toolkit: [World-Puppeteer](https://github.com/nikolaj-lat/World-Puppeteer).","## Pitfalls\n\n- **Hallucinated fields.** Agents confidently invent fields that do not exist. The cure is the per-section doc — make the agent read it and treat the schema fragment as the whitelist.\n- **Drift over long sessions.** The agent forgets rules as context fills. Keep the rules in `CLAUDE.md`/`AGENTS.md` so they reload every session, rather than relying on memory.\n- **Validator as a quality check.** It verifies structure and references, not whether the writing is good. Read the content yourself.\n- **Whole-wiki fetches.** The quickest path to a surprise bill. Fetch single sections.\n- **Rate limits.** `429` means back off, not retry instantly.","## Example prompts\n\nConcrete prompts to drive the loop. Adapt the bracketed parts to your world.\n\nKick off a session, after opening the working folder:\n\n```text\nYou're helping me build a Voyage V33 world in worlds/my-world/world.json. Rules: before editing\nany section, fetch its field rules from\nhttps://unofficial.voyage/api/sections/

.md and use only the fields shown\nthere — never invent fields. Each keyed-map entry's outer key must be identical to\nits inner \"name\". After every change, validate by POSTing the whole worlds/my-world/world.json to\nhttps://unofficial.voyage/api/validate and fix all errors before continuing.\nStart by fetching /api/sections.json and listing the sections we'll need.\n```\n\nDesign before building, a good moment to use plan mode:\n\n```text\nBefore writing any JSON, interview me about this world: premise, tone, the main\nfactions and their conflict, and the player's role. Then propose a build order\nfor the sections. Don't edit files yet.\n```\n\nAuthor one section:\n\n```text\nLet's do the NPCs section. Fetch /api/sections/npcs.md first. Then draft 5 NPCs\nthat fit [premise], using only documented fields, key = name, with real\nhiddenInfo and personality. Validate worlds/my-world/world.json and fix everything before showing\nme the result.\n```\n\nValidate and fix:\n\n```text\nValidate worlds/my-world/world.json against https://unofficial.voyage/api/validate. Fix every\nerror, then list the warnings with a suggested fix for each so I can decide.\n```","## Building on an existing IP\n\nIf your world is based on an existing setting (an anime, game, or book series), the agent will happily invent \"canon\" from its training data — and get it subtly wrong. Give it an authoritative source instead. Most fan wikis run on MediaWiki and expose an API at `https://.fandom.com/api.php` (`action=parse` to pull a page, `action=query` to search), so the agent can look up characters, locations, and events and verify facts rather than recall them.\n\nThink of it as two reference layers: this wiki's API tells the agent **how V33 works** (fields, limits, validation); the source's wiki tells it **what is true** in the setting. Put both in your instructions — for example, \"for any canon fact, query `https://.fandom.com/api.php` and use what it returns; never state lore from memory\" — and you get a world that is both structurally valid and lore-accurate.","## Work offline (mirror the wiki)\n\nSome agents — notably ChatGPT and Codex in long-running threads — intermittently fail to fetch live URLs they should be able to reach. Mirroring the wiki to local disk once sidesteps that entirely and cuts repeat fetches (which saves tokens). The wiki ships a copy-paste script for it: see [Mirror the wiki for an offline agent](/tools/api/#offline-mirror) on the API page (bash and PowerShell versions; the section loop is driven from the live manifest, so each run always covers every current section).\n\nOnce mirrored, point your instruction file or skills at the local files instead of URLs — for example, tell the agent to read `./voyage-wiki/sections/

.md` rather than fetching the endpoint. A small offline skill is just a `SKILL.md` that says where the mirror lives and to read section docs from there. Validation still goes to `POST /api/validate` (or a locally run validator, if you set one up).\n\nThe mirror is a point-in-time snapshot, not a permanent copy: the wiki changes (schema bumps, corrected field rules, new or removed sections), so re-run the script every so often to refresh it. Validating against the live `/api/validate` still catches schema drift even when your local docs have fallen behind.","## Wire the agent to the wiki (the API workflow)\n\nThe whole method is a tight read-write-check loop, and it lives in the instruction file (or a skill). Three endpoints matter:\n\n- `GET /api/sections.json` — once, to discover the section keys (`npcs`, `locations`, `traits`, `aiInstructions`, and so on).\n- `GET /api/sections/

.md` — per section being worked on. This is the targeted, cheap read: prose, field notes, and the schema fragment for just that section.\n- `POST /api/validate` — after every change. The body is the entire `worlds/my-world/world.json`; the response is `{ counts, errors, warnings, recommendations, validatorVersion }`.\n\nRead the validator output by severity: **errors** will break at runtime (fix them all), **warnings** might (review each), **recommendations** are optional quality nudges. The endpoints are CORS-open, unauthenticated, and free, but rate-limited — on `HTTP 429` the response carries a `Retry-After`; slow the loop down rather than hammering it.\n\nA bare-terminal version of the loop, to confirm the wiring before handing it to the agent:\n\n```bash\n# Field rules for the section you're about to edit (targeted, cheap)\ncurl https://unofficial.voyage/api/sections/npcs.md\n\n# Validate the whole world after editing\ncurl -X POST https://unofficial.voyage/api/validate \\\n -H 'Content-Type: application/json' \\\n --data-binary @worlds/my-world/world.json\n```","## Per-world notes\n\n- Keep each world's bible (premise, factions, central conflict, player role) in\n its own folder, e.g. `worlds//DESIGN.md`, and decide it before\n mass-authoring. CLAUDE.md holds project-wide rules only, not one world's lore.\n```","## Canon (for worlds based on existing IP)\n\n- Verify every canon fact against the source, not memory. Query the setting's\n wiki API, e.g. `https://.fandom.com/api.php` (`action=parse` to read a\n page, `action=query` to search). If you did not look it up, do not state it.","## Standing rules\n\n- The fetched section doc is the authority for that section's fields, formats, and\n limits. Follow it rather than memory; the wiki changes, so don't bake its\n specifics into your assumptions.\n- A clean validator proves structure, not quality; passing does not mean the\n content is good. Don't stop at a clean validate.","## Workflow (per section)\n\n1. Fetch only that section's rules first:\n `GET https://unofficial.voyage/api/sections/

.md`.\n Read just that section, never `/api/wiki.md` or the HTML pages.\n2. Draft or edit the section in that world's `world.json`, following the field\n list and rules in the doc you just fetched. If a field is not in that doc, it\n does not exist; never invent fields.\n3. Validate: `POST https://unofficial.voyage/api/validate` with the whole\n `world.json` as the body. Fix every error; review every warning.\n4. Repeat until clean, then add a dated entry to that world's `changelog.md`.\n\nBefore writing a trigger script, fetch the triggers section doc first; script\ncapabilities are narrow.","## Set up the project structure\n\nBoth ecosystems use the same idea: a plain-text instruction file at the project root that the agent reads every session, plus optional reusable \"skills\" it can pull in on demand.\n\n**Claude (Claude Code / the IDE extension):**\n\n- `CLAUDE.md` at the project root — your standing instructions: what the project is, the per-section workflow, and where worlds live.\n- `./.claude/skills//SKILL.md` — optional reusable skills, for example one per schema section carrying that section's field rules and the endpoint to consult.\n\n**Codex (CLI / IDE):**\n\n- `AGENTS.md` at the project root — the same role as `CLAUDE.md`. Codex reads it for project conventions.\n\nA minimal layout:\n\n```text\nvoyage/ # your working folder\n├── worlds/\n│ └── my-world/ # one folder per world\n│ └── world.json # pasted from the editor's JSON toggle\n├── CLAUDE.md # Claude's standing instructions (AGENTS.md for Codex)\n└── .claude/\n └── skills/\n └── npcs/\n └── SKILL.md # optional per-section authoring skill\n```\n\n**Work out of one folder, and keep returning to it.** In Claude Cowork, set that folder as the working folder and reuse the same conversation for all your Voyage work, so the world's context carries across sessions. With the Claude Code CLI, `cd` into the folder, start the agent, and use `/resume` to continue your previous session instead of starting cold. Codex is the same: run `codex resume --last` (or `codex resume` to pick from history) to continue a prior session in that folder. The `CLAUDE.md`/`AGENTS.md` and `.claude/skills/` conventions above are read by the CLI and IDE tools; the desktop apps run the same engine on the same folder.\n\nFor anything bigger than a quick edit, use the agent's plan mode first — Claude Code's plan mode, or Codex's plan/approval controls — so it proposes an approach for you to approve before it touches files.\n\nKeep the instruction file short and durable — it is reloaded every session, so it should carry rules, not raw data the agent can fetch. A workable `CLAUDE.md` (or `AGENTS.md`) skeleton:\n\n```markdown\n# Voyage V33 worlds\n\nThis project builds and edits Voyage V33 worlds. Each world lives in its own\nfolder: `worlds//world.json` (the source of truth). Work on whichever world\nthe task names. Validate after every change; never call a section done until the\nvalidator is clean.","## Prerequisites\n\n- **An agent.** Either the Claude track — Claude Code (the CLI, also available in your IDE) or Claude Cowork (the desktop app, paid plan) — or the Codex track — the Codex CLI or its desktop app (paid ChatGPT plan or API key).\n- **A working folder** for the project. Your world JSON lives here (in `./worlds`), alongside the agent's instruction file.\n- **A world JSON to edit.** In the Voyage editor, create a new world, toggle **JSON** (top-right), and copy the whole document into a file in your working folder — `./worlds/my-world/world.json` is a good spot. That editor-generated JSON is always current and valid, which makes it the right starting point.\n- **Comfort running a terminal command** if you take the CLI route. The desktop clients need less of this.","## Fastest start: World-Puppeteer\n\n[World-Puppeteer](https://github.com/nikolaj-lat/World-Puppeteer) is a community-built, customised **Claude Code** setup for exactly this task. It runs in VS Code or Cursor through the Claude Code extension, with a `.claude/` config that gives Claude a worldbuilder persona: it interviews you about your vision, then spawns a troupe of specialist sub-agents — one per content type (NPCs, locations, items, quests, factions, traits, triggers, and more) — that write the `tabs/*.json` files, with validation hooks that catch malformed content before the build.\n\nTo start in minutes, clone it and follow its `SETUP.md` rather than building the structure by hand. You'll need VS Code or Cursor with the Claude Code extension and Node.js (plus an optional Gemini API key if you want it to generate portraits). The rest of this guide still applies either way — it explains the moving parts Puppeteer automates, and works with any agent (Codex included), not just this Claude Code setup.","## Running a model locally (optional)\n\nYou can skip per-token billing entirely by running an open-weight model on your own machine — free after hardware, and fully private and offline. The catch is quality: open models trail the frontier ones at the demanding parts of this task (strict JSON, canon accuracy, not inventing fields), so expect more babysitting and re-validation. Local is best for cheap bulk passes and experimentation rather than as the primary driver of a polished world.\n\n- **Run it with** [Ollama](https://ollama.com) (the de-facto runner — pull a model by name) or [LM Studio](https://lmstudio.ai) (a polished GUI). Get models from Ollama's library, LM Studio's in-app browser, or [Hugging Face](https://huggingface.co); the Qwen Coder and DeepSeek Coder families are among the stronger open coding models.\n- **Both clients in this guide can point at a local model.** Claude Code talks to Ollama's Anthropic-compatible API — set `ANTHROPIC_BASE_URL=http://localhost:11434` and `ANTHROPIC_AUTH_TOKEN=ollama`, then map its model-tier variables to your local model. Codex runs local with `codex --oss`, or a `[model_providers.ollama]` block in `~/.codex/config.toml`. Prefer a local-first agent instead? Aider (terminal) and Cline (in your IDE) are built for it.\n- **Hardware is the real limit.** It is RAM/VRAM-bound — roughly 16–32 GB for small or quantized models, 32–64 GB for mid-size coding models, and 64 GB+ for the larger ones. Claude Code also wants a large context window (64k+), which raises the bar.\n\nEither way the workflow below is identical: point the agent at `/api/sections/

.md` and `/api/validate` just the same.","## What it costs (read this first)\n\nThese agents are metered. You pay per token, and a full world is many iterations, so this is real spend, not a free tool. Cost scales with two things: the model you pick, and how much text you feed it each turn. The most capable Claude models are the priciest per token; smaller models cost a fraction.\n\nThe single biggest lever is **how the agent reads the wiki**. Point it at the targeted endpoints, never the firehose:\n\n- **Do:** fetch only the section being worked on — `GET /api/sections/

.md` (for example `/api/sections/npcs.md`). That is a few KB.\n- **Don't:** pull the whole reference every turn. `/api/wiki.md` is the entire wiki in one payload, and scraping the rendered HTML pages is worse still — page markup the agent does not need. Loading either into context on every step multiplies your bill for no benefit.\n\nOther ways to keep usage down:\n\n- Use a smaller, cheaper model for bulk and mechanical passes (generating many similar entries, reformatting) and reserve the top model for the hard reasoning — world design, canon, tricky validator fixes.\n- [Mirror the wiki](#work-offline-mirror-the-wiki) once and read from disk, so the agent never re-fetches the same docs.\n- Keep each task scoped to one section or one change instead of asking for the whole world in a single sprawling turn.\n\nDesktop clients also carry a subscription cost: Claude Cowork is paid-plan only (Pro and up), and Codex needs a paid ChatGPT plan or an API key. Budget for it before a long session.","## Overview\n\nA Voyage world is a large structured JSON document, and this wiki publishes the V33 schema in a machine-readable form: per-section docs, the raw codec, and a validator endpoint. That combination makes a coding agent — something like Claude or Codex — a natural way to draft and refine a world. The agent reads the field rules for the section it is working on, writes the JSON, checks it against the live validator, and fixes whatever is flagged, looping until clean.\n\nThis guide sets that workflow up end to end: which tools to use, how to lay out the project folder and instruction files, how to point the agent at the wiki without burning tokens, how to work offline, and how to drive it with example prompts. The core is tool-agnostic — the same loop drives any capable agent — with concrete setup shown for Claude and Codex.\n\nIf you would rather not wire it up by hand, there is a faster on-ramp: see [Fastest start: World-Puppeteer](#fastest-start-world-puppeteer).\n\n> **Coming from Voyage: Studio.** Voyage has announced **Studio**, a native feature for building a world by talking to an agent directly on the site — the same idea as this guide, built in. When it ships it may change the manual UI steps below (create a world, toggle JSON), and for many authors it will be the simplest path. Until then, this guide is how you drive your own agent against the wiki.","welcome-to-community-guides","Welcome to Community Guides","What Community Guides are, who writes them, and how these community tutorials differ from the field-by-field V33 schema reference, plus how to add one.",1,[65,66,67],{"_41":42,"_43":70},{"_41":42,"_43":69},{"_41":42,"_43":68},"## Writing one\n\nAnyone can propose a guide straight from the site, no account needed. You write it in the\nbrowser, optionally add a handle for credit, and submit it for review. Approved guides are published\nhere with your handle attached.","## How guides differ from the reference\n\nThe schema reference is authoritative: it states facts about how V33 works. Guides are opinionated and\npractical, contributed by the community and reviewed before publishing. Treat them as experienced\nadvice rather than ground truth, and always confirm engine behavior against the reference.","## What this is\n\nCommunity Guides are practical, free-form tutorials written by Voyage authors. Unlike the rest of the\nwiki, which documents the V33 schema field by field, guides walk through *how to actually do things*:\nbuilding a believable faction, wiring a reputation system out of triggers, pacing a slice-of-life\nworld, and so on."]