Worldbuilding CMS for AI Agents

Description

# Worldbuilding CMS — Agent Skill Guide This document tells AI agents how to effectively use the worldbuilding model layer. Read this before interacting with a world. ## Quick Start ```ts import { WorldEngine } from "./src/index.js"; // Open a world using default built-in types const engine = new WorldEngine({ worldDir: "world" }); await engine.open(); // Create entities — only name and body are required await engine.create("character", { name: "Kira Solane", body: "A shipwright who discovered she can hear the ocean's memories.", tags: ["protagonist", "gifted"], species: "human", status: "alive", }); // Query, validate, close const chars = await engine.list("character"); const result = await engine.validate(); engine.close(); ``` ## Architecture You Need to Know ``` Agent (you) ↓ reads/writes via WorldEngine ├── DuckDBLayer — SQL queries over flat JSON files (read_json_auto) ├── FileStore — one JSON file per entity in world/<type-plural>/ ├── Validator — schema + referential integrity checks └── VectorIndex — semantic search (cosine similarity) ``` **Key principle:** Entities are flat JSON files in git. Every entity file is the single source of truth. DuckDB queries them in-place. The search index is disposable. ## Entity Model Every entity has these base fields: | Field | Type | Notes | |---|---|---| | `id` | string | Auto-generated from name via slugify, or pass custom | | `type` | string | Entity type name (e.g. "character", "planet") | | `name` | string | **Required.** Display name | | `body` | string | **Required.** Freeform prose lore — the main content | | `tags` | string[] | Defaults to `[]` | | `relations` | Relation[] | Typed references to other entities. Defaults to `[]` | | `metadata` | object | Arbitrary key-value data. Defaults to `{}` | | `created_at` | ISO 8601 | Auto-set | | `updated_at` | ISO 8601 | Auto-set on create and update | Plus type-specific fields (e.g. `species`, `faction_id` for characters). ### Built-in Types | Type | Directory | Key Fields | |---|---|---| | `character` | characters/ | title, species, status, faction_id, location_id | | `location` | locations/ | region, parent_location_id, climate, population | | `faction` | factions/ | motto, leader_id, headquarters_id, alignment | | `event` | events/ | date_in_world, location_id, participants, outcome | | `item` | items/ | item_type, owner_id, location_id, rarity, properties | | `lore` | lore/ | category, era, scope | ### Custom Types Define in `world.config.json`: ```json { "name": "My Universe", "types": { "planet": { "plural": "planets", "fields": { "system": { "type": "string" }, "classification": { "type": "string", "enum": ["terrestrial", "gas_giant"] }, "population": { "type": "integer", "minimum": 0 }, "parent_star_id": { "type": "string", "reference": true } } } } } ``` Custom types get the same base fields, validation, search indexing, and DuckDB querying as built-ins. Set `"builtInTypes": false` to use only your custom types. Load from config: ```ts const engine = await WorldEngine.fromConfig("./world.config.json", { worldDir: "./world", }); ``` ## CRUD Operations ### Create ```ts // Minimal — just name and body await engine.create("character", { name: "Elara Voss", body: "A wandering mage.", }); // Full — all optional fields await engine.create("character", { name: "Elara Voss", body: "A wandering mage from the Northern Reaches.", id: "custom-id", // optional, auto-slugified from name otherwise tags: ["mage", "wanderer"], relations: [{ target_id: "some-faction", target_type: "faction", relation: "member_of" }], metadata: { alignment: "chaotic good" }, species: "human", status: "alive", faction_id: "some-faction", }); ``` ### Read ```ts const entity = await engine.get("character", "elara-voss"); const allChars = await engine.list("character"); ``` ### Update ```ts await engine.update("character", "elara-voss", { status: "dead", body: "Updated lore text...", }); ``` ### Delete ```ts await engine.delete("character", "elara-voss"); ``` ## Querying ### SQL via DuckDB ```ts // WHERE clause on a type const mages = await engine.queryWhere("character", "faction_id = 'mages-guild'"); // Raw SQL — full DuckDB power const result = await engine.sql(` SELECT c.name, f.name as faction_name FROM read_json_auto('world/characters/*.json', union_by_name=true) c JOIN read_json_auto('world/factions/*.json', union_by_name=true) f ON c.faction_id = f.id `); ``` ### Semantic Search ```ts // Natural language query const results = await engine.semanticSearch("political tensions in the north"); // Filter by type const results = await engine.semanticSearch("magic system", { type: "lore", topK: 5 }); ``` **Important:** Call `await engine.reindex()` after bulk operations to rebuild the search index. Individual creates/updates automatically update it incrementally. ## Validation ```ts const result = await engine.validate(); if (!result.valid) { for (const err of result.errors) { console.log(`[${err.entityType}/${err.entityId}] ${err.message}`); } } ``` Validation checks: 1. **Schema conformance** — every entity matches its type's JSON Schema 2. **Referential integrity** — all `*_id` foreign keys and relation targets point to existing entities Validation runs automatically on every `create()` and `update()` call (schema only). Run `validate()` for a full integrity check across the entire world. ## Relations Relations are explicit typed edges between entities: ```ts await engine.create("character", { name: "Commander Vex", body: "...", faction_id: "iron-compact", // foreign key (validated) relations: [ { target_id: "iron-compact", target_type: "faction", relation: "leads" }, { target_id: "elara-voss", target_type: "character", relation: "rival_of" }, ], }); ``` **Foreign keys** (`faction_id`, `location_id`, etc.) are type-specific fields marked with `reference: true` in the schema. They are validated for existence. **Relations** are a generic edge list on every entity. The `relation` field is freeform — use whatever relationship names make sense for your world. ## File Layout ``` my-world/ world.config.json ← optional: defines custom types world/ characters/ elara-voss.json locations/ ashenvale.json factions/ iron-compact.json planets/ ← custom type directory kepler-442b.json .worldindex/ ← gitignored, regenerable vectors.json ``` ## Working With Git - Each entity is one file → minimal merge conflicts - Branch = alternative world state (e.g. `timeline/war-of-ash`) - Meaningful diffs: changing a faction leader is a one-line change - Run `npm run validate` as a pre-commit hook - Run `npm run reindex` after switching branches ## Common Patterns ### Seeding a World See `examples/verdance/seed.ts` (built-in types) and `examples/the-lattice/seed.ts` (custom types) for complete examples. ### Cross-Entity Queries ```ts // Characters in a location's region const northern = await engine.queryWhere("character", `location_id IN ( SELECT id FROM read_json_auto('world/locations/*.json') WHERE region = 'Northern Reaches' )` ); ``` ### Bulk Operations ```ts // Create many entities, then reindex once for (const char of characters) { await engine.create("character", char); } await engine.reindex(); // rebuild search index once at the end ``` ## What NOT to Do - **Don't edit JSON files directly** — use the engine so validation runs - **Don't commit `.worldindex/`** — it's a derived artifact, regenerate with `npm run reindex` - **Don't rely on the search index for correctness** — it's for discovery; use DuckDB/SQL for precise queries - **Don't create circular foreign keys in a single batch** — create entities first, then update with references (see the Verdance seed script's faction leader pattern)

Security Status