@onlyworlds/sdk 3.0.0 → 3.1.0

package/AGENTS.md

@@ -0,0 +1,30 @@
+# For AI agents using @onlyworlds/sdk
+
+**What this package is**: the canonical typed TypeScript client for the OnlyWorlds v2 API,
+plus the canonical constants (element types, icons, colour families, field schema).
+OnlyWorlds is an open standard for portable world data — 22 element types, UUID-linked.
+
+**Use the v2 surface.** `OwV2Client` + the `V2ElementType` slug union + the generated
+interfaces in `types.generated.ts` (emitted from the canonical schema YAML, validated
+against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum) is frozen
+legacy — do not build new work on it.
+
+**SDK vs MCP server — pick correctly**:
+- Known, deterministic operations (CRUD, sync, bulk) → **this SDK**. Typed calls, typed
+  responses, far cheaper than tool-schema reasoning.
+- Live exploration of a user's world from a chat/agent context → the **MCP server** at
+  `https://www.onlyworlds.com/mcp` (same `API-Key`/`API-Pin` headers, 11 tools).
+
+**Wire facts that bite** (full details in README):
+- Never send a `"world"` field in payloads — world identity comes from the API key (422 otherwise).
+- v2 link fields use ONE name both directions (no `_ids` suffix — that is v1 dialect only).
+- PATCH is destructive on sent fields; use `editLinks` (atomic add/remove) for relationships.
+- World-meta changes do NOT appear in `/changes` — poll `GET /world` separately.
+- Extension fields: `x_<toolname>_*` is the sanctioned namespace for tool-specific state;
+  unknown unprefixed fields 422.
+- Colour carries the element's FAMILY (`elementColor(type, mode)`); the icon
+  (`ELEMENT_ICONS`) carries the TYPE. Icon + label are required alongside colour, not optional.
+
+**Auth**: prefixed keys — `ow_w_` (read+write), `ow_r_` (read-only, no PIN — the share
+primitive), `ow_a_` (account Bearer). Demo keys `0000000000`–`0000000009` are read-only
+test credentials against real data.

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to `@onlyworlds/sdk`. Maintained from 3.1.0 onward (Kael, Assembly);
+earlier history lives in git log only.
+
+## [3.1.0] — 2026-07-23
+
+### Added
+- **Canonical element colour palette** (`src/v2/palette.ts`, exported from root):
+  `ELEMENT_FAMILIES` (type → family), `FAMILY_COLORS` (family → `{light, dark}` hex),
+  `familyOf(type)`, `elementColor(type, mode)`, `FAMILY_ORDER`, type `ElementFamily`.
+  Four semantic families (agents / world / abstract / temporal) ruled 2026-07-22 after
+  CVD-validated measurement (Orrery `product/schema/element-palette-measurements.md`).
+  Colour carries the FAMILY; `ELEMENT_ICONS` carries the TYPE. Keyed on the v2 slug
+  union. First proven live in atlas and council, whose local copies become re-exports.
+  **`ELEMENT_FAMILIES` is GENERATED** from the `family:` key in keel's schema YAML
+  (keel `c69366b`, a keel presentation-wrapper key — not part of the council-governed
+  OnlyWorlds standard); hexes are hand-authored design constants beside it. Membership
+  and hex invariants test-gated (`test/palette.test.mjs`); light hexes render-proven on
+  the ruled OnlyWorlds light mode (ow-house-light) 2026-07-23.
+- **Codegen drift guard**: `python codegen/generate_types.py --check` fails if
+  `types.generated.ts` doesn't match the schema YAMLs (release gate; mirrors keel's
+  schema CI job). Codegen also hard-fails on missing/invalid `family:` keys — the
+  canary for a canonical-refresh that overwrote keel's wrapper layer.
+- **CI**: GitHub Action building + running the full suite against the compiled bundle.
+- **AGENTS.md** shipped in the tarball — usage guide for AI agents reading the package
+  locally, including the SDK-vs-MCP division of labor and the wire gotchas.
+- README: worked create→link→read-back round-trip, schema-verified field by field
+  (also fixes the old example patching `'character'` with a location's id); canonical
+  colour section; SDK-vs-MCP guidance.
+- This CHANGELOG.
+
+### Fixed
+- `FieldType` union now includes `'number'` — the legacy alias that 70 `FIELD_SCHEMA`
+  entries actually carry (consumers switch on it; data normalization deferred to 4.0).
+- `generate_types.py` exits with a clear message when the sibling keel checkout is
+  absent instead of a bare traceback.
+
+## [3.0.0] — 2026-07-18
+
+- v2-native client (`OwV2Client`) absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
+  wire-corrected against live staging fixtures (S22). Generated element types from the
+  canonical keel schema YAML (`src/v2/types.generated.ts`), validated against all 1,086
+  live W11 elements. v1 surface unchanged and frozen.

package/README.md

@@ -33,17 +33,28 @@ for await (const character of client.listAll('character')) {
   // ...
 }
 
-// Create -- id is minted client-side when omitted (retries stay idempotent)
+// A worked round-trip: two elements, linked, read back. Byte-true v2 dialect:
+// link fields use ONE bare name both directions (no _ids suffix — that's v1),
+// and you NEVER send a "world" field (identity comes from the key; sending it 422s).
 const location = await client.create('location', {
   name: 'Dragon Peak',
   description: 'A treacherous mountain peak where dragons nest',
+}); // id minted client-side when omitted (retries stay idempotent)
+
+const dragon = await client.create('creature', {
+  name: 'Vorrath the Ember-Scaled',
+  location: location.id,            // single link: UUID (or null)
 });
 
-// Partial update (arrays replace wholesale -- for links prefer editLinks)
-await client.patch('character', location.id, { name: 'Updated Name' });
+const fetched = await client.get('creature', dragon.id);
+// fetched.location === location.id — reads the way it writes
+
+// Partial update (PATCH is destructive on sent fields; arrays replace wholesale)
+await client.patch('location', location.id, { supertype: 'Mountain' });
 
-// Atomic link merge -- returns the full updated element
-await client.editLinks('event', eventId, 'objects', { add: [swordId], remove: [] });
+// For relationships, prefer the atomic link merge -- returns the full updated element
+const fireBreath = await client.create('ability', { name: 'Ember Breath' });
+await client.editLinks('creature', dragon.id, 'abilities', { add: [fireBreath.id], remove: [] });
 
 // Bulk write (up to ~1000; partial success by default, atomic:true for all-or-nothing)
 const res = await client.bulk([
@@ -59,10 +70,22 @@ for await (const change of client.changesAll(cursor)) {
 }
 ```
 
-### AI-assistant access (MCP)
+### Canonical element colours
+
+```typescript
+import { elementColor, ELEMENT_FAMILIES, FAMILY_COLORS } from '@onlyworlds/sdk';
+
+elementColor('character', 'dark');  // '#3987e5' — colour carries the FAMILY
+// (agents / world / abstract / temporal); ELEMENT_ICONS carries the TYPE.
+// CVD-validated: always pair colour with icon + label, never colour alone.
+```
+
+### AI-assistant access (MCP) — and when to use which
 
 An MCP server exists at `https://www.onlyworlds.com/mcp` for AI assistants (Claude and other MCP clients) to read and write worlds directly -- no SDK code required. See the [docs](https://onlyworlds.github.io) for setup.
 
+Division of labor: for **known, deterministic operations** (CRUD, sync, bulk) use this SDK — typed calls, no tool-schema overhead. For **live exploration of a user's world from a chat/agent context**, use the MCP server. Agents: see `AGENTS.md` in this package.
+
 ## Legacy: v1 client (`OnlyWorldsClient`)
 
 The v1 resource-style client remains fully supported and served forever. Prefer `OwV2Client` for new code.

package/dist/index.d.mts

@@ -907,7 +907,7 @@ declare const ELEMENT_ICONS: Record<ElementType$1, string>;
 /**
  * Field type definitions for OnlyWorlds elements
  */
-type FieldType = 'text' | 'integer' | 'integer_max' | 'single_link' | 'multi_link';
+type FieldType = 'text' | 'integer' | 'integer_max' | 'number' | 'single_link' | 'multi_link';
 /**
  * Field metadata structure
  */
@@ -3146,6 +3146,12 @@ interface OwElementBase {
 }
 type ElementType = 'ability' | 'character' | 'collective' | 'construct' | 'creature' | 'event' | 'family' | 'institution' | 'language' | 'law' | 'location' | 'map' | 'marker' | 'narrative' | 'object' | 'phenomenon' | 'pin' | 'relation' | 'species' | 'title' | 'trait' | 'zone';
 declare const ELEMENT_TYPES: ElementType[];
+/** The four semantic families (colour carries the family; ELEMENT_ICONS carries the type). */
+type ElementFamily = 'agents' | 'world' | 'abstract' | 'temporal';
+/** Per-type semantic family. Source: keel's PRESENTATION-WRAPPER schema key `family:`
+ *  (first-party rendering metadata, keel-only — NOT part of the council-governed
+ *  OnlyWorlds standard; see keel/schema-pipeline.md "The wrapper layer"). */
+declare const ELEMENT_FAMILIES: Record<ElementType, ElementFamily>;
 
 /**
  * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
@@ -3458,4 +3464,54 @@ declare class OwV2Client {
     private request;
 }
 
-export { type Ability, type AbilityInput, type AccessKeyResponse, type AnyElementId, type ApiResponse, type BaseElement, type Character, type CharacterInput, type Collective, type CollectiveInput, type Construct, type ConstructInput, type Creature, type CreatureInput, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementId, type ElementIds, ElementType$1 as ElementType, type EncryptionInfo, type Event, type EventInput, FIELD_SCHEMA, type Family, type FamilyInput, type FieldInfo, type FieldType, GameTier, type Institution, type InstitutionInput, type Language, type LanguageInput, type Law, type LawInput, type ListOptions, type ListParams, type Location, type LocationInput, type Map, type MapInput, type Marker, type MarkerInput, type Narrative, type NarrativeInput, ONLYWORLDS_VERSION, type Object$1 as Object, type ObjectInput, OnlyWorldsClient, type OnlyWorldsConfig, OwApiError, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwChange, type OwChangesPage, type OwClientConfig, type OwElement, type OwElementBase, type OwErrorBody, type OwKeyKind, type OwLinkEdit, OwNetworkError, type OwPage, OwV2Client, type OwWorldMeta, type Phenomenon, type PhenomenonInput, type Pin, type PinInput, type Relation, type RelationInput, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type Species, type SpeciesInput, type Title, type TitleInput, type TokenConsumeParams, type TokenConsumeResponse, type TokenStatus, type Trait, type TraitInput, type ElementType as V2ElementType, type World, type WorldInput, type Zone, type ZoneInput, createAnyElementId, createElementId, createElementIds, detectKeyKind, errorFromResponse, getElementIcon, getElementLabel, getElementSections, isDemoKey, kindCanWrite, parseEnvelope, pinExpectation };
+/**
+ * Canonical element colour palette — four semantic families.
+ *
+ * Ruled by Captain 2026-07-22 after Skeld's measurement pass (Orrery
+ * `product/schema/element-palette-measurements.md`): 22 mutually-separable
+ * hues is structurally impossible; four families is the ceiling that passes
+ * all-pairs CVD separation in both modes. **Colour carries the FAMILY; the
+ * icon (`ELEMENT_ICONS`) carries the TYPE.** Dark-mode pairs land in the 6–8
+ * CVD floor band, so secondary encoding (icon + label) is REQUIRED alongside
+ * colour, not optional.
+ *
+ * The type→family map is GENERATED: `ELEMENT_FAMILIES` is emitted by
+ * `codegen/generate_types.py` from the `family:` key in keel's schema YAML
+ * (added 2026-07-23, keel c69366b) — a keel PRESENTATION-WRAPPER key
+ * (first-party rendering metadata, not part of the council-governed
+ * OnlyWorlds standard). It cannot drift from the schema; membership and hex
+ * invariants stay test-gated in `test/palette.test.mjs`.
+ *
+ * The hexes below are design constants, hand-authored beside the generated
+ * map. Do not change any value without re-running the CVD validation (every
+ * brighter World green collides with Temporal amber for protan viewers — the
+ * green is pinned BY the accessibility budget).
+ *
+ * Provenance: first proven live in atlas (`src/core/element-colors.ts`) and
+ * council (`src/cosmos/element-families.ts`) — both become re-exports of this
+ * module.
+ */
+
+/**
+ * Family → validated hex per surface mode. `light` assumes near-white
+ * surfaces, `dark` assumes near-black (measured against #0a0a0a).
+ * World green is identical in both modes and sits at its low-contrast end
+ * deliberately — see module header before "fixing" it.
+ */
+declare const FAMILY_COLORS: Record<ElementFamily, {
+    light: string;
+    dark: string;
+}>;
+/** Semantic family for an element type slug. */
+declare function familyOf(type: ElementType): ElementFamily;
+/**
+ * The convenience most callers want: canonical colour for an element type.
+ * Name matches the live atlas/council implementations so their SDK swap is a
+ * re-export, not a rename. Defaults to `dark` (both current consumers are
+ * dark-surface).
+ */
+declare function elementColor(type: ElementType, mode?: 'light' | 'dark'): string;
+/** All four families, in ruling order (the order IS the CVD-safety mechanism of the source palette). */
+declare const FAMILY_ORDER: readonly ElementFamily[];
+
+export { type Ability, type AbilityInput, type AccessKeyResponse, type AnyElementId, type ApiResponse, type BaseElement, type Character, type CharacterInput, type Collective, type CollectiveInput, type Construct, type ConstructInput, type Creature, type CreatureInput, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementId, type ElementIds, ElementType$1 as ElementType, type EncryptionInfo, type Event, type EventInput, FAMILY_COLORS, FAMILY_ORDER, FIELD_SCHEMA, type Family, type FamilyInput, type FieldInfo, type FieldType, GameTier, type Institution, type InstitutionInput, type Language, type LanguageInput, type Law, type LawInput, type ListOptions, type ListParams, type Location, type LocationInput, type Map, type MapInput, type Marker, type MarkerInput, type Narrative, type NarrativeInput, ONLYWORLDS_VERSION, type Object$1 as Object, type ObjectInput, OnlyWorldsClient, type OnlyWorldsConfig, OwApiError, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwChange, type OwChangesPage, type OwClientConfig, type OwElement, type OwElementBase, type OwErrorBody, type OwKeyKind, type OwLinkEdit, OwNetworkError, type OwPage, OwV2Client, type OwWorldMeta, type Phenomenon, type PhenomenonInput, type Pin, type PinInput, type Relation, type RelationInput, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type Species, type SpeciesInput, type Title, type TitleInput, type TokenConsumeParams, type TokenConsumeResponse, type TokenStatus, type Trait, type TraitInput, type ElementType as V2ElementType, type World, type WorldInput, type Zone, type ZoneInput, createAnyElementId, createElementId, createElementIds, detectKeyKind, elementColor, errorFromResponse, familyOf, getElementIcon, getElementLabel, getElementSections, isDemoKey, kindCanWrite, parseEnvelope, pinExpectation };

package/dist/index.d.ts

@@ -907,7 +907,7 @@ declare const ELEMENT_ICONS: Record<ElementType$1, string>;
 /**
  * Field type definitions for OnlyWorlds elements
  */
-type FieldType = 'text' | 'integer' | 'integer_max' | 'single_link' | 'multi_link';
+type FieldType = 'text' | 'integer' | 'integer_max' | 'number' | 'single_link' | 'multi_link';
 /**
  * Field metadata structure
  */
@@ -3146,6 +3146,12 @@ interface OwElementBase {
 }
 type ElementType = 'ability' | 'character' | 'collective' | 'construct' | 'creature' | 'event' | 'family' | 'institution' | 'language' | 'law' | 'location' | 'map' | 'marker' | 'narrative' | 'object' | 'phenomenon' | 'pin' | 'relation' | 'species' | 'title' | 'trait' | 'zone';
 declare const ELEMENT_TYPES: ElementType[];
+/** The four semantic families (colour carries the family; ELEMENT_ICONS carries the type). */
+type ElementFamily = 'agents' | 'world' | 'abstract' | 'temporal';
+/** Per-type semantic family. Source: keel's PRESENTATION-WRAPPER schema key `family:`
+ *  (first-party rendering metadata, keel-only — NOT part of the council-governed
+ *  OnlyWorlds standard; see keel/schema-pipeline.md "The wrapper layer"). */
+declare const ELEMENT_FAMILIES: Record<ElementType, ElementFamily>;
 
 /**
  * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
@@ -3458,4 +3464,54 @@ declare class OwV2Client {
     private request;
 }
 
-export { type Ability, type AbilityInput, type AccessKeyResponse, type AnyElementId, type ApiResponse, type BaseElement, type Character, type CharacterInput, type Collective, type CollectiveInput, type Construct, type ConstructInput, type Creature, type CreatureInput, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementId, type ElementIds, ElementType$1 as ElementType, type EncryptionInfo, type Event, type EventInput, FIELD_SCHEMA, type Family, type FamilyInput, type FieldInfo, type FieldType, GameTier, type Institution, type InstitutionInput, type Language, type LanguageInput, type Law, type LawInput, type ListOptions, type ListParams, type Location, type LocationInput, type Map, type MapInput, type Marker, type MarkerInput, type Narrative, type NarrativeInput, ONLYWORLDS_VERSION, type Object$1 as Object, type ObjectInput, OnlyWorldsClient, type OnlyWorldsConfig, OwApiError, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwChange, type OwChangesPage, type OwClientConfig, type OwElement, type OwElementBase, type OwErrorBody, type OwKeyKind, type OwLinkEdit, OwNetworkError, type OwPage, OwV2Client, type OwWorldMeta, type Phenomenon, type PhenomenonInput, type Pin, type PinInput, type Relation, type RelationInput, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type Species, type SpeciesInput, type Title, type TitleInput, type TokenConsumeParams, type TokenConsumeResponse, type TokenStatus, type Trait, type TraitInput, type ElementType as V2ElementType, type World, type WorldInput, type Zone, type ZoneInput, createAnyElementId, createElementId, createElementIds, detectKeyKind, errorFromResponse, getElementIcon, getElementLabel, getElementSections, isDemoKey, kindCanWrite, parseEnvelope, pinExpectation };
+/**
+ * Canonical element colour palette — four semantic families.
+ *
+ * Ruled by Captain 2026-07-22 after Skeld's measurement pass (Orrery
+ * `product/schema/element-palette-measurements.md`): 22 mutually-separable
+ * hues is structurally impossible; four families is the ceiling that passes
+ * all-pairs CVD separation in both modes. **Colour carries the FAMILY; the
+ * icon (`ELEMENT_ICONS`) carries the TYPE.** Dark-mode pairs land in the 6–8
+ * CVD floor band, so secondary encoding (icon + label) is REQUIRED alongside
+ * colour, not optional.
+ *
+ * The type→family map is GENERATED: `ELEMENT_FAMILIES` is emitted by
+ * `codegen/generate_types.py` from the `family:` key in keel's schema YAML
+ * (added 2026-07-23, keel c69366b) — a keel PRESENTATION-WRAPPER key
+ * (first-party rendering metadata, not part of the council-governed
+ * OnlyWorlds standard). It cannot drift from the schema; membership and hex
+ * invariants stay test-gated in `test/palette.test.mjs`.
+ *
+ * The hexes below are design constants, hand-authored beside the generated
+ * map. Do not change any value without re-running the CVD validation (every
+ * brighter World green collides with Temporal amber for protan viewers — the
+ * green is pinned BY the accessibility budget).
+ *
+ * Provenance: first proven live in atlas (`src/core/element-colors.ts`) and
+ * council (`src/cosmos/element-families.ts`) — both become re-exports of this
+ * module.
+ */
+
+/**
+ * Family → validated hex per surface mode. `light` assumes near-white
+ * surfaces, `dark` assumes near-black (measured against #0a0a0a).
+ * World green is identical in both modes and sits at its low-contrast end
+ * deliberately — see module header before "fixing" it.
+ */
+declare const FAMILY_COLORS: Record<ElementFamily, {
+    light: string;
+    dark: string;
+}>;
+/** Semantic family for an element type slug. */
+declare function familyOf(type: ElementType): ElementFamily;
+/**
+ * The convenience most callers want: canonical colour for an element type.
+ * Name matches the live atlas/council implementations so their SDK swap is a
+ * re-export, not a rename. Defaults to `dark` (both current consumers are
+ * dark-surface).
+ */
+declare function elementColor(type: ElementType, mode?: 'light' | 'dark'): string;
+/** All four families, in ruling order (the order IS the CVD-safety mechanism of the source palette). */
+declare const FAMILY_ORDER: readonly ElementFamily[];
+
+export { type Ability, type AbilityInput, type AccessKeyResponse, type AnyElementId, type ApiResponse, type BaseElement, type Character, type CharacterInput, type Collective, type CollectiveInput, type Construct, type ConstructInput, type Creature, type CreatureInput, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementId, type ElementIds, ElementType$1 as ElementType, type EncryptionInfo, type Event, type EventInput, FAMILY_COLORS, FAMILY_ORDER, FIELD_SCHEMA, type Family, type FamilyInput, type FieldInfo, type FieldType, GameTier, type Institution, type InstitutionInput, type Language, type LanguageInput, type Law, type LawInput, type ListOptions, type ListParams, type Location, type LocationInput, type Map, type MapInput, type Marker, type MarkerInput, type Narrative, type NarrativeInput, ONLYWORLDS_VERSION, type Object$1 as Object, type ObjectInput, OnlyWorldsClient, type OnlyWorldsConfig, OwApiError, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwChange, type OwChangesPage, type OwClientConfig, type OwElement, type OwElementBase, type OwErrorBody, type OwKeyKind, type OwLinkEdit, OwNetworkError, type OwPage, OwV2Client, type OwWorldMeta, type Phenomenon, type PhenomenonInput, type Pin, type PinInput, type Relation, type RelationInput, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type Species, type SpeciesInput, type Title, type TitleInput, type TokenConsumeParams, type TokenConsumeResponse, type TokenStatus, type Trait, type TraitInput, type ElementType as V2ElementType, type World, type WorldInput, type Zone, type ZoneInput, createAnyElementId, createElementId, createElementIds, detectKeyKind, elementColor, errorFromResponse, familyOf, getElementIcon, getElementLabel, getElementSections, isDemoKey, kindCanWrite, parseEnvelope, pinExpectation };

package/dist/index.js

@@ -20,11 +20,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ELEMENT_FAMILIES: () => ELEMENT_FAMILIES,
   ELEMENT_ICONS: () => ELEMENT_ICONS,
   ELEMENT_LABELS: () => ELEMENT_LABELS,
   ELEMENT_SECTIONS: () => ELEMENT_SECTIONS,
   ELEMENT_TYPES: () => ELEMENT_TYPES,
   ElementType: () => ElementType,
+  FAMILY_COLORS: () => FAMILY_COLORS,
+  FAMILY_ORDER: () => FAMILY_ORDER,
   FIELD_SCHEMA: () => FIELD_SCHEMA,
   GameTier: () => GameTier,
   ONLYWORLDS_VERSION: () => ONLYWORLDS_VERSION,
@@ -37,7 +40,9 @@ __export(index_exports, {
   createElementId: () => createElementId,
   createElementIds: () => createElementIds,
   detectKeyKind: () => detectKeyKind,
+  elementColor: () => elementColor,
   errorFromResponse: () => errorFromResponse,
+  familyOf: () => familyOf,
   getElementIcon: () => getElementIcon,
   getElementLabel: () => getElementLabel,
   getElementSections: () => getElementSections,
@@ -1550,16 +1555,58 @@ function buildQuery(params) {
 
 // src/v2/types.generated.ts
 var ELEMENT_TYPES = ["ability", "character", "collective", "construct", "creature", "event", "family", "institution", "language", "law", "location", "map", "marker", "narrative", "object", "phenomenon", "pin", "relation", "species", "title", "trait", "zone"];
+var ELEMENT_FAMILIES = {
+  ability: "abstract",
+  character: "agents",
+  collective: "agents",
+  construct: "world",
+  creature: "agents",
+  event: "temporal",
+  family: "agents",
+  institution: "agents",
+  language: "abstract",
+  law: "abstract",
+  location: "world",
+  map: "world",
+  marker: "world",
+  narrative: "temporal",
+  object: "world",
+  phenomenon: "temporal",
+  pin: "world",
+  relation: "temporal",
+  species: "agents",
+  title: "abstract",
+  trait: "abstract",
+  zone: "world"
+};
 
 // src/v2/types.ts
 var SPATIAL_TYPES = ["map", "pin", "marker", "zone"];
+
+// src/v2/palette.ts
+var FAMILY_COLORS = {
+  agents: { light: "#2a78d6", dark: "#3987e5" },
+  world: { light: "#008300", dark: "#008300" },
+  abstract: { light: "#e87ba4", dark: "#d55181" },
+  temporal: { light: "#eda100", dark: "#c98500" }
+};
+function familyOf(type) {
+  return ELEMENT_FAMILIES[type];
+}
+function elementColor(type, mode = "dark") {
+  return FAMILY_COLORS[ELEMENT_FAMILIES[type]][mode];
+}
+var FAMILY_ORDER = ["agents", "world", "abstract", "temporal"];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ELEMENT_FAMILIES,
   ELEMENT_ICONS,
   ELEMENT_LABELS,
   ELEMENT_SECTIONS,
   ELEMENT_TYPES,
   ElementType,
+  FAMILY_COLORS,
+  FAMILY_ORDER,
   FIELD_SCHEMA,
   GameTier,
   ONLYWORLDS_VERSION,
@@ -1572,7 +1619,9 @@ var SPATIAL_TYPES = ["map", "pin", "marker", "zone"];
   createElementId,
   createElementIds,
   detectKeyKind,
+  elementColor,
   errorFromResponse,
+  familyOf,
   getElementIcon,
   getElementLabel,
   getElementSections,

package/dist/index.mjs

@@ -1500,15 +1500,57 @@ function buildQuery(params) {
 
 // src/v2/types.generated.ts
 var ELEMENT_TYPES = ["ability", "character", "collective", "construct", "creature", "event", "family", "institution", "language", "law", "location", "map", "marker", "narrative", "object", "phenomenon", "pin", "relation", "species", "title", "trait", "zone"];
+var ELEMENT_FAMILIES = {
+  ability: "abstract",
+  character: "agents",
+  collective: "agents",
+  construct: "world",
+  creature: "agents",
+  event: "temporal",
+  family: "agents",
+  institution: "agents",
+  language: "abstract",
+  law: "abstract",
+  location: "world",
+  map: "world",
+  marker: "world",
+  narrative: "temporal",
+  object: "world",
+  phenomenon: "temporal",
+  pin: "world",
+  relation: "temporal",
+  species: "agents",
+  title: "abstract",
+  trait: "abstract",
+  zone: "world"
+};
 
 // src/v2/types.ts
 var SPATIAL_TYPES = ["map", "pin", "marker", "zone"];
+
+// src/v2/palette.ts
+var FAMILY_COLORS = {
+  agents: { light: "#2a78d6", dark: "#3987e5" },
+  world: { light: "#008300", dark: "#008300" },
+  abstract: { light: "#e87ba4", dark: "#d55181" },
+  temporal: { light: "#eda100", dark: "#c98500" }
+};
+function familyOf(type) {
+  return ELEMENT_FAMILIES[type];
+}
+function elementColor(type, mode = "dark") {
+  return FAMILY_COLORS[ELEMENT_FAMILIES[type]][mode];
+}
+var FAMILY_ORDER = ["agents", "world", "abstract", "temporal"];
 export {
+  ELEMENT_FAMILIES,
   ELEMENT_ICONS,
   ELEMENT_LABELS,
   ELEMENT_SECTIONS,
   ELEMENT_TYPES,
   ElementType,
+  FAMILY_COLORS,
+  FAMILY_ORDER,
   FIELD_SCHEMA,
   GameTier,
   ONLYWORLDS_VERSION,
@@ -1521,7 +1563,9 @@ export {
   createElementId,
   createElementIds,
   detectKeyKind,
+  elementColor,
   errorFromResponse,
+  familyOf,
   getElementIcon,
   getElementLabel,
   getElementSections,

package/package.json

@@ -1,19 +1,23 @@
 {
   "name": "@onlyworlds/sdk",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "AGENTS.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
     "pretest": "npm run build",
     "test": "node --test \"test/**/*.test.mjs\"",
+    "codegen": "python codegen/generate_types.py",
+    "codegen:check": "python codegen/generate_types.py --check",
     "prepublishOnly": "npm run build"
   },
   "keywords": [