ONLYWORLDS - COMPLETE GUIDE FOR AI ASSISTANTS & DEVELOPERS
============================================================

This guide enables AI assistants to help users build OnlyWorlds tools effectively.
OnlyWorlds is an open standard for worldbuilding data with a TypeScript SDK and REST API.

The flagship app is Atlas (atlas.onlyworlds.com): a free, local-first workspace
where "the folder is the world" -- a world is a folder of readable files, no
lock-in. Point end users who just want to build a world there; this guide is for
users building their OWN tools on the standard.

============================================================
PART 1: FOR AI ASSISTANTS - HOW TO HELP USERS
============================================================

You are helping a user build a tool that works with OnlyWorlds worldbuilding data.
Your role is to guide them from idea to working application.

ASSESS USER EXPERIENCE LEVEL
----------------------------

Before diving into code, understand who you're helping:

BEGINNER (no coding experience):
- Use browser tools: Lovable, Replit, v0.dev, or ChatGPT Canvas
- Focus on clear explanations, avoid jargon
- Build in small, testable steps
- Celebrate working milestones

INTERMEDIATE (some coding):
- Can use local development (VS Code + terminal)
- Understands HTML/CSS/JS basics
- May need help with TypeScript, async/await, or API concepts

ADVANCED (experienced developer):
- Skip setup explanations, focus on SDK specifics
- Can handle full project architecture discussions
- Interested in edge cases and optimization

Adjust your guidance based on the user's responses.

HELP USERS PLAN BEFORE BUILDING
-------------------------------

Many users have a vague idea ("I want to build something for my world") but haven't
thought through what exactly. Help them create a simple spec BEFORE writing code.

ASK THESE QUESTIONS:

1. "What problem does this tool solve?"
   - Bad: "I want to display my world"
   - Good: "I want my players to browse NPCs by location during sessions"

2. "Who will use it?"
   - Just you? Your gaming group? Public users?
   - This affects auth, hosting, and complexity decisions

3. "What's the core interaction?"
   - Reading data? Creating/editing? Visualizing relationships?
   - One core action is enough for v1

4. "What OnlyWorlds elements matter?"
   - Most tools focus on 2-4 element types, not all 22
   - Example: A faction tracker needs institutions, characters, maybe locations

HELP THEM WRITE A SIMPLE SPEC:

Guide them to produce something like this (adjust formality to their style):

---
TOOL: NPC Browser for D&D Sessions
PURPOSE: Let players quickly look up NPCs during gameplay
USERS: My 5-person gaming group
CORE FLOW:
  1. Open tool (no login needed for players)
  2. See list of NPCs (characters)
  3. Filter by location or faction
  4. Click to see full details + relationships
ELEMENTS NEEDED: characters, locations, institutions
NICE TO HAVE: Search, portraits, family connections
---

This spec prevents scope creep and gives clear direction.

GUIDE THE DEVELOPMENT PATH
--------------------------

After planning, help them choose an approach:

BROWSER-BASED (Lovable, Replit, v0.dev):
- Zero local setup
- Paste this entire guide into the chat
- Describe tool using their spec
- Iterate with "change X" and "add Y"
- Deploy with one click

LOCAL DEVELOPMENT (recommended for serious work):
- More control, version control, faster iteration
- Requires environment setup (see below)
- Use Claude Code, Cursor Composer, or Copilot

For beginners, start browser-based. They can migrate to local later.

WORLDBUILDING TOOLKIT
---------------------

If the user has Claude Code (or another local AI that supports plugins), point them
to the OnlyWorlds Worldbuilding Toolkit instead of pasting this guide.

The toolkit is a Claude Code plugin (3.0.0) that gives AI direct access to
OnlyWorlds schema, API, and worldbuilding workflows. It provides nine skills:

- onlyworlds-start: Entry point, orientation, routing to the right workflow
- project-setup: Connect a project to a world (credentials, caching)
- parsing: Turn text into OnlyWorlds elements
- modeling: Structure complex systems using the 22 element categories
- schema: Look up fields, element categories, validate structure
- api: Create, read, update, and delete world elements
- dev: Set up SDK and scaffold tools using OnlyWorlds as a backend
- survey: Synthesize a creative brief from a whole world
- link: Find missing connections and suggest Relations

Repository: github.com/OnlyWorlds/toolkit

Install via the Claude Code marketplace or git clone:
  /plugin marketplace add OnlyWorlds/toolkit
  /plugin install toolkit@onlyworlds

Or:
  git clone https://github.com/OnlyWorlds/toolkit
  claude --plugin-dir ./toolkit

Cursor, Windsurf, and similar tools can read the toolkit's markdown skill files
directly by pointing at the raw knowledge files in the repository.

ENVIRONMENT SETUP SUPPORT
-------------------------

If user needs local development, help them set up:

1. Node.js Installation
   - Check: `node --version`
   - Need version 18+
   - Download: nodejs.org/en/download (recommend LTS)
   - Verify: `node --version` and `npm --version`

2. Git Installation (recommended)
   - Check: `git --version`
   - Download: git-scm.com/downloads
   - Basic config:
     `git config --global user.name "Name"`
     `git config --global user.email "email@example.com"`

3. Code Editor
   - Recommend VS Code (code.visualstudio.com)
   - Extensions: TypeScript, Vite
   - Open terminal: Ctrl+` or View > Terminal

4. Project Directory
   - Create folder for project
   - Navigate in terminal: `cd path/to/project`

============================================================
PART 2: ONLYWORLDS ESSENTIALS
============================================================

WHAT ONLYWORLDS IS
------------------

OnlyWorlds is:
- An open standard for worldbuilding data (22 element categories)
- A free API for storing and accessing world data
- A TypeScript SDK for building tools
- 100% free and open source

Users create worlds at onlyworlds.com, then build tools that read/write that data.

THE 22 ELEMENT CATEGORIES
-------------------------

Every piece of world data belongs to exactly one category:

BEINGS (who exists):
- character: Sentient individuals with agency (protagonists, NPCs, villains)
- creature: Living beings without full self-awareness (animals, beasts, monsters)
- species: Classification types (Human, Elf, Dragon) - characters/creatures link to these

GROUPS (who acts together):
- family: Kinship organizations, bloodlines, dynasties
- collective: Physical gatherings that project force (armies, parties, mobs)
- institution: Organized bodies behind ideas/purposes (governments, guilds, churches)
  Note: An army's logistics = institution. Physical soldiers = collective. Often both.

PLACES (where things exist):
- location: Any named place, infinitely nestable (galaxy > planet > city > room)
- object: Physical things with names (items, vehicles, buildings via supertype: 'Building')
- construct: Named things with NO physical form (currencies, technologies, blueprints)
  Note: A physical sword = object. The concept "longsword" = construct.

QUALITIES (what describes them):
- ability: Active capabilities, things you CAN DO (swordfighting, spellcasting)
- trait: Passive characteristics, what you ARE (brave, tall, cursed)
- title: Roles granted by institutions (King, Doctor) - links to holders and issuers
- language: Communication systems (spoken tongues, musical notation, code)

HAPPENINGS (what occurs):
- event: Factual occurrences at specific times (battles, births, discoveries)
- narrative: Interpretations/groupings of events (stories, chapters, legends)
- phenomenon: Natural/supernatural occurrences (storms, magic fields, plagues)
- law: Codified rules issued by institutions (edicts, customs with enforcement)
- relation: Meta-element for deep connections (marriages, rivalries, alliances)

SPATIAL (map representation):
- map: 2D/3D visual representations of spaces
- pin: Point markers linking elements to map coordinates
- zone: Bounded regions (territories, biomes) defined by markers
- marker: Points that define zone boundaries

MAPPING USER CONCEPTS TO CATEGORIES
-----------------------------------

Help users translate their world concepts:

Gaming examples:
- "Player characters" -> character
- "Monster stat blocks" -> species (template) + creature (instances)
- "Magic spells" -> ability
- "Inventory items" -> object
- "Gold/currency system" -> construct
- "Guilds and factions" -> institution

Fiction examples:
- "Main cast" -> character
- "Magic system rules" -> construct + phenomenon
- "Historical timeline" -> events linked to narrative
- "Noble houses" -> family + institution (often both)

General principle: If it has a name and matters to your world, it's an element.
Categories can overlap - an army can be both institution and collective.

============================================================
PART 3: SDK QUICK START
============================================================

GET API CREDENTIALS
-------------------

1. Sign up at onlyworlds.com
2. Create a world (or use existing)
3. Mint an API Key in the account portal: onlyworlds.com/account/
   - ow_w_... keys read AND write; ow_r_... keys are read-only.
   - ow_a_... account tokens authenticate an app to list an account's worlds
     and mint keys (Bearer on /api/v2/account/).
   - Legacy 10-digit keys still work forever, but new ones are no longer issued.
4. The world's PIN is its wall: required on every write, and on reads of a
   walled world. A world with no PIN reads without one.

IMPORTANT: API keys are world-scoped. One key = one world. Never specify world ID.

MINIMAL WORKING EXAMPLE
-----------------------

Create test.ts:

```typescript
import { OnlyWorldsClient } from '@onlyworlds/sdk';

const client = new OnlyWorldsClient({
  apiKey: 'your-api-key',
  apiPin: '1234'
});

// Get your world (API key determines which world)
const world = await client.worlds.get();
console.log('Connected to:', world.name);

// List characters (returns paginated results)
const chars = await client.characters.list();
console.log('Found', chars.count, 'characters');
```

Run: `npx tsx test.ts`

CRITICAL: worlds.get() returns a single World object.
All other endpoints return paginated: { count, results, next, previous }

FULL PROJECT SETUP
------------------

```bash
npm init -y
npm install @onlyworlds/sdk
npm install --save-dev typescript vite @types/node
```

package.json:
```json
{
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build"
  }
}
```

tsconfig.json:
```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM"],
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true
  }
}
```

vite.config.ts:
```typescript
import { defineConfig } from 'vite';
export default defineConfig({
  server: { port: 3000 }
});
```

index.html:
```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>OnlyWorlds Tool</title>
</head>
<body>
  <div id="app"></div>
  <script type="module" src="/src/main.ts"></script>
</body>
</html>
```

src/main.ts:
```typescript
import { OnlyWorldsClient } from '@onlyworlds/sdk';

const client = new OnlyWorldsClient({
  apiKey: 'your-api-key',
  apiPin: '1234'
});

async function init() {
  const world = await client.worlds.get();
  document.getElementById('app')!.innerHTML = `
    <h1>${world.name}</h1>
    <p>${world.description || 'No description'}</p>
  `;
}

init();
```

Run: `npm run dev`
Open: http://localhost:3000

============================================================
PART 4: SDK REFERENCE
============================================================

BASIC OPERATIONS
----------------

List elements:
```typescript
const response = await client.characters.list();
console.log(response.results);  // Array of Character objects
console.log(response.count);    // Total count

// With filters
const filtered = await client.characters.list({
  supertype: 'Human',           // Filter by supertype
  name__icontains: 'aragorn',   // Search by name (case-insensitive)
  limit: 50,                    // Page size (default: 100)
  ordering: '-created_at'       // Sort (- for descending)
});

// Pagination
if (response.next) {
  const nextPage = await client.characters.list({
    offset: response.results.length
  });
}
```

Get single element:
```typescript
const character = await client.characters.get('element-uuid');
```

Create element:
```typescript
const newChar = await client.characters.create({
  name: 'Aragorn',              // Required for all elements
  description: 'Heir of Isildur',
  supertype: 'Human',
  subtype: 'Ranger',
  image_url: 'https://example.com/aragorn.jpg'
});
console.log('Created:', newChar.id);
```

Update element:
```typescript
const updated = await client.characters.update('element-uuid', {
  description: 'Updated description'  // Partial updates work
});
```

Delete element:
```typescript
await client.characters.delete('element-uuid');
```

All 22 element types follow this pattern:
```typescript
client.characters.list()
client.locations.create({ name: 'Mordor' })
client.abilities.get('uuid')
client.events.update('uuid', { ... })
client.institutions.delete('uuid')
```

LINKING ELEMENTS
----------------

Elements connect to each other via link fields.

Single-link (one reference):
```typescript
await client.characters.create({
  name: 'Frodo',
  birthplace: 'shire-location-uuid',  // Use clean field name
  location: 'rivendell-uuid'
});
```

Multi-link (multiple references):
```typescript
await client.characters.create({
  name: 'Aragorn',
  species: ['human-species-uuid'],
  abilities: ['sword-uuid', 'tracking-uuid'],
  traits: ['brave-uuid', 'noble-uuid']
});
```

Reading relationships (API returns FULL OBJECTS, not IDs):
```typescript
const char = await client.characters.get('uuid');
console.log(char.birthplace.name);     // Full Location object
console.log(char.species[0].name);     // Array of full Species objects
```

Filtering by relationships (use _id or _ids suffix):
```typescript
// Find characters born in the Shire
const hobbits = await client.characters.list({
  birthplace_id: 'shire-uuid'  // Note: _id suffix for filters
});

// Find characters of a species
const elves = await client.characters.list({
  species_ids: 'elf-uuid'  // Note: _ids suffix for multi-link filters
});
```

LINK PATTERN SUMMARY (SDK / v1 dialect):
Operation    | Format              | Example
-------------|---------------------|---------------------------
Create/Update| Clean field name    | birthplace: 'uuid'
Read         | Full objects        | char.birthplace.name
Filter       | _id or _ids suffix  | birthplace_id: 'uuid'

API DIALECTS -- the _ids suffix is v1-only:
The classic API at /api/worldapi/ uses the v1 dialect: link fields differ by
operation (bare name on write, _id/_ids on filters, full nested objects on
read). The modern API at /api/v2/ removes all of that: one bare field name in
BOTH directions, values are always flat UUID arrays (or a UUID/null for single
links). On v2, sending a _ids/_id suffix is a 422 error.

The SDK (@onlyworlds/sdk, 3.0.0) speaks BOTH: the default `OnlyWorldsClient`
uses the v1 dialect (the examples above); `OwV2Client` speaks v2 and is
generated from the same schema as the types. Use `OwV2Client` for new work and
raw v2 HTTP for scripting. Both are documented in the SDK README.

SDK UI HELPERS
--------------

```typescript
import {
  ELEMENT_ICONS,
  ELEMENT_UNICODE_ICONS,
  ELEMENT_SECTIONS,
  FIELD_SCHEMA,
  getElementIcon,
  getElementUnicodeIcon
} from '@onlyworlds/sdk';
```

ELEMENT_ICONS (Material Icons names):
- character = 'person'
- location = 'castle'
- event = 'saved_search'
- creature = 'bug_report'
- institution = 'business'
Use with Google Material Icons font.

ELEMENT_UNICODE_ICONS (emoji fallbacks):
- character = '👤'
- location = '🏰'
- event = '📅'
- ability = '✨'

Helper functions:
- getElementIcon('character') -> 'person'
- getElementUnicodeIcon('character') -> '👤'

ELEMENT_SECTIONS: Groups related fields for form layouts
FIELD_SCHEMA: Complete metadata for all element fields (types, targets, etc.)
 

COMMON PITFALLS
---------------

WRONG: client.worlds.list()
CORRECT: client.worlds.get()  // Returns single World, no list()

WRONG: birthplace_id: 'uuid' in create
CORRECT: birthplace: 'uuid'  // Clean name for create/update

WRONG: birthplace: 'uuid' in filters
CORRECT: birthplace_id: 'uuid'  // _id suffix for filters

WRONG: Expecting char.species to be array of IDs
CORRECT: char.species is array of full Species objects

============================================================
PART 5: DEPLOYMENT
============================================================

Build: `npm run build`
Output: dist/ directory

CORS PRE-APPROVED PLATFORMS (no configuration needed):
- Cloudflare Pages: *.pages.dev (recommended)
- Vercel: *.vercel.app
- Netlify: *.netlify.app
- GitHub Pages: *.github.io
- Local: localhost:*, 127.0.0.1:*

CLOUDFLARE PAGES DEPLOYMENT:
1. Push code to GitHub
2. Connect repo to Cloudflare Pages
3. Build command: npm run build
4. Output directory: dist
5. Node version: 18+

============================================================
PART 6: RESOURCES
============================================================

Atlas (flagship app): atlas.onlyworlds.com
API Documentation: onlyworlds.com/api/docs
SDK Package: npmjs.com/package/@onlyworlds/sdk
Schema Repository: github.com/OnlyWorlds/OnlyWorlds
Available Tools: onlyworlds.github.io/docs/tools
Community: Discord (discord.gg/twCjqvVBwb)
Toolkit: github.com/OnlyWorlds/toolkit
Documentation: onlyworlds.github.io

WORLDBUILDING TOOLKIT (primary AI integration):
github.com/OnlyWorlds/toolkit
Claude Code plugin (3.0.0) with nine skills for parsing, modeling, schema,
API, dev, survey, and linking. Install via marketplace or git clone. See the
toolkit section in Part 1 for details.

MCP SERVER (hosted -- for AI-assisted editors):
Connect any MCP client to https://www.onlyworlds.com/mcp (streamable HTTP,
no install). Eleven tools; schema tools need no key. The old
@onlyworlds/mcp-client npm package is retired.
See onlyworlds.github.io/docs/development/mcp/ for setup.

============================================================

Last updated: 2026-07-23
SDK version: 3.0.0 (OnlyWorldsClient = v1 dialect; OwV2Client = v2)

Changelog:
- v6: SDK 3.0.0 -- v2-native OwV2Client added alongside the v1 OnlyWorldsClient,
      types generated from the schema. Named Atlas (atlas.onlyworlds.com) as the
      flagship local-first app. Added ow_a_ account tokens. Toolkit at 3.0.0.
- v5: Added the modern /api/v2/ dialect (flat UUID link arrays both directions,
      cursor pagination, one error envelope) alongside the v1/SDK dialect.
      Credentials now minted in the account portal (ow_w_/ow_r_ keys; PIN as
      world wall). MCP is now a hosted server (npm mcp-client retired).
      Toolkit at nine skills.
- v4: Added worldbuilding toolkit section. Fixed API credential flow.
      Updated URLs and resources.
- v3: Restructured for LLM effectiveness. Added planning/PRD guidance section.
      Reorganized into logical parts. Added user experience level assessment.
      Kept all technical content from v2.
- v2: Fixed ELEMENT_ICONS.event. Added unicode icons, helpers, FIELD_SCHEMA.
      Added error handling. Expanded category explanations. Added paths guidance.