@onlyworlds/sdk 4.7.0 → 4.7.2

package/AGENTS.md

@@ -1,6 +1,6 @@
 # For AI agents using @onlyworlds/sdk
 
-**Current as of**: SDK **4.x** · schema-dist **v0.30.1-dist.15** (canonical 00.30.01).
+**Current as of**: SDK **4.x** · schema-dist **v0.31.0-dist.18** (canonical 00.31.00).
 This line is asserted by `codegen:check` in CI — if the pin moves and this file is not
 re-read against it, the check fails rather than letting this document rot quietly.
 

package/CHANGELOG.md

@@ -1,10 +1,38 @@
 # Changelog
 
-All notable changes to `@onlyworlds/sdk`. Maintained from 3.1.0 onward (Kael, Assembly);
+All notable changes to `@onlyworlds/sdk`. Maintained from 3.1.0 onward;
 earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.7.2] — 2026-10-09
+
+### Changed
+- **README first run** finds Admiral Fluffington by name (the demo world's default list order moves with every edit, so "the first three" could not be promised); the npm page shows the corrected output.
+- **Schema repinned `v0.30.2-dist.16` → `v0.31.0-dist.18`** (canonical **00.31.00**).
+  `ONLYWORLDS_VERSION` is now `'00.31.00'`. The World gains three optional free-text settings,
+  `length_unit`, `mass_unit` and `distance_unit`; the nine element fields that promised "world
+  LENGTH / MASS / DISTANCE units" now name them in their descriptions (Ability `range`, Character
+  and Creature `height` and `weight`, Creature `speed`, Location `elevation`, Object and Species
+  `weight`). No element field shape and no `FIELD_SCHEMA` entry changed. The world body is not
+  typed per field (`OwWorldMeta` is open), so `getWorld` returns the three keys and `patchWorld`
+  sends them with no code change; a test says so.
+
+## [4.7.1] — 2026-10-08
+
+### Changed
+- **README rewritten**: install, a first run against the public demo world (its output shown,
+  run as written), your own world with an agent seat for writes, then the reference. It no
+  longer calls a `world` field in a payload an error: the API ignores it.
+- Comments, the RFC and pin-file prose no longer name people or internal places.
+- **Schema repinned `v0.30.1-dist.15` → `v0.30.2-dist.16`** (canonical **00.30.02**).
+  `ONLYWORLDS_VERSION` is now `'00.30.02'`. Field descriptions move with the schema: Location's
+  `rivalries` and `partnerships`, Marker's `order`, and Pin's `element` pair. No field shape and
+  no `FIELD_SCHEMA` entry changed: canonical now requires only `name` on every type, which is
+  what `FIELD_SCHEMA` already said, so its hand-made exception for the old Pin and Marker
+  lists is gone. If the schema lists more than `name` again, codegen stops and asks for a
+  ruling instead of dropping the list. 31/31 file hashes recomputed from the tag.
+
 ## [4.7.0] — 2026-10-08
 
 ### Added
@@ -36,7 +64,7 @@ Includes 4.5.1's documentation fixes: 4.5.1 was staged and never published.
   refusals (`ticket_used`, `ticket_expired`, `bad_key`, `exists`, `unsupported_type`, ...) arrive
   as `OwApiError` with their code. Set the returned `url` as an element's `image_url` yourself.
   Checked live on 2026-10-06: one upload through keel's ticket to the edge (201), and the same
-  ticket again refused with 401 `ticket_used` (Keel #59).
+  ticket again refused with 401 `ticket_used`.
 - **`createMediaTicket()`**: the first step alone, for callers that upload themselves (progress
   bars, say). Types `OwMediaTicket` and `OwUploadedImage`.
 
@@ -51,11 +79,11 @@ Docs only: no code path changes.
 ### Documented
 - **`isOwnerOnly`'s JSDoc in 4.5.0 was wrong about who sees `owner_only`.** It said owners and
   co-builders never see it. A member key, a co-builder's too, gets it on `PATCH /world`; only the
-  owner's key is exempt (keel spec section 9; confirmed from keel's `patch_world` by Skeld,
+  owner's key is exempt (keel spec section 9; confirmed from keel's `patch_world`,
   2026-10-04).
 - **`world_gone` is reserved.** `OwAuthErrorCode` and `isAuthError` still carry it, but keel never
   emits it: a deleted world's keys are deleted with it, so the key answers 401 `invalid_credentials`
-  (Skeld, 2026-10-04; keel spec section 2, T6b). Found by the wire gate reading the SDK's own
+  (2026-10-04; keel spec section 2). Found by the wire gate reading the SDK's own
   built file for the codes it keys on.
 
 ## [4.5.0] — 2026-10-04
@@ -66,7 +94,7 @@ three behaviours the server has always had that no client doc said. Additive; no
 ### Added
 - **`OwApiError.isOwnerOnly`**: 403 `owner_only`, a contributor attempting a world-level change
   (`patchWorld`, publishing a show page). Owners and co-builders never see it. keel's OpenAPI
-  document does not name the code yet (Skeld has that to close); the wire returns it.
+  document does not name the code yet (the schema side has that to close); the wire returns it.
 
 ### Documented
 - **An atomic `/bulk` rollback still returns 201 slots** for the items that would have
@@ -95,10 +123,10 @@ contributor meets on someone else's. Additive; nothing is removed or narrows.
 ### Fixed
 - **`FIELD_SCHEMA` no longer marks `marker.map/zone/x/y/order` and `pin.map/element_type/element_id/x/y`
   as `required: true`.** The wire requires `name` and nothing else (rulings.yaml `nullable-by-default`,
-  Captain 2026-07-28; keel's OpenAPI write schemas say `required: [name]`), but the schema files still
+  ruling 2026-07-28; keel's OpenAPI write schemas say `required: [name]`), but the schema files still
   list those fields and the generator copied the lists, so a form built from the table demanded
   coordinates the server never did. Found by comparing the SDK with keel's OpenAPI document (the
-  new `verify-sdk-wire` gate in Assembly). **If you read `required` from this table, marker and pin
+  new `verify-sdk-wire` gate). **If you read `required` from this table, marker and pin
   fields now read as optional**, which is what the server accepts. The generator notes the lists it
   ignores on every run and says when canonical stops carrying them.
 
@@ -146,7 +174,7 @@ Ids, honest filter docs, and the schema repin. Nothing is removed; no call needs
   order elements by id. For creation order use `created_at`; `change_seq` is last-write
   order. This is a **default, not a
   requirement**: a v4 or v7 id a caller supplies is still accepted as-is, and
-  every id already stored stays valid. Keel mints v7 server-side too (Captain's ruling,
+  every id already stored stays valid. Keel mints v7 server-side too (ruling,
   2026-09-28). Pinned by six tests: version and variant, the big-endian timestamp above
   bit 32, fractional and pre-1970 clocks floored consistently, creation order across 50
   consecutive milliseconds, 1,000 distinct ids inside one millisecond, and the no-`crypto`
@@ -156,7 +184,7 @@ Ids, honest filter docs, and the schema repin. Nothing is removed; no call needs
   edges, and keel's `uuid7()` agrees on timestamp, version and variant for a pinned clock.
 - **`elementColor()` on an unknown type now throws a `TypeError` that names the type.** It
   used to crash with `Cannot read properties of undefined (reading 'dark')`. Found while
-  building the Forge's colour gate: atlas's own copy falls back to the `world` family for an
+  building a colour gate: atlas's own copy falls back to the `world` family for an
   unknown type, so swapping it for this export is not a pure re-export for that input, and the
   docstring now says so. Whether the package should fall back is left to its consumers.
 - The generated field-schema comment no longer calls `maximum:` an open question or counts
@@ -303,7 +331,7 @@ pinned consumers.
 ### Added (post-alpha.0, same night)
 - **`ELEMENT_ICONS` GENERATED** from keel's `icon:` wrapper key (keel `56c124a`).
 - **`ELEMENT_SECTIONS` DERIVED** from the canonical schema's own document structure
-  (Skeld's ruling: sections are the standard tier's property groups; document order is
+  (ruling: sections are the standard tier's property groups; document order is
   display order). Divergence check vs the old hand table found and fixed three fossils:
   creature "Behaviour"→"Behavior", pin's triple-listed generic link → `element`,
   relation "Involves" listing a nonexistent `relations` field. Canonical is truth.
@@ -312,18 +340,18 @@ pinned consumers.
   covered by the codegen drift guard. AGENTS.md points agents at it first.
 - **`OwV2Client.request()` is public** (typed escape hatch; does not sanitize) and
   structurally satisfies `TokenTransport` — `new TokenResource(client)` just works.
-  Token ruling (Skeld): keel keeps `/tokens/*` long-term; ported, not deleted.
+  Token ruling: keel keeps `/tokens/*` long-term; ported, not deleted.
 - README rewritten v2-native (v1 sections, branded types, and the encrypted-key
   walkthrough removed; bulk partial-failure and idempotency-key hygiene promoted).
 
-### alpha.1 — consumer-pin fixes (Temper's atlas review, same night)
+### alpha.1 — consumer-pin fixes (atlas review, same night)
 - **`parseEnvelope` → `parseErrorEnvelope`** (it parses the platform *error* envelope;
   renamed before the 4.0 name freeze to avoid collision with the world-export envelope).
 - The never-whitelist LAW now lives as a comment on `READ_ONLY_FIELDS` itself.
 - Stale v1 example in the shipped d.ts fixed (TokenResource JSDoc).
 
 ### Release gates — ALL GREEN (2026-07-23 night)
-- **Gate 3 (wire-log v1-traffic query, Skeld)**: GREEN — no unknown v1-SDK consumer on
+- **Gate 3 (wire-log v1-traffic query)**: GREEN — no unknown v1-SDK consumer on
   the wire; observed v1 traffic is pinned deployed builds (council proxy, legacy plugin
   walks) that an npm major cannot touch. The v1 API dialect stays served regardless.
 - **`/api/v2/tokens/` live on prod + staging** (keel `e181689`; three-base byte
@@ -331,7 +359,7 @@ pinned consumers.
   "older server", not "no tokens". Requirement noted in the migration guide.
 - **`ONLYWORLDS_VERSION` now GENERATED** from canonical's `VERSION` file (carried
   into keel `schema/` by the refresh script, keel `492168c`) — the last hand-synced
-  constant is dead. Consumer soak: Temper pinned the alpha against atlas's full
+  constant is dead. Consumer soak: the atlas app pinned the alpha against its full
   static surface — strict-clean compile, correct runtime, package shape approved.
 - **No `npm deprecate` on 3.x** (landscape research; 3.x stays plainly supported).
 - 4.x wishlist: account client (list/mint/create — atlas first consumer), world-export
@@ -345,7 +373,7 @@ pinned consumers.
   `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`).
+  CVD-validated measurement.
   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
@@ -373,7 +401,7 @@ pinned consumers.
 
 ## [3.0.0] — 2026-07-18
 
-- v2-native client (`OwV2Client`) absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
+- v2-native client (`OwV2Client`) absorbed from an earlier v2 client (ow-v2-client v0.9.0),
   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

@@ -3,74 +3,77 @@
 [![npm version](https://badge.fury.io/js/@onlyworlds%2Fsdk.svg)](https://www.npmjs.com/package/@onlyworlds/sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-The canonical typed client for the [OnlyWorlds](https://onlyworlds.github.io) v2 API, plus the
-canonical constants (element types, icons, colour families, field schema) — generated from the
-canonical OnlyWorlds schema, obtained through the public
-[schema distribution](https://github.com/OnlyWorlds/schema-dist) at a pinned, hash-verified
-tag. The generated files carry that tag and commit in their header, so what these types were
-built from is checkable rather than asserted.
+OnlyWorlds is an open standard for worldbuilding data: 22 element types (characters, locations, events, laws and the rest) that any tool can read and write. This is a typed client for its API, with the schema's constants (element types, icons, colour families, field metadata) generated from the published [schema distribution](https://github.com/OnlyWorlds/schema-dist). It runs in Node 18+ and in the browser through a bundler (ESM only).
 
-**4.x is v2-native and ESM-only (Node 18+).** If you need the legacy v1 API dialect
-(`OnlyWorldsClient`) or CommonJS `require()`, stay on 3.x — it remains published and the v1 API
-remains served. See [docs/migrating-3-to-4.md](docs/migrating-3-to-4.md).
-
-## Installation
+## Install
 
 ```bash
 npm install @onlyworlds/sdk
 ```
 
-## Quick Start
+## First run
+
+Moppetopia is a public demo world. Its read-only key, `0000000001`, needs no account:
 
 ```typescript
 import { OwV2Client } from '@onlyworlds/sdk';
 
-const client = new OwV2Client({ apiKey: 'ow_r_your_key' }); // read-only key: that's all you need
-const page = await client.list('character');                 // { data, has_more, next_cursor }
+const client = new OwV2Client({ apiKey: '0000000001' });
+console.log((await client.getWorld()).name);
+const { data } = await client.list('character', { filter: { name__icontains: 'fluffington' } });
+for (const c of data) console.log(' ', c.name);
+```
+
+```
+Moppetopia
+  Admiral Fluffington
 ```
 
-Key kinds: `ow_w_` write / `ow_r_` read-only (no PIN — the "give this to your players" key) /
-`ow_a_` account Bearer / 10-digit legacy. Writes on a PIN-protected world also pass `apiPin`.
-Demo keys `0000000000`–`0000000009` read real sample worlds.
+## Your own world
 
-## The full round-trip
+Create a world at [onlyworlds.com](https://www.onlyworlds.com); its keys are on the world's page. A new key is shown once, so copy it then.
+
+- An `ow_r_` key reads, with no PIN. It is the key to give to players or a public site.
+- An `ow_w_` key reads and writes. Writes also send a PIN as `apiPin`.
+- Anyone who loads a web page can read the keys in its code. Ship only an `ow_r_` key to a browser, and keep write keys and seat secrets on a server.
+- For code that writes, give it its own [agent seat](https://onlyworlds.github.io/docs/development/agents), a key for one tool or script. The seat's key and its `ow_s_` secret (sent as `apiPin`) work in one world, and you can remove them without touching your account PIN.
 
 ```typescript
-const writer = new OwV2Client({ apiKey: 'ow_w_your_key', apiPin: '1234' });
+const writer = new OwV2Client({ apiKey: 'ow_w_…', apiPin: 'ow_s_…' });
+```
+
+## Reading and writing
 
-// v2 dialect rules, worth internalizing once:
-// - link fields use ONE bare name both directions (no _ids suffix — that's v1)
-// - NEVER send a "world" field (identity comes from the key; the client strips it anyway)
+```typescript
 const location = await writer.create('location', {
   name: 'Dragon Peak',
-  description: 'A treacherous mountain peak where dragons nest',
-}); // id minted client-side when omitted (retries stay idempotent)
-// name is the one required field, and required means the key is present:
-// '' and null are accepted and stored as '' (nameless Markers exist).
+  description: 'A mountain peak where dragons nest',
+}); // the id is minted client-side when omitted, so a retry creates nothing twice
 
 const dragon = await writer.create('creature', {
   name: 'Vorrath the Ember-Scaled',
-  location: location.id,            // single link: UUID (or null)
+  location: location.id, // a single link: a UUID or null
 });
 
 const fetched = await writer.get('creature', dragon.id);
-// fetched.location === location.id — reads the way it writes
+// fetched.location === location.id: a field reads the way it writes
 
-// PATCH is destructive on sent fields; arrays replace wholesale
+// PATCH replaces the fields it sends; an array is replaced whole
 await writer.patch('location', location.id, { supertype: 'Mountain' });
 
-// For relationships, use the atomic link merge — returns the full updated element
-const fireBreath = await writer.create('ability', { name: 'Ember Breath' });
-await writer.editLinks('creature', dragon.id, 'abilities', { add: [fireBreath.id], remove: [] });
+// For links, the atomic merge; it returns the updated element
+const breath = await writer.create('ability', { name: 'Ember Breath' });
+await writer.editLinks('creature', dragon.id, 'abilities', { add: [breath.id], remove: [] });
 
-// Walk every page of a type
+// Every page of a type
 for await (const character of writer.listAll('character')) { /* ... */ }
 ```
 
-## Bulk writes — always check `errors`
+A link field has one name in both directions (`location`, not `location_id`). Only `name` is required, and an empty name is stored as `''`. A `world` field in a payload is ignored: the key decides the world, and the client strips it anyway.
+
+## Bulk writes
 
-`/bulk` **succeeds partially by default** (HTTP 200 with per-slot statuses). The one mistake to
-never make: treating a 200 as "everything landed."
+`/bulk` answers 200 even when some items fail, so check `errors`:
 
 ```typescript
 const res = await writer.bulk(
@@ -78,87 +81,80 @@ const res = await writer.bulk(
     { type: 'character', element: { name: 'A' } },
     { type: 'event', element: { name: 'B' } },
   ],
-  { idempotencyKey: crypto.randomUUID() }, // mint FRESH per attempt — a failed batch is
-);                                          // cached under its key; never reuse across retries
+  { idempotencyKey: crypto.randomUUID() }, // a new key per attempt: a failed batch is cached under its key
+);
 if (res.errors) {
   for (const slot of res.items.filter((s) => s.status >= 400)) {
     console.warn(slot.error?.code, slot.error?.message, slot.error?.doc_url);
   }
 }
-// Pass { atomic: true } for all-or-nothing instead. res.wasReplay flags idempotent replays.
-// After a failed atomic batch NOTHING was written, but the slots that would have succeeded
-// still say 201 (keel's counterfactual 201s): do not record those ids as created.
 ```
 
+Pass `{ atomic: true }` for all or nothing. After a failed atomic batch nothing was written, but the slots that would have succeeded still read 201: don't record those ids as created. `res.wasReplay` marks an idempotent replay.
+
 ## Images
 
 ```typescript
-const image = await writer.uploadImage(file);             // a Blob, File, ArrayBuffer or Uint8Array
+const image = await writer.uploadImage(file); // a Blob, File, ArrayBuffer or Uint8Array
 await writer.patch('character', id, { image_url: image.url });
 ```
 
-Two requests: a single-use ticket from keel, then the bytes straight to the edge (keel never
-sees them, and the edge never sees your key). webp, png, jpeg or avif (never SVG or gif), read from the
-bytes. Each ticket counts toward the world's daily limit and the account's image
-storage. To upload yourself (for a progress bar), take `createMediaTicket()` and POST the bytes to
-its `upload_url` with `Authorization: Bearer <ticket>`.
+The SDK asks the API for a single-use ticket, then sends the bytes straight to the upload host, which never sees your key. webp, png, jpeg or avif (no SVG or gif), up to 15 MB. Each upload counts toward the world's daily limit and the account's storage. To upload yourself (for a progress bar), call `createMediaTicket()` and POST the bytes to its `upload_url` with `Authorization: Bearer <ticket>`.
 
 ## Sync
 
 ```typescript
-let cursor; // opaque, never expires; persist it
+let cursor; // opaque and never expires: keep it
 for await (const change of client.changesAll(cursor)) {
-  // ops arrive in (change_seq, id) order — apply in order → convergence
+  // changes arrive in order; apply them in order and you converge
 }
-// GOTCHA: world-meta edits (name, calendar, public_read) do NOT enter /changes.
-// Poll client.getWorld() and compare updated_at separately.
 ```
 
+Edits to the world itself (its name, calendar, `public_read`) don't appear in the change feed. Read `client.getWorld()` and compare `updated_at`.
+
 ## Errors
 
-Every non-2xx throws `OwApiError` carrying the platform envelope: `.status`, `.type`, `.code`,
-`.param` (the exact field that failed), and `.docUrl` — surface `docUrl` in your UX. Transport
-failures throw `OwNetworkError`. `err.isValidationError` is the common branch.
+Every non-2xx response throws `OwApiError` with the API's envelope: `.status`, `.type`, `.code`, `.param` (the field that failed) and `.docUrl`, which is worth showing to your users. A transport failure throws `OwNetworkError`. `err.isValidationError` covers the common case.
 
-## Canonical constants (all generated or test-gated from schema)
+## Schema constants
 
 ```typescript
 import {
-  ELEMENT_TYPES,        // the 22 slugs (and the ElementType union)
-  ELEMENT_ICONS,        // Material Symbols icon per type
-  ELEMENT_LABELS,       // plural display labels
-  ELEMENT_SECTIONS,     // canonical field grouping + display order
-  FIELD_SCHEMA,         // per-field type/target metadata
-  elementColor,         // canonical colour: family carries COLOUR, icon carries TYPE
+  ELEMENT_TYPES,    // the 22 type slugs (and the ElementType union)
+  ELEMENT_ICONS,    // a Material Symbols icon per type
+  ELEMENT_LABELS,   // plural display labels
+  ELEMENT_SECTIONS, // field grouping and display order
+  FIELD_SCHEMA,     // per-field type and link target
+  elementColor,     // colour by family; the icon carries the type
 } from '@onlyworlds/sdk';
 
-elementColor('character', 'dark'); // '#3987e5' — four CVD-validated families
-// Always pair colour with icon + label; colour alone is not accessible.
+elementColor('character', 'dark'); // '#3987e5'
 ```
 
-The full schema with per-field meaning lives in [SCHEMA.md](SCHEMA.md) (generated, ships in this
-package). AI agents: read [AGENTS.md](AGENTS.md) first.
+The four colour families (agents, world, abstract, temporal) are checked for colour-blind separation. Show colour with the icon and label, never alone. [SCHEMA.md](SCHEMA.md) (generated, in the package) describes every field; AI agents should read [AGENTS.md](AGENTS.md) first.
+
+## Tokens
 
-## Token rating system
+The account's token allowance and ratings, which some OnlyWorlds tools use.
 
 ```typescript
 import { TokenResource } from '@onlyworlds/sdk';
-const tokens = new TokenResource(writer); // OwV2Client.request() satisfies TokenTransport
+const tokens = new TokenResource(writer);
 const status = await tokens.getStatus();
 ```
 
-## AI access — when to use which
+## SDK or MCP
 
-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 at `https://www.onlyworlds.com/mcp` (same `API-Key`/`API-Pin` headers, 12 tools;
-unaffected by SDK versioning).
+Use this SDK for known operations in your own code (CRUD, sync, bulk). To let an AI assistant that speaks MCP (the Model Context Protocol) explore a world in a chat, connect it to `https://www.onlyworlds.com/mcp` with the same key and PIN as `API-Key` and `API-Pin` headers.
 
-## License
+## Version 3 and the old API
 
-MIT
+4.x speaks the current (v2) API only. The v1 client (`OnlyWorldsClient`) and CommonJS `require()` stay on 3.x, which remains published and supported: see [the migration guide](docs/migrating-3-to-4.md).
 
 ## Links
 
-- [OnlyWorlds](https://www.onlyworlds.com) · [Docs](https://onlyworlds.github.io) · [API reference](https://www.onlyworlds.com/api/docs)
-- [Issues](https://github.com/OnlyWorlds/sdk/issues) · [CHANGELOG](CHANGELOG.md) · [Migration 3→4](docs/migrating-3-to-4.md)
+[Docs](https://onlyworlds.github.io/docs/development/typescript) · [Games](https://onlyworlds.github.io/docs/development/games) · [API reference](https://www.onlyworlds.com/api/docs) · [Issues](https://github.com/OnlyWorlds/sdk/issues) · [Changelog](CHANGELOG.md)
+
+## License
+
+MIT

package/SCHEMA.md

@@ -1,6 +1,6 @@
 # OnlyWorlds Schema Reference
 
-**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.30.1-dist.15** — canonical schema **00.30.01**, published 2026-09-18.
+**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.31.0-dist.18** — canonical schema **00.31.00**, published 2026-10-09.
 
 GENERATED from the canonical schema YAML — do not hand-edit (regenerate: `python codegen/generate_types.py`).
 Written for both humans and AI agents reading this package locally.
@@ -24,7 +24,7 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 - `activation` (text) — Method or conditions under which the ability is activated
 - `duration` (integer) — Length of time the ability remains active or its effects persist, measured in TIME units
 - `potency` (integer) — Relative measure of the ability's inherent potency or force, used for scaling or comparison purposes
-- `range` (integer) — Effective reach or distance at which the ability can be used, measured in DISTANCE units
+- `range` (integer) — Effective reach or distance at which the ability can be used, in the world's distance unit (World distance_unit)
 - `effects` (multi link → phenomenon) — Phenomena that result from the ability's use, such as environmental changes or sensory effects
 - `challenges` (text) — Describes specific difficulties or constraints that make the ability hard to master or use effectively
 - `talents` (multi link → trait) — Traits that naturally enhance or improve performance with this ability
@@ -47,8 +47,8 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 
 - `physicality` (text) — The character's visible physical features and body attributes
 - `mentality` (text) — The character's mindset, emotional tone, and style of thinking
-- `height` (integer) — The character's approximate or exact height, using world LENGTH units
-- `weight` (integer) — The character's approximate or exact weight, using world MASS units
+- `height` (integer) — The character's approximate or exact height, in the world's length unit (World length_unit)
+- `weight` (integer) — The character's approximate or exact weight, in the world's mass unit (World mass_unit)
 - `species` (multi link → species) — Species the character might belong to
 - `traits` (multi link → trait) — Traits for notable behavioral, physical, or systemic characteristics
 - `abilities` (multi link → ability) — Abilities the character might perform, control, or invoke
@@ -164,8 +164,8 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 ### Biology
 
 - `appearance` (text) — Visual description of the creature
-- `weight` (integer) — Approximate or exact weight of the creature, using world MASS units
-- `height` (integer) — Approximate height of the creature, using the world's defined LENGTH units
+- `weight` (integer) — Approximate or exact weight of the creature, in the world's mass unit (World mass_unit)
+- `height` (integer) — Approximate height of the creature, in the world's length unit (World length_unit)
 - `species` (multi link → species) — Species this creature belongs to
 
 ### Behavior
@@ -188,7 +188,7 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 - `challenge_rating` (integer) — Difficulty or threat level of the creature in a gameplay context
 - `hit_points` (integer) — Total health or durability value in combat
 - `armor_class` (integer) — Defense rating against physical attacks or effects
-- `speed` (integer) — Typical movement speed, measured in the world's DISTANCE unit per round
+- `speed` (integer) — Typical movement speed, in the world's distance unit (World distance_unit) per round
 - `actions` (multi link → ability) — Combat or tactical abilities the creature can perform or use
 
 
@@ -326,8 +326,8 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 - `governing_title` (single link → title) — Governing figure assigned by the location's primary power
 - `secondary_powers` (multi link → institution) — Institutions with significant political control
 - `zone` (single link → zone) — Zone of interest that is associated with the location
-- `rival` (single link → location) — Locations with active, traditional, or historical rivalries
-- `partner` (single link → location) — Locations with active, cooperative, or historical ties
+- `rival` (single link → location) — Location with an active, traditional, or historical rivalry with this one
+- `partner` (single link → location) — Location with active, cooperative, or historical ties to this one
 
 ### World
 
@@ -359,7 +359,7 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 ### Defense
 
 - `defensibility` (text) — Qualities of natural, constructed, and implemented defenses at the location
-- `elevation` (integer) — Height or elevation of the location relative to surrounding terrain, defined in world DISTANCE units
+- `elevation` (integer) — Height or elevation of the location relative to surrounding terrain, in the world's distance unit (World distance_unit)
 - `fighters` (multi link → construct) — Military units or forces responsible for defending the location
 - `defensive_objects` (multi link → object) — Objects or installations for defending the location
 
@@ -388,7 +388,7 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 - `x` (integer) — x coordinate, from bottom left of the map
 - `y` (integer) — y coordinate, from bottom left of the map
 - `z` (integer) — z coordinate, in case of depth
-- `order` (integer) — Sequence position when markers define a polygon or line (0 = first point)
+- `order` (integer) — Sequence position when markers define a polygon or line (0 = first point); without it, markers keep the order they were made in
 
 
 ## narrative  ·  family: temporal  ·  icon: menu_book
@@ -435,7 +435,7 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 ### Form
 
 - `aesthetics` (text) — Appearance, design, or visual presentation of the object
-- `weight` (integer) — Approximate or exact mass of the object, defined by world MASS units
+- `weight` (integer) — Approximate or exact mass of the object, in the world's mass unit (World mass_unit)
 - `amount` (integer) — The number of identical units in this object entry
 - `parent_object` (single link → object) — Larger object that this one is part of or contained within
 - `materials` (multi link → construct) — The physical matter that constitutes the object
@@ -482,7 +482,7 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 ### Details
 
 - `map` (single link → map) — Map that the pin is placed on
-- `element` (generic link (any element type)) — Link to any Element (managed by ContentType + UUID)
+- `element` (generic link (any element type)) — The element this pin places on the map, of any type
 - `x` (integer) — x coordinate, from bottom left of the map
 - `y` (integer) — y coordinate, from bottom left of the map
 - `z` (integer) — z coordinate, in case of depth (optional)
@@ -517,7 +517,6 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 - `families` (multi link → family) — Families relevant to the relation
 - `titles` (multi link → title) — Titles relevant to the relation
 - `constructs` (multi link → construct) — Concepts, contracts, or principles relevant to the relation
-- `events` (multi link → event) — Events where the relation is involved or relevant
 - `narratives` (multi link → narrative) — Narratives relevant to the relation
 
 
@@ -528,7 +527,7 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 
 - `appearance` (text) — Typical physical or form features of the species
 - `life_span` (integer) — Average or typical life expectancy of an individual, defined in world TIME units
-- `weight` (integer) — Average or typical adult weight, defined in world MASS units
+- `weight` (integer) — Average or typical adult weight, in the world's mass unit (World mass_unit)
 - `nourishment` (multi link → species) — Other species consumed as food sources
 - `reproduction` (multi link → construct) — Reproductive method(s) of the species
 - `adaptations` (multi link → ability) — Special physiological or evolutionary abilities

package/dist/index.d.ts

@@ -33,7 +33,7 @@ type ElementType = 'ability' | 'character' | 'collective' | 'construct' | 'creat
 declare const ELEMENT_TYPES: ElementType[];
 /** Canonical OnlyWorlds schema version. Source: the `canonical:` value of the pinned
  *  distribution's VERSION file (see the provenance block at the top of this file). */
-declare const ONLYWORLDS_VERSION: "00.30.01";
+declare const ONLYWORLDS_VERSION: "00.31.00";
 /** The four semantic families (colour carries the family; ELEMENT_ICONS carries the type). */
 type ElementFamily = 'agents' | 'world' | 'abstract' | 'temporal';
 /** Per-type semantic family. Source: the distribution's `presentation.json` sidecar
@@ -1844,7 +1844,7 @@ declare const FIELD_SCHEMA: {
 };
 
 /**
- * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
+ * keel v2 engine absorbed from an earlier v2 client (ow-v2-client v0.9.0),
  * wire-corrected against live staging fixtures 2026-07-18.
  *
  * OnlyWorlds v2 (keel) wire types -- the NON-generated, hand-owned wire shapes
@@ -2024,7 +2024,7 @@ interface OwClientConfig {
 }
 
 /**
- * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
+ * keel v2 engine absorbed from an earlier v2 client (ow-v2-client v0.9.0),
  * wire-corrected against live staging fixtures 2026-07-18.
  *
  * keel error envelope handling. The error contract is part of the contract:
@@ -2115,7 +2115,7 @@ declare function parseErrorEnvelope(status: number, body: unknown, retryAfter?:
 declare function errorFromResponse(res: Response): Promise<OwApiError>;
 
 /**
- * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
+ * keel v2 engine absorbed from an earlier v2 client (ow-v2-client v0.9.0),
  * wire-corrected against live staging fixtures 2026-07-18.
  *
  * OnlyWorlds key-kind detection. Prefixes make leaked keys grep-scannable
@@ -2143,7 +2143,7 @@ declare function kindCanWrite(kind: OwKeyKind): boolean;
 declare function pinExpectation(kind: OwKeyKind): 'never' | 'optional' | 'required-for-private-reads';
 
 /**
- * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
+ * keel v2 engine absorbed from an earlier v2 client (ow-v2-client v0.9.0),
  * wire-corrected against live staging fixtures 2026-07-18.
  *
  * OwV2Client -- thin typed fetch client for the keel v2 API.
@@ -2300,9 +2300,8 @@ declare class OwV2Client {
 /**
  * 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
+ * Ruled 2026-07-22 after a measurement pass: 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
@@ -2493,7 +2492,7 @@ declare enum GameTier {
 /**
  * Minimal transport the token resource needs — structurally satisfied by
  * `OwV2Client` (its `request()` is public since 4.0): `new TokenResource(client)`.
- * Wire ruling (Skeld 2026-07-23): keel keeps the /tokens/* economy long-term
+ * Wire ruling (2026-07-23): keel keeps the /tokens/* economy long-term
  * (Tangle ratings write it, Council voting reads it) — port, don't delete.
  */
 interface TokenTransport {

package/dist/index.js

@@ -433,7 +433,7 @@ 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 ONLYWORLDS_VERSION = "00.30.01";
+var ONLYWORLDS_VERSION = "00.31.00";
 var ELEMENT_FAMILIES = {
   ability: "abstract",
   character: "agents",
@@ -564,7 +564,7 @@ var ELEMENT_SECTIONS = {
   ],
   relation: [
     { name: "Nature", order: 1, fields: ["background", "start_date", "end_date", "intensity", "actor", "events"] },
-    { name: "Involves", order: 2, fields: ["characters", "objects", "locations", "species", "creatures", "institutions", "traits", "collectives", "zones", "abilities", "phenomena", "languages", "families", "titles", "constructs", "events", "narratives"] }
+    { name: "Involves", order: 2, fields: ["characters", "objects", "locations", "species", "creatures", "institutions", "traits", "collectives", "zones", "abilities", "phenomena", "languages", "families", "titles", "constructs", "narratives"] }
   ],
   species: [
     { name: "Biology", order: 1, fields: ["appearance", "life_span", "weight", "nourishment", "reproduction", "adaptations"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlyworlds/sdk",
-  "version": "4.7.0",
+  "version": "4.7.2",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {