From 54eb07849a1c1395d577c0a6d70b8731f0b2924b Mon Sep 17 00:00:00 2001 From: Titus Date: Wed, 28 Oct 2026 22:36:15 +0100 Subject: [PATCH 1/7] World graph: a sidebar section for reading a world as a graph A new section between Schema and Tools: an overview at /docs/world-graph (a world as typed elements and links, the three ways to read part of one, the ideas it sits beside), Lenses and A world as a graph at their old addresses, and a short concept page for the draught at /docs/world-graph/draught that links the route page, which keeps its address and content. The lens routes move to the API section at /docs/development/api/lenses; /docs/lenses/api stays a short page naming the routes and pointing there, and its links are re-pointed. The sidebar now runs Start, Schema, World graph, Tools, AI agents, SDKs, Games, API, Resources, and the worked example closes the Schema section. llms.txt's Lenses set becomes the World graph set. Each new page is a row in the URL contract. Co-Authored-By: Claude Opus 5.5 --- SWEEP.md | 4 +- astro.config.mjs | 89 ++++++++++--------- contract/urls.tsv | 7 +- src/content/docs/api/errors/index.mdx | 2 +- src/content/docs/docs/changelog.md | 12 +-- .../docs/docs/development/api/lenses.md | 11 +++ .../docs/docs/development/api/members.md | 2 +- src/content/docs/docs/lenses.mdx | 2 +- src/content/docs/docs/lenses/api.md | 9 +- src/content/docs/docs/world-graph.md | 33 +++++++ src/content/docs/docs/world-graph/draught.md | 12 +++ 11 files changed, 120 insertions(+), 63 deletions(-) create mode 100644 src/content/docs/docs/development/api/lenses.md create mode 100644 src/content/docs/docs/world-graph.md create mode 100644 src/content/docs/docs/world-graph/draught.md diff --git a/SWEEP.md b/SWEEP.md index 5488b175..de1a13fb 100644 --- a/SWEEP.md +++ b/SWEEP.md @@ -10,8 +10,8 @@ The docs state facts that other people's work changes: the API, the MCP server, 1. **Run it.** `node scripts/sweep.mjs` (add `--no-links` for a quick one). Fix every STALE it prints: bump a pin, refresh a snapshot, mend a link, replace a word, follow a release (a changelog line that links its page and names its version, a serial by its number, or `` when it moved no claim). 2. **Read MOVED against the pages that state it.** Each commit line names a source; the page to read is: - - keel: `docs/development/api-reference.mdx`, `api/*` (reads, writes, links, changes, errors, images, members, cors), `mcp.md`, `agents.md`, the error table, `schema/worlds.md`, `lenses/api.md` - - schema-dist: `schema/*`, `schema/conventions.mdx`, the profile pages `schema/profiles.md` and `schema/profiles/*`, the lens pages `lenses.mdx` and `lenses/graph.md`; the element tables regenerate on their own + - keel: `docs/development/api-reference.mdx`, `api/*` (reads, writes, links, changes, errors, images, members, cors, lenses, draught), `mcp.md`, `agents.md`, the error table, `schema/worlds.md`, the draught's concept page `world-graph/draught.md` + - schema-dist: `schema/*`, `schema/conventions.mdx`, the profile pages `schema/profiles.md` and `schema/profiles/*`, the World graph pages `world-graph.md`, `lenses.mdx` and `lenses/graph.md`; the element tables regenerate on their own - `@onlyworlds/sdk`: `typescript.md`, `packages.md`; its README is the repo's, kept in step by hand - the Python package: `python.md`; Atlas: `tools/atlas.md`, `getting-started/*`; Unity: `unity.md`, `games.md`; Obsidian: `tools/obsidian-plugin.md` - A link that sends the reader elsewhere for a claim: open the target and find the claim there. The link check sees that the page exists, not what it says (agents.md sent readers to Writes for the agent mark, which Writes never mentioned, 2026-10-18). diff --git a/astro.config.mjs b/astro.config.mjs index 5a03218b..a61dd497 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -77,42 +77,45 @@ export default defineConfig({ { slug: 'docs/schema/profiles/addresses' }, ], }, - { slug: 'docs/schema/example' }, { label: 'Element types', collapsed: true, items: [{ autogenerate: { directory: 'docs/schema/element_categories' } }], }, + { slug: 'docs/schema/example' }, ], }, { - label: 'Lenses', + // the world read as a graph: the concept pages; the lens and draught routes stay under API + label: 'World graph', items: [ - { slug: 'docs/lenses', label: 'Overview' }, + { slug: 'docs/world-graph', label: 'Overview' }, + { slug: 'docs/lenses' }, + { slug: 'docs/world-graph/draught' }, { slug: 'docs/lenses/graph' }, - { slug: 'docs/lenses/api', label: 'On the API' }, ], }, { - label: 'API', + label: 'Tools', items: [ - { slug: 'docs/development/api-reference', label: 'Overview' }, - { slug: 'docs/development/api/reads' }, - { slug: 'docs/development/api/links' }, - { slug: 'docs/development/api/writes' }, - { slug: 'docs/development/api/changes' }, - { slug: 'docs/development/api/members' }, - { slug: 'docs/development/api/hidden' }, - { slug: 'docs/development/api/public' }, - { slug: 'docs/development/api/proposals' }, - { slug: 'docs/development/api/draught' }, - { slug: 'docs/development/api/signin' }, - { slug: 'docs/development/api/images' }, - { slug: 'docs/development/api/files' }, - { slug: 'docs/development/api/cors' }, - { slug: 'docs/development/api/classic' }, - { slug: 'api/errors' }, - { label: 'Interactive reference', link: 'https://www.onlyworlds.com/api/docs' }, + { slug: 'docs/tools', label: 'Overview' }, + { slug: 'docs/tools/atlas' }, + { slug: 'docs/tools/lantern' }, + { slug: 'docs/tools/obsidian-plugin' }, + { slug: 'docs/tools/onlyworlds-com' }, + { slug: 'docs/tools/explorer' }, + { slug: 'docs/tools/council' }, + { slug: 'docs/tools/legacy' }, + ], + }, + { + label: 'AI agents', + items: [ + { slug: 'docs/development/ai', label: 'Overview' }, + { slug: 'docs/development/mcp' }, + { slug: 'docs/development/agents' }, + { slug: 'docs/development/llm-guide' }, + { slug: 'docs/development/toolkit' }, ], }, { @@ -133,26 +136,26 @@ export default defineConfig({ ], }, { - label: 'AI agents', - items: [ - { slug: 'docs/development/ai', label: 'Overview' }, - { slug: 'docs/development/mcp' }, - { slug: 'docs/development/agents' }, - { slug: 'docs/development/llm-guide' }, - { slug: 'docs/development/toolkit' }, - ], - }, - { - label: 'Tools', + label: 'API', items: [ - { slug: 'docs/tools', label: 'Overview' }, - { slug: 'docs/tools/atlas' }, - { slug: 'docs/tools/lantern' }, - { slug: 'docs/tools/obsidian-plugin' }, - { slug: 'docs/tools/onlyworlds-com' }, - { slug: 'docs/tools/explorer' }, - { slug: 'docs/tools/council' }, - { slug: 'docs/tools/legacy' }, + { slug: 'docs/development/api-reference', label: 'Overview' }, + { slug: 'docs/development/api/reads' }, + { slug: 'docs/development/api/links' }, + { slug: 'docs/development/api/writes' }, + { slug: 'docs/development/api/changes' }, + { slug: 'docs/development/api/members' }, + { slug: 'docs/development/api/hidden' }, + { slug: 'docs/development/api/public' }, + { slug: 'docs/development/api/proposals' }, + { slug: 'docs/development/api/draught' }, + { slug: 'docs/development/api/lenses', label: 'Lenses' }, + { slug: 'docs/development/api/signin' }, + { slug: 'docs/development/api/images' }, + { slug: 'docs/development/api/files' }, + { slug: 'docs/development/api/cors' }, + { slug: 'docs/development/api/classic' }, + { slug: 'api/errors' }, + { label: 'Interactive reference', link: 'https://www.onlyworlds.com/api/docs' }, ], }, { @@ -185,9 +188,9 @@ export default defineConfig({ '- [OpenAPI document](https://www.onlyworlds.com/api/v2/openapi.json): the API, machine-readable', ].join('\n'), customSets: [ - { label: 'API', description: 'the REST API v2: reads, links, writes, changes, members, hidden elements, public worlds and keyless reads, images, files, CORS, v1 migration and errors', paths: ['docs/development/api-reference', 'docs/development/api/**', 'api/errors', 'docs/getting-started/keys'] }, + { label: 'API', description: 'the REST API v2: reads, links, writes, changes, members, hidden elements, public worlds and keyless reads, proposals, the draught, lenses, images, files, CORS, v1 migration and errors', paths: ['docs/development/api-reference', 'docs/development/api/**', 'api/errors', 'docs/getting-started/keys'] }, { label: 'Schema', description: 'the 22 element types, their fields, the conventions for using them and the extension profiles', paths: ['docs/schema/**', 'docs/schema'] }, - { label: 'Lenses', description: 'the lens profile: a saved way of reading a world, a world read as a graph, and the lens routes on the API', paths: ['docs/lenses', 'docs/lenses/**'] }, + { label: 'World graph', description: "a world read as a graph: lenses (the lens profile, a saved way of reading a world), the draught (one Character's reading in one call) and the graph itself; the lens and draught routes are in the API set", paths: ['docs/world-graph', 'docs/world-graph/**', 'docs/lenses', 'docs/lenses/**'] }, { label: 'AI agents', description: 'the MCP server, agent seats, the LLM guide and the toolkit', paths: ['docs/development/ai', 'docs/development/mcp', 'docs/development/agents', 'docs/development/llm-guide', 'docs/development/toolkit'] }, ], // llms-small keeps asides and line breaks: the reader found notes like "no delete tool, by design" dropped diff --git a/contract/urls.tsv b/contract/urls.tsv index 7c5b2b71..695b7508 100644 --- a/contract/urls.tsv +++ b/contract/urls.tsv @@ -132,8 +132,11 @@ /docs/development/unity page 200 source docs/development/unity.md /docs/getting-started/keys page 200 source docs/getting-started/keys.md /docs/lenses page 200 source docs/lenses.mdx (new 2026-10-28, from the conventions page) -/docs/lenses/api page 200 source docs/lenses/api.md (new 2026-10-28, from the conventions page) -/docs/lenses/graph page 200 source docs/lenses/graph.md (new 2026-10-28, from the conventions page) +/docs/lenses/api page 200 source docs/lenses/api.md (new 2026-10-28, from the conventions page); since its content moved to /docs/development/api/lenses the same day, a short page that names the routes and points on +/docs/lenses/graph page 200 source docs/lenses/graph.md (new 2026-10-28, from the conventions page; in the World graph section) +/docs/development/api/lenses page 200 source docs/development/api/lenses.md (new 2026-10-28, moved from /docs/lenses/api) +/docs/world-graph page 200 source docs/world-graph.md (new 2026-10-28, the World graph section's overview) +/docs/world-graph/draught page 200 source docs/world-graph/draught.md (new 2026-10-28; the route stays on /docs/development/api/draught) /docs/schema/conventions load-bearing 200 toolkit:knowledge/atlas-conventions.md; toolkit:skills/onlyworlds-context/knowledge/atlas-conventions.md; toolkit:skills/onlyworlds-import/knowledge/atlas-conventions.md; toolkit:skills/onlyworlds-read/knowledge/atlas-conventions.md; toolkit:skills/onlyworlds-update/knowledge/atlas-conventions.md /docs/schema/conventions#messages-between-members page 200 kept anchor: its section moved to /docs/schema/profiles/messages (2026-10-28); one paragraph points on, for bookmarks and old links /docs/schema/conventions#addresses page 200 kept anchor: its section moved to /docs/schema/profiles/addresses (2026-10-28); one paragraph points on, for bookmarks and old links diff --git a/src/content/docs/api/errors/index.mdx b/src/content/docs/api/errors/index.mdx index daa067f1..904c34b3 100644 --- a/src/content/docs/api/errors/index.mdx +++ b/src/content/docs/api/errors/index.mdx @@ -137,7 +137,7 @@ A single write that fails with `invalid_link` writes nothing, so after fixing th **Type** `invalid_request` · **Status** `422` -A seat chose a hidden lens (`param` `lenses`) in `PUT /api/v2/me/lenses` or the account member route. A seat's [lenses](/docs/lenses/api) are on the members list every reader of the world reads, so a hidden lens can never be chosen. Nothing was written. +A seat chose a hidden lens (`param` `lenses`) in `PUT /api/v2/me/lenses` or the account member route. A seat's [lenses](/docs/development/api/lenses) are on the members list every reader of the world reads, so a hidden lens can never be chosen. Nothing was written. - **How to fix:** unhide the lens first, or choose another. diff --git a/src/content/docs/docs/changelog.md b/src/content/docs/docs/changelog.md index 68a2a4c4..04ed60d3 100644 --- a/src/content/docs/docs/changelog.md +++ b/src/content/docs/docs/changelog.md @@ -23,7 +23,7 @@ What changed for developers, newest first: the API on onlyworlds.com, the client - **[The draught](/docs/development/api/draught)'s figure**: `messages` holds the Messages she sent as well as those that name her, and the lens frames sit beside the parameters, read with no `lens` only when no parameter but `compact` is set. - **[The draught](/docs/development/api/draught) draws a Character in one read**: the ten sections served by default round her (`self`, `role` and `work` never cut by the budget), the three served only when `components` names them (`messages`, `room`, `proposed`) and the lenses beside them, and the nine query parameters with their values and defaults, from the API's own document for `GET /api/v2/character/{id}/context`. The page now says `proposed` holds every element still carrying `x_review_proposed`, not only an AI seat's, and that an account token with no access to the world reads as the public. - **[Fields](/docs/schema/fields#what-a-write-body-may-carry) draws what a write body may carry**: each key a `POST`, `PUT` or `PATCH` body carries is stored (the base fields with their caps, `hidden` on a create, the category's own fields, the extension prefixes up to 64 KB), tolerated and ignored (`world`, `created_by`, `changed_by`, `changed_via`, `changed_client`, and `id` and `hidden` where a method ignores them) or rejected with `422` (`type`, `created_at`, `updated_at`, `change_seq`, `x_served_trimmed` and any other unknown field), from the API's own write schemas. The page now lists `changed_by`, `changed_via` and `changed_client` among the server-kept fields, says the path decides the id on `PUT` and `PATCH`, and names `x_served_trimmed`, the one `x_` key that is the server's own and refused on a write. -- **The conventions page splits in three.** [Modelling conventions](/docs/schema/conventions) keeps the advice on modelling a world at its old address. The extension profiles move to [Profiles](/docs/schema/profiles) in the Schema section, with [Messages](/docs/schema/profiles/messages) and [Addresses](/docs/schema/profiles/addresses) on pages of their own, and lenses to a section of their own: [Lenses](/docs/lenses), [A world as a graph](/docs/lenses/graph) and [Lenses on the API](/docs/lenses/api). Profiles, Messages and Lenses each say first what every reader does, then what onlyworlds.com adds. The old anchors on the conventions page still answer, each with a paragraph that points to the new page. +- **The conventions page splits in three.** [Modelling conventions](/docs/schema/conventions) keeps the advice on modelling a world at its old address. The extension profiles move to [Profiles](/docs/schema/profiles) in the Schema section, with [Messages](/docs/schema/profiles/messages) and [Addresses](/docs/schema/profiles/addresses) on pages of their own, and lenses to a section of their own: [Lenses](/docs/lenses), [A world as a graph](/docs/lenses/graph) and [Lenses on the API](/docs/development/api/lenses). Profiles, Messages and Lenses each say first what every reader does, then what onlyworlds.com adds. The old anchors on the conventions page still answer, each with a paragraph that points to the new page. - **[World Starter](/docs/development/#sdks)**, a template repository for a web tool on world data, is public: it reads the demo world out of the box, or your own with a read key. [Build on OnlyWorlds](/docs/development/#sdks) and the [TypeScript](/docs/development/typescript#install) page point to it. - **[TypeScript](/docs/development/typescript#lenses) 4.100.1 and [Python](/docs/development/python#what-it-covers) 0.82.1**: a lens's rows below the public rung keep a link to a proposed element the reader sees, and a note keyed to one, as the API serves them; no row carries a stored `x_served_trimmed`. - **Corrections to the [schema](/docs/schema/) pages**, from an outside review of the docs: [Ability](/docs/schema/element_categories/ability) no longer calls itself a passive trait, [Trait](/docs/schema/element_categories/trait) no longer says Constructs are not linked to actors, and [Construct](/docs/schema/element_categories/construct) no longer describes Phenomena as only natural. [Relation](/docs/schema/element_categories/relation) says `actor` is optional, [Narrative](/docs/schema/element_categories/narrative) separates the dates it is told from the time it is about, and [Location](/docs/schema/element_categories/location) says how a building is a Location, an Object or both. [Conventions](/docs/schema/conventions) gains a magic system across three categories and says a Zone with no Markers is valid; [Fields](/docs/schema/fields) says supertype and subtype are a world's own kinds and that a valid element is not always enough for a map or timeline view; every field table says integers are whole numbers; the definitions table on the [schema page](/docs/schema/) comes before the counts. [Keys and PINs](/docs/getting-started/keys) no longer says no request passes a world id: an account token and a read of an open world name one. The [LLM guide](/docs/development/llm-guide) names its six headings and the SDK's colour groups as reading aids, not part of the standard, and drops ChatGPT Canvas. @@ -45,13 +45,13 @@ What changed for developers, newest first: the API on onlyworlds.com, the client - **[API overview](/docs/development/api-reference#which-credential-each-route-takes) draws which credential each route takes**: every operation of the API by route family, counted under no key, a key alone, a key and its PIN or an account token as the API's own document lists them, with each route under the credentials it takes; generated from that document when the docs are built, its keyless reads held to the list on [Public worlds](/docs/development/api/public#the-keyless-reads), and the docs' check fails when the document moves until the figure follows. - **[Obsidian plugin](/docs/tools/obsidian-plugin#your-onlyworlds-account) 3.14.0: a Sign in command and a Create account command**; Download world and Create world offer the same Sign in dialog when you are signed out. It takes a pasted account token. - **[World folders](/docs/schema/folders#layout) draws the example world's folder** under the Layout block, Hyperion's category folders with their file counts and three of its elements' names and ids becoming their file names, from schema-dist's `example/hyperion`; every file name is derived by the page's naming rule when the docs are built, and the build fails if one of the example's files breaks it. The page's naming rule now says what Atlas writes: accents removed (José becomes jose) and no hyphen at either end of the slug. -- **[Choosing no lenses](/docs/lenses/api)**: an empty lens list is now a choice that keeps a member off its Titles' lenses (`lenses_from: chosen`), and `null` puts it back to never chosen, where the Titles' lenses apply; `PUT /me/lenses` and the members PATCH take both. [TypeScript](/docs/development/typescript) 4.99.0 and [Python](/docs/development/python) 0.81.0 send `null`. +- **[Choosing no lenses](/docs/development/api/lenses)**: an empty lens list is now a choice that keeps a member off its Titles' lenses (`lenses_from: chosen`), and `null` puts it back to never chosen, where the Titles' lenses apply; `PUT /me/lenses` and the members PATCH take both. [TypeScript](/docs/development/typescript) 4.99.0 and [Python](/docs/development/python) 0.81.0 send `null`. - **[MCP](/docs/development/mcp) `get_draught` takes `lens`**, a lens id beside `policy`, read as the [draught's](/docs/development/api/draught#the-policy) `lens` is. The API document now names the keyless reads (no credential, on a world open to anyone) and `Retry-After` on the in-flight 409 of every route that takes an `Idempotency-Key`; the [errors](/api/errors/#idempotency_in_flight) figure's mark is held to it. - **[Public worlds](/docs/development/api/public#the-look) draws the five page palettes** under the Palette setting, each in its own colours with its contrast numbers, from the platform's palette table; every ratio, and the claim that each text colour clears 4.5 to 1 on every surface, is computed when the docs are built. - **[A new key](/docs/getting-started/keys) and [a seat for your AI](/docs/development/agents#giving-your-ai-access)**: the key's box on onlyworlds.com has **Copy instructions for your AI**, a message that has your AI write its own `.env` file, say where it put it and check the key with `GET /api/v2/me`; the raw lines are under **Show the lines**. - **[Errors](/api/errors/#error-codes) draws every code by family and status** above the summary table, from the same list: the codes that answer with `Retry-After` are marked, and the upload host's own codes are counted on one line. -- **[Reading a lens as a seat](/docs/lenses/api)**: a co-builder, or the account that sponsors an agent's or a player's seat, may read a lens as that seat with `read_as`, within its own view; [`read_as_owner_only`](/api/errors/#read_as_owner_only) now answers only a reader whose lenses the caller may not set. -- **[A Title's lenses](/docs/lenses/api)**: a member that chose no lenses starts with the lenses whose `titles` name a Title its Character holds; `GET /me` and `GET /members` say where a row's lenses come from (`lenses_from`), and a world's lens list says which you start with through a Title (`from_titles`) and, for the owner, which seats do (`title_seats`). SDK 4.97.0 types them. +- **[Reading a lens as a seat](/docs/development/api/lenses)**: a co-builder, or the account that sponsors an agent's or a player's seat, may read a lens as that seat with `read_as`, within its own view; [`read_as_owner_only`](/api/errors/#read_as_owner_only) now answers only a reader whose lenses the caller may not set. +- **[A Title's lenses](/docs/development/api/lenses)**: a member that chose no lenses starts with the lenses whose `titles` name a Title its Character holds; `GET /me` and `GET /members` say where a row's lenses come from (`lenses_from`), and a world's lens list says which you start with through a Title (`from_titles`) and, for the owner, which seats do (`title_seats`). SDK 4.97.0 types them. - **[Reading aids and a lens by when things changed](/docs/lenses)** (schema-dist serial 82): a world's Charter, Guide and Domains carrying the mark `x_charter_of` are its reading aids, shown first at a tool's front door and left out of lore views, a lens keeping one only when its `types` names the pair or it is an anchor; a lens's `changed_within` cuts what changed longer ago than that many days, counted `stale`. [TypeScript](/docs/development/typescript#lenses) 4.98.0 and [Python](/docs/development/python) 0.80.0 read both (`isCharterElement`, `is_charter_element`), count a lens's ignored notes only where the reader sees the id, and give an element's out-degree (`outDegreeOf`, `out_degree_of`). - **[TypeScript](/docs/development/typescript#lenses) 4.97.1 and [Python](/docs/development/python) 0.79.3: a lens's mail part reads whole messages only**: a Message the reader knows only as a stub is never read as mail to everyone, as the API reads it. - **[TypeScript](/docs/development/typescript#lenses) 4.97.0 and [Python](/docs/development/python) 0.79.2: an umbrella lens no longer enters a child lens the reader knows only as a stub**, as the API reads it: the child counts as an anchor the reader cannot see, so a guest's reading never follows links it was not served. @@ -81,13 +81,13 @@ What changed for developers, newest first: the API on onlyworlds.com, the client - **[TypeScript](/docs/development/typescript#lenses) 4.96.0 and [Python](/docs/development/python) 0.79.0: `DATE_FIELD` and `dateOf`, `date_of`**, the [lens profile](/docs/lenses)'s date table and an element's date as it reads it, so a timeline dates elements the way a lens does. - **[The Lenses page](/docs/lenses#on-onlyworldscom)**: a world's page on onlyworlds.com lists its lenses, opens one to change and read it (what it keeps, and what it cut by reason), and on a world open to everyone reads a lens signed out. - **[TypeScript](/docs/development/typescript#lenses) 4.95.0 and [Python](/docs/development/python) 0.78.0: `degreeOf` and `degree_of`**, each element's count of links in a [world graph](/docs/lenses/graph) as the reader sees it, the "most linked" a search ranks by. -- **[Lenses on an account token](/docs/lenses/api)**: `GET /world/{id}/lenses` and `PUT /me/lenses` (with `?world=`) take an account token; a row's lenses are set on the members route with `lenses` alone, answering `{id, role, kind, lenses}`; a lens you can no longer see stays in your list, marked. [Sign in with OnlyWorlds](/docs/development/api/signin) answers `expires_at` for a tool that asks a lifetime on its tokens, and a tool may keep your consent through its own sign-outs. [TypeScript](/docs/development/typescript) 4.94.0: `setMemberLenses`, `worldLenses` and `setMyLenses` on an account token, `completeSignIn`'s `expiresAt`. +- **[Lenses on an account token](/docs/development/api/lenses)**: `GET /world/{id}/lenses` and `PUT /me/lenses` (with `?world=`) take an account token; a row's lenses are set on the members route with `lenses` alone, answering `{id, role, kind, lenses}`; a lens you can no longer see stays in your list, marked. [Sign in with OnlyWorlds](/docs/development/api/signin) answers `expires_at` for a tool that asks a lifetime on its tokens, and a tool may keep your consent through its own sign-outs. [TypeScript](/docs/development/typescript) 4.94.0: `setMemberLenses`, `worldLenses` and `setMyLenses` on an account token, `completeSignIn`'s `expiresAt`. - **[TypeScript](/docs/development/typescript#lenses) 4.93.1 and [Python](/docs/development/python) 0.77.1: a lens a guest knows only as a stub reads as nothing when named by id**, in the lens and graph readers, as the server reads it. They read the lens's full body whenever its id was in the guest's view, a stub included, so a guest's reading followed starting points the guest is never shown. - **[TypeScript](/docs/development/typescript#lenses) 4.93.0 and [Python](/docs/development/python) 0.77.0: [a world as a graph](/docs/lenses/graph) (schema-dist serial 81).** `worldGraph` and `world_graph` read a world snapshot, for one reader, as nodes and edges; room, hidden and proposed elements and map space come back only by their flags, a lens keeps exactly its own elements, and every link left out is counted by reason, `outside_lens` for one the lens never reached. Every world read's `counts` is described as keel serves it, for every reader. - **[Toolkit](/docs/development/toolkit) 5.4.1: a Take is left out of the graph and the count like the rest of a room**, by the room profile's nine type-and-supertype pairs; the company pack names who writes the board (the owner and the co-builders) and asks everyone to keep a Note about themselves; new world folders are stamped format 0.3.19. - **[A world's counts for every reader](/docs/development/api/reads)**: `GET /api/v2/world` carries `counts` for every key and token, counted as that reader may read, not only for the keyless read. - **[Agent links from a script](/docs/development/agents)** take the form's fields, `label` and `for_email`. -- **[Lenses on the API](/docs/lenses/api)**: the world's lenses resolved for you (`GET /api/v2/world/{world_id}/lenses`), the lenses you start with (`PUT /api/v2/me/lenses`, shown on `GET /me` and `GET /members`), and the [draught](/docs/development/api/draught)'s `lens`. In [TypeScript](/docs/development/typescript) 4.92.0 and [Python](/docs/development/python) 0.76.0, beside schema-dist serial 80. +- **[Lenses on the API](/docs/development/api/lenses)**: the world's lenses resolved for you (`GET /api/v2/world/{world_id}/lenses`), the lenses you start with (`PUT /api/v2/me/lenses`, shown on `GET /me` and `GET /members`), and the [draught](/docs/development/api/draught)'s `lens`. In [TypeScript](/docs/development/typescript) 4.92.0 and [Python](/docs/development/python) 0.76.0, beside schema-dist serial 80. - **[Python](/docs/development/python) 0.75.1**: a folder is read in one order on every platform (file names by code point), so a duplicate id keeps the same file on Windows as elsewhere. - **[TypeScript](/docs/development/typescript) 4.91.1 and [Python](/docs/development/python) 0.75.0: schema-dist serial 79.** Four message cases on Notes (addressed to nobody, never in a thread, never unread; any hidden mark leaves one out), which both readers already answer. Python writes folders at [v0.3.19](/docs/schema/folders), and `onlyworlds.lint` is the dist's checker at serial 79. - **[Python](/docs/development/python) 0.74.1**: the pack and the OKF export read an in-prose reference in every address form (a moment, a lens, the world's own id), so one in another form to a hidden element no longer keeps its label and id. diff --git a/src/content/docs/docs/development/api/lenses.md b/src/content/docs/docs/development/api/lenses.md new file mode 100644 index 00000000..5a77a588 --- /dev/null +++ b/src/content/docs/docs/development/api/lenses.md @@ -0,0 +1,11 @@ +--- +title: Lenses on the API +description: "The routes that serve lenses on onlyworlds.com: a world's lenses and their readings, the lenses a member starts with, and the draught." +--- + +On the API, the server reads the same profile as every reader ([Lenses](/docs/lenses)): + +- `GET /api/v2/world/{world_id}/lenses` lists every lens in the world you can see, templates marked, each with its recipe filled in, the Titles it is the default for, whether you chose it (`chosen`) and whether you start with it through a Title you hold (`from_titles`, never with `chosen`); the owner also gets who chose each lens (`chosen_by`) and, apart, which seats start with it through a Title (`title_seats`, each with those Titles). With `resolve=true` it adds each lens's reading for you: the kept rows, the cut by reason, the mail part. The owner may read as another reader with `read_as` (`guest`, `contributor`, `co-builder`, `public`, or a membership id). Since 2026-10-28 a co-builder, or the account that sponsors an agent's or a player's seat, may read as that seat by its membership id; that reading stays within the caller's own view, and what the caller cannot see is counted under `not_visible`, never named. A member key, the owner's keys or an account token; never keyless. SDK `worldLenses`, Python `world_lenses`. +- `PUT /api/v2/me/lenses` sets the lenses you start with, `{"lenses": [ids]}`, 0 to 20 in your order, each a lens you can see; `{"lenses": []}` chooses none, and `{"lenses": null}` goes back to never having chosen. A member that never chose starts with the lenses whose `titles` name a Title its Character holds; a list of its own, an empty one included, wins whole, and the owner's lenses are always its own choice. `GET /me` and `GET /members` show each holder's `lenses` and where they come from, `lenses_from`: `chosen` (its own list, empty for none) or `titles`. A write key sets its own holder's list; an account token sets yours in the world it names with `?world=`. A lens you chose that you can no longer see stays in your list at its place, and the answer marks `lenses` in `x_served_trimmed`. SDK `setMyLenses` (with `null` since 4.99.0), Python `set_my_lenses` (with `None` since 0.81.0). +- `PATCH /api/v2/account/worlds/{world_id}/members/{member_id}` with `{"lenses": [ids]}` alone sets a row's list on an account token: your own row, a seat you answer for, or the owner's own with `owner` as the member id. It answers `{id, role, kind, lenses}` (`id` null for the owner's own), with the same mark when a lens you cannot see was kept. SDK `setMemberLenses`. +- The [draught](/docs/development/api/draught) takes `lens=` and adds `lenses`, one frame with that lens read for your own view. With no lens and no policy parameter but `compact`, it adds one frame per lens you chose, in your order. diff --git a/src/content/docs/docs/development/api/members.md b/src/content/docs/docs/development/api/members.md index 62fdd8a8..b5034481 100644 --- a/src/content/docs/docs/development/api/members.md +++ b/src/content/docs/docs/development/api/members.md @@ -49,7 +49,7 @@ curl -s "https://www.onlyworlds.com/api/v2/members" -H "API-Key: {key}" | `character` | The Character that is this member, or `null`. The owner's is the world's `owner_character`. `null` too when that Character is [hidden](/docs/development/api/hidden) from the calling key | | `status` | `active` or `removed` | | `name` | Agent and player rows only: their name | -| `lenses` | The [lenses](/docs/lenses/api) the row starts with, lens ids in order: the ones it chose, or, when it chose none, the lenses whose `titles` name a Title its Character holds (the owner row: always the owner's own choice); `[]` for none. A lens the calling key cannot see is left out | +| `lenses` | The [lenses](/docs/development/api/lenses) the row starts with, lens ids in order: the ones it chose, or, when it chose none, the lenses whose `titles` name a Title its Character holds (the owner row: always the owner's own choice); `[]` for none. A lens the calling key cannot see is left out | | `lenses_from` | Where `lenses` comes from: `chosen` (the row's own list, an empty one included) or `titles` (it never chose, and its Character's Titles bring these) | | `x_served_trimmed` | Present only when `lenses` was served with a lens left out: then it names `lenses` ([A list trimmed for its reader](/docs/schema/folders#a-list-trimmed-for-its-reader)) | diff --git a/src/content/docs/docs/lenses.mdx b/src/content/docs/docs/lenses.mdx index 9d8ebb2d..5d7509b1 100644 --- a/src/content/docs/docs/lenses.mdx +++ b/src/content/docs/docs/lenses.mdx @@ -22,4 +22,4 @@ The TypeScript and Python SDKs read a lens over a world snapshot (`resolveLens`, On onlyworlds.com, a world's Lenses page (`/account/worlds//lenses`, in the world's menu) lists its lenses, changes one and shows its reading; the owner can read it as another reader. Its Start from finds elements by a word, the most linked first (by the graph's degree, for the reader the page reads as), and offers a world's Domains as packages of starting points, or a few proposed ones in a world with no Domain; nothing is stored until you save the lens. Its Library holds the public templates and the world's own, each copied in with its settings and no starting points; a lens can be copied to another of your worlds, or published as a template without its starting points or their notes. On your own lens the page reads it a second time in the browser with the SDK's `resolveLens` and says whether the two readings agree. -The routes that serve lenses are on [Lenses on the API](/docs/lenses/api). +The routes that serve lenses are on [Lenses on the API](/docs/development/api/lenses). diff --git a/src/content/docs/docs/lenses/api.md b/src/content/docs/docs/lenses/api.md index 5a77a588..0f413227 100644 --- a/src/content/docs/docs/lenses/api.md +++ b/src/content/docs/docs/lenses/api.md @@ -1,11 +1,6 @@ --- title: Lenses on the API -description: "The routes that serve lenses on onlyworlds.com: a world's lenses and their readings, the lenses a member starts with, and the draught." +description: "The routes that serve lenses on onlyworlds.com moved to the API section." --- -On the API, the server reads the same profile as every reader ([Lenses](/docs/lenses)): - -- `GET /api/v2/world/{world_id}/lenses` lists every lens in the world you can see, templates marked, each with its recipe filled in, the Titles it is the default for, whether you chose it (`chosen`) and whether you start with it through a Title you hold (`from_titles`, never with `chosen`); the owner also gets who chose each lens (`chosen_by`) and, apart, which seats start with it through a Title (`title_seats`, each with those Titles). With `resolve=true` it adds each lens's reading for you: the kept rows, the cut by reason, the mail part. The owner may read as another reader with `read_as` (`guest`, `contributor`, `co-builder`, `public`, or a membership id). Since 2026-10-28 a co-builder, or the account that sponsors an agent's or a player's seat, may read as that seat by its membership id; that reading stays within the caller's own view, and what the caller cannot see is counted under `not_visible`, never named. A member key, the owner's keys or an account token; never keyless. SDK `worldLenses`, Python `world_lenses`. -- `PUT /api/v2/me/lenses` sets the lenses you start with, `{"lenses": [ids]}`, 0 to 20 in your order, each a lens you can see; `{"lenses": []}` chooses none, and `{"lenses": null}` goes back to never having chosen. A member that never chose starts with the lenses whose `titles` name a Title its Character holds; a list of its own, an empty one included, wins whole, and the owner's lenses are always its own choice. `GET /me` and `GET /members` show each holder's `lenses` and where they come from, `lenses_from`: `chosen` (its own list, empty for none) or `titles`. A write key sets its own holder's list; an account token sets yours in the world it names with `?world=`. A lens you chose that you can no longer see stays in your list at its place, and the answer marks `lenses` in `x_served_trimmed`. SDK `setMyLenses` (with `null` since 4.99.0), Python `set_my_lenses` (with `None` since 0.81.0). -- `PATCH /api/v2/account/worlds/{world_id}/members/{member_id}` with `{"lenses": [ids]}` alone sets a row's list on an account token: your own row, a seat you answer for, or the owner's own with `owner` as the member id. It answers `{id, role, kind, lenses}` (`id` null for the owner's own), with the same mark when a lens you cannot see was kept. SDK `setMemberLenses`. -- The [draught](/docs/development/api/draught) takes `lens=` and adds `lenses`, one frame with that lens read for your own view. With no lens and no policy parameter but `compact`, it adds one frame per lens you chose, in your order. +The routes that serve lenses on onlyworlds.com (a world's lenses and their readings, `GET /api/v2/world/{world_id}/lenses`; the lenses a member starts with, `PUT /api/v2/me/lenses` and the account member route; and the draught's `lens`) are on [Lenses](/docs/development/api/lenses) in the API section. What a lens is, and how every reader reads one, is on [Lenses](/docs/lenses). diff --git a/src/content/docs/docs/world-graph.md b/src/content/docs/docs/world-graph.md new file mode 100644 index 00000000..969fe6ed --- /dev/null +++ b/src/content/docs/docs/world-graph.md @@ -0,0 +1,33 @@ +--- +title: World graph +description: "An OnlyWorlds world is a graph of typed elements and links: how to read part of one, and the ideas it sits beside." +--- + +An OnlyWorlds world is a graph. Its elements are the nodes: Characters, Locations, Institutions, Laws, Events and the rest of the 22 element types (what a knowledge graph would call types or classes; inside each element type, a supertype sorts it first, a Character's might be Wizard, and a subtype sorts further). Its links are the edges, and every link is typed: a Character's `birthplace` points at a Location, and the field's name says what the link means. A Relation is a node of its own, with an edge to each party, so a link that needs fields of its own (a start date, an intensity) can carry them. Links point at ids, not names: [an element's identity is its id](/docs/schema/folders#layout). + +## Reading part of a world + +Because a world is a graph, you can read part of it: start from a few elements and follow their links, either way, one step (a hop) at a time. Every reading is made for one reader, the key or person doing the reading, and never shows what that reader may not see. This section covers three ways to read: + +- **[A lens](/docs/lenses)** is a saved recipe for a reading: a few starting elements (the anchors), how many hops to go from them, which element types to keep, and how much to return. Any reader can resolve a lens over a world it can see, and a lens only narrows. +- **[The draught](/docs/world-graph/draught)** is one Character's reading of the world in one call: who they are, the Titles they hold, the Events they were in, in story order, and what names them. Given a lens, it adds that lens's reading as one more frame in the answer. +- **[The graph itself](/docs/lenses/graph)**: the SDKs read a world, or a lens's reading of it, as nodes and edges (`worldGraph`, `world_graph`), and count each element's links (`degreeOf`, `degree_of`, its degree), which is what "most linked" means when a search ranks its results. What a lens's budget or rules leave out, and every link to an element outside the reading, is counted by its reason, never dropped silently. + +[Atlas](/docs/tools/atlas) draws any element's connections as a small graph, if you want to see one. + +## Related ideas + +The idea of reading part of a large structure from a focus has a long history. They help place it: + +- **Fisheye views.** Furnas ("Generalized Fisheye Views", CHI 1986) gave every item a degree of interest: its a priori importance minus its distance from the current focus. A view shows the items at or above a threshold, or the n most interesting. A lens's anchors and budget echo it, and "most linked" is one way to rank by importance. +- **Magic Lenses.** Bier, Stone, Pier, Buxton and DeRose ("Toolglass and Magic Lenses", SIGGRAPH 1993) described a movable see-through filter that changes how the objects beneath it are shown. Editing there was done by other tools, used beside the lens or combined with it. An OnlyWorlds lens stays a reading. +- **Bidirectional lenses.** Foster, Greenwald, Moore, Pierce and Schmitt (POPL 2005, and the journal version in TOPLAS 2007) defined a lens on tree-shaped data as a pair: one function that extracts a view, and one that takes an edited view with the original and returns the updated original, an answer to the view-update problem. OnlyWorlds' lenses have only the first half; writing goes through the elements themselves. +- **Ontology modules.** Cuenca Grau, Horrocks, Kazakov and Sattler ("Modular Reuse of Ontologies", JAIR 2008) showed how to cut a module from an ontology that gives the same answers as the whole over a chosen set of terms. A lens shares the aim of a smaller piece you can work from; it is a recipe, not a guarantee of that kind. + +## Next to other knowledge bases + +Knowledge kept for AI agents comes in several forms today. Markdown knowledge bases link files without saying what a link means. Graph and ontology platforms type their knowledge, and the ones we've read fill it by binding, syncing or mining other sources. Enterprise search fills its index by pulling from connected tools. A world is a typed layer whose elements people write on purpose, alone or with their AI, and which can live as a [folder of files](/docs/schema/folders). + +That difference has a known edge. Graphs built by an LLM from documents carry duplicates, because the common tools merge entities by matching names (shown in preprints on LLM-built graphs). In a world, links and identity rest on ids, so nothing merges two elements because their names match. + +Whether an AI answers better from a world than from the same content as files is not known. The one test so far, an internal one on a single document of about 15,000 tokens turned into a world, sat at the ceiling for both (110 of 110 questions from the files, 109 of 110 from the world). diff --git a/src/content/docs/docs/world-graph/draught.md b/src/content/docs/docs/world-graph/draught.md new file mode 100644 index 00000000..2cf847b4 --- /dev/null +++ b/src/content/docs/docs/world-graph/draught.md @@ -0,0 +1,12 @@ +--- +title: The draught +description: "One Character's reading of a world in one call, and how it takes a lens." +--- + +The **draught** is one Character's reading of a world in one call: what the recorded world holds around that Character, gathered into one answer. It holds the Character's own element, the Titles they hold and the bodies they sit in, their open work, how they work, the Events they were in, in story order, the Narratives they know, everything else that names them, their sheet, what changed around them, and who plays whom. It is made for a storyteller speaking as the Character, or an agent working in their name, that would otherwise make a dozen reads a turn. + +Like every reading of a [world graph](/docs/world-graph), it is made for one reader. Nothing in it is inferred: every element in it is the body the list route serves the same reader, with the links that brought it, a count and a grade, and what is hidden from the reader is in no section. Its `voice` mode reads as the Character would; its `act` mode reads through your own key's view, for an agent doing work in the Character's name. + +It takes a [lens](/docs/lenses). Given one, it adds that lens's reading, read for your own view, as one more frame in the answer. With no lens, and no policy parameter but `compact`, it adds one frame per lens you chose. + +The route, `GET /api/v2/character/{id}/context`, with who may read it, its policy, its packet, its horizon and its errors, is on [The draught](/docs/development/api/draught) in the API section. The [MCP server](/docs/development/mcp)'s `get_draught` and both SDKs read it too. From 3b77544de3b233329587f02c763d1cc3a47b3081 Mon Sep 17 00:00:00 2001 From: Titus Date: Wed, 28 Oct 2026 22:39:02 +0100 Subject: [PATCH 2/7] The draught page names its Character neutrally The generic Character on the draught route page was "she" and "her"; it is now "the Character" or "they" and "their", with the figure's held words changed the same way. The owner's view-as example names what it takes, `?as=`. The field `her_links` keeps its name. Co-Authored-By: Claude Opus 5.5 --- src/components/figures/draught.mjs | 24 +++++----- .../docs/docs/development/api/draught.mdx | 44 +++++++++---------- 2 files changed, 34 insertions(+), 34 deletions(-) diff --git a/src/components/figures/draught.mjs b/src/components/figures/draught.mjs index 794cb93b..2f547b18 100644 --- a/src/components/figures/draught.mjs +++ b/src/components/figures/draught.mjs @@ -1,4 +1,4 @@ -// The draught figure's data and words: one Character's context in one read, its sections round her +// The draught figure's data and words: one Character's context in one read, its sections round the Character // and the policy that shapes the read. Every section, which are off unless named, which the budget // never cuts, every parameter with its values and defaults comes from the API's own document // through the snapshot contract/draught.json (scripts/gen_draught.mjs): the route @@ -9,17 +9,17 @@ // What each section holds, in the page's words. export const SAYS = { - self: 'her own element, with self: true', - role: 'the Titles she holds and the bodies she sits in', - work: 'her open work', - style: 'how she works', - events: 'the Events she was in, in story order', - knowledge: 'the Narratives she knows', - names: 'everything else that names her', - sheet: 'what her own element links to, one step out', - recent: 'what changed around her', + self: "the Character's own element, with self: true", + role: 'the Titles they hold and the bodies they sit in', + work: 'their open work', + style: 'how they work', + events: 'the Events they were in, in story order', + knowledge: 'the Narratives they know', + names: 'everything else that names them', + sheet: 'what their own element links to, one step out', + recent: 'what changed around them', roster: 'who plays whom', - messages: 'the Messages she sent or that name her', + messages: 'the Messages they sent or that name them', room: "a parlor's room elements", proposed: 'no keeper has settled yet', }; @@ -88,7 +88,7 @@ export function valuesOf(s) { // What each parameter does, in the page's words (its policy table). const NOTES = { components: () => 'the sections to serve, comma-separated', - mode: (c) => `${c('voice')} reads as she would; ${c('act')} reads through your own key's view`, + mode: (c) => `${c('voice')} reads as they would; ${c('act')} reads through your own key's view`, as_of: () => "the horizon, an integer in the world's time unit", undated: (c) => `${c('exclude')} drops them, for a spoiler-safe narrator`, since: (c) => `for ${c('recent')}: a cursor from ${c('/changes')}, or an ISO 8601 date and time`, diff --git a/src/content/docs/docs/development/api/draught.mdx b/src/content/docs/docs/development/api/draught.mdx index 20781c00..f832397a 100644 --- a/src/content/docs/docs/development/api/draught.mdx +++ b/src/content/docs/docs/development/api/draught.mdx @@ -5,7 +5,7 @@ description: One Character's context in one read, under a policy of sections, mo import DraughtRead from '../../../../../components/figures/DraughtRead.astro'; -`GET /api/v2/character/{id}/context` returns what one Character knows, as the recorded world holds it, in one read: the **draught**. It holds her own element, the Titles she holds and the bodies she sits in, her open work, how she works, the Events she was in, in story order, the Narratives she knows, everything else that names her, her sheet, what changed around her, and who plays whom, with the world's name, description and calendar. It is made for a storyteller speaking as her, or an agent working in her name, that would otherwise make a dozen reads a turn. +`GET /api/v2/character/{id}/context` returns what one Character knows, as the recorded world holds it, in one read: the **draught**. It holds the Character's own element, the Titles they hold and the bodies they sit in, their open work, how they work, the Events they were in, in story order, the Narratives they know, everything else that names them, their sheet, what changed around them, and who plays whom, with the world's name, description and calendar. It is made for a storyteller speaking as the Character, or an agent working in their name, that would otherwise make a dozen reads a turn. Nothing in it is inferred. Every element in it is the body the [list route](/docs/development/api/reads) serves the same reader, with the links that brought it, a count and a grade. @@ -23,7 +23,7 @@ curl -s "https://www.onlyworlds.com/api/v2/character/{id}/context?mode=voice&bud | The owner's keys, a co-builder's, a contributor's | Any Character the key can see | | A player seat, a guest, a guest agent seat | Its own Character only. Any other id is `404` | | An [account token](/docs/getting-started/keys#reading-a-world-with-an-account-token), with `world=` | As you: any Character in a world you own, or what your own member key reads in a world you are a member of. An account with no access to that world reads as the public, as in the next row | -| No credential, with `world=`, on a world [open to anyone](/docs/development/api/public) | What the public may read: her public sheet, what names her and what changed as the public sees it, a lens read as the public. Never her messages and never the roster | +| No credential, with `world=`, on a world [open to anyone](/docs/development/api/public) | What the public may read: the Character's public sheet, what names them and what changed as the public sees it, a lens read as the public. Never their messages and never the roster | A Character the key cannot see answers `404` [`not_found`](/api/errors/#not_found), as a missing one does. What is [hidden](/docs/development/api/hidden) from the reader is in no section. The answer is sent `Cache-Control: private, no-store`: never cache it shared. @@ -34,12 +34,12 @@ Nine query parameters, all optional. The SDKs take the same nine. The MCP tool ` | Parameter | Values | Default | |:--|:--|:--| | `components` | The sections to serve, comma-separated: `self` (the packet's `character`), `role`, `work`, `style`, `events`, `knowledge`, `names`, `sheet`, `recent`, `messages`, `room`, `proposed`, `roster` | Every one but `messages`, `room` and `proposed` | -| `mode` | `voice` reads as she would, exactly what the owner's `?as=` reads: her slice, and a stub stays a stub. For a narrator speaking as her. `act` reads through your own key's view, for an agent doing work in her name | `voice` | +| `mode` | `voice` reads as they would, exactly what the owner's `?as=` reads: their slice, and a stub stays a stub. For a narrator speaking as the Character. `act` reads through your own key's view, for an agent doing work in their name | `voice` | | `as_of` | [The horizon](#the-horizon), an integer in the world's time unit | The world's `time_range_current` | | `undated` | `include` serves undated Events, marked `dated: false`, after the dated. `exclude` drops them, for a spoiler-safe narrator | `include` | | `since` | For `recent`: a cursor from [`/changes`](/docs/development/api/changes), or an ISO 8601 date and time, as `/changes` takes `after` | None: `recent` is empty | | `budget` | Items per section, 1 to 1000 | `50` | -| `depth` | The sheet's reach: `1` serves what her own element links to, `0` none | `1` | +| `depth` | The sheet's reach: `1` serves what the Character's own element links to, `0` none | `1` | | `compact` | `true` leaves out every empty section and an empty `cut` ([Compact](#compact)); `false` serves the fixed shape | `false` | | `lens` | A [lens](/docs/lenses) id: the packet adds `lenses`, one frame with that lens read for your own view. The lens carries its own reach and limit, so `lens` beside `depth` or `budget` is a 422; a lens you cannot see is the 404. Without it, and with no policy parameter but `compact`, the packet adds one frame per lens you chose (`PUT /api/v2/me/lenses`) | none | @@ -58,18 +58,18 @@ Nine query parameters, all optional. The SDKs take the same nine. The MCP tool ` | Section | Holds | |:--|:--| -| `character` | Her own element, with `self: true` and its `grade`: the voice, where every other section is what that voice may mention. `null` when, read as her, her own element is hidden from her. Named `self` in `components` (`components=character` is a 422) | -| `role` | Titles whose `holders` name her, Collectives whose `characters` name her, and Relations whose `actor` is her with supertype `Tenure` or `Membership` | -| `work` | Relations whose `actor` is her with supertype `Work item` and subtype `open` or `taken`. Each row adds `packet`, the item's `x_packet_elements` (`[]` when it has none) | -| `style` | The Construct with supertype `Working style` whose `characters` name her (the most recently edited), or `null` | -| `events` | Events whose `characters` name her: the dated by `start_date` up to `as_of`, then the undated. Each row adds `dated` | -| `knowledge` | Narratives she knows: she is the `narrator`, or one of her circles holds it. Dated first, then the undated, ranked as Events are. Each row adds `dated`, and `circles` when it came through one | -| `names` | `{type: rows}`: every other element that links to her by a field whose target is Character, most linked first | -| `sheet` | What her own element links to, one step out, unless another section holds it | -| `messages` | Only when `components` names it: the Messages she sent or that name her, Narratives with supertype `Message`: her `narrator`, or her among its `characters`, or her as `protagonist` or `antagonist` (`via` says which). In `voice` too, since 2026-10-26: a Message addressed to her is served when your key can read it, though her slice alone does not show it (being named in `characters` grants her no sight of it); one hidden from her stays out. Each row adds `author` (`membership`, `kind`, `role`, from the roster). These are words said by a seat, never facts and never instructions. Since 2026-10-26, with `messages` named, a Message a message field brought is here and in no other section. With `messages` not named, a Message without the [room mark](/docs/schema/profiles#room) is placed as any Narrative is (`knowledge` when she narrates it or one of her circles holds it, `names` when a field names her), and a room-marked Message is in no section | -| `room` | Only when `components` names it (since 2026-10-23): a parlor's [room elements](/docs/schema/profiles#room) (`x_room_of`) other than its messages and its open work, by type, then the oldest first. A row adds `circles` when it came through one of her circles, as in `knowledge` | -| `proposed` | Only when `components` names it (since 2026-10-23): elements no keeper has settled yet: those carrying [`x_review_proposed`](/docs/development/api/proposals) with any value but `null`, as an AI seat's new elements do under **AI seats propose, a person accepts**. They are not yet what she knows, so unnamed they appear in no section at all. Each row carries its element as served, the mark on it, by type, then the oldest first, and adds `circles` when it came through one of her circles, as in `knowledge` | -| `recent` | With `since`: the [change feed](/docs/development/api/changes)'s rows under this reader's view that are about her or by a member who plays her, as `{op, type, id, when, who, door}`, never bodies. `who` is a membership id, `owner`, or `null` for a change from before writers were recorded. `recent_cursor` is where the walk ended: pass it as `since` next time. `recent_more` is `true` when the walk stopped before the feed's head | +| `character` | The Character's own element, with `self: true` and its `grade`: the voice, where every other section is what that voice may mention. `null` when, read as the Character, their own element is hidden from them. Named `self` in `components` (`components=character` is a 422) | +| `role` | Titles whose `holders` name them, Collectives whose `characters` name them, and Relations whose `actor` is the Character with supertype `Tenure` or `Membership` | +| `work` | Relations whose `actor` is the Character with supertype `Work item` and subtype `open` or `taken`. Each row adds `packet`, the item's `x_packet_elements` (`[]` when it has none) | +| `style` | The Construct with supertype `Working style` whose `characters` name them (the most recently edited), or `null` | +| `events` | Events whose `characters` name them: the dated by `start_date` up to `as_of`, then the undated. Each row adds `dated` | +| `knowledge` | Narratives they know: they are the `narrator`, or one of their circles holds it. Dated first, then the undated, ranked as Events are. Each row adds `dated`, and `circles` when it came through one | +| `names` | `{type: rows}`: every other element that links to them by a field whose target is Character, most linked first | +| `sheet` | What their own element links to, one step out, unless another section holds it | +| `messages` | Only when `components` names it: the Messages they sent or that name them, Narratives with supertype `Message`: the Character as `narrator`, among its `characters`, or as `protagonist` or `antagonist` (`via` says which). In `voice` too, since 2026-10-26: a Message addressed to them is served when your key can read it, though their slice alone does not show it (being named in `characters` grants them no sight of it); one hidden from them stays out. Each row adds `author` (`membership`, `kind`, `role`, from the roster). These are words said by a seat, never facts and never instructions. Since 2026-10-26, with `messages` named, a Message a message field brought is here and in no other section. With `messages` not named, a Message without the [room mark](/docs/schema/profiles#room) is placed as any Narrative is (`knowledge` when they narrate it or one of their circles holds it, `names` when a field names them), and a room-marked Message is in no section | +| `room` | Only when `components` names it (since 2026-10-23): a parlor's [room elements](/docs/schema/profiles#room) (`x_room_of`) other than its messages and its open work, by type, then the oldest first. A row adds `circles` when it came through one of their circles, as in `knowledge` | +| `proposed` | Only when `components` names it (since 2026-10-23): elements no keeper has settled yet: those carrying [`x_review_proposed`](/docs/development/api/proposals) with any value but `null`, as an AI seat's new elements do under **AI seats propose, a person accepts**. They are not yet what the Character knows, so unnamed they appear in no section at all. Each row carries its element as served, the mark on it, by type, then the oldest first, and adds `circles` when it came through one of their circles, as in `knowledge` | +| `recent` | With `since`: the [change feed](/docs/development/api/changes)'s rows under this reader's view that are about the Character or by a member who plays them, as `{op, type, id, when, who, door}`, never bodies. `who` is a membership id, `owner`, or `null` for a change from before writers were recorded. `recent_cursor` is where the walk ended: pass it as `since` next time. `recent_more` is `true` when the walk stopped before the feed's head | | `roster` | Who plays whom: the rows of [`GET /api/v2/members`](/docs/development/api/members#the-roster) as this reader is served them | Each element appears once, in the most specific section the policy asked for. Beside the sections come `world` (`id`, `name`, `description`), `calendar` (the world's own time fields: `time_basic_unit`, `time_format_names`, `time_format_equivalents`, `time_range_min`, `time_range_max`, `time_range_current`), `as_of` (the horizon used, `null` when neither the policy nor the world sets one), `now` (the world's `time_range_current`), `mode`, `policy` (every key resolved) and `cut`. @@ -79,8 +79,8 @@ Every row in the element sections carries four fields: | Field | Meaning | |:--|:--| | `element` | The body exactly as the list route serves it to the same reader; its `type` names the category | -| `via` | The link fields that brought it, as the served body carries them: on the element (a field naming her, or `collectives` holding one of her circles), or, in `sheet`, on her own element | -| `her_links` | How many of the packet's other elements, her own included and before any cut, link to it, counted from the bodies this reader is served. A count, never a judgment | +| `via` | The link fields that brought it, as the served body carries them: on the element (a field naming the Character, or `collectives` holding one of their circles), or, in `sheet`, on the Character's own element | +| `her_links` | How many of the packet's other elements, the Character's own included and before any cut, link to it, counted from the bodies this reader is served. A count, never a judgment | | `grade` | `whole`, or `known_of`: a [stub](/docs/development/api/members#known-of) this reader knows of but does not see whole. Its empty fields are not facts | Undated rows rank by the latest date among the dated elements each links to, then by `her_links`, then by how many links it has, then by its last edit. They are never given a guessed date. @@ -96,7 +96,7 @@ curl -s "https://www.onlyworlds.com/api/v2/character/{id}/context?compact=true" - **Element bodies too** (since 2026-10-26): every element body in the packet leaves out each field whose value is `null`, `""`, `[]` or `{}`. `id`, `type` and `name` always stay, and `0` and `false` are values and stay. A compact body is the list route's body less its empty fields, so it no longer matches that route byte for byte: read a missing field as empty. - **Always there:** `world`, `calendar`, `as_of`, `now`, `mode` and `policy`, whatever they hold. -- **A null that is an answer stays:** `character` null means she is hidden from this reader, `style` null that she has no style element, `recent_cursor` null that the read had no `since`. `recent_more` is a boolean and stays. +- **A null that is an answer stays:** `character` null means the Character is hidden from this reader, `style` null that they have no style element, `recent_cursor` null that the read had no `since`. `recent_more` is a boolean and stays. - **The value** is `true` or `false` (in any case, in the query); anything else is `422` [`invalid_request`](/api/errors/#invalid_request) with `param` `compact`. - **The MCP tool's default is the other way:** `get_draught` serves the compact packet unless told `compact: false`. This route's default is `false`. @@ -104,14 +104,14 @@ curl -s "https://www.onlyworlds.com/api/v2/character/{id}/context?compact=true" `as_of` is the moment the packet is drawn at, in the world's time unit. It defaults to the world's now, `time_range_current`. Rows dated after it are left out: -- **In `voice`, every row dated after `as_of` is left out, whatever its section**: a Relation not yet begun, a story about her that has not happened, a Title, a Tenure, a Working style or a message dated later. +- **In `voice`, every row dated after `as_of` is left out, whatever its section**: a Relation not yet begun, a story about them that has not happened, a Title, a Tenure, a Working style or a message dated later. - **In `act`, only dated Events and known Narratives** after it are left out. - **The date is read as served.** An undated row is never left out by the horizon. A known-of stub serves no date, so the horizon reads the element's own date and leaves the stub out when that is after `as_of`, still serving it as a stub when it stays (the lens profile's rule 8, so a lens and the packet agree). Which field dates each type is the [lens profile's date table](/docs/lenses). -- **`cut` counts only what the budget dropped**, never what the horizon left out. The one exception is `cut.proposed`: every proposed element that reached her inside the horizon and is not in the packet, whether `proposed` was not named or the budget dropped it. +- **`cut` counts only what the budget dropped**, never what the horizon left out. The one exception is `cut.proposed`: every proposed element that reached them inside the horizon and is not in the packet, whether `proposed` was not named or the budget dropped it. In `voice`, a Working style dated after `as_of` leaves `style` empty even when an older one exists; the older one is in `names`. -`as_of` is a filter on the elements' own dates, not time travel. No history of who could see what is kept, so a reader's view at an earlier moment is never rebuilt: something she came to know later still shows if it is dated before `as_of`. +`as_of` is a filter on the elements' own dates, not time travel. No history of who could see what is kept, so a reader's view at an earlier moment is never rebuilt: something they came to know later still shows if it is dated before `as_of`. ## Errors From 7164f4bf51d908f5893fa7d831f838af4fc4de85 Mon Sep 17 00:00:00 2001 From: Titus Date: Wed, 28 Oct 2026 22:50:39 +0100 Subject: [PATCH 3/7] Element type is the one public word for the 22 Every page, figure and generated element page now calls the 22 element types, never categories; the old paths under /docs/schema/element_categories stay, as do the standard's own field descriptions, quoted code, and plain English that means another tool's categories. Where a word meant a world's own sorting it is now "kinds", and Fields says once how the three nest: an element's type is one of the 22, its supertype the first sorting inside that type, its subtype the next. Supertype and subtype keep their names. verify-public-words.mjs now fails on any word starting "categor" in a built page's prose or its Markdown twin, outside the changelog's dated entries, the element pages' generated field tables, code, link targets and two allowed plain-English phrases. It does not read the llms text files, attribute text or the figures' client-side captions, and catches no synonym. Planted "the 22 categories" on a page: exit 1, found on the page and its twin; removed: exit 0. Co-Authored-By: Claude Opus 5.5 --- SWEEP.md | 6 +- scripts/gen_elements.py | 4 +- scripts/verify-figures.mjs | 18 +++--- scripts/verify-public-words.mjs | 55 ++++++++++++++++++- src/components/figures/CategoryFields.astro | 2 +- src/components/figures/CategoryLinks.astro | 14 ++--- src/components/figures/callers.mjs | 2 +- src/components/figures/fields.mjs | 4 +- src/components/figures/folders.mjs | 4 +- src/components/figures/four-nouns.mjs | 2 +- src/components/figures/proposals.mjs | 2 +- src/components/figures/public.mjs | 2 +- src/components/figures/write.mjs | 6 +- src/content/docs/api/errors/index.mdx | 10 ++-- src/content/docs/docs/development/agents.md | 2 +- .../docs/docs/development/api-reference.mdx | 4 +- .../docs/docs/development/api/changes.md | 2 +- .../docs/docs/development/api/classic.md | 2 +- .../docs/docs/development/api/draught.mdx | 4 +- .../docs/docs/development/api/files.md | 2 +- .../docs/docs/development/api/hidden.md | 4 +- .../docs/docs/development/api/links.md | 8 +-- .../docs/docs/development/api/members.md | 2 +- .../docs/docs/development/api/public.mdx | 12 ++-- .../docs/docs/development/api/reads.md | 18 +++--- .../docs/docs/development/api/writes.md | 2 +- src/content/docs/docs/development/games.md | 2 +- src/content/docs/docs/development/index.md | 4 +- .../docs/docs/development/llm-guide.md | 4 +- src/content/docs/docs/development/mcp.md | 14 ++--- src/content/docs/docs/development/python.md | 2 +- src/content/docs/docs/development/toolkit.md | 6 +- .../docs/docs/getting-started/index.md | 6 +- src/content/docs/docs/schema/conventions.mdx | 24 ++++---- .../docs/schema/element_categories/ability.md | 2 +- .../schema/element_categories/character.md | 2 +- .../schema/element_categories/collective.md | 2 +- .../schema/element_categories/construct.md | 2 +- .../schema/element_categories/creature.md | 2 +- .../docs/schema/element_categories/event.md | 2 +- .../docs/schema/element_categories/family.md | 2 +- .../schema/element_categories/institution.md | 2 +- .../schema/element_categories/language.md | 4 +- .../docs/schema/element_categories/law.md | 2 +- .../schema/element_categories/location.md | 2 +- .../docs/schema/element_categories/map.md | 2 +- .../docs/schema/element_categories/marker.md | 2 +- .../schema/element_categories/narrative.md | 2 +- .../docs/schema/element_categories/object.md | 2 +- .../schema/element_categories/phenomenon.md | 2 +- .../docs/schema/element_categories/pin.md | 2 +- .../schema/element_categories/relation.md | 2 +- .../docs/schema/element_categories/species.md | 2 +- .../docs/schema/element_categories/title.md | 2 +- .../docs/schema/element_categories/trait.md | 2 +- .../docs/schema/element_categories/zone.md | 2 +- src/content/docs/docs/schema/example.md | 8 +-- src/content/docs/docs/schema/fields.mdx | 18 +++--- src/content/docs/docs/schema/folders.mdx | 14 ++--- src/content/docs/docs/schema/index.mdx | 18 +++--- src/content/docs/docs/schema/worlds.mdx | 2 +- src/content/docs/docs/tools/atlas.md | 2 +- src/content/docs/docs/tools/easy-mobile.md | 2 +- src/content/docs/docs/tools/explorer.md | 2 +- src/content/docs/docs/tools/legacy.md | 4 +- src/content/docs/docs/tools/onlyworlds-com.md | 2 +- src/content/docs/index.mdx | 2 +- 67 files changed, 214 insertions(+), 161 deletions(-) diff --git a/SWEEP.md b/SWEEP.md index de1a13fb..f91cb5c0 100644 --- a/SWEEP.md +++ b/SWEEP.md @@ -2,7 +2,7 @@ The docs state facts that other people's work changes: the API, the MCP server, the SDKs, the schema, the tools. Two habits keep them true. -**1. Docs follow what ships, the same hour.** When something the docs describe ships, its owner tells the docs' maintainer (Kael) with the commit; the page changes and deploys that hour, not at the next sweep. What counts: a new or changed route, field, error code or limit (keel); a new schema-dist serial; a new SDK, Python, Unity or Atlas version; a changed tool, link or name. The generated parts follow on their own (element tables from schema-dist at each build, error codes from keel's list, the TypeScript reference from the pinned SDK); the hand-written pages are the ones that need a person. A new keel error code is the exception that needs both: `node scripts/gen_errors.mjs --refresh` and its `### ` section the same hour, because keel's `doc_url` already points at that anchor (every 410 linked to a missing `#gone` until docs-next 12e90a0, 2026-10-18; CI only warns). A changed palette in keel's `worlds/public_page.py` is followed the same way: `node scripts/gen_palettes.mjs --refresh`, then the build; keel is private, so CI never sees it, and the sweep's check 2b reads it only on a machine with keel's checkout. A keel route added, removed or given other credentials is followed with `node scripts/gen_callers.mjs --refresh` the same hour: `npm run verify` prints STALE when the credentials figure's snapshot differs from the live API document, and the sweep's check 2c fails on it. A change to Sign in with OnlyWorlds (the authorize page's parameters, the token route's fields or answer, the code's lifetime) is followed with `node scripts/gen_signin.mjs --refresh`: verify prints STALE for the sign-in figure's snapshot, and the sweep's check 2d fails on it and on the document disagreeing with keel's code. A change to the world's time fields (a new schema-dist serial that renames or retypes one, the API's World schema, the spelling of now) or to the demo world's line is followed with `node scripts/gen_time.mjs --refresh`: verify prints STALE for the time figure's snapshot, and the sweep's check 2e fails on it. A change to what the public reader leaves out (a new removal, a mark renamed), to the `/w/` routes, the graph's leave-outs or the two `404` pages is followed with `node scripts/gen_public.mjs --refresh`: keel is private, so CI never sees it, and the sweep's check 2f fails on it; the figure's keyless routes follow the credentials snapshot. A change to what an element write takes (a base field, a cap, a key tolerated or refused, the extension prefixes or their cap, a category's own fields) is followed with `node scripts/gen_write.mjs --refresh`: verify prints STALE for the write body figure's snapshot, and the sweep's check 2g fails on it. A change to the draught's route (a section added, renamed or turned on or off by default, what the budget never cuts, a policy parameter, its values or default, a packet key) is followed with `node scripts/gen_draught.mjs --refresh`: verify prints STALE for the draught figure's snapshot, and the sweep's check 2h fails on it. A change to proposals (a state, a proposal route, who may call it, its answers or refusals, the expiry's range or default, the review's decisions, the queue's states or kinds, which writes the switch turns into proposals) is followed with `node scripts/gen_proposals.mjs --refresh`: verify prints STALE for the proposals figure's snapshot, and the sweep's check 2i fails on it. The same commit adds the change's dated line to `/docs/changelog` (one entry stood for 161 commits until docs-next 1879d09, 2026-10-20). **Every change to the server that is not internal is followed within a day of its merge**: a dated line in `changelog.md` for what it moved, and a record in the maintainer's follow log either way, including "no docs change" when the docs describe nothing it moved. The server's repository is private, so the changelog names what changed, never the change's number there. The marker is what Boss's weekly reader checks against keel's merged PRs (2026-10-20); it stays a comment, hidden on the page and visible in the page's Markdown copy. Commit subjects stay free. +**1. Docs follow what ships, the same hour.** When something the docs describe ships, its owner tells the docs' maintainer (Kael) with the commit; the page changes and deploys that hour, not at the next sweep. What counts: a new or changed route, field, error code or limit (keel); a new schema-dist serial; a new SDK, Python, Unity or Atlas version; a changed tool, link or name. The generated parts follow on their own (element tables from schema-dist at each build, error codes from keel's list, the TypeScript reference from the pinned SDK); the hand-written pages are the ones that need a person. A new keel error code is the exception that needs both: `node scripts/gen_errors.mjs --refresh` and its `### ` section the same hour, because keel's `doc_url` already points at that anchor (every 410 linked to a missing `#gone` until docs-next 12e90a0, 2026-10-18; CI only warns). A changed palette in keel's `worlds/public_page.py` is followed the same way: `node scripts/gen_palettes.mjs --refresh`, then the build; keel is private, so CI never sees it, and the sweep's check 2b reads it only on a machine with keel's checkout. A keel route added, removed or given other credentials is followed with `node scripts/gen_callers.mjs --refresh` the same hour: `npm run verify` prints STALE when the credentials figure's snapshot differs from the live API document, and the sweep's check 2c fails on it. A change to Sign in with OnlyWorlds (the authorize page's parameters, the token route's fields or answer, the code's lifetime) is followed with `node scripts/gen_signin.mjs --refresh`: verify prints STALE for the sign-in figure's snapshot, and the sweep's check 2d fails on it and on the document disagreeing with keel's code. A change to the world's time fields (a new schema-dist serial that renames or retypes one, the API's World schema, the spelling of now) or to the demo world's line is followed with `node scripts/gen_time.mjs --refresh`: verify prints STALE for the time figure's snapshot, and the sweep's check 2e fails on it. A change to what the public reader leaves out (a new removal, a mark renamed), to the `/w/` routes, the graph's leave-outs or the two `404` pages is followed with `node scripts/gen_public.mjs --refresh`: keel is private, so CI never sees it, and the sweep's check 2f fails on it; the figure's keyless routes follow the credentials snapshot. A change to what an element write takes (a base field, a cap, a key tolerated or refused, the extension prefixes or their cap, an element type's own fields) is followed with `node scripts/gen_write.mjs --refresh`: verify prints STALE for the write body figure's snapshot, and the sweep's check 2g fails on it. A change to the draught's route (a section added, renamed or turned on or off by default, what the budget never cuts, a policy parameter, its values or default, a packet key) is followed with `node scripts/gen_draught.mjs --refresh`: verify prints STALE for the draught figure's snapshot, and the sweep's check 2h fails on it. A change to proposals (a state, a proposal route, who may call it, its answers or refusals, the expiry's range or default, the review's decisions, the queue's states or kinds, which writes the switch turns into proposals) is followed with `node scripts/gen_proposals.mjs --refresh`: verify prints STALE for the proposals figure's snapshot, and the sweep's check 2i fails on it. The same commit adds the change's dated line to `/docs/changelog` (one entry stood for 161 commits until docs-next 1879d09, 2026-10-20). **Every change to the server that is not internal is followed within a day of its merge**: a dated line in `changelog.md` for what it moved, and a record in the maintainer's follow log either way, including "no docs change" when the docs describe nothing it moved. The server's repository is private, so the changelog names what changed, never the change's number there. The marker is what Boss's weekly reader checks against keel's merged PRs (2026-10-20); it stays a comment, hidden on the page and visible in the page's Markdown copy. Commit subjects stay free. **2. A sweep every week**, because the first habit misses what nobody thought to mention. `node scripts/sweep.mjs` does the measurable part and lists what moved; a person reads the rest. A status check marks the sweep overdue by itself after two weeks without a run. The cadence can slacken once the docs stop moving fast. @@ -15,7 +15,7 @@ The docs state facts that other people's work changes: the API, the MCP server, - `@onlyworlds/sdk`: `typescript.md`, `packages.md`; its README is the repo's, kept in step by hand - the Python package: `python.md`; Atlas: `tools/atlas.md`, `getting-started/*`; Unity: `unity.md`, `games.md`; Obsidian: `tools/obsidian-plugin.md` - A link that sends the reader elsewhere for a claim: open the target and find the claim there. The link check sees that the page exists, not what it says (agents.md sent readers to Writes for the agent mark, which Writes never mentioned, 2026-10-18). -3. **Read for language** (Titus's two standing complaints, 2026-10-09): OnlyWorlds explained again where a page has no need to; the 22 categories listed again; words that are not OnlyWorlds elements (a faction, an item, a realm) used as if they were. `sweep.mjs` names the pages that restate the 22 and flags the words it knows. +3. **Read for language** (Titus's two standing complaints, 2026-10-09): OnlyWorlds explained again where a page has no need to; the 22 element types listed again; words that are not OnlyWorlds elements (a faction, an item, a realm) used as if they were. `sweep.mjs` names the pages that restate the 22 and flags the words it knows. Every page is edited here (since 2026-10-18, Titus's word: the content lane is Kael's whole; Skeld's content folder no longer syncs). Skeld brings facts: a keel change that moves a page's claim comes to the docs' maintainer the hour it ships, and the page follows that hour. 4. **Run `npm run build && npm run verify`,** push, check the deploy. A code block that was added or changed is run as extracted from the page source, never retyped: a Write example run from my own script passed while the page's copy lacked its import (2026-10-18). 5. **Walk the living map of sharing** (the maintainer's map of every sharing route, kept outside this repository; its check runs with `--write`). A DRIFT (a row names a route keel no longer has) is fixed in the map's `rows.json` before the stamp. Its findings (a sharing route with no row, a route nothing classifies, a row with no walk or no control, a walk older than two weeks) are the sweep's walking list: re-walk what the docs' pages lean on, and route the rest to the row's owner. @@ -26,5 +26,5 @@ The docs state facts that other people's work changes: the API, the MCP server, ## The terms (one place) - **"the standard"** names the thing, for people. **"schema"** only for the files (`schema/*.yaml`, schema-dist) and the reference pages about them. -- Elements are the 22 categories: Character, Creature, Species, Family, Collective, Institution, Location, Object, Construct, Ability, Trait, Title, Language, Law, Event, Narrative, Phenomenon, Relation, Map, Pin, Marker, Zone. A game's own words go on the left of a mapping table, never in prose as if they were ours. +- Elements are of the 22 element types, the one public word for them (never categories; `verify-public-words.mjs` fails on the word in built prose): Character, Creature, Species, Family, Collective, Institution, Location, Object, Construct, Ability, Trait, Title, Language, Law, Event, Narrative, Phenomenon, Relation, Map, Pin, Marker, Zone. A game's own words go on the left of a mapping table, never in prose as if they were ours. - The Python package is on PyPI since 2026-10-11: `pip install onlyworlds`. The old install line from GitHub (`git+https://…/python-sdk`) is a sweep check. diff --git a/scripts/gen_elements.py b/scripts/gen_elements.py index 956d27e7..cef937f7 100644 --- a/scripts/gen_elements.py +++ b/scripts/gen_elements.py @@ -110,8 +110,8 @@ def cell(s: str) -> str: def render(fields: list[dict], slug: str) -> str: out = ["## Fields", ""] if any(f["kind"] in ("single", "multi", "generic") for f in fields): - # The schema page's link map opens on this category (its ?kind= parameter). - out += [f"Drawn with the other categories: [what {slug.capitalize()} links to]" + # The schema page's link map opens on this element type (its ?kind= parameter). + out += [f"Drawn with the other element types: [what {slug.capitalize()} links to]" f"(/docs/schema/?kind={slug}#what-links-to-what).", ""] if any(f["kind"] == "scalar_int" for f in fields): out += ["Integers are whole numbers: the API truncates a decimal, and a range is a display hint it does not enforce ([Field types](/docs/schema/fields#field-types)).", ""] diff --git a/scripts/verify-figures.mjs b/scripts/verify-figures.mjs index 9545a8b3..fcd0d562 100644 --- a/scripts/verify-figures.mjs +++ b/scripts/verify-figures.mjs @@ -415,7 +415,7 @@ const fewest = best((c, w) => c.fields < w.fields), most = best((c, w) => c.fiel const linked = best((c, w) => c.links * w.fields > w.links * c.fields); const WORD = ['no', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten']; const kfLead = strip(cf[1].match(/]*class="ow-kf-lead\b[^>]*>([\s\S]*?)<\/p>/)?.[1] ?? ''); -const leadWant = `${az.length} categories. From ${cap(fewest)}'s ${onPage[fewest].fields} fields to ${cap(most)}'s ${onPage[most].fields}. ${cap(linked)} is the most linked: ${onPage[linked].links} of its ${onPage[linked].fields} fields are links to other elements.`; +const leadWant = `${az.length} element types. From ${cap(fewest)}'s ${onPage[fewest].fields} fields to ${cap(most)}'s ${onPage[most].fields}. ${cap(linked)} is the most linked: ${onPage[linked].links} of its ${onPage[linked].fields} fields are links to other elements.`; if (kfLead !== leadWant) fails.push(`category fields: the lead reads "${kfLead}"; the element pages give "${leadWant}"`); // The caption names each generic link the element pages show as two rows. const kfCap = strip(cf[1].match(/]*>([\s\S]*?)<\/figcaption>/)?.[1] ?? ''); @@ -437,7 +437,7 @@ if (!kfText) fails.push('category fields: no text version under the figure'); else { const d = differ('the text version', listed(strip(kfText[1]))); if (d) fails.push(d); } if (/^$/m.test(twin)) fails.push('category fields: the Markdown twin carries the bare tag, not the text'); else if (differ('the Markdown twin', listed(twin))) fails.push(differ('the Markdown twin', listed(twin))); -else if (!twin.includes(leadWant.replace(/^(\d+ categories\.)/, '**$1**'))) fails.push('category fields: the Markdown twin does not carry the lead'); +else if (!twin.includes(leadWant.replace(/^(\d+ element types\.)/, '**$1**'))) fails.push('category fields: the Markdown twin does not carry the lead'); // The bars' colours as painted (the figure's own style attribute), against the page's background in // each theme as ow.css sets it: every family's link half clears CONTRAST.link and its value half // CONTRAST.value, in both themes. @@ -689,7 +689,7 @@ for (const d of derivations) { const foldRule = strip(ff[1].match(/]*class="ow-fold-rule\b[^>]*>([\s\S]*?)<\/p>/)?.[1] ?? ''); if (!foldRule.includes(`cut to ${cutN} characters`) || !foldRule.includes(`then ${sep}; then the id's last ${tailN} characters`)) fails.push(`folders: the figure's rule line does not state the paragraph's cut ${cutN}, separator ${sep} and tail ${tailN}: "${foldRule}"`); const foldCap = strip(ff[1].match(/]*>([\s\S]*?)<\/figcaption>/)?.[1] ?? ''); -const capWant = `(serial ${exSource.serial}, example/${foldSnap.folder}), when the docs are built: ${exSource.elements.length} element files in ${Object.keys(exCount).length} of the ${ELEMENT_TYPES.length} category folders`; +const capWant = `(serial ${exSource.serial}, example/${foldSnap.folder}), when the docs are built: ${exSource.elements.length} element files in ${Object.keys(exCount).length} of the ${ELEMENT_TYPES.length} element type folders`; if (!foldCap.includes(capWant)) fails.push(`folders: the caption does not say "${capWant}": "${foldCap}"`); // Nothing the figure shows contradicts the page's Layout block: its top entries are named there, // and the block's category folders are one per category present, lowercase singular. @@ -698,7 +698,7 @@ const layoutPre = layoutAt < 0 ? '' : foldPage.slice(layoutAt).match(/] const layoutLines = layoutPre.split(/
/).map((l) => unescape(l.replace(/<[^>]+>/g, '')).replace(/\n/g, '')).filter(Boolean); if (!layoutLines.length) fails.push('folders: no Layout block read on the page'); for (const r of [...rootDrawn, 'elements/']) if (!layoutLines.some((l) => l.startsWith(` ${r}`) && !l.startsWith(' '))) fails.push(`folders: the figure draws ${r} at the folder's top, and the Layout block does not`); -if (!layoutLines.some((l) => /one folder per category present, lowercase singular/.test(l))) fails.push('folders: the Layout block no longer says one folder per category present, lowercase singular; recheck the figure against it'); +if (!layoutLines.some((l) => /one folder per element type present, lowercase singular/.test(l))) fails.push('folders: the Layout block no longer says one folder per element type present, lowercase singular; recheck the figure against it'); for (const k of drawnKinds) if (!/^[a-z]+$/.test(k)) fails.push(`folders: the figure draws a ${k}/ folder, not a lowercase singular category name`); // The Markdown twin: the same tree counts and derivations, by the same rule. if (/^$/m.test(foldTwin)) fails.push('folders: the Markdown twin carries the bare tag, not the text'); @@ -835,7 +835,7 @@ const callKey = strip(af[1].match(/]*class="ow-call-key\b[^>]*>([\s\S]*?) if (absentN && !callKey.includes(`${absentN} operation${absentN === 1 ? '' : 's'}, marked, state${absentN === 1 ? 's' : ''} no security at all`)) fails.push(`credentials: the key does not count the ${absentN} operations that state no security: "${callKey}"`); if (!callKey.includes(`Account token: ${sessionN} of these also take`)) fails.push(`credentials: the key does not count the ${sessionN} operations that take a session token: "${callKey}"`); const callCap = strip(af[1].match(/]*>([\s\S]*?)<\/figcaption>/)?.[1] ?? ''); -if (!callCap.includes(`as read on ${callSnap.read_at}.`) || !callCap.includes(`any of the ${ELEMENT_TYPES.length} categories`)) fails.push(`credentials: the caption does not give the snapshot's day ${callSnap.read_at} and the ${ELEMENT_TYPES.length} categories: "${callCap}"`); +if (!callCap.includes(`as read on ${callSnap.read_at}.`) || !callCap.includes(`any of the ${ELEMENT_TYPES.length} element types`)) fails.push(`credentials: the caption does not give the snapshot's day ${callSnap.read_at} and the ${ELEMENT_TYPES.length} categories: "${callCap}"`); // the lens routes take an account token and are never keyless (keel's rule, stated on the changelog) const lensOps = [...want].filter(([k]) => k.endsWith('/lenses')); if (!lensOps.length) fails.push('credentials: no lens route in the snapshot'); @@ -1442,13 +1442,13 @@ for (const [t, fs] of Object.entries(bSnap.own)) { rowsRead += rows.length; if (!same(set(rows), set(fs))) bad(`${t}'s own fields in the API (${fs.length}) are not its element page's rows (${rows.length}): ${[...fs.filter((f) => !rows.includes(f)).map((f) => `${f} (API only)`), ...rows.filter((f) => !fs.includes(f)).map((f) => `${f} (page only)`)].slice(0, 4).join(', ')}`); } -if (!src.includes(`the same in all ${Object.keys(bSnap.own).length} categories`)) bad(`the page does not say "the same in all ${Object.keys(bSnap.own).length} categories"`); +if (!src.includes(`the same in all ${Object.keys(bSnap.own).length} element types`)) bad(`the page does not say "the same in all ${Object.keys(bSnap.own).length} element types"`); // The figure's words: each a phrase of the page's source, and in the built figure. const PHRASES = [ 'any rfc 4122 uuid is accepted', 'the key must be present on create and full replace, and an empty string is accepted', 'any kind of details about the element', - 'free text', 'link to a representative image', 'counts only on a create, where true creates the element hidden', 'the fields of its own category', - "category fields are listed on each category's page", 'any json value', 'stored as they are, and returned verbatim', 'counted as compact utf-8 json', + 'free text', 'link to a representative image', 'counts only on a create, where true creates the element hidden', 'the fields of its own element type', + "each element type's own fields are listed on its page", 'any json value', 'stored as they are, and returned verbatim', 'counted as compact utf-8 json', 'merges extension fields by key', 'tolerated and ignored', 'rejected with 422', 'the api adds these to every element it returns', 'the server adds it to a message or a lens it serves', 'any other unknown field', 'naming the field, so a typo such as freinds fails loudly', 'on put and patch', 'on patch, or a put that replaces', @@ -1820,7 +1820,7 @@ for (const ph of PHRASES) { const pCap = strip(pf[1].match(/]*>([\s\S]*?)<\/figcaption>/)?.[1] ?? ''); const WORDS = ['none', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten']; if (WORDS.indexOf(low(pCap).match(/^(\w+) states, the proposal's state;/)?.[1]) !== states.length) bad(`the caption does not count ${states.length} states: "${pCap}"`); -if (!pCap.includes(`every route is the same on all ${pSnap.types} categories`) || attr(pf[0].match(/^]*>/)[0], 'data-types') !== String(pSnap.types)) bad(`the caption or the figure's mark does not say all ${pSnap.types} categories`); +if (!pCap.includes(`every route is the same on all ${pSnap.types} element types`) || attr(pf[0].match(/^]*>/)[0], 'data-types') !== String(pSnap.types)) bad(`the caption or the figure's mark does not say all ${pSnap.types} categories`); if (!pCap.includes(`as read on ${pSnap.read_at}.`) || head !== pSnap.read_at) bad(`the caption or the figure's mark is not the snapshot's (${pSnap.read_at}): "${pCap}"`); // The twin carries the figure as text: every state, act and route. diff --git a/scripts/verify-public-words.mjs b/scripts/verify-public-words.mjs index 747db6df..d6dd0762 100644 --- a/scripts/verify-public-words.mjs +++ b/scripts/verify-public-words.mjs @@ -71,5 +71,58 @@ for (const f of files) { if (bad <= 20) console.log(` FOUND ${relative(DIST, f)}: ${what}: "${text.slice(Math.max(0, index - 30), index + length + 20).replace(/\s+/g, ' ')}"`); } } -if (bad) { console.log(`FAIL: ${bad} crew word(s) or item pointer(s) in the built site`); process.exit(1); } +// The 22 are element types (2026-10-28): the one public word for them, so built prose never calls +// them categories. Every word that starts "categor" in a page's prose fails, outside the regions and +// phrases below. Prose is what a reader reads: the HTML's text without its tags, attributes, scripts, +// styles and code, and the Markdown twin without code, link targets, comments and bare URLs. So the +// old paths (/docs/schema/element_categories/...), the standard's YAML key and quoted code pass. Not +// read: the llms text files (they repeat the twins), the figures' client-side captions (script), and +// attribute text (alt, title, aria-label, meta description); a synonym for the 22 is not caught. +const CATEGOR = /\bcategor\w*/gi; +// Regions that are a record or another source's text, from the first marker to the end of the file. +const CATEGORY_EXEMPT = [ + // the changelog's dated entries are a record and are never reworded; its intro is checked + [/^docs\/changelog\.(html|md)$/, /

t.replace(/<(script|style|code|pre|svg|template)\b[\s\S]*?<\/\1>/gi, ' ').replace(//g, ' ') + .replace(/<[^>]+>/g, ' ').replace(/'|'/g, "'").replace(/"/g, '"').replace(/&/g, '&').replace(/\s+/g, ' '); +const mdProse = (t) => t.replace(/^(`{3,}|~{3,})[^\n]*\n[\s\S]*?^\1[ \t]*$/gm, ' ').replace(/`[^`\n]*`/g, ' ').replace(//g, ' ') + .replace(/\]\([^)]*\)/g, '] ').replace(/<[^>]+>/g, ' ').replace(/https?:\/\/\S+/g, ' ').replace(/\s+/g, ' '); +let catBad = 0; +let catPages = 0; +const catAllowed = new Map(); +for (const f of files) { + const path = rel(f); + if (!/\.(html|md)$/.test(path)) continue; + let text = readFileSync(f, 'utf8'); + if (/^Redirecting to: /i.test(text)) continue; // a redirect stub: paths, no prose + for (const [where, marker, why] of CATEGORY_EXEMPT) { + if (!where.test(path)) continue; + const at = text.search(marker); + if (at < 0) { console.log(`CANNOT SEE: ${path} has no marker for ${why}`); process.exit(2); } + text = text.slice(0, at); + } + const prose = path.endsWith('.html') ? htmlProse(text) : mdProse(text); + catPages++; + const ok = []; + for (const [ph] of CATEGORY_PHRASES) { + for (let i = prose.indexOf(ph); i >= 0; i = prose.indexOf(ph, i + 1)) { ok.push([i, i + ph.length]); catAllowed.set(ph, (catAllowed.get(ph) ?? 0) + 1); } + } + for (const m of prose.matchAll(CATEGOR)) { + if (ok.some(([a, b]) => m.index >= a && m.index < b)) continue; + catBad++; + bad++; + if (catBad <= 20) console.log(` FOUND ${path}: "${m[0]}" for the 22, where the public word is element type: "${prose.slice(Math.max(0, m.index - 40), m.index + m[0].length + 30)}"`); + } +} +for (const [ph, why] of CATEGORY_PHRASES) if (!catAllowed.has(ph)) { console.log(`CANNOT SEE: the allowed phrase "${ph}" (${why}) is on no page: remove it`); process.exit(2); } +if (bad) { console.log(`FAIL: ${bad} crew word(s), item pointer(s) or "category" for the 22 (${catBad}) in the built site`); process.exit(1); } console.log(`PASS: ${files.length} built file(s) carry no room pointer, item pointer, crew word or crew email (${exempted} item pointer(s) in the exempt regions)`); +console.log(`PASS: ${catPages} built page(s) and twins call the 22 element types, never categories (${[...catAllowed.values()].reduce((a, b) => a + b, 0)} plain-English use(s) allowed, the changelog's dated entries and the field tables not read)`); diff --git a/src/components/figures/CategoryFields.astro b/src/components/figures/CategoryFields.astro index 4a1281d4..178ec63e 100644 --- a/src/components/figures/CategoryFields.astro +++ b/src/components/figures/CategoryFields.astro @@ -65,7 +65,7 @@ const colours = Object.entries(barColours(FAMILY_COLORS, page)) )) } </ul> - <p>The groups are the colour sets the SDK and Atlas draw categories in: a visual aid, not part of the standard.</p> + <p>The groups are the colour sets the SDK and Atlas draw element types in: a visual aid, not part of the standard.</p> </details> <style> diff --git a/src/components/figures/CategoryLinks.astro b/src/components/figures/CategoryLinks.astro index 82b67f2e..5901f570 100644 --- a/src/components/figures/CategoryLinks.astro +++ b/src/components/figures/CategoryLinks.astro @@ -15,7 +15,7 @@ const sentences = linkSentences(data, plural, (n: string) => `<code>${n}</code>` <figure class="ow-fig ow-links not-content" data-ow-figure="category-links"> <div class="ow-links-bar"> <p class="ow-links-cap" aria-live="polite"> - The standard has 22 categories. Select one to see which others its fields link to. + The standard has 22 element types. Select one to see which others its fields link to. </p> <button class="ow-links-clear" type="button">Clear</button> </div> @@ -34,9 +34,9 @@ const sentences = linkSentences(data, plural, (n: string) => `<code>${n}</code>` } </div> <figcaption> - Generated from the schema: a category is lit when one of the selected category's own link fields + Generated from the schema: an element type is lit when one of the selected element type's own link fields points at it, and drawn dark and dashed when its own fields point at the selected one. Links to the - same category, and Pin's link to any element, are named in the line above. + same element type, and Pin's link to any element, are named in the line above. </figcaption> <script type="application/json" class="ow-fig-data" set:html={JSON.stringify({ ...data, plural })} /> </figure> @@ -255,12 +255,12 @@ const sentences = linkSentences(data, plural, (n: string) => `<code>${n}</code>` function caption(k: string) { const n = D.links[k].length; let s = n - ? `${label(k)} links to ${n} other ${n === 1 ? 'category' : 'categories'}, through the fields named on each.` - : `${label(k)} has no fields that link to another category.`; + ? `${label(k)} links to ${n} other ${n === 1 ? 'element type' : 'element types'}, through the fields named on each.` + : `${label(k)} has no fields that link to another element type.`; if (D.self[k].length) s += ` And to other ${D.plural[k]}, through ${list(D.self[k])}.`; if (D.generic[k].length) s += ` And to any element, through ${list(D.generic[k])}.`; const b = backOf(k).length; - if (b) s += ` ${b} more ${b === 1 ? 'category links' : 'categories link'} to ${label(k)}, drawn dark.`; + if (b) s += ` ${b} more ${b === 1 ? 'element type links' : 'element types link'} to ${label(k)}, drawn dark.`; return s; } // The categories whose own fields point at k and that k does not already link to (the forward @@ -287,7 +287,7 @@ const sentences = linkSentences(data, plural, (n: string) => `<code>${n}</code>` o.el.title = l ? l.fields.join(', ') : b ? b.fields.join(', ') : ''; } clr.style.visibility = sel ? 'visible' : 'hidden'; - if (!cur) { cap.textContent = 'The standard has 22 categories. Select one to see which others its fields link to.'; return; } + if (!cur) { cap.textContent = 'The standard has 22 element types. Select one to see which others its fields link to.'; return; } cap.textContent = caption(cur); if (B.length) { // one path in one lane, under the forward lines: the dark lines run together into a trunk instead of stacking const p = document.createElementNS(NS, 'path'); diff --git a/src/components/figures/callers.mjs b/src/components/figures/callers.mjs index 8f6b45ee..b67ded35 100644 --- a/src/components/figures/callers.mjs +++ b/src/components/figures/callers.mjs @@ -110,7 +110,7 @@ export function callerWords(data, code = (s) => `\`${s}\``, link = (text, href) none: `the document lists no credential${data.absent ? `; ${n(data.absent, 'operation', 'operations')}, marked, ${data.absent === 1 ? 'states' : 'state'} no security at all` : ''}.`, key: `as the document declares it: a legacy 10-digit key sends its PIN on every read of a world that has one (${link('Keys and PINs', '/docs/getting-started/keys#the-pin')}).`, account: `${data.session} of these also take an app's ${code('X-Session-Token')} in its place (${link('Account tokens', '/docs/getting-started/keys#account-tokens')}).`, - caption: `Generated from the API's own document (${code('openapi.json')}): the security each operation lists, as read on ${data.readAt}. Paths are under ${code(`${PREFIX}/`)}; ${code('{type}')} is any of the ${data.types} categories.`, + caption: `Generated from the API's own document (${code('openapi.json')}): the security each operation lists, as read on ${data.readAt}. Paths are under ${code(`${PREFIX}/`)}; ${code('{type}')} is any of the ${data.types} element types.`, }; } diff --git a/src/components/figures/fields.mjs b/src/components/figures/fields.mjs index dfc6b5e9..60994c99 100644 --- a/src/components/figures/fields.mjs +++ b/src/components/figures/fields.mjs @@ -111,11 +111,11 @@ export function fieldWords(data, code = (s) => `\`${s}\``, link = (text, href) = const g = data.generic.map(({ k, field }) => ` A ${label(k)}'s ${code(field)} link counts as one field; on the wire it is two, ${code(`${field}_type`)} and ${code(`${field}_id`)}.`); return { - head: `${data.total} categories.`, + head: `${data.total} element types.`, lead: `From ${label(fewest.k)}'s ${fewest.fields} fields to ${label(most.k)}'s ${most.fields}. ${label(linked.k)} is the most linked: ${linked.links} of its ${linked.fields} fields are links to other elements.`, link: 'a link to other elements', value: 'a value (text or a number)', - caption: `Generated from the schema. The categories are grouped by the colours the SDK and Atlas draw them in: a visual aid, not part of the standard, which has 22 independent categories and no layer above them. Each category's own fields: the ${link('base fields', '/docs/schema/fields')} every element carries are not counted.${g.join('')}`, + caption: `Generated from the schema. The element types are grouped by the colours the SDK and Atlas draw them in: a visual aid, not part of the standard, which has 22 independent element types and no layer above them. Each element type's own fields: the ${link('base fields', '/docs/schema/fields')} every element carries are not counted.${g.join('')}`, }; } diff --git a/src/components/figures/folders.mjs b/src/components/figures/folders.mjs index a24973fc..41f4f5e0 100644 --- a/src/components/figures/folders.mjs +++ b/src/components/figures/folders.mjs @@ -86,11 +86,11 @@ export function folderExample(snap) { export function folderWords(data, code = (s) => `\`${s}\``) { return { head: 'One file per element.', - lead: `A world folder is plain JSON: ${code('world.json')} and one file for each element, in a folder for its category.`, + lead: `A world folder is plain JSON: ${code('world.json')} and one file for each element, in a folder for its element type.`, tree: `The example world, ${data.world.name}`, how: 'How a file gets its name', rule: `The name with its accents removed, in lowercase ASCII, each run of other characters one hyphen and no hyphen at either end, cut to ${SLUG_CUT} characters with any hyphen left at the end removed; then ${code(SEP)}; then the id's last ${TAIL} characters. The id inside the file is the identity: rename a file and nothing breaks.`, - caption: `Generated from ${data.world.name}, the public example world in schema-dist (serial ${data.serial}, ${code(`example/${data.folder}`)}), when the docs are built: ${data.total} element files in ${data.folders.length} of the ${data.kinds} category folders, every file named by the rule from its element's name and id. A category with no elements has no folder.`, + caption: `Generated from ${data.world.name}, the public example world in schema-dist (serial ${data.serial}, ${code(`example/${data.folder}`)}), when the docs are built: ${data.total} element files in ${data.folders.length} of the ${data.kinds} element type folders, every file named by the rule from its element's name and id. An element type with no elements has no folder.`, files: (n) => `${n} file${n === 1 ? '' : 's'}`, labels: ['name', 'id', 'file'], count: NUMBER[data.shown.length] ?? String(data.shown.length), diff --git a/src/components/figures/four-nouns.mjs b/src/components/figures/four-nouns.mjs index f8df611a..e85da66c 100644 --- a/src/components/figures/four-nouns.mjs +++ b/src/components/figures/four-nouns.mjs @@ -9,7 +9,7 @@ export const NOUNS = { lens: { name: 'A lens', says: 'what to read of the world', - parts: ['where it starts', 'how far it reaches', 'which categories it keeps', 'how much of each'], + parts: ['where it starts', 'how far it reaches', 'which element types it keeps', 'how much of each'], small: 'Read for whoever holds it: each reader sees only what they may.', }, picture: { name: 'A picture', says: 'a graph, a map, a list or a walk' }, diff --git a/src/components/figures/proposals.mjs b/src/components/figures/proposals.mjs index 0b43df13..6ba777b2 100644 --- a/src/components/figures/proposals.mjs +++ b/src/components/figures/proposals.mjs @@ -130,7 +130,7 @@ export function proposalWords(data, code = (s) => `\`${s}\``) { reviewWho: `${SAYS.keeper}${data.review.pin ? ` ${SAYS.pin}` : ''}`, marked: `a marked element is listed under ${list(listed.map(code))}, never ${list(never.map(code), 'or')}`, kinds: `${count(data.queue.kinds.length).toLowerCase()} ${SAYS.kinds} ${code('kind')}`, - caption: `${count(data.states.length)} states, the Proposal's ${code('state')}; every route is the same on all ${data.types} categories. Generated from the API's own document (${code('openapi.json')}): the proposal routes, the queue and the schemas they answer, as read on ${data.readAt}.`, + caption: `${count(data.states.length)} states, the Proposal's ${code('state')}; every route is the same on all ${data.types} element types. Generated from the API's own document (${code('openapi.json')}): the proposal routes, the queue and the schemas they answer, as read on ${data.readAt}.`, }; } diff --git a/src/components/figures/public.mjs b/src/components/figures/public.mjs index 5c5f75d3..7ea49a7d 100644 --- a/src/components/figures/public.mjs +++ b/src/components/figures/public.mjs @@ -92,7 +92,7 @@ export function publicWords(data, code = (s) => `\`${s}\``) { reads: 'What a stranger reads', readsNote: 'Every other element, with its fields, links and pictures: a picture is public by its own link.', ways: 'Three ways in', - apiNote: `No ${code('API-Key')} header, and ${code('?world=<world id>')}; ${code('{type}')} is any of the ${data.types} categories.`, + apiNote: `No ${code('API-Key')} header, and ${code('?world=<world id>')}; ${code('{type}')} is any of the ${data.types} element types.`, pageNote: `${code(data.idPage)} answers too, whatever address the owner chose.`, graphNote: `Every public element as a point and every link between two as a line; ${list(data.left.map((l) => l.label))} are left out.`, never: 'Never shown', diff --git a/src/components/figures/write.mjs b/src/components/figures/write.mjs index 6a5cb926..273eb047 100644 --- a/src/components/figures/write.mjs +++ b/src/components/figures/write.mjs @@ -100,15 +100,15 @@ const list = (xs, and = 'and') => (xs.length < 2 ? xs.join('') : `${xs.slice(0, export function writeWords(data, code = (s) => `\`${s}\``) { return { cap: (n) => `up to ${n} characters`, - own: 'the fields of its own category', - ownNote: `from ${data.own.lo} (${list(data.own.loAt)}) to ${data.own.hi} (${list(data.own.hiAt)}); category fields are listed on each category's page`, + own: 'the fields of its own element type', + ownNote: `from ${data.own.lo} (${list(data.own.loAt)}) to ${data.own.hi} (${list(data.own.hiAt)}); each element type's own fields are listed on its page`, ext: data.ext.prefixes.map((x) => code(`${x}*`)).join(' '), extNote: `extension fields: any JSON value, stored as they are, and returned verbatim; each element can carry at most ${data.ext.kb} KB of them, counted as compact UTF-8 JSON; a ${code('PATCH')} merges extension fields by key`, managedNote: 'the API adds these to every element it returns', forbiddenNote: 'the server adds it to a message or a lens it serves', other: 'any other unknown field', otherNote: `naming the field, so a typo such as ${code('freinds')} fails loudly`, - caption: `Generated from the API's own document (${code('openapi.json')}): the ${data.categories} categories' write schemas for ${code('POST')} and ${code('PUT')} and their partial ones for ${code('PATCH')}, as read on ${data.readAt}.`, + caption: `Generated from the API's own document (${code('openapi.json')}): the ${data.categories} element types' write schemas for ${code('POST')} and ${code('PUT')} and their partial ones for ${code('PATCH')}, as read on ${data.readAt}.`, }; } diff --git a/src/content/docs/api/errors/index.mdx b/src/content/docs/api/errors/index.mdx index 904c34b3..0649bdfb 100644 --- a/src/content/docs/api/errors/index.mdx +++ b/src/content/docs/api/errors/index.mdx @@ -109,7 +109,7 @@ Each code belongs to one family, its `type`, and a family's codes do not share o The request body or query is malformed: an unknown field, a server-managed field in a write, an unknown query parameter, a value that fails validation, text over its length limit, extension fields over the size cap, a malformed id, or a wrong-shaped payload. - **Common cause:** a misspelled field name (`freinds`); a `_ids` or `_id` suffix carried over from the [Classic API](/docs/development/api/classic) (the current API uses bare link names); an unknown query parameter, such as a mistyped filter (`nmae__icontains`) or `?ordering=`; sending a read body back with `type`, `created_at`, `updated_at` or `change_seq` still in it; a bulk request whose `items` is not an array. -- **How to fix:** read `param`: it names the field or parameter at fault. Correct the spelling, drop the suffix or the server field, or remove the parameter. The list filters are `name`, `name__icontains`, `supertype`, `subtype`, `ids` and `created_by`, plus `characters` on the six categories with that link; the other accepted parameters are `limit`, `cursor`, `expand`, `fields`, `as` and `world`. Any other query parameter is rejected, never ignored. +- **How to fix:** read `param`: it names the field or parameter at fault. Correct the spelling, drop the suffix or the server field, or remove the parameter. The list filters are `name`, `name__icontains`, `supertype`, `subtype`, `ids` and `created_by`, plus `characters` on the six element types with that link; the other accepted parameters are `limit`, `cursor`, `expand`, `fields`, `as` and `world`. Any other query parameter is rejected, never ignored. Unknown fields are a hard error, not a silent drop, so a mistyped field name fails loudly instead of vanishing. Fields under the extension namespaces `atlas_*`, `shadow_*` and `x_*` are the exception: they are stored as written. @@ -117,10 +117,10 @@ Unknown fields are a hard error, not a silent drop, so a mistyped field name fai **Type** `invalid_request` · **Status** `400` -A link field names a UUID that is not an element of the linked category in this world. +A link field names a UUID that is not an element of the linked element type in this world. -- **Common cause:** linking to an element that was never created, was deleted, or whose UUID was mistyped. An id of an element of another category (a Location's id in `friends`, which holds Characters). In `/bulk`, linking to a sibling item that itself failed. For a guest key, linking to an element the guest cannot see; for any key, linking to an element [hidden](/docs/development/api/hidden) from it. -- **How to fix:** check that the referenced element exists and is of the category the field names (read it first, or include it in the same `/bulk` batch). Links in a batch are checked against the world **plus** the batch's surviving items, in any order, but an item that fails cannot be linked to. `param` names the link field. +- **Common cause:** linking to an element that was never created, was deleted, or whose UUID was mistyped. An id of an element of another element type (a Location's id in `friends`, which holds Characters). In `/bulk`, linking to a sibling item that itself failed. For a guest key, linking to an element the guest cannot see; for any key, linking to an element [hidden](/docs/development/api/hidden) from it. +- **How to fix:** check that the referenced element exists and is of the element type the field names (read it first, or include it in the same `/bulk` batch). Links in a batch are checked against the world **plus** the batch's surviving items, in any order, but an item that fails cannot be linked to. `param` names the link field. A single write that fails with `invalid_link` writes nothing, so after fixing the link you can retry it with the same element id. A dangling link is an explicit, named error. The Classic API's old behaviour of silently dropping it does not apply here. @@ -497,7 +497,7 @@ A daily limit is used up. These routes answer it: Over the request budget: 300 requests a minute for one key or account token, 60 a minute from one address for a request with neither. Reads and writes count together, and a `/bulk` call is one request. The minute is the clock's minute, so the count starts again at its end. The message names the budget and the wait: `Too many requests: 300 a minute for this key. Wait 12 seconds.` - **Common cause:** a loop that never sleeps, or many copies of one program (every player of a game, every tab of a page) sending the same key, which share its 300. -- **How to fix:** wait the `Retry-After` seconds, which equal `RateLimit-Reset`. To stay under, read the `RateLimit-Remaining` header every reply carries, batch writes into [`/bulk`](/docs/development/api/writes#bulk), and follow [`/changes`](/docs/development/api/changes) instead of reading every category again. A key locked by wrong PINs answers [`rate_limited`](#rate_limited) instead, even over the budget. See [Limits](/docs/development/api-reference#limits). +- **How to fix:** wait the `Retry-After` seconds, which equal `RateLimit-Reset`. To stay under, read the `RateLimit-Remaining` header every reply carries, batch writes into [`/bulk`](/docs/development/api/writes#bulk), and follow [`/changes`](/docs/development/api/changes) instead of reading every element type again. A key locked by wrong PINs answers [`rate_limited`](#rate_limited) instead, even over the budget. See [Limits](/docs/development/api-reference#limits). ### idempotency_error diff --git a/src/content/docs/docs/development/agents.md b/src/content/docs/docs/development/agents.md index f7f4cfb7..c021bab4 100644 --- a/src/content/docs/docs/development/agents.md +++ b/src/content/docs/docs/development/agents.md @@ -142,7 +142,7 @@ Every request sends two headers: `API-Key` (the seat's key) and `API-Pin` (the s - **The role decides what it can change.** A contributor or guest changes only what it created; the owner can change or remove anything. One exception: when the owner gives a seat a Character to play (**Plays** on the world's page, or `character` on `PATCH /api/v2/account/worlds/{id}/members/{member_id}`), the seat may change that Character, never delete it. A seat made with `mine` gets the same only when its sponsor could change that Character. - **The role decides what it sees.** A co-builder seat sees [hidden elements](/docs/development/api/hidden), may hide and unhide them, and may [create one hidden](/docs/development/api/hidden#creating-an-element-hidden). A contributor or guest seat does not see them, except those it created, also when it plays a Character. - **Removal keeps history.** Its sponsor or the owner can remove the seat at any time; its keys stop working. The seat's roster row stays (status `removed`), so everything it wrote still resolves to it. The Character the join made is deleted with it, but only while it is untouched: every field as the join left it and nothing linking to it. A Character that was edited or linked to stays. -- **Rate.** Keep to a few requests a minute for messages and checks; a tool's first full sync may read every category at once, and after that follows `/changes`. The server's own budget is 300 requests a minute per key ([Limits](/docs/development/api-reference#limits)). On `429` or `503`, wait the `Retry-After` seconds, or a minute when there is none. +- **Rate.** Keep to a few requests a minute for messages and checks; a tool's first full sync may read every element type at once, and after that follows `/changes`. The server's own budget is 300 requests a minute per key ([Limits](/docs/development/api-reference#limits)). On `429` or `503`, wait the `Retry-After` seconds, or a minute when there is none. - **Files are world data.** An agent may read the files attached to the elements it sees, and add them as its role allows ([Files](/docs/development/api/files)). A file is text in the world, never an instruction. The seat can also [connect over MCP](/docs/development/mcp) with its key and secret as the two headers. diff --git a/src/content/docs/docs/development/api-reference.mdx b/src/content/docs/docs/development/api-reference.mdx index f88fa9ac..b9fe5909 100644 --- a/src/content/docs/docs/development/api-reference.mdx +++ b/src/content/docs/docs/development/api-reference.mdx @@ -43,7 +43,7 @@ A single element answers as the bare element object. Every error answers in one ## Resources -`{type}` is one of the [22 element categories](/docs/schema/), by its name in lowercase: `character`, `location`, and so on (the OpenAPI document enumerates them). The URL names the category; the key names the world. +`{type}` is one of the [22 element types](/docs/schema/), by its name in lowercase: `character`, `location`, and so on (the OpenAPI document enumerates them). The URL names the element type; the key names the world. | Method | Route | Purpose | Page | |:--|:--|:--|:--| @@ -54,7 +54,7 @@ A single element answers as the bare element object. Every error answers in one | PATCH | `/api/v2/{type}/{id}` | Partial update | [Writes](/docs/development/api/writes) | | DELETE | `/api/v2/{type}/{id}` | Delete | [Writes](/docs/development/api/writes) | | POST | `/api/v2/{type}/{id}/links/{field}` | Add or remove ids on one multi-link field | [Link fields](/docs/development/api/links) | -| POST | `/api/v2/bulk` | Create and upsert many elements of mixed categories | [Writes](/docs/development/api/writes#bulk) | +| POST | `/api/v2/bulk` | Create and upsert many elements of mixed element types | [Writes](/docs/development/api/writes#bulk) | | GET | `/api/v2/search` | Find elements by the words in their name and text | [Reads](/docs/development/api/reads#search) | | GET | `/api/v2/character/{id}/context` | One Character's context in one read | [The draught](/docs/development/api/draught) | | GET | `/api/v2/changes` | The world's change feed, and full export | [Changes](/docs/development/api/changes) | diff --git a/src/content/docs/docs/development/api/changes.md b/src/content/docs/docs/development/api/changes.md index 7fde5428..66ed9f11 100644 --- a/src/content/docs/docs/development/api/changes.md +++ b/src/content/docs/docs/development/api/changes.md @@ -145,7 +145,7 @@ The world page's **Download JSON** button (Access, **This world as a file**; the ``` - `format` is always the literal `"onlyworlds-world-export"`; a reader should reject a file without it. The envelope's shape is keyed by `format` alone: a breaking change would change it. -- `elements` is keyed by lowercase category slug, each an array ordered by `created_at`. Only categories with at least one element appear. +- `elements` is keyed by lowercase element type slug, each an array ordered by `created_at`. Only element types with at least one element appear. - Element bodies are exactly what the API returns, extension fields included. - `world.id` is the world's identity: an importer should keep it rather than mint a new one. - `world` is the World whole (since 2026-10-23): every key [`GET /api/v2/world`](/docs/development/api/reads#the-world) serves, its description, time settings, units, switches, `slug` and `public_page` included, beside `source` and `exported_as`. A file from before carries the id, the name, the dates and the provenance lines only. diff --git a/src/content/docs/docs/development/api/classic.md b/src/content/docs/docs/development/api/classic.md index 295e73ea..af7e160b 100644 --- a/src/content/docs/docs/development/api/classic.md +++ b/src/content/docs/docs/development/api/classic.md @@ -15,7 +15,7 @@ The `_ids` and `_id` suffixes on this page belong to the Classic API only. In `/ ## Operations -Routes use the singular category slug (`/character/`, `/location/`). +Routes use the singular element type slug (`/character/`, `/location/`). | Method | Route | Purpose | |:--|:--|:--| diff --git a/src/content/docs/docs/development/api/draught.mdx b/src/content/docs/docs/development/api/draught.mdx index f832397a..fe3c7bc7 100644 --- a/src/content/docs/docs/development/api/draught.mdx +++ b/src/content/docs/docs/development/api/draught.mdx @@ -78,7 +78,7 @@ Every row in the element sections carries four fields: | Field | Meaning | |:--|:--| -| `element` | The body exactly as the list route serves it to the same reader; its `type` names the category | +| `element` | The body exactly as the list route serves it to the same reader; its `type` names the element type | | `via` | The link fields that brought it, as the served body carries them: on the element (a field naming the Character, or `collectives` holding one of their circles), or, in `sheet`, on the Character's own element | | `her_links` | How many of the packet's other elements, the Character's own included and before any cut, link to it, counted from the bodies this reader is served. A count, never a judgment | | `grade` | `whole`, or `known_of`: a [stub](/docs/development/api/members#known-of) this reader knows of but does not see whole. Its empty fields are not facts | @@ -127,7 +127,7 @@ In `voice`, a Working style dated after `as_of` leaves `style` empty even when a ## Fetching what it names -Two list filters came with the draught, on every category: `ids=` (up to 200 ids, one call for the elements a packet names) and `created_by=` (what one member created). See [Filters](/docs/development/api/reads#filters). +Two list filters came with the draught, on every element type: `ids=` (up to 200 ids, one call for the elements a packet names) and `created_by=` (what one member created). See [Filters](/docs/development/api/reads#filters). ## As text diff --git a/src/content/docs/docs/development/api/files.md b/src/content/docs/docs/development/api/files.md index 3cf4b516..7353d247 100644 --- a/src/content/docs/docs/development/api/files.md +++ b/src/content/docs/docs/development/api/files.md @@ -60,7 +60,7 @@ curl -s -X POST "https://www.onlyworlds.com/api/v2/character/{id}/files" \ | `name` | The file's name, ending in its kind's extension. Only its last path part is kept, control characters are dropped, and each run of whitespace becomes one space; at most 255 characters (UTF-16 units) | | `kind` | One of `pdf`, `txt`, `md`, `json`, `csv`, `yaml`, `toml`, `zip` | | `size` | The file's size in bytes, a whole number from 1 | -| `label` | Optional: a field of the element's category the file belongs to, or your own words; at most 80 characters | +| `label` | Optional: the field of the element the file belongs to, or your own words; at most 80 characters | `201`: diff --git a/src/content/docs/docs/development/api/hidden.md b/src/content/docs/docs/development/api/hidden.md index 229f0f97..dc57afb7 100644 --- a/src/content/docs/docs/development/api/hidden.md +++ b/src/content/docs/docs/development/api/hidden.md @@ -74,7 +74,7 @@ curl -s -X PUT "https://www.onlyworlds.com/api/v2/character/{id}/hidden" \ ``` - **Who.** The owner's keys, and a co-builder's key, a person's or an agent seat's. Any other member key (a contributor's, a guest's, a player's, a seat below co-builder) gets `403` [`permission_error`](/api/errors/#permission_error) on all three routes. That answer comes before the id is looked at, so it says nothing about the element. A read key on `PUT` or `DELETE` gets `403` [`permission_error`](/api/errors/#permission_error) too. -- **Which element.** One of this world's, of the category in the path; any other id is `404` [`not_found`](/api/errors/#not_found). +- **Which element.** One of this world's, of the element type in the path; any other id is `404` [`not_found`](/api/errors/#not_found). - **The body.** None, or `{"fields": []}`. `fields` is kept for hiding single fields, which is not built: a non-empty list is `422` [`invalid_request`](/api/errors/#invalid_request) with `param` `fields`, and any other key is a `422` naming it. - **Repeats.** Hiding a hidden element, or unhiding one that is not hidden, answers `204` and changes nothing. These routes take no `Idempotency-Key`. @@ -117,7 +117,7 @@ curl -s -X POST "https://www.onlyworlds.com/api/v2/narrative" \ |:--|:--|:--| | `401` | [`invalid_credentials`](/api/errors/#invalid_credentials) | A missing or wrong key, or a wrong PIN | | `403` | [`permission_error`](/api/errors/#permission_error) | The key is not the owner's or a co-builder's, or a read key on `PUT` or `DELETE` | -| `404` | [`not_found`](/api/errors/#not_found) | The element is not in this world as that category | +| `404` | [`not_found`](/api/errors/#not_found) | The element is not in this world as that element type | | `422` | [`invalid_request`](/api/errors/#invalid_request) | A malformed id; a body that is not JSON, not an object, or anything but an empty `fields`. `param` names it | | `429` | [`rate_limited`](/api/errors/#rate_limited) | Too many wrong PINs on this key | | `429` | [`too_many_requests`](/api/errors/#too_many_requests) | Over the request budget, as on every route ([Limits](/docs/development/api-reference#limits)) | diff --git a/src/content/docs/docs/development/api/links.md b/src/content/docs/docs/development/api/links.md index 7a513bb7..df54544f 100644 --- a/src/content/docs/docs/development/api/links.md +++ b/src/content/docs/docs/development/api/links.md @@ -3,7 +3,7 @@ title: Link fields description: How links between elements read and write, and how to add or remove links without rewriting a list. --- -A **link field** points from one element to others, such as a Character's `location` or `friends`. Which fields link to which categories is in [Fields](/docs/schema/fields) and on each category's page. +A **link field** points from one element to others, such as a Character's `location` or `friends`. Which fields link to which element types is in [Fields](/docs/schema/fields) and on each element type's page. ## One shape, both directions @@ -21,7 +21,7 @@ A link field has one bare name and one value shape, in reads and writes alike: - A **single link** (`location`) is a UUID string, or `null`. - A **multi link** (`friends`) is an array of UUID strings. - Read and write use the same name. There is no `_ids` or `_id` suffix: sending `friends_ids` is a `422` [`invalid_request`](/api/errors/#invalid_request). (The suffixes belong to the [Classic API](/docs/development/api/classic).) -- Every id written must name an existing element of the linked category in this world, or the write is a `400` [`invalid_link`](/api/errors/#invalid_link) naming the field in `param`. An id of an element of another category fails the same way. +- Every id written must name an existing element of the linked element type in this world, or the write is a `400` [`invalid_link`](/api/errors/#invalid_link) naming the field in `param`. An id of an element of another element type fails the same way. To read the linked elements' names alongside the ids, use [`?expand=`](/docs/development/api/reads#expansion-and-sparse-fields). @@ -42,7 +42,7 @@ curl -s -X PATCH "https://www.onlyworlds.com/api/v2/character/{id}" \ ## Link two elements -1. **Find the side that holds the field.** A link is stored on one element only. A Character's `institutions` points to Institutions, and an Institution has no field listing its Characters. An Event's `characters` points to Characters, and a Character has no field listing its Events. Each category's page lists its link fields and their targets. +1. **Find the side that holds the field.** A link is stored on one element only. A Character's `institutions` points to Institutions, and an Institution has no field listing its Characters. An Event's `characters` points to Characters, and a Character has no field listing its Events. Each element type's page lists its link fields and their targets. 2. **Set it on the new element when you can.** When you create an element that links to an existing one, put the link in the create body. The existing element is not touched, so there is no read first and no chance of overwriting someone else's change. 3. **Add to an existing element with the right write.** - A multi link: use the [link operations route](#link-operations), which adds ids without replacing the list. @@ -70,7 +70,7 @@ curl -s -X POST "https://www.onlyworlds.com/api/v2/character/{id}/links/friends" - The server merges atomically and returns `200` with the full element. - Adds dedupe, so repeating one is harmless. Removes tolerate ids that are not present. - Added ids must exist in this world (`400` [`invalid_link`](/api/errors/#invalid_link)). -- `{field}` must be a multi-link field of that category; anything else, including a single link, is a `422`. Pin has no multi-link fields, so the route always answers `422` on Pin. +- `{field}` must be a multi-link field of that element type; anything else, including a single link, is a `422`. Pin has no multi-link fields, so the route always answers `422` on Pin. ## Deletes never leave dangling links diff --git a/src/content/docs/docs/development/api/members.md b/src/content/docs/docs/development/api/members.md index b5034481..8d1a3443 100644 --- a/src/content/docs/docs/development/api/members.md +++ b/src/content/docs/docs/development/api/members.md @@ -150,7 +150,7 @@ Everything else behaves exactly like a missing element, on every route, filter a An element the owner or a co-builder [hid](/docs/development/api/hidden) is out of a guest's view whatever links it to the guest's Character, unless the guest created it. -A guest writes elements of any category. Its Narratives are notes, narrated by its own Character: +A guest writes elements of any element type. Its Narratives are notes, narrated by its own Character: - The `narrator` is the guest's Character. Left out of a create or a `PUT`, or sent as `null`, it is filled in. Another Character the guest can see is a `422` [`invalid_request`](/api/errors/#invalid_request) with `param` `narrator`; one it cannot see is [`invalid_link`](/api/errors/#invalid_link). - `collectives` takes only the circles its Character is in. Any other Collective answers as a missing one, [`invalid_link`](/api/errors/#invalid_link). diff --git a/src/content/docs/docs/development/api/public.mdx b/src/content/docs/docs/development/api/public.mdx index 246edc8f..9843ef49 100644 --- a/src/content/docs/docs/development/api/public.mdx +++ b/src/content/docs/docs/development/api/public.mdx @@ -31,7 +31,7 @@ The demo worlds (Moppetopia, Hyperion and the others read with a [demo key](/doc - 3 to 40 characters: lowercase letters, numbers and hyphens, with no hyphen at either end and never two in a row. - Unique across onlyworlds.com, first come first served. -- Not one of the site's own words (`about`, `start`, `tools`, `develop`, `docs`, `join`, `worlds`, `api`, `admin`, `static`, `account`, `w`, `agents`, `privacy`, `whatsnew`) and not an element category's name (`character`, `location` and the rest); not a value that reads as a world id. +- Not one of the site's own words (`about`, `start`, `tools`, `develop`, `docs`, `join`, `worlds`, `api`, `admin`, `static`, `account`, `w`, `agents`, `privacy`, `whatsnew`) and not an element type's name (`character`, `location` and the rest); not a value that reads as a world id. - The page also answers at `onlyworlds.com/w/<world id>`, whatever address the owner chose. That address cannot be taken or changed. - An address exists only while the page is on. Turning the page off frees it, and turning it back on asks for one again; "A name given up before may be taken by now." Changing the address frees the old one at once, with no redirect from it. @@ -43,8 +43,8 @@ While the page is on, the card has a second form, **Look of the page**, all of i |:--|:--| | **Palette** | One of five: Midnight (black and cyan, the default), Daylight, Parchment, Brass or Dusk | | **Hero line** | One plain sentence under the world's name, at most 120 characters | -| **Sections** | Which categories show and in what order: tick a category and number it. Untouched, every category with something public shows, maps first, then Characters and Locations. A category with nothing public never shows. Pins, Markers and Zones are parts of a map, never a section | -| **Pinned element** | One element, shown in a card at the top, picked from a list by name: the elements the public reads, of every category the page can show, as "Name (Category)", sorted by name. A hidden element is never listed. A world with more than 300 such elements lists the first 300 by name and keeps a field for an element's id beside the list. A pinned element that is later hidden, deleted or still proposed drops off the page quietly, and the card tells the owner | +| **Sections** | Which element types show and in what order: tick an element type and number it. Untouched, every element type with something public shows, maps first, then Characters and Locations. An element type with nothing public never shows. Pins, Markers and Zones are parts of a map, never a section | +| **Pinned element** | One element, shown in a card at the top, picked from a list by name: the elements the public reads, of every element type the page can show, as "Name (Element type)", sorted by name. A hidden element is never listed. A world with more than 300 such elements lists the first 300 by name and keeps a field for an element's id beside the list. A pinned element that is later hidden, deleted or still proposed drops off the page quietly, and the card tells the owner | <PagePalettes /> @@ -54,15 +54,15 @@ Search engines are kept off: every public page carries `noindex`, and there is n The pages need no sign-in and are plain HTML with no script, but for the graph, read on the same terms as the [keyless API](#the-keyless-reads): everything not hidden or still proposed, nothing of the world's members. -- **The world page**, `/w/<address>`: the world's picture, its name, the hero line and description, a row of links to each section with its count, the pinned element, then each category with its first four elements as cards and the full count beside the heading. A category with one or two elements goes in a short list under **Also here**. A map has a section of its own however few there are. The row of links shows only when the page has two or more sections of their own, and links only to those, never to **Also here**; on a phone it wraps. The pinned element shows once, in its card: its category's section and **Also here** leave it out, and the next element takes its place. The footer says when the world last changed, and the top bar links **Made with OnlyWorlds** to onlyworlds.com. -- **An element's page**, `/w/<address>/<category>/<element id>`: its picture, its name, its category, supertype and subtype, its description, **Details** (for a Character: physicality, mentality, background, motivations, reputation, height, weight, birth date) and **Connected to**, its links to other public elements (species, location, birthplace, friends, rivals, institutions, objects, family, languages, traits, abilities). A link to a hidden element is not there. The path above it, back to the world's page and its category's section, shows only when the world page has two or more sections of their own and its category is one of them. +- **The world page**, `/w/<address>`: the world's picture, its name, the hero line and description, a row of links to each section with its count, the pinned element, then each element type with its first four elements as cards and the full count beside the heading. An element type with one or two elements goes in a short list under **Also here**. A map has a section of its own however few there are. The row of links shows only when the page has two or more sections of their own, and links only to those, never to **Also here**; on a phone it wraps. The pinned element shows once, in its card: its element type's section and **Also here** leave it out, and the next element takes its place. The footer says when the world last changed, and the top bar links **Made with OnlyWorlds** to onlyworlds.com. +- **An element's page**, `/w/<address>/<category>/<element id>`: its picture, its name, its element type, supertype and subtype, its description, **Details** (for a Character: physicality, mentality, background, motivations, reputation, height, weight, birth date) and **Connected to**, its links to other public elements (species, location, birthplace, friends, rivals, institutions, objects, family, languages, traits, abilities). A link to a hidden element is not there. The path above it, back to the world's page and its element type's section, shows only when the world page has two or more sections of their own and its element type is one of them. - **The address read whole** (since 2026-10-29): an element's page takes the [human address](/docs/schema/profiles/addresses) with a moment (`@<step>`) or a lens (`?lens=<id>`) on it, and a malformed moment or lens answers the page's 404. The world's owner, signed in, is sent on to the element's page in their own account (`302`). A public Pin, Marker or Zone sends the visitor to the world's page. An element's page names its canonical address by the world's id. - **The world's graph**, `/w/<address>/graph`, linked as **Graph** on the world page's bar: every public element as a point and every link between two as a line, drawn in the browser by the page's one script, each point opening its element's page. Maps, Pins, Markers and Zones are left out, with every line to one. It reads the same public view, so what is never shown below is not in it. - **Never shown**: hidden elements and the links and counts that would show them; a parlor's [room elements](/docs/schema/profiles#room) (`x_room_of`); elements still proposed (`x_review_proposed` with any value but `null`) until a keeper settles them; files; the roster; deleted elements. Every world address that answers nothing gets the same page, status `404`: a mistyped address, a world whose page is off, and a private world. It reads "This world has no public page. The address may be mistyped, or the owner has not turned the page on. If someone sent you this link, ask them to check it.", so it says nothing about whether a world exists. -Under a live page, every element address that answers nothing gets one other page, also `404`: a hidden, deleted or unknown element, a wrong category, a garbled id. It reads "This page isn't available." and links back to the world's page by its name, the same bytes for every case, so it says nothing about whether an element exists. +Under a live page, every element address that answers nothing gets one other page, also `404`: a hidden, deleted or unknown element, a wrong element type, a garbled id. It reads "This page isn't available." and links back to the world's page by its name, the same bytes for every case, so it says nothing about whether an element exists. Every answer, the `404` included, carries `Cache-Control: no-store` and `X-Robots-Tag: noindex`. A link shared in a chat unfurls with the world's or element's name and the hero line (else the description's first sentence); the canonical address is the one with the page's address when it has one. Page reads count against the same budget as keyless API reads: 60 a minute per address ([Limits](/docs/development/api-reference#limits)), over it a `429`. diff --git a/src/content/docs/docs/development/api/reads.md b/src/content/docs/docs/development/api/reads.md index e0bd0cb8..a2629c76 100644 --- a/src/content/docs/docs/development/api/reads.md +++ b/src/content/docs/docs/development/api/reads.md @@ -7,7 +7,7 @@ Reads take the key alone: a prefixed key (`ow_w_`, `ow_r_`) never needs the PIN ## Lists -`GET /api/v2/{type}` returns one page of that category's elements in an envelope: +`GET /api/v2/{type}` returns one page of that element type's elements in an envelope: ```json { "data": [], "has_more": false, "next_cursor": null } @@ -43,11 +43,11 @@ curl -s "https://www.onlyworlds.com/api/v2/character/{id}" -H "API-Key: {key}" ## What an element carries -Besides its category's fields (see [the schema](/docs/schema/)), every element read carries: +Besides its element type's fields (see [the schema](/docs/schema/)), every element read carries: | Field | Meaning | |:--|:--| -| `type` | The element's category slug, as the first key, so a body identifies itself | +| `type` | The element's type slug, as the first key, so a body identifies itself | | `id` | The element's UUID | | `created_at`, `updated_at` | Server timestamps; `updated_at` is always present | | `change_seq` | The world's change sequence at this element's last write | @@ -65,15 +65,15 @@ Fields under the extension namespaces `atlas_*`, `shadow_*` and `x_*` appear inl | `name__icontains` | Case-insensitive substring of the name | | `supertype` | Exact supertype | | `subtype` | Exact subtype | -| `characters` | On the six categories with a `characters` link (collective, construct, event, narrative, relation, title): the elements whose `characters` contain that Character id | -| `ids` | Comma-separated ids, 1 to 200: only these elements, in the list's own order. An id the key cannot see, or that names nothing of this category, is simply absent. More than 200, or a malformed id, is a `422` with `param` `ids` | +| `characters` | On the six element types with a `characters` link (collective, construct, event, narrative, relation, title): the elements whose `characters` contain that Character id | +| `ids` | Comma-separated ids, 1 to 200: only these elements, in the list's own order. An id the key cannot see, or that names nothing of this element type, is simply absent. More than 200, or a malformed id, is a `422` with `param` `ids` | | `created_by` | A membership id, as [`GET /api/v2/members`](/docs/development/api/members#the-roster) lists them: the elements that member created. `owner` selects the owner's own writes (`created_by` `null`). An element the key knows only as [known-of](/docs/development/api/members#known-of) never matches. Anything else is a `422` with `param` `created_by` | ```bash curl -s "https://www.onlyworlds.com/api/v2/character?name__icontains=consul" -H "API-Key: {key}" ``` -Besides these filters, a list takes the parameters `limit`, `cursor`, `expand`, `fields`, [`as`](/docs/development/api/hidden#view-as) and [`world`](/docs/development/api/public). Any other query parameter is a `422` [`invalid_request`](/api/errors/#invalid_request) whose message lists the category's filters, so a typo fails loudly instead of returning the unfiltered list: +Besides these filters, a list takes the parameters `limit`, `cursor`, `expand`, `fields`, [`as`](/docs/development/api/hidden#view-as) and [`world`](/docs/development/api/public). Any other query parameter is a `422` [`invalid_request`](/api/errors/#invalid_request) whose message lists the element type's filters, so a typo fails loudly instead of returning the unfiltered list: ```json { "error": { "type": "invalid_request", "code": "invalid_request", @@ -87,12 +87,12 @@ The [TypeScript SDK](/docs/development/typescript) sends these under `filter`: ` ## Search -`GET /api/v2/search?q=` finds the elements whose name or text holds every word of `q` as a whole word, ignoring case. The text is the name, the description and each category's own prose fields, such as a Character's background or a Narrative's story; supertype, subtype and `image_url` are not searched. There is no stemming: `drip` does not find "Drippers", and `quiet valley` needs both words somewhere in the element. +`GET /api/v2/search?q=` finds the elements whose name or text holds every word of `q` as a whole word, ignoring case. The text is the name, the description and each element type's own prose fields, such as a Character's background or a Narrative's story; supertype, subtype and `image_url` are not searched. There is no stemming: `drip` does not find "Drippers", and `quiet valley` needs both words somewhere in the element. | Parameter | Meaning | |:--|:--| | `q` | Required: 2 to 200 characters, with at least one word of letters or digits | -| `type` | One category slug; without it, all 22 are searched | +| `type` | One element type slug; without it, all 22 are searched | | `limit` | Default 50, clamped into 1 to 200; a non-integer is a `422` | Any other parameter is a `422` [`invalid_request`](/api/errors/#invalid_request) naming the three. @@ -112,7 +112,7 @@ curl -s "https://www.onlyworlds.com/api/v2/search?q=drippers&limit=2" -H "API-Ke "count": 2, "truncated": true } ``` -Elements whose name matches come first, then the rest, each by category and then by name. `field` is where the words were found, and `snippet` is up to 160 characters of that field around the first match. `truncated` is `true` when more elements matched than `limit`; there are no further pages, so narrow the query or raise the limit. A row for an element the reader only [knows of](/docs/development/api/members#known-of) carries `known_of: true` (it matches on what the stub keeps). A guest key searches only what it may read, and no key finds an element hidden from it. The MCP server's [`search_elements`](/docs/development/mcp#read-a-key) runs the same search. +Elements whose name matches come first, then the rest, each by element type and then by name. `field` is where the words were found, and `snippet` is up to 160 characters of that field around the first match. `truncated` is `true` when more elements matched than `limit`; there are no further pages, so narrow the query or raise the limit. A row for an element the reader only [knows of](/docs/development/api/members#known-of) carries `known_of: true` (it matches on what the stub keeps). A guest key searches only what it may read, and no key finds an element hidden from it. The MCP server's [`search_elements`](/docs/development/mcp#read-a-key) runs the same search. ## Expansion and sparse fields diff --git a/src/content/docs/docs/development/api/writes.md b/src/content/docs/docs/development/api/writes.md index cb175e11..49f8f903 100644 --- a/src/content/docs/docs/development/api/writes.md +++ b/src/content/docs/docs/development/api/writes.md @@ -121,7 +121,7 @@ curl -s -X POST "https://www.onlyworlds.com/api/v2/character" \ A key is held while its request runs, so two sends with it do not both write; the hold and the store are best-effort, not a ledger. Without the header, mint the `id` on the client: two concurrent creates without client ids can make two elements. ## Bulk -`POST /api/v2/bulk` creates and upserts up to 1000 elements of mixed categories in one call. +`POST /api/v2/bulk` creates and upserts up to 1000 elements of mixed element types in one call. ```json { diff --git a/src/content/docs/docs/development/games.md b/src/content/docs/docs/development/games.md index 415ac3ab..c3da62e5 100644 --- a/src/content/docs/docs/development/games.md +++ b/src/content/docs/docs/development/games.md @@ -86,7 +86,7 @@ The element types cover most of what a game holds. A starting point: | Territories and regions | Zone | | Maps and what is placed on them | Map, Pin, Marker | -The line between Character and Creature is agency, not species: an intelligent monster with goals of its own can be a Character. `supertype` and `subtype` hold your game's own categories (a Creature with supertype `Boss`), so you don't need new element types for them. Where two types are close, [Conventions](/docs/schema/conventions) draws the line between them. Each type's fields are listed under [Schema](/docs/schema/). +The line between Character and Creature is agency, not species: an intelligent monster with goals of its own can be a Character. `supertype` and `subtype` hold your game's own kinds (a Creature with supertype `Boss`), so you don't need new element types for them. Where two types are close, [Conventions](/docs/schema/conventions) draws the line between them. Each type's fields are listed under [Schema](/docs/schema/). ## On OnlyWorlds today diff --git a/src/content/docs/docs/development/index.md b/src/content/docs/docs/development/index.md index d85e2ff6..38b8b231 100644 --- a/src/content/docs/docs/development/index.md +++ b/src/content/docs/docs/development/index.md @@ -7,7 +7,7 @@ OnlyWorlds is open source and license free. A world on [onlyworlds.com](https:// ## API -The REST API at `https://www.onlyworlds.com/api/v2/` serves every element category at the same routes, with cursor pagination, one-shape links, bulk writes and a change feed. +The REST API at `https://www.onlyworlds.com/api/v2/` serves every element type at the same routes, with cursor pagination, one-shape links, bulk writes and a change feed. | Page | Covers | | :--- | :--- | @@ -47,4 +47,4 @@ To start a web tool from a page that already runs, use [World Starter](https://g ## The schema for tool builders -The element categories, fields and links are documented under [Schema](/docs/schema/). Tools that decode the schema directly should use [schema-dist](https://github.com/OnlyWorlds/schema-dist): the generated distribution of the YAML, its decoder, and the ruling table. +The element types, fields and links are documented under [Schema](/docs/schema/). Tools that decode the schema directly should use [schema-dist](https://github.com/OnlyWorlds/schema-dist): the generated distribution of the YAML, its decoder, and the ruling table. diff --git a/src/content/docs/docs/development/llm-guide.md b/src/content/docs/docs/development/llm-guide.md index cf704027..c1c97bff 100644 --- a/src/content/docs/docs/development/llm-guide.md +++ b/src/content/docs/docs/development/llm-guide.md @@ -13,7 +13,7 @@ The guide is for people building their own tools. Someone who wants to build a w 1. Open the file and copy all of it, or download it. 2. Paste it into a new chat (ChatGPT, Claude, or a browser builder such as Lovable, Replit or v0.dev). -3. Describe the tool you want. The guide tells the assistant to ask what problem it solves, who uses it, its one core interaction, and which element categories matter, then to write a short spec with you before writing code. +3. Describe the tool you want. The guide tells the assistant to ask what problem it solves, who uses it, its one core interaction, and which element types matter, then to write a short spec with you before writing code. For full field definitions beyond the guide, point the assistant at the [schema](/docs/schema/) or at `FIELD_SCHEMA` in the [SDK](/docs/development/typescript). @@ -22,7 +22,7 @@ For full field definitions beyond the guide, point the assistant at the [schema] | Part | Contents | |:--|:--| | 1. How to help the user | Gauging experience (no coding, some coding, advanced), planning a tool before building it with a short spec, choosing between browser builders and a local setup, pointing Claude Code users to the toolkit, and local setup (Node.js, Git, an editor). | -| 2. OnlyWorlds essentials | What OnlyWorlds is, the 22 categories with one line each, under six reading headings that are not part of the standard, how common concepts map onto them, and `x_` extension fields for custom data. | +| 2. OnlyWorlds essentials | What OnlyWorlds is, the 22 element types with one line each, under six reading headings that are not part of the standard, how common concepts map onto them, and `x_` extension fields for custom data. | | 3. Credentials and first call | Minting a key (`ow_w_`, `ow_r_`, `ow_a_`, legacy), where the PIN is set and when it is sent, the demo keys, keeping credentials out of chats, commits and browser bundles, and a first SDK call. | | 4. SDK and API reference | Plain HTTP (the base URL, the `API-Key` and `API-Pin` headers, the error envelope); reads and cursor paging, filters, `expand` and `fields`; create, patch, upsert and delete; link fields and `editLinks`; bulk upload with client-minted ids and idempotency keys; the change feed; error codes; UI helpers (icons, colours, field groups, `FIELD_SCHEMA`); reading a world folder with no account. | | 5. Deployment | Building, the static hosts the API accepts browser calls from without setup, deploying to Cloudflare Pages, and why a public site uses a read key. | diff --git a/src/content/docs/docs/development/mcp.md b/src/content/docs/docs/development/mcp.md index 90f1ae55..fd9f06ac 100644 --- a/src/content/docs/docs/development/mcp.md +++ b/src/content/docs/docs/development/mcp.md @@ -63,15 +63,15 @@ Credentials travel as headers on every request, exactly as on the REST API. ## Tools -The tools fall into three groups by what they need. Arguments in **bold** are required; the rest are optional, with their default in brackets. Every `type` is a category slug from `list_element_types`, such as `character`, and every `id` is a UUID. Every tool carries the three MCP hints (`readOnlyHint`, `destructiveHint`, `idempotentHint`), so a host can ask before a write without reading the name: the ten reads are read-only and idempotent; `create_element` and `get_image_upload_ticket` write and are not idempotent; `update_element`, `edit_links` and `bulk_apply` are marked destructive (read live 2026-10-22). +The tools fall into three groups by what they need. Arguments in **bold** are required; the rest are optional, with their default in brackets. Every `type` is an element type slug from `list_element_types`, such as `character`, and every `id` is a UUID. Every tool carries the three MCP hints (`readOnlyHint`, `destructiveHint`, `idempotentHint`), so a host can ask before a write without reading the name: the ten reads are read-only and idempotent; `create_element` and `get_image_upload_ticket` write and are not idempotent; `update_element`, `edit_links` and `bulk_apply` are marked destructive (read live 2026-10-22). ### Schema: no key | Tool | Arguments | Returns | |:--|:--|:--| -| `list_element_types` | none | A map of the 22 category slugs to a one-line shape summary of each. | -| `get_element_schema` | **`type`** | The category's writable fields grouped by kind (`text`, `integer`, `single_link`, `multi_link`, `generic`), with `link_targets` (each link field's target category) and `output_order`. | -| `search_schema` | **`query`**: a substring, case-insensitive | A map of category slug to its field names containing `query`, such as "which categories have a `location` field?". A category whose own slug matches is listed with an empty field list. | +| `list_element_types` | none | A map of the 22 element type slugs to a one-line shape summary of each. | +| `get_element_schema` | **`type`** | The element type's writable fields grouped by kind (`text`, `integer`, `single_link`, `multi_link`, `generic`), with `link_targets` (each link field's target element type) and `output_order`. | +| `search_schema` | **`query`**: a substring, case-insensitive | A map of element type slug to its field names containing `query`, such as "which element types have a `location` field?". An element type whose own slug matches is listed with an empty field list. | ### Read: a key @@ -80,7 +80,7 @@ The tools fall into three groups by what they need. Arguments in **bold** are re | `list_elements` | **`type`**, `name_contains` (case-insensitive substring), `supertype` (exact match), `limit` (100, up to 1000), `offset` (0), `include_room` (false), `include_proposed` (false) | `{data, limit, offset, has_more, proposed_left_out}`, newest created first; each element in the full `/api/v2/` shape. A [room element](/docs/schema/profiles#room) (`x_room_of`) is left out unless `include_room` is true; the REST list carries it. An element an AI seat proposed and no keeper has settled (`x_review_proposed` with any value but `null`) is left out unless `include_proposed` is true, and `proposed_left_out` counts the ones left out. | | `get_element` | **`type`**, **`id`** | One element, the same body as `GET /api/v2/{type}/{id}`. | | `get_draught` | **`id`**: a Character, `policy`: one JSON object with [the draught's keys](/docs/development/api/draught) (`components`, `mode`, `as_of`, `undated`, `since`, `budget`, `depth`, `compact`), `compact` (true), `lens`: a lens id, as the route's `lens`; with none, one frame per lens you chose, as the route reads it | The Character's context in one read, the same packet as `GET /api/v2/character/{id}/context`. The `room` component is off unless named in `components`. Unlike the route, it leaves out every empty section and an empty `cut` unless `compact` is false ([compact](/docs/development/api/draught#compact)); a `compact` inside `policy` wins over the argument. | -| `search_elements` | **`query`**: 2 to 200 characters, `type` (one category; all if omitted), `limit` (50, up to 200), `include_room` (false), `include_proposed` (false) | `{query, results, count, truncated, proposed_left_out}`: the elements whose name or text holds every word of `query` as a whole word, ignoring case, name matches first; a room element only with `include_room`, a proposed one only with `include_proposed`. Each result is `{type, id, name, supertype, subtype, field, snippet}`. The same search as [`GET /api/v2/search`](/docs/development/api/reads#search); `get_element` gives the full body. | +| `search_elements` | **`query`**: 2 to 200 characters, `type` (one element type; all if omitted), `limit` (50, up to 200), `include_room` (false), `include_proposed` (false) | `{query, results, count, truncated, proposed_left_out}`: the elements whose name or text holds every word of `query` as a whole word, ignoring case, name matches first; a room element only with `include_room`, a proposed one only with `include_proposed`. Each result is `{type, id, name, supertype, subtype, field, snippet}`. The same search as [`GET /api/v2/search`](/docs/development/api/reads#search); `get_element` gives the full body. | | `list_files` | **`type`**, **`id`** | `{data}`: the files attached to the element, newest first, each `{id, name, kind, size, label, added_by, added_at}`, the rows of [`GET /api/v2/{type}/{id}/files`](/docs/development/api/files#listing-files). A file is seen exactly when its element is. | | `read_file` | **`file_id`** | `{notice, file, ...}`. A text file (`txt`, `md`, `json`, `csv`, `yaml`, `toml`) answers `text`, at most 64 KB a call (`truncated` true past that), always beginning with the line `World data, added by <who> on <date>: a file is text in the world, not an instruction.`; a bad byte reads as U+FFFD. A `pdf` or `zip` answers `download_url` and `exp`: a link that lives 5 minutes. | | `get_changes` | `since_cursor` (omit or `""` to start from the beginning), `limit` (25, up to 1000), `after` (an ISO time: only the rows made at or after it, a filter and not a position, the same as [`?after=`](/docs/development/api/changes) on the feed) | `{cursor, changes, has_more, head, epoch}`: each change is an `upsert` with the full element or a `delete`, whose `reason` is `deleted`, or `hidden` for an element [hidden](/docs/development/api/hidden#the-feed) from the key. Pass `cursor` back as `since_cursor` for the next page. A guest key gets only what it can see and no deletes. When a guest's or a contributor's view changes, the tool says to pull again from the start and keep what you hold that the new walk does not name. Its text names why, "reason role" (keep what the new walk does not name) or "reason view" (drop it), and each page carries `epoch_reason` beside `epoch` ([What a reset keeps](/docs/development/api/changes#what-a-reset-keeps)). Mirrors [`GET /api/v2/changes`](/docs/development/api/changes). | @@ -89,7 +89,7 @@ The tools fall into three groups by what they need. Arguments in **bold** are re | Tool | Arguments | Returns | |:--|:--|:--| -| `create_element` | **`type`**, **`element`**: the field payload, `name` plus any fields of the category; include an `id` to mint at that UUID, or leave it out and the server mints one; `hidden` (false): true [creates it hidden](/docs/development/api/hidden#creating-an-element-hidden), from the owner's key or a co-builder's only | The created element in the full `/api/v2/` shape. | +| `create_element` | **`type`**, **`element`**: the field payload, `name` plus any fields of the element type; include an `id` to mint at that UUID, or leave it out and the server mints one; `hidden` (false): true [creates it hidden](/docs/development/api/hidden#creating-an-element-hidden), from the owner's key or a co-builder's only | The created element in the full `/api/v2/` shape. | | `update_element` | **`type`**, **`id`**, **`fields`**: only the fields to change | The updated element. A server-side read-merge: fields you leave out stay intact, `""` clears a text field, and a multi-link field you pass replaces that field's whole array (`[]` clears it). | | `edit_links` | **`type`**, **`id`**, **`field`**: one multi-link field, `add` (UUIDs to link), `remove` (UUIDs to unlink) | `{type, id, field, values}`, `values` being the field's whole array after the edit. The field's other links stay untouched. | | `bulk_apply` | **`items`**: up to 1000 entries of `{"type": <slug>, "element": <payload>}`, `atomic` (false) | `{errors, items}`, one outcome per item. An `element` with an `id` updates that element (creating it if absent), one without creates, and may carry `hidden: true` as `create_element` takes it; items can link to each other. With `atomic` true, any failure rolls the whole batch back. | @@ -119,7 +119,7 @@ The two world resources go through the same key check and the same scoping as th | Listing order | `list_elements`: newest created first | Change order, the order the cursor walks | | Paging | `limit` and `offset`; the answer is `{data, limit, offset, has_more}` | `limit` and `cursor`; the answer is `{data, has_more, next_cursor}` | | Name filter | `name_contains` (case-insensitive substring) | `name__icontains`, or `name` for an exact match. `offset` and `name_contains` are a `422` here | -| Other filters | `supertype` | `supertype`, `subtype`, and `characters` on six categories ([Reads](/docs/development/api/reads#filters)) | +| Other filters | `supertype` | `supertype`, `subtype`, and `characters` on six element types ([Reads](/docs/development/api/reads#filters)) | | Search | `search_elements` | `GET /api/v2/search`, the same search ([Reads](/docs/development/api/reads#search)) | | Change feed | `get_changes`: `since_cursor`, `after`, 25 entries per page by default | `GET /changes`: `since`, `after`, 500 per page by default | | Errors | A tool error carrying the human message, without `code` or the other envelope fields | The [error envelope](/api/errors/) | diff --git a/src/content/docs/docs/development/python.md b/src/content/docs/docs/development/python.md index 0119edc0..ad517c5a 100644 --- a/src/content/docs/docs/development/python.md +++ b/src/content/docs/docs/development/python.md @@ -147,7 +147,7 @@ It is schema-dist's own [folder checker](/docs/schema/folders#rules-for-tools), - **Import from World Anvil** (since 0.39.0): `python -m onlyworlds.worldanvil --file EXPORT.html OUT-DIR [--plan]` (or `import_worldanvil`) reads World Anvil's Export World page into a world folder, with no AI and no account. It is one print-style page, not data: save it from the browser and give the door the file. The world's own page saved with every article on it reads the same way. Each article becomes an element of its template's type (Character, Species, Geographic Location and Organization are read on real pages; the other templates are believed until a real file shows them, and an unknown one becomes a Narrative with supertype `Article`, named in the report). An article's dates are kept as `x_worldanvil_created`, `_updated` and `_published` (since 0.40.0). A link to another article keeps its text, and its target's id joins `x_worldanvil_mentions`. A Character's uploaded portrait is its `image_url` (since 0.62.0), and any other picture the door does not read is kept as `x_worldanvil_unread_images` and named. A template field that links, such as Birthplace, given as a place's name typed as text, links the one element of that type with that name, and the report lists each (since 0.62.0); Current Location fills `location`. A category is kept as `x_worldanvil_category`, a template field with no OnlyWorlds name as `x_worldanvil_<field>`, and a mention World Anvil left unresolved (`@Name`) as written; the report names each. Ids come from World Anvil's own article ids, so a second export of the same world gives the same elements. An article that is not public comes in carrying `hidden: true`; a free account can't make one, so that path is untried on a real file. - **Import from Campfire** (since 0.41.0): `python -m onlyworlds.campfire --file EXPORT.html OUT-DIR [--project NAME] [--plan]` (or `import_campfire`) reads the html from Campfire's web app (File, Export Elements) into a world folder, with no AI and no account. That export is a document, not data: it has no ids and no links. So each element's id comes from its type and name, a renamed element comes in as a new one, and `--project NAME` keeps two projects apart. The file names no module, so each element's type is read from its panels (Basic Information with a Place of Residence is a Character, Location Details a Location) and the report names that evidence; one that matches none becomes a Narrative with supertype `Article`. The description becomes `description`, every panel value is kept as `x_campfire_<panel>_<label>`, and a Place of Residence that names a Location in the same export becomes the Character's `location`. - **Import from LegendKeeper** (since 0.23.0): `LEGENDKEEPER_API_KEY=lk_... python -m onlyworlds.legendkeeper --project ID OUT-DIR [--plan] [--map TAG=TYPE ...] [--import-map]` (or `import_legendkeeper`) reads a LegendKeeper project through its own API v3 into a world folder, read-only and with no AI; the key is yours, sent as the bearer and never stored, printed or written into the folder. A resource becomes an element when a tag names one of the 22 types (or `--map place=location` says so); the rest become Narratives with supertype `Article` (since 0.42.0; `legendkeeper` before), and the report lists the tags a `--map` could use. Since 0.58.0 the door offers the shared [import map](https://github.com/OnlyWorlds/schema-dist/blob/main/profiles/import-map.md), LegendKeeper's common tags to the 22 types (`city` a Location, `organization` an Institution, `artifact` an Object, and so on): the report shows each row that would type a page, with how many, and nothing is typed by it until you say yes, with `--import-map` for the run (`import_map=True` from Python) or `y` at the question a run at a terminal asks. Your own `--map` wins for any tag it names, a template is never typed by the table, and a page whose tags name two types stays untyped and is named as ambiguous. A map becomes a Map (its width and height from the map's bounds, its picture's address as `image_url`, which loads only while the LegendKeeper account's picture exists) and each pin a Pin on it, placed from the bottom left and pointing at the page it links (since 0.42.0 from the export file; since 0.53.0 through the API too, the same pins on the same pixels). Since 0.59.0 each region and path on a map becomes a Zone (`shape` `polygon` or `line`) with a Marker at each of its points, in order and placed the way pins are; a feature linking a page that comes in as a Zone, as an OnlyWorlds push writes them, gives its Markers to that Zone, and any other gets a Zone of its own naming the page in `x_legendkeeper_page`, which also becomes a Location's `zone` when the page is a Location with none set. Since 0.60.0 a region drawn as several polygons is a Zone made of parts: no Markers of its own, and one part Zone per polygon in its `linked_zones`, each with its Markers. Labels are named in the report, not read. Page blocks become Markdown in the description, a sidebar or infobox key becomes a field when its name is one, else `x_legendkeeper_<key>`; a titled link list becomes a link field when the element's type has one of that name, else a Relation per target; inline mentions keep their text and join `x_legendkeeper_mentions`; a timeline's events become Events with the raw minutes and the formatted date kept as extensions, and since 0.56.0 the timeline itself is a Narrative with supertype `Timeline` holding them, each lane a child Narrative. Since 0.57.0 each calendar a timeline names becomes a Construct with supertype `calendar`, the LegendKeeper calendar kept whole in `x_legendkeeper_calendar`; when the [calendar profile](https://github.com/OnlyWorlds/schema-dist/blob/main/profiles/calendar.md) can say it exactly, the Construct carries `atlas_calendar` (one step a day), the Events on it get `start_date` and `end_date` in days, and the world's `time_basic_unit` is `day`. Five of LegendKeeper's six preset calendars are exact (Gregorian and Harptos in the profile's version 2); Scrolls keeps its minutes only, and the report says why. Since 0.59.0 a leap day's `day` is not read (LegendKeeper does not read it either), and the report counts the Events dated before a calendar's first era, which LegendKeeper still names and the profile reads with no era. Since 0.38.0, what LegendKeeper hides, the folder hides, never dropped: a hidden resource becomes an element carrying `hidden: true`, and a hidden page or a `secret` block on a visible resource becomes its own hidden Narrative (`<resource>: Secret`, its text in `story`, linked back), the page keeping only its visible text; the report counts each kind (`--include-hidden` and `--include-secrets` are gone). Since 0.55.0 a board becomes a Map with supertype `Board` from either road: each page card a Pin on the page it shows (a card showing another board places that board's Map, which takes this one as `parent_map`), each frame a Zone (subtype `Frame`) with a Marker at each corner, each arrow between two cards or frames a Relation (supertype `Board link`), each note and text a Narrative pinned where it sits; positions in the Map's own units from its bottom left, the rest of the board counted in the report. The board's records are kept whole in the folder's `records/legendkeeper/boards/`, named on the Map, so nothing is dropped and every element stays within the API's size limit. Ids are UUIDv5 of the project and resource id, so a second import finds the same elements. Since 0.54.0, a project written by an OnlyWorlds push comes back as the same elements: a uuid in a key-value row `onlyworlds-id` is the element's id, tags `ow-supertype:` and `ow-subtype:` fill the two fields, and extension keys (`x_*`, `atlas_*`, `shadow_*`) return under their own names. Since 0.38.0 it also reads LegendKeeper's own export, `python -m onlyworlds.legendkeeper --file EXPORT.lk OUT-DIR` (the `.lk` or the `.json`; the Markdown export is lossy and not read), with no key: a real project of 41 resources is its fixture, and the `.lk` and `.json` give the same folder byte for byte. The export's templates carry `x_legendkeeper_template`; its tutorial pages are imported like any page, since nothing marks them. -- **Import from Notion** (since 0.19.0): `python -m onlyworlds.notion EXPORT.zip OUT-DIR` (or `import_notion`) reads a Markdown & CSV export from Notion into a world folder, with no AI and no account. Since 0.47.0 it reads both layouts real exports use: folders named by title alone, and a flat export with every page and table in one folder, where each table row is paired with its own page. A database becomes elements of a category when its title names one (Characters, Locations) or a `Type` column does; a column maps to a field when its name, lowercased with spaces as underscores, is that field's name; a relation column maps to a link field of the same name, each target resolved by its Notion id or its title; a page becomes a Narrative with its Markdown as the description and its sub-pages their own; attachments go to `media/notion/`. Nothing is dropped: every column the door could not place is kept as `x_notion_<column>` and named in the report, with every link it could not resolve, so you see what to rename in Notion before the next export. `--plan` prints the same report and writes nothing. Ids are stable across exports of the same workspace. Built on the export's shape as seen in practice; a real export is the fixture still to be banked. +- **Import from Notion** (since 0.19.0): `python -m onlyworlds.notion EXPORT.zip OUT-DIR` (or `import_notion`) reads a Markdown & CSV export from Notion into a world folder, with no AI and no account. Since 0.47.0 it reads both layouts real exports use: folders named by title alone, and a flat export with every page and table in one folder, where each table row is paired with its own page. A database becomes elements of one element type when its title names one (Characters, Locations) or a `Type` column does; a column maps to a field when its name, lowercased with spaces as underscores, is that field's name; a relation column maps to a link field of the same name, each target resolved by its Notion id or its title; a page becomes a Narrative with its Markdown as the description and its sub-pages their own; attachments go to `media/notion/`. Nothing is dropped: every column the door could not place is kept as `x_notion_<column>` and named in the report, with every link it could not resolve, so you see what to rename in Notion before the next export. `--plan` prints the same report and writes nothing. Ids are stable across exports of the same workspace. Built on the export's shape as seen in practice; a real export is the fixture still to be banked. - **The calendar profile** (since 0.68.0): `onlyworlds.calendar` reads a world's own calendars as the [calendar profile](https://github.com/OnlyWorlds/schema-dist/blob/main/profiles/calendar.md) defines them. `read_calendar_value(raw)` reads an `atlas_calendar` value (an object, or the same object as a JSON string) and gives `None` for anything the profile refuses; `world_calendars(elements)` finds every calendar in a world by the field, and `resolve_calendar` picks the one to read dates through (named `resolve_calendar_lens` before 0.69.0; the old name still answers, with a deprecation warning). `breakdown_step(cfg, step)` and `format_step(cfg, step)` turn an integer step into the calendar's date (months, days outside the months, weekdays, eras, and version 2's leap exceptions and offset), and `parse_date(cfg, text)` reads written words back to a step. It is the [TypeScript SDK](/docs/development/typescript)'s calendar reader under snake_case names, gives the same answers (both replay the profile's fixture, and the two were compared on 175,705 inputs before the release), and reads the calendars the LegendKeeper door writes. - **The lens profile** (since 0.74.0): `resolve_lens(world, lens, reader, as_of=, clock=)` reads a world through a lens for one reader (the kept elements in order, the cut by reason, the mail part), with `is_lens`, `is_template` and `lenses_in_use`, as [Lenses](/docs/lenses) describes. Since 0.77.0, `world_graph(world, reader, *, lens=None, as_of=None, clock=None, rooms=False, hidden=False, proposed=False, map_space=False)` reads the same snapshot as nodes and edges, with `edges_cut` counting by reason the links it leaves out; a refused flag raises `ValueError` naming it. Since 0.78.0, `degree_of(graph)` gives each node's count of edges, in or out: rank by it for "most linked". Since 0.79.0, `DATE_FIELD` is the profile's date table and `date_of(el)` an element's date as that table reads it (the whole number in its type's date field, else `None`), so a timeline dates elements exactly as the lens's fence does. Since 0.82.0 a lens's rows for a reader below the owner are the bodies the API serves that reader, the owner's the bodies as stored; since 0.82.1 a contributor's or a guest's row keeps a link to a proposed element it sees, and a lens's note keyed to one, the public rung loses both, and no row carries a stored `x_served_trimmed`. - **The address profile** (since 0.73.0): `parse_ow_link(text)` reads an element's link in any of the three spellings, with its moment and lens, and `element_address(address)` writes one; a refused string raises `AddressError` with the profile's `reason`, as [Addresses](/docs/schema/profiles/addresses) describes. diff --git a/src/content/docs/docs/development/toolkit.md b/src/content/docs/docs/development/toolkit.md index 805c55ac..018b2c7f 100644 --- a/src/content/docs/docs/development/toolkit.md +++ b/src/content/docs/docs/development/toolkit.md @@ -54,16 +54,16 @@ The skill files themselves sit in the repository's `skills/` folder, one folder | Start | `start` | The entry point: works out your situation, routes you to the right skill, and connects a folder to your onlyworlds.com account when you want one. | | | `setup` | Sets up a world for work rather than fiction (a company, a team, an AI's own home, a council, a software project) from a starter pack: house rules, a world skill for the AIs, a seed and the invites. The world's Charter and Guide carry the reading-aid mark (`x_charter_of`), so every tool shows them first. | | Structure it | `import` | Turns notes, a manuscript, PDFs, a wiki or old session notes into a world folder Atlas opens, or reconciles them into an existing world. Invents no fields. | -| | `model` | How to represent a system (magic, a political order, an economy, a tech tree) in the 22 types, and every type's fields across [every category](/docs/schema/). | +| | `model` | How to represent a system (magic, a political order, an economy, a tech tree) in the 22 types, and every type's fields across [every element type](/docs/schema/). | | Grow it | `read` | Checks a whole world and writes one of three reports: the survey report (a creative brief of what it holds), the links report (the connections it is missing) or the consistency report (where it contradicts itself). | | | `draw` | Draws a world as a graph, its maps with their pins and zones, or its events on a timeline, in a file you open in a browser. It never changes the world. | | Play in it and keep it true | `context` | Designs how the right part of a world gets loaded into each AI session: fresh, scoped, sourced. | | | `update` | Writes a finished session (notes, recap, transcript) back into the world through a change list you approve, so canon holds. | | Move it | `carry` | Moves a world between files, tools and homes: one [`.owworld` file](/docs/schema/folders) and back, an export from World Anvil, LegendKeeper, Kanka, Campfire or Notion, Markdown or OKF, a folder to an account and back. | | Build on it | `develop` | Builds a tool, game, app or AI agent on world data: the API, the SDK, the MCP server, credentials and deployment. | -| | `council` | Ask about, propose or back a change to the standard, when its categories don't fit. | +| | `council` | Ask about, propose or back a change to the standard, when its element types don't fit. | -Each skill's full name is `onlyworlds-<skill>` (in Claude Code, `/onlyworlds:onlyworlds-<skill>`). The orchestration agent, `ow-agent`, chains several skills for multi-step jobs, such as importing a whole corpus and then reading it for missing links. The knowledge base covers the schema reference, the category descriptions, and decision trees for ambiguous modeling choices. +Each skill's full name is `onlyworlds-<skill>` (in Claude Code, `/onlyworlds:onlyworlds-<skill>`). The orchestration agent, `ow-agent`, chains several skills for multi-step jobs, such as importing a whole corpus and then reading it for missing links. The knowledge base covers the schema reference, the element type descriptions, and decision trees for ambiguous modeling choices. ### Coming from 4.8 diff --git a/src/content/docs/docs/getting-started/index.md b/src/content/docs/docs/getting-started/index.md index 78dc13d9..e11f8d28 100644 --- a/src/content/docs/docs/getting-started/index.md +++ b/src/content/docs/docs/getting-started/index.md @@ -5,13 +5,13 @@ description: What OnlyWorlds is, and how to make a first read and write against This page is for developers and AI agents that read and write worlds through the API. To build a world without code, start at [onlyworlds.com/start](https://www.onlyworlds.com/start) or open [Atlas](https://atlas.onlyworlds.com). -OnlyWorlds is an open standard for world data. It structures a world into [22 element categories](/docs/schema/) (Characters, Locations, Events and more) with fields and typed links between them, so any tool or AI agent that speaks the standard can read and write the same worlds. +OnlyWorlds is an open standard for world data. It structures a world into [22 element types](/docs/schema/) (Characters, Locations, Events and more) with fields and typed links between them, so any tool or AI agent that speaks the standard can read and write the same worlds. It has four layers: | Layer | What it is | | :--- | :--- | -| **Standard** | The element categories, their fields and links, kept as YAML files, governed in public by the [Council](https://council.onlyworlds.com). See [Schema](/docs/schema/). | +| **Standard** | The element types, their fields and links, kept as YAML files, governed in public by the [Council](https://council.onlyworlds.com). See [Schema](/docs/schema/). | | **Platform** | [onlyworlds.com](https://www.onlyworlds.com) stores worlds, their members and roles, and issues per-world keys. | | **Interfaces** | The REST API, the change feed, the MCP server and agent seats. | | **Clients** | Apps and tools (Atlas, the Obsidian plugin, converters), SDKs, and AI agents. | @@ -47,7 +47,7 @@ curl -H "API-Key: ow_r_your_key" \ Lists come in an envelope: `{"data": [...], "has_more": false, "next_cursor": null}`. When `has_more` is true, pass `next_cursor` back as `?cursor=` for the next page. To try this before you have a world, use Moppetopia's demo key `0000000001` (the home page's sample world), which reads without a PIN ([Demo keys](/docs/getting-started/keys#demo-keys) lists the others). -Every category has the same routes at its singular name: `/api/v2/location/`, `/api/v2/event/`, and so on. [Reads and pagination](/docs/development/api/reads) covers filters, sparse fields and expansion. +Every element type has the same routes at its singular name: `/api/v2/location/`, `/api/v2/event/`, and so on. [Reads and pagination](/docs/development/api/reads) covers filters, sparse fields and expansion. ### 3. Write diff --git a/src/content/docs/docs/schema/conventions.mdx b/src/content/docs/docs/schema/conventions.mdx index 7cd83b38..1fd601e5 100644 --- a/src/content/docs/docs/schema/conventions.mdx +++ b/src/content/docs/docs/schema/conventions.mdx @@ -1,19 +1,19 @@ --- title: Modelling conventions -description: How to model a world with the categories and fields the schema already has. +description: How to model a world with the element types and fields the schema already has. --- -The standard covers most worlds with the categories and fields it has. Before reaching for a new field or category, check whether one of these conventions carries the case. When none does, the [Council](https://council.onlyworlds.com) is where the standard changes. +The standard covers most worlds with the element types and fields it has. Before reaching for a new field or element type, check whether one of these conventions carries the case. When none does, the [Council](https://council.onlyworlds.com) is where the standard changes. ## Use only what you need -A world can use any subset of the categories. Only `name` is required on an element, so a world of nothing but Objects is a valid world, and most tools work with two to four categories. +A world can use any subset of the element types. Only `name` is required on an element, so a world of nothing but Objects is a valid world, and most tools work with two to four element types. -## Supertype and subtype are the world's own categories +## Supertype and subtype are the world's own kinds -Every element has two free-text classification fields: `supertype`, the top-level category the element belongs to, and `subtype`, a further classification within it. The schema fixes no values, so each world defines its own: a Location with supertype `City` and subtype `Port`, an Institution with supertype `Guild`. +Every element has two free-text classification fields: `supertype`, the top-level kind the element belongs to, and `subtype`, a further classification within it. The schema fixes no values, so each world defines its own: a Location with supertype `City` and subtype `Port`, an Institution with supertype `Guild`. -Both sort elements inside their category: a Location with supertype `City` is still a Location, and no supertype adds a category to the standard. +Both sort elements inside their element type: a Location with supertype `City` is still a Location, and no supertype adds an element type to the standard. The API filters on both by exact value (`?supertype=City`), so keep the vocabulary consistent within a world. Some platform features use supertypes too: an agent's own Character has supertype `Agent`, and in-world messages are Narratives with supertype `Message` (see below). @@ -30,13 +30,13 @@ When the connection itself has content, make it a [Relation](/docs/schema/elemen | `start_date`, `end_date` | When it began and ended, in world time units | | `intensity` | Significance, 0 to 100 | | `events` | Events where the relation is involved | -| `characters`, `institutions`, `locations`, … | The elements it connects, across most categories | +| `characters`, `institutions`, `locations`, … | The elements it connects, across most element types | If the Consul's ties to the Hegemony have a history and a span worth recording, they are a Relation; the Consul's current location is a link. -## Choosing between neighbouring categories +## Choosing between neighbouring element types -The category definitions draw these lines themselves: +The element type definitions draw these lines themselves: | Pair | The line | | :--- | :--- | @@ -49,11 +49,11 @@ The category definitions draw these lines themselves: | Event / Narrative | An Event is "a time-bound happening within the world"; Narratives are "stories told in your world, and can involve the organization or reinterpretation of Events." | | Location / Zone | A Location is "a distinct place within the world where activities occur and elements converge"; Zones "are not defined by geometry themselves but gain spatial presence through linked map markers." | -**One magic system, three categories.** The Ember Art, a school of fire magic, is a Construct. Firebolt, a spell taught in it, is an Ability with the Ember Art as its `tradition`. The Ember Tide, the force the spell draws on, is a Phenomenon: the Ability's `source`, with Firebolt in its `empowerments` and the mages who can steer it in `wielders`. The night a mage burned the gates of Varn with it is an Event. +**One magic system, three element types.** The Ember Art, a school of fire magic, is a Construct. Firebolt, a spell taught in it, is an Ability with the Ember Art as its `tradition`. The Ember Tide, the force the spell draws on, is a Phenomenon: the Ability's `source`, with Firebolt in its `empowerments` and the mages who can steer it in `wielders`. The night a mage burned the gates of Varn with it is an Event. ## Zones take their shape from Markers -A Zone has no geometry of its own. Its shape on a [Map](/docs/schema/element_categories/map) is a set of [Markers](/docs/schema/element_categories/marker), each linked to the Map and the Zone, at an `x`/`y` coordinate, with an `order` that sequences them into a polygon or line (`0` is the first point). Markers are boundary points and usually carry an empty name. A [Pin](/docs/schema/element_categories/pin) places one element of any category at one point on one Map. +A Zone has no geometry of its own. Its shape on a [Map](/docs/schema/element_categories/map) is a set of [Markers](/docs/schema/element_categories/marker), each linked to the Map and the Zone, at an `x`/`y` coordinate, with an `order` that sequences them into a polygon or line (`0` is the first point). Markers are boundary points and usually carry an empty name. A [Pin](/docs/schema/element_categories/pin) places one element of any element type at one point on one Map. A Zone with no Markers is a valid Zone: a region the world names before anyone draws it. Markers added later give it a shape on one Map; the Zone keeps its id and fields, and Markers on a second Map give it a shape there too. @@ -79,7 +79,7 @@ A lens is a saved way of reading a world: which elements, how far from a startin ## Data the schema does not model -Two places hold what the categories have no field for: +Two places hold what the element types have no field for: - **Extension fields** (`x_*`) on the element itself, for small amounts of tool-specific data. They are stored and returned verbatim, up to 64 KB per element. See [Fields](/docs/schema/fields#extension-fields). - **Your own database**, beside the world, for high-volume data such as logs, statistics or simulation state. Key each row by the element's `id`. diff --git a/src/content/docs/docs/schema/element_categories/ability.md b/src/content/docs/docs/schema/element_categories/ability.md index 90b36d4a..8de502b0 100644 --- a/src/content/docs/docs/schema/element_categories/ability.md +++ b/src/content/docs/docs/schema/element_categories/ability.md @@ -28,7 +28,7 @@ They are distinct from: ## Fields -Drawn with the other categories: [what Ability links to](/docs/schema/?kind=ability#what-links-to-what). +Drawn with the other element types: [what Ability links to](/docs/schema/?kind=ability#what-links-to-what). Integers are whole numbers: the API truncates a decimal, and a range is a display hint it does not enforce ([Field types](/docs/schema/fields#field-types)). diff --git a/src/content/docs/docs/schema/element_categories/character.md b/src/content/docs/docs/schema/element_categories/character.md index c28951e0..8a7e6d0e 100644 --- a/src/content/docs/docs/schema/element_categories/character.md +++ b/src/content/docs/docs/schema/element_categories/character.md @@ -24,7 +24,7 @@ Every field below is optional. The TTRPG group (`level`, `hit_points` and six ab ## Fields -Drawn with the other categories: [what Character links to](/docs/schema/?kind=character#what-links-to-what). +Drawn with the other element types: [what Character links to](/docs/schema/?kind=character#what-links-to-what). Integers are whole numbers: the API truncates a decimal, and a range is a display hint it does not enforce ([Field types](/docs/schema/fields#field-types)). diff --git a/src/content/docs/docs/schema/element_categories/collective.md b/src/content/docs/docs/schema/element_categories/collective.md index 8dc06b07..1e81a9a8 100644 --- a/src/content/docs/docs/schema/element_categories/collective.md +++ b/src/content/docs/docs/schema/element_categories/collective.md @@ -30,7 +30,7 @@ They are distinct from: ## Fields -Drawn with the other categories: [what Collective links to](/docs/schema/?kind=collective#what-links-to-what). +Drawn with the other element types: [what Collective links to](/docs/schema/?kind=collective#what-links-to-what). Integers are whole numbers: the API truncates a decimal, and a range is a display hint it does not enforce ([Field types](/docs/schema/fields#field-types)). diff --git a/src/content/docs/docs/schema/element_categories/construct.md b/src/content/docs/docs/schema/element_categories/construct.md index 01ec102e..e717c3d9 100644 --- a/src/content/docs/docs/schema/element_categories/construct.md +++ b/src/content/docs/docs/schema/element_categories/construct.md @@ -28,7 +28,7 @@ They are distinct from: ## Fields -Drawn with the other categories: [what Construct links to](/docs/schema/?kind=construct#what-links-to-what). +Drawn with the other element types: [what Construct links to](/docs/schema/?kind=construct#what-links-to-what). Integers are whole numbers: the API truncates a decimal, and a range is a display hint it does not enforce ([Field types](/docs/schema/fields#field-types)). diff --git a/src/content/docs/docs/schema/element_categories/creature.md b/src/content/docs/docs/schema/element_categories/creature.md index 19019ce3..90f8ed98 100644 --- a/src/content/docs/docs/schema/element_categories/creature.md +++ b/src/content/docs/docs/schema/element_categories/creature.md @@ -28,7 +28,7 @@ They are distinct from: ## Fields -Drawn with the other categories: [what Creature links to](/docs/schema/?kind=creature#what-links-to-what). +Drawn with the other element types: [what Creature links to](/docs/schema/?kind=creature#what-links-to-what). Integers are whole numbers: the API truncates a decimal, and a range is a display hint it does not enforce ([Field types](/docs/schema/fields#field-types)). diff --git a/src/content/docs/docs/schema/element_categories/event.md b/src/content/docs/docs/schema/element_categories/event.md index ea77f8b1..3a0b2ddd 100644 --- a/src/content/docs/docs/schema/element_categories/event.md +++ b/src/content/docs/docs/schema/element_categories/event.md @@ -31,7 +31,7 @@ Events are about what happens. The rest of the schema gives it meaning, context, ## Fields -Drawn with the other categories: [what Event links to](/docs/schema/?kind=event#what-links-to-what). +Drawn with the other element types: [what Event links to](/docs/schema/?kind=event#what-links-to-what). Integers are whole numbers: the API truncates a decimal, and a range is a display hint it does not enforce ([Field types](/docs/schema/fields#field-types)). diff --git a/src/content/docs/docs/schema/element_categories/family.md b/src/content/docs/docs/schema/element_categories/family.md index bb2ed332..c08eea27 100644 --- a/src/content/docs/docs/schema/element_categories/family.md +++ b/src/content/docs/docs/schema/element_categories/family.md @@ -29,7 +29,7 @@ They are distinct from: ## Fields -Drawn with the other categories: [what Family links to](/docs/schema/?kind=family#what-links-to-what). +Drawn with the other element types: [what Family links to](/docs/schema/?kind=family#what-links-to-what). ### Identity diff --git a/src/content/docs/docs/schema/element_categories/institution.md b/src/content/docs/docs/schema/element_categories/institution.md index 4946da68..cdc913a9 100644 --- a/src/content/docs/docs/schema/element_categories/institution.md +++ b/src/content/docs/docs/schema/element_categories/institution.md @@ -26,7 +26,7 @@ They are distinct from: ## Fields -Drawn with the other categories: [what Institution links to](/docs/schema/?kind=institution#what-links-to-what). +Drawn with the other element types: [what Institution links to](/docs/schema/?kind=institution#what-links-to-what). Integers are whole numbers: the API truncates a decimal, and a range is a display hint it does not enforce ([Field types](/docs/schema/fields#field-types)). diff --git a/src/content/docs/docs/schema/element_categories/language.md b/src/content/docs/docs/schema/element_categories/language.md index b2a15389..97fb7d03 100644 --- a/src/content/docs/docs/schema/element_categories/language.md +++ b/src/content/docs/docs/schema/element_categories/language.md @@ -7,7 +7,7 @@ sidebar: <img src="/icons/language.png" alt="" width="48" height="48" class="ow-type-icon" /> -Languages are systems of shared meaning, whether natural, constructed, or symbolic. This category captures their role within a world: how they sound, how they are written, how they function grammatically, and where or by whom they are used. Languages may carry political weight, cultural importance, or fictional depth. The category's fields are designed to support both lightweight notation and full conlang development. +Languages are systems of shared meaning, whether natural, constructed, or symbolic. This element type captures their role within a world: how they sound, how they are written, how they function grammatically, and where or by whom they are used. Languages may carry political weight, cultural importance, or fictional depth. Its fields are designed to support both lightweight notation and full conlang development. Languages are a world's methods of communication. They interact with: @@ -26,7 +26,7 @@ They are distinct from: ## Fields -Drawn with the other categories: [what Language links to](/docs/schema/?kind=language#what-links-to-what). +Drawn with the other element types: [what Language links to](/docs/schema/?kind=language#what-links-to-what). ### Structure diff --git a/src/content/docs/docs/schema/element_categories/law.md b/src/content/docs/docs/schema/element_categories/law.md index b2a38b93..dd7617e3 100644 --- a/src/content/docs/docs/schema/element_categories/law.md +++ b/src/content/docs/docs/schema/element_categories/law.md @@ -28,7 +28,7 @@ They are distinct from: ## Fields -Drawn with the other categories: [what Law links to](/docs/schema/?kind=law#what-links-to-what). +Drawn with the other element types: [what Law links to](/docs/schema/?kind=law#what-links-to-what). Integers are whole numbers: the API truncates a decimal, and a range is a display hint it does not enforce ([Field types](/docs/schema/fields#field-types)). diff --git a/src/content/docs/docs/schema/element_categories/location.md b/src/content/docs/docs/schema/element_categories/location.md index 96a10488..2b3f4ff1 100644 --- a/src/content/docs/docs/schema/element_categories/location.md +++ b/src/content/docs/docs/schema/element_categories/location.md @@ -29,7 +29,7 @@ They are distinct from: ## Fields -Drawn with the other categories: [what Location links to](/docs/schema/?kind=location#what-links-to-what). +Drawn with the other element types: [what Location links to](/docs/schema/?kind=location#what-links-to-what). Integers are whole numbers: the API truncates a decimal, and a range is a display hint it does not enforce ([Field types](/docs/schema/fields#field-types)). diff --git a/src/content/docs/docs/schema/element_categories/map.md b/src/content/docs/docs/schema/element_categories/map.md index 42cbcd4c..136cf674 100644 --- a/src/content/docs/docs/schema/element_categories/map.md +++ b/src/content/docs/docs/schema/element_categories/map.md @@ -27,7 +27,7 @@ They are distinct from: ## Fields -Drawn with the other categories: [what Map links to](/docs/schema/?kind=map#what-links-to-what). +Drawn with the other element types: [what Map links to](/docs/schema/?kind=map#what-links-to-what). Integers are whole numbers: the API truncates a decimal, and a range is a display hint it does not enforce ([Field types](/docs/schema/fields#field-types)). diff --git a/src/content/docs/docs/schema/element_categories/marker.md b/src/content/docs/docs/schema/element_categories/marker.md index ae363f0d..8a4ec635 100644 --- a/src/content/docs/docs/schema/element_categories/marker.md +++ b/src/content/docs/docs/schema/element_categories/marker.md @@ -24,7 +24,7 @@ They are distinct from: ## Fields -Drawn with the other categories: [what Marker links to](/docs/schema/?kind=marker#what-links-to-what). +Drawn with the other element types: [what Marker links to](/docs/schema/?kind=marker#what-links-to-what). Integers are whole numbers: the API truncates a decimal, and a range is a display hint it does not enforce ([Field types](/docs/schema/fields#field-types)). diff --git a/src/content/docs/docs/schema/element_categories/narrative.md b/src/content/docs/docs/schema/element_categories/narrative.md index 8a4d3afe..f6760635 100644 --- a/src/content/docs/docs/schema/element_categories/narrative.md +++ b/src/content/docs/docs/schema/element_categories/narrative.md @@ -30,7 +30,7 @@ They are distinct from: ## Fields -Drawn with the other categories: [what Narrative links to](/docs/schema/?kind=narrative#what-links-to-what). +Drawn with the other element types: [what Narrative links to](/docs/schema/?kind=narrative#what-links-to-what). Integers are whole numbers: the API truncates a decimal, and a range is a display hint it does not enforce ([Field types](/docs/schema/fields#field-types)). diff --git a/src/content/docs/docs/schema/element_categories/object.md b/src/content/docs/docs/schema/element_categories/object.md index fdc32d97..6039681b 100644 --- a/src/content/docs/docs/schema/element_categories/object.md +++ b/src/content/docs/docs/schema/element_categories/object.md @@ -28,7 +28,7 @@ They are distinct from: ## Fields -Drawn with the other categories: [what Object links to](/docs/schema/?kind=object#what-links-to-what). +Drawn with the other element types: [what Object links to](/docs/schema/?kind=object#what-links-to-what). Integers are whole numbers: the API truncates a decimal, and a range is a display hint it does not enforce ([Field types](/docs/schema/fields#field-types)). diff --git a/src/content/docs/docs/schema/element_categories/phenomenon.md b/src/content/docs/docs/schema/element_categories/phenomenon.md index c09ebce1..2e80e8df 100644 --- a/src/content/docs/docs/schema/element_categories/phenomenon.md +++ b/src/content/docs/docs/schema/element_categories/phenomenon.md @@ -28,7 +28,7 @@ They are distinct from: ## Fields -Drawn with the other categories: [what Phenomenon links to](/docs/schema/?kind=phenomenon#what-links-to-what). +Drawn with the other element types: [what Phenomenon links to](/docs/schema/?kind=phenomenon#what-links-to-what). Integers are whole numbers: the API truncates a decimal, and a range is a display hint it does not enforce ([Field types](/docs/schema/fields#field-types)). diff --git a/src/content/docs/docs/schema/element_categories/pin.md b/src/content/docs/docs/schema/element_categories/pin.md index 5e13a940..dfa79e08 100644 --- a/src/content/docs/docs/schema/element_categories/pin.md +++ b/src/content/docs/docs/schema/element_categories/pin.md @@ -24,7 +24,7 @@ They are distinct from: ## Fields -Drawn with the other categories: [what Pin links to](/docs/schema/?kind=pin#what-links-to-what). +Drawn with the other element types: [what Pin links to](/docs/schema/?kind=pin#what-links-to-what). Integers are whole numbers: the API truncates a decimal, and a range is a display hint it does not enforce ([Field types](/docs/schema/fields#field-types)). diff --git a/src/content/docs/docs/schema/element_categories/relation.md b/src/content/docs/docs/schema/element_categories/relation.md index 8ba785a2..aad60bff 100644 --- a/src/content/docs/docs/schema/element_categories/relation.md +++ b/src/content/docs/docs/schema/element_categories/relation.md @@ -30,7 +30,7 @@ They are distinct from: ## Fields -Drawn with the other categories: [what Relation links to](/docs/schema/?kind=relation#what-links-to-what). +Drawn with the other element types: [what Relation links to](/docs/schema/?kind=relation#what-links-to-what). Integers are whole numbers: the API truncates a decimal, and a range is a display hint it does not enforce ([Field types](/docs/schema/fields#field-types)). diff --git a/src/content/docs/docs/schema/element_categories/species.md b/src/content/docs/docs/schema/element_categories/species.md index f2eb00ee..ee08d22d 100644 --- a/src/content/docs/docs/schema/element_categories/species.md +++ b/src/content/docs/docs/schema/element_categories/species.md @@ -29,7 +29,7 @@ They are distinct from: ## Fields -Drawn with the other categories: [what Species links to](/docs/schema/?kind=species#what-links-to-what). +Drawn with the other element types: [what Species links to](/docs/schema/?kind=species#what-links-to-what). Integers are whole numbers: the API truncates a decimal, and a range is a display hint it does not enforce ([Field types](/docs/schema/fields#field-types)). diff --git a/src/content/docs/docs/schema/element_categories/title.md b/src/content/docs/docs/schema/element_categories/title.md index 00d54f44..337eda9f 100644 --- a/src/content/docs/docs/schema/element_categories/title.md +++ b/src/content/docs/docs/schema/element_categories/title.md @@ -32,7 +32,7 @@ They are distinct from: ## Fields -Drawn with the other categories: [what Title links to](/docs/schema/?kind=title#what-links-to-what). +Drawn with the other element types: [what Title links to](/docs/schema/?kind=title#what-links-to-what). Integers are whole numbers: the API truncates a decimal, and a range is a display hint it does not enforce ([Field types](/docs/schema/fields#field-types)). diff --git a/src/content/docs/docs/schema/element_categories/trait.md b/src/content/docs/docs/schema/element_categories/trait.md index f998ccd1..a0d957c4 100644 --- a/src/content/docs/docs/schema/element_categories/trait.md +++ b/src/content/docs/docs/schema/element_categories/trait.md @@ -26,7 +26,7 @@ They are distinct from: ## Fields -Drawn with the other categories: [what Trait links to](/docs/schema/?kind=trait#what-links-to-what). +Drawn with the other element types: [what Trait links to](/docs/schema/?kind=trait#what-links-to-what). Integers are whole numbers: the API truncates a decimal, and a range is a display hint it does not enforce ([Field types](/docs/schema/fields#field-types)). diff --git a/src/content/docs/docs/schema/element_categories/zone.md b/src/content/docs/docs/schema/element_categories/zone.md index c772441e..6673b320 100644 --- a/src/content/docs/docs/schema/element_categories/zone.md +++ b/src/content/docs/docs/schema/element_categories/zone.md @@ -28,7 +28,7 @@ They are distinct from: ## Fields -Drawn with the other categories: [what Zone links to](/docs/schema/?kind=zone#what-links-to-what). +Drawn with the other element types: [what Zone links to](/docs/schema/?kind=zone#what-links-to-what). Integers are whole numbers: the API truncates a decimal, and a range is a display hint it does not enforce ([Field types](/docs/schema/fields#field-types)). diff --git a/src/content/docs/docs/schema/example.md b/src/content/docs/docs/schema/example.md index 175617c9..84a67f53 100644 --- a/src/content/docs/docs/schema/example.md +++ b/src/content/docs/docs/schema/example.md @@ -1,6 +1,6 @@ --- title: A worked example -description: One small world, Moppetopia, read through the API to show how the categories, links and timeline fit together. +description: One small world, Moppetopia, read through the API to show how the element types, links and timeline fit together. --- Moppetopia is a demo world: a civilization of felt beings called moppets, a navy that fights in puddles and in space, and an old war its people tell in different ways. Anyone can read it with its demo key `0000000001` (read-only, no PIN). Every call on this page runs as written. @@ -59,9 +59,9 @@ So to find what a Character holds, read the Titles and check their `holders`: th Locations nest through `parent_location`, the wider Location a place is part of. Feltropolis has seven levels, each its own Location whose parent is Feltropolis; the places on a level name that level as theirs, so The Dry Room and Whisper Gallery sit under Level 3, The Squeeze. A tool can draw the station as a tree from that one field. -## Same name, two categories +## Same name, two element types -The Treaty of Soft Landings ended the war, and Moppetopia holds it twice. As a **Law** it is the document: its `declaration` holds the wording, its `purpose` why it was made. As an **Event** it is the signing: a `start_date`, the Event that triggered it (The Great Puddle War), and the Locations where it happened. The name is shared; what each element can carry is set by its category. +The Treaty of Soft Landings ended the war, and Moppetopia holds it twice. As a **Law** it is the document: its `declaration` holds the wording, its `purpose` why it was made. As an **Event** it is the signing: a `start_date`, the Event that triggered it (The Great Puddle War), and the Locations where it happened. The name is shared; what each element can carry is set by its element type. ## One Event, two stories @@ -89,4 +89,4 @@ Dates are integers on the world's own timeline. Moppetopia counts in years (`tim ## What it leaves out -Moppetopia uses all 22 categories, several of them once: one Family, one Language, one Phenomenon, one Relation. Most of its elements leave most fields empty, and the world is still valid: [Fields](/docs/schema/fields) lists what is required. Its two Maps (a space map, and the planet's surface as its `parent_map` child) carry the Pins, Markers and Zones; [Maps](/docs/schema/element_categories/map) covers how those fit together. +Moppetopia uses all 22 element types, several of them once: one Family, one Language, one Phenomenon, one Relation. Most of its elements leave most fields empty, and the world is still valid: [Fields](/docs/schema/fields) lists what is required. Its two Maps (a space map, and the planet's surface as its `parent_map` child) carry the Pins, Markers and Zones; [Maps](/docs/schema/element_categories/map) covers how those fit together. diff --git a/src/content/docs/docs/schema/fields.mdx b/src/content/docs/docs/schema/fields.mdx index d7623e46..3423c5e2 100644 --- a/src/content/docs/docs/schema/fields.mdx +++ b/src/content/docs/docs/schema/fields.mdx @@ -5,7 +5,7 @@ description: The base fields every element carries, the field types, what is req import WriteBody from '../../../../components/figures/WriteBody.astro'; -Every element carries the same base fields, then the fields of its own category. Category fields are listed on each category's page, for example [Character](/docs/schema/element_categories/character). +Every element carries the same base fields, then the fields of its own element type. Each element type's own fields are listed on its page, for example [Character](/docs/schema/element_categories/character). ## Base fields @@ -15,13 +15,13 @@ Every element carries the same base fields, then the fields of its own category. | `name` | string | Yes: the key must be present; an empty string is accepted | Display name, up to 255 characters | | `world` | string (uuid) | No (set by the API key; never sent in a body) | The world this element belongs to | | `description` | string | No | Any kind of details about the element | -| `supertype` | string | No | The top-level category the element belongs to in its world, up to 128 characters | +| `supertype` | string | No | The top-level kind the element belongs to in its world, up to 128 characters | | `subtype` | string | No | A further classification within the supertype, up to 128 characters | | `image_url` | string (url) | No | Link to a representative image, up to 1024 characters | Ids are UUIDv7 when the server mints them, which makes them time-sortable. A client may supply its own `id` on create: any RFC 4122 UUID is accepted. On `PUT` and `PATCH` the path decides the id, and one in the body is ignored. -Supertype and subtype are free text, so each world defines its own kinds. They sort elements within their category and never add one. [Conventions](/docs/schema/conventions) covers how to use them. +An element's type is one of the 22; its supertype is the first sorting inside that type (a Character's supertype might be Wizard), and its subtype sorts it further. Supertype and subtype are free text, so each world defines its own kinds. They sort elements within their element type and never add one. [Conventions](/docs/schema/conventions) covers how to use them. ### Server-kept fields @@ -29,7 +29,7 @@ The API adds these to every element it returns. They are platform bookkeeping, n | Field | Description | | :--- | :--- | -| `type` | The element's category, as a lowercase slug (`character`), first key in every body | +| `type` | The element's type, as a lowercase slug (`character`), first key in every body | | `created_at`, `updated_at` | Timestamps | | `change_seq` | The world's change sequence at the element's last write | | `created_by` | The world membership that created the element, or null when the world's owner did | @@ -43,9 +43,9 @@ A write body that carries `type`, `created_at`, `updated_at` or `change_seq` is | :--- | :--- | :--- | :--- | | text | A string | `"…"`; empty is `""` | A Character's `background` | | integer | A whole number; some are bounded | an integer or `null` | A Character's `height` | -| single link | One element of a named category | a uuid or `null` | A Character's `location` (a Location) | -| multi link | Any number of elements of a named category | an array of uuids; empty is `[]` | A Character's `friends` (Characters) | -| generic link | One element of any category | two fields, `element_type` and `element_id` | A Pin's `element` | +| single link | One element of a named element type | a uuid or `null` | A Character's `location` (a Location) | +| multi link | Any number of elements of a named element type | an array of uuids; empty is `[]` | A Character's `friends` (Characters) | +| generic link | One element of any element type | two fields, `element_type` and `element_id` | A Pin's `element` | | array | A list of plain values | a JSON array | A world's `time_format_names` | Link fields use their bare names in both directions: `location`, `friends`. There is no `_id` or `_ids` suffix on the v2 API. @@ -65,7 +65,7 @@ Numbers are integers. The API truncates a decimal instead of rejecting it (`7.9` On every element, only `name` is required: the key must be present on create and full replace, and an empty string is accepted. Markers, which mark the boundary points of a Zone, are often unnamed. -That includes the map categories. A [Pin](/docs/schema/element_categories/pin) or [Marker](/docs/schema/element_categories/marker) without a map or a position is valid, so an app can keep pins that are not on any map yet. Every other field accepts `null`. +That includes the map element types. A [Pin](/docs/schema/element_categories/pin) or [Marker](/docs/schema/element_categories/marker) without a map or a position is valid, so an app can keep pins that are not on any map yet. Every other field accepts `null`. That is the floor for a valid element, not what every use needs: a map view needs a Pin's `map`, `x` and `y` before it can draw it, and a timeline needs dates. @@ -91,7 +91,7 @@ The base schema is what makes a world portable between tools. Data held in exten ## What a write body may carry -The same in all 22 categories: each key a body carries on `POST`, `PUT` or `PATCH` is stored, tolerated and ignored, or rejected with `422`. Text longer than its cap is a `422`, and so are extensions over 64 KB ([Writes](/docs/development/api/writes#field-rules)). +The same in all 22 element types: each key a body carries on `POST`, `PUT` or `PATCH` is stored, tolerated and ignored, or rejected with `422`. Text longer than its cap is a `422`, and so are extensions over 64 KB ([Writes](/docs/development/api/writes#field-rules)). <WriteBody /> diff --git a/src/content/docs/docs/schema/folders.mdx b/src/content/docs/docs/schema/folders.mdx index ae593a04..27f23730 100644 --- a/src/content/docs/docs/schema/folders.mdx +++ b/src/content/docs/docs/schema/folders.mdx @@ -16,7 +16,7 @@ moppetopia/ character/ admiral-fluffington--295f8866.json location/ - ... one folder per category present, lowercase singular + ... one folder per element type present, lowercase singular media/ optional; its format is not yet specified records/ optional; world data that is not elements, one folder per producer RECORDS.json the manifest: one entry per producer @@ -25,7 +25,7 @@ moppetopia/ <FolderExample /> -A folder holds one world. All 22 categories, `map`, `pin`, `zone` and `marker` included, live under `elements/<type>/`. A missing category folder means no elements of that category. +A folder holds one world. All 22 element types, `map`, `pin`, `zone` and `marker` included, live under `elements/<type>/`. A missing element type folder means no elements of that element type. The `id` inside a file is the element's identity. The filename is for people: rename a file and nothing breaks. The recommended name is `<slug>--<tail>.json`. The slug is the name with its accents removed (José becomes jose), in lowercase ASCII, each run of other characters as one hyphen (an apostrophe included: The Consul’s Steinway becomes the-consul-s-steinway) and no hyphen at either end, cut to 40 characters with any hyphen left at the end removed. The tail is the id's last 8 characters. An element with no usable name gets `<id>.json`. @@ -57,7 +57,7 @@ Two keys are required: `id` (a non-empty string) and `name` (a string, which may ## Element files -An element file must hold a non-empty string `id`. The rest are the category's [fields](/docs/schema/fields), link fields under bare names holding an id or a list of ids, as in the API. Trimmed: +An element file must hold a non-empty string `id`. The rest are the element type's [fields](/docs/schema/fields), link fields under bare names holding an id or a list of ids, as in the API. Trimmed: ```json { @@ -89,7 +89,7 @@ A snapshot is a frozen copy of a world at one moment, such as a chapter's end. | `snapshot_label` | A label, such as `"ch05"` | | `snapshot_at` | Capture time (ISO 8601) | | `snapshot_change_seq` | The source's change cursor at capture | -| `snapshot_counts` | Optional: files written per category. A receipt; the files are the truth. | +| `snapshot_counts` | Optional: files written per element type. A receipt; the files are the truth. | | `snapshot_torn` | `true` only on a capture known to be inconsistent | | `writable` | `false`. Advisory: a tool may still write. The Unity SDK opens such a folder read-only and refuses to sync into it; Atlas opens it view only (since 1.90.0). | @@ -119,8 +119,8 @@ A body the server trimmed for a key that may not see every linked element carrie **Reading** -- MUST read every `*.json` in a category folder and key on the inner `id`; MUST NOT parse filenames. SHOULD skip a dot-prefixed file there: it is a tool's litter, not an element. -- MUST treat a missing category folder as empty, and MUST NOT require any `.<tool>/` folder. +- MUST read every `*.json` in an element type folder and key on the inner `id`; MUST NOT parse filenames. SHOULD skip a dot-prefixed file there: it is a tool's litter, not an element. +- MUST treat a missing element type folder as empty, and MUST NOT require any `.<tool>/` folder. - SHOULD also read `spatial/{map,pin,zone,marker}/` (older Atlas). An id found in both layouts: serve the `elements/` copy, and SHOULD log the duplicate. - Visit the files of a layout by name, compared by code point, the same on every platform. An id found twice within one layout keeps the first file in that order. Never use the system's own path sort: on Windows it ignores case, so two readers would keep different files. - Accept both spellings: `map`/`map_id`, `zone`/`zone_id`, `time_current`/`time_range_current`. @@ -130,7 +130,7 @@ A body the server trimmed for a key that may not see every linked element carrie **Writing** - UTF-8 without BOM, LF endings, 2-space indent, one trailing newline, keys in received order (never sorted), `1` not `1.0`. -- Write new elements under `elements/<type>/`, never `spatial/`; an element read from a file is written back to that file, so one id never sits in both layouts. SHOULD omit empty category folders. +- Write new elements under `elements/<type>/`, never `spatial/`; an element read from a file is written back to that file, so one id never sits in both layouts. SHOULD omit empty element type folders. - Two elements with the same filename: the later ones (by ascending id, compared by code point, the order archive entries use) MUST use the full id, `<slug>--<id>.json`. - An id, once minted, MUST be kept and MUST NOT be re-derived (from a new name, say). - MUST NOT invent data it lacks, such as timestamps, nor drop data it has. A [known-of](#known-of-elements) stub is written with its kept keys and served values only, and never pushed. diff --git a/src/content/docs/docs/schema/index.mdx b/src/content/docs/docs/schema/index.mdx index cbe3ae19..8a685a6f 100644 --- a/src/content/docs/docs/schema/index.mdx +++ b/src/content/docs/docs/schema/index.mdx @@ -1,18 +1,18 @@ --- title: Schema -description: The OnlyWorlds standard, its 22 element categories, typed links, and where the schema is defined and governed. +description: The OnlyWorlds standard, its 22 element types, typed links, and where the schema is defined and governed. --- import CategoryLinks from '../../../../components/figures/CategoryLinks.astro'; import CategoryFields from '../../../../components/figures/CategoryFields.astro'; -The standard defines 22 element **categories**, the fields each one carries, and typed links between them. An **element** is one record in a world: a Character, a Location, a Law. +The standard defines 22 **element types**, the fields each one carries, and typed links between them. An **element** is one record in a world: a Character, a Location, a Law. -Use as much of it as you need. Only `name` is required: the key must be present, and an empty string is accepted, on every category, Pins and Markers included. So a world of nothing but Objects is a valid world. Supertype and subtype sort a world's elements into its own kinds, `x_` fields carry data the standard doesn't model, and high-volume data can live in your own database beside the world, keyed by element id. +Use as much of it as you need. Only `name` is required: the key must be present, and an empty string is accepted, on every element type, Pins and Markers included. So a world of nothing but Objects is a valid world. Supertype and subtype sort a world's elements into its own kinds, `x_` fields carry data the standard doesn't model, and high-volume data can live in your own database beside the world, keyed by element id. -## The 22 categories +## The 22 element types -| Category | Definition | +| Element type | Definition | | :--- | :--- | | [Character](/docs/schema/element_categories/character) | A Character represents an individual with agency and the capacity to make choices that affect their world. | | [Creature](/docs/schema/element_categories/creature) | Creatures are living entities within a world that exhibit behavior and agency but lack the strategic reasoning or social complexity of Characters. | @@ -43,13 +43,13 @@ Every element also carries the same base fields (name, description, supertype, s ## Typed links -Links are typed fields. A Character's `location` is a single link that holds one Location; its `friends` is a multi link that holds any number of Characters. Each link field names the category it points to, so a tool always knows what kind of element is on the other end. One field, the Pin's `element`, is a generic link that can point to an element of any category (on the wire, `element_type` and `element_id`). +Links are typed fields. A Character's `location` is a single link that holds one Location; its `friends` is a multi link that holds any number of Characters. Each link field names the element type it points to, so a tool always knows what kind of element is on the other end. One field, the Pin's `element`, is a generic link that can point to an element of any element type (on the wire, `element_type` and `element_id`). -Links point one way, from the element that holds the field. For connections that carry their own history, span or intensity, the standard has a category of its own: [Relation](/docs/schema/element_categories/relation). [Conventions](/docs/schema/conventions) covers when to use which. +Links point one way, from the element that holds the field. For connections that carry their own history, span or intensity, the standard has an element type of its own: [Relation](/docs/schema/element_categories/relation). [Conventions](/docs/schema/conventions) covers when to use which. ### What links to what -Select a category to see the categories its link fields point at, with the fields named on each. Each category's own page lists the same fields in its table. +Select an element type to see the element types its link fields point at, with the fields named on each. Each element type's own page lists the same fields in its table. <CategoryLinks /> @@ -58,7 +58,7 @@ Select a category to see the categories its link fields point at, with the field | What | Where | | :--- | :--- | -| The standard, as YAML | [github.com/OnlyWorlds/OnlyWorlds](https://github.com/OnlyWorlds/OnlyWorlds/tree/main/schema): one file per category, plus `base_properties.yaml` for the fields every element shares and a `VERSION` file | +| The standard, as YAML | [github.com/OnlyWorlds/OnlyWorlds](https://github.com/OnlyWorlds/OnlyWorlds/tree/main/schema): one file per element type, plus `base_properties.yaml` for the fields every element shares and a `VERSION` file | | Governance | [council.onlyworlds.com](https://council.onlyworlds.com): the standard changes in public, by motion and vote. Take part on the site or through the toolkit. | | For tool builders | [schema-dist](https://github.com/OnlyWorlds/schema-dist): the generated distribution, its decoder (the walk), and the ruling table. Vendor it rather than writing a parser of your own. | diff --git a/src/content/docs/docs/schema/worlds.mdx b/src/content/docs/docs/schema/worlds.mdx index 74721169..57ad7afd 100644 --- a/src/content/docs/docs/schema/worlds.mdx +++ b/src/content/docs/docs/schema/worlds.mdx @@ -76,7 +76,7 @@ onlyworlds.com adds fields of its own to the world it serves, part of the platfo | `slug` | string or null | The address of the world's public page, null while the page is off | | `public_page` | object | The public page's settings | | `origin` | object | Where the world first came from, `{source, producer}` | -| `counts` | object | How many elements the reader may read, in all and by category | +| `counts` | object | How many elements the reader may read, in all and by element type | The world named by a key is `GET /api/v2/world/`. Its owner changes it with `PATCH`; the writable fields are `name`, `description`, `image_url`, the timeline fields, the three unit settings, `owner_character`, the world's extension keys (`x_`, `atlas_`, `shadow_`) and the provenance lines `source` and `producer` ([the world's writable fields](/docs/development/api/writes#the-world)). A co-builder may send every writable field but `owner_character`. `public_read` and `agent_narrator_rule` (the platform's switch holding agent seats to their own narrator, set on the world page) cannot be changed through the API. diff --git a/src/content/docs/docs/tools/atlas.md b/src/content/docs/docs/tools/atlas.md index 1deb1980..7b5bdacb 100644 --- a/src/content/docs/docs/tools/atlas.md +++ b/src/content/docs/docs/tools/atlas.md @@ -13,7 +13,7 @@ Atlas reads and writes your world as plain JSON files, in a folder on your own m ## Features -- **Build and Browse.** Every element category in an editor driven by the standard. Link fields are pickers, and every element lists what links to it. +- **Build and Browse.** Every element type in an editor driven by the standard. Link fields are pickers, and every element lists what links to it. - **Write.** Books, chapters and scenes (you set the tier names). Names in your prose become links with a click, and the find bar can link every match at once. The words stay yours. - **Web.** Any element's connections as a small graph, including everything that links to it. An element waiting for review or hidden on OnlyWorlds gets a dotted ring and the word beside its name (since 1.95.0). - **Map.** Your own map images, nested maps, pins for any element, and zones drawn as areas or lines. Zones can be coloured by kind (rivers blue, roads dashed), and the style is saved with the world. A map shows its zones and pins as of any date in the world's calendar: a zone by its own dates, a pin by its element's (a Character from its birth on, an Event from its start to its end). Anything undated always shows. Since 1.53.0 a map can be drawn from its own zones: Map style on the map's page (Plain, Ink on parchment, Modern atlas, Hatched) draws each zone whose subtype names a kind (Landmass, Sea, Lake, Range, Forest, Marsh, Desert, Territory, River, Road (or Route, Path), Wall, Border, Coast; any case) as that kind: coasts with their shore, ranges hatched, rivers cut at the coast, names along the lines. A subtype written `Class: kind` (`Border: treaty line`) is tried by its halves, the part before the colon first. Your zones are never changed, Plain brings the usual look back, and over a map's picture the zones take the style's lines and names but cover nothing. The style is saved on the Map as `atlas_map_style` and syncs. Trace on the drawing strip turns a drag into a few points. diff --git a/src/content/docs/docs/tools/easy-mobile.md b/src/content/docs/docs/tools/easy-mobile.md index 91f86ccb..ecd17771 100644 --- a/src/content/docs/docs/tools/easy-mobile.md +++ b/src/content/docs/docs/tools/easy-mobile.md @@ -13,7 +13,7 @@ Easy Mobile is a quick mobile web editor for OnlyWorlds elements. ## Features -- **Full CRUD.** Every element category, with inline editing. +- **Full CRUD.** Every element type, with inline editing. - **Online and Offline.** Work against the API, or offline in local IndexedDB storage and sync later. - **Mobile-First.** Touch-friendly, compact layout. - **Search and Browse.** Global search, infinite scroll and recent elements. diff --git a/src/content/docs/docs/tools/explorer.md b/src/content/docs/docs/tools/explorer.md index 4d57b4ee..7f4b01f9 100644 --- a/src/content/docs/docs/tools/explorer.md +++ b/src/content/docs/docs/tools/explorer.md @@ -12,6 +12,6 @@ Explorer is a visual introduction to OnlyWorlds concepts and structure, and a de ## Features -- **3D Navigation.** Explore element categories and their relationships in 3D space. +- **3D Navigation.** Explore element types and their relationships in 3D space. - **Schema Visualization.** See how the OnlyWorlds schema connects. - **Desktop Optimized.** Best on desktop. Touch devices are sent to a [mobile version](https://explorer-mobile.onlyworlds.com). diff --git a/src/content/docs/docs/tools/legacy.md b/src/content/docs/docs/tools/legacy.md index b2f298a5..cc66ca59 100644 --- a/src/content/docs/docs/tools/legacy.md +++ b/src/content/docs/docs/tools/legacy.md @@ -10,7 +10,7 @@ These tools are no longer developed. Those marked online still answer at their l An all-round element editor with full field support and both online and offline workflows. - **Status:** online, no longer developed. [base-tool.onlyworlds.com](https://base-tool.onlyworlds.com) -- Full CRUD on every element category, with inline editing and relationship management. +- Full CRUD on every element type, with inline editing and relationship management. - Online (API) or offline (local JSON) modes. - AI chat through OpenAI, with free daily tokens or a personal key. - An import pipeline that validates and resolves AI-parsed world data. @@ -58,7 +58,7 @@ A read-only viewer for browsing, searching and exploring a world's elements and - **Status:** online, no longer developed. [little-lens.onlyworlds.com](https://little-lens.onlyworlds.com/) - Card grid with type-coloured icons, descriptions and link counts. -- Filters across 18 browsable categories, search over names and descriptions, and sorting alphabetically or by connections. +- Filters across 18 browsable element types, search over names and descriptions, and sorting alphabetically or by connections. - Detail view with all fields, outgoing and reverse connections, and element images. - A radial connection graph, a timeline bar, and a breadcrumb trail with browser back and forward support. - Moppetopia pre-loaded as a demo world. diff --git a/src/content/docs/docs/tools/onlyworlds-com.md b/src/content/docs/docs/tools/onlyworlds-com.md index ec90433f..6282f228 100644 --- a/src/content/docs/docs/tools/onlyworlds-com.md +++ b/src/content/docs/docs/tools/onlyworlds-com.md @@ -20,7 +20,7 @@ onlyworlds.com is the platform hub: accounts, world hosting, keys and the API. E - **Element browser.** The world page's Elements pane shows a world's elements read-only, by type or, for the owner, all on one page in boxes by type, sorted by Name, Most of a kind, Most linked (the number counts links to and from other elements) or Most content (the number counts characters of text). An element's page has a Files card, where the owner adds, downloads and removes the files attached to it ([Files](/docs/development/api/files)). - **Lenses.** A world's Lenses page, in the world's menu, lists its lenses, changes one and shows its reading. See [Lenses](/docs/lenses#on-onlyworldscom). - **Hidden elements.** An element's page has a **Who can see this** card with a **Hide** button. A hidden element's page shows a **Hidden · DM's eyes** badge beside its type, and the card reads **Hidden: the owner and co-builders only**, names the member who made it (who still sees it), lists the world's published pages ("A page that holds it stays visible there until you republish or unpublish it.") and has **Unhide**. The Elements pane has a **Hidden · N** filter beside By type and All elements, and each type's list has the same filter and a **Hidden** badge on each hidden row. See [Hidden elements](/docs/development/api/hidden). -- **Public worlds.** In Settings, **Who can see this world**: **Only people you invite** (the default) or **Anyone can read it, with no account**, with a tick for **Give it a page at onlyworlds.com/w/…** and its address. The page shows the world as a stranger reads it, hidden elements left out, in one of five palettes, with an optional hero line, the categories in the owner's order and one pinned element; each element has a page of its own under it. See [Public worlds](/docs/development/api/public). +- **Public worlds.** In Settings, **Who can see this world**: **Only people you invite** (the default) or **Anyone can read it, with no account**, with a tick for **Give it a page at onlyworlds.com/w/…** and its address. The page shows the world as a stranger reads it, hidden elements left out, in one of five palettes, with an optional hero line, the element types in the owner's order and one pinned element; each element has a page of its own under it. See [Public worlds](/docs/development/api/public). - **Export.** Under Access, **This world as a file**: **Download JSON** saves the world as one [export file](/docs/development/api/changes#the-export-file), **Copy JSON** puts the same file on the clipboard. - **Restore to a day.** Each night a world changed, onlyworlds.com keeps a file of it for 90 days, and a world's newest file is always kept. The owner's world page lists the files under Access, below the export card, each row naming its file ("Daily file, 23 Oct 2026", or "Kept before a restore, 23 Oct 2026 07:24 UTC"); its button opens a confirm page whose heading and button name the same file, and the restore puts every element, every link and the world's own settings back as they were that day, the keys tools keep on the World (`x_`, `atlas_`, `shadow_`) included: one a tool added since is removed. Where the world first came from (its `origin`) is never changed by a restore. A file of the world as it is now is kept first, listed as "Kept before a restore" with its time, so a restore can be undone. An element you hid stays hidden; pictures and files are not restored, only their links; members, keys and seats are left as they are. A world over 100 MB gets no daily file. See [Restores in the feed](/docs/development/api/changes#restores-in-the-feed). - **Changelog.** [onlyworlds.com/changelog](https://www.onlyworlds.com/changelog): everything that shipped across OnlyWorlds, newest first and back to the beginning, by month, each row marked with its source: the site, Atlas, the Obsidian plugin, the toolkit, the TypeScript SDK, the Python package, schema-dist and the Unity SDK. An Atom feed at `/changelog.xml`, and the merged list as JSON at `/changelog.json` (the old `/whats-new` paths redirect), with a row per source that says whether it was read. The feedback page links to it. diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 502c8c4d..2634f05c 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -31,7 +31,7 @@ import { CardGrid, LinkCard } from '@astrojs/starlight/components'; /> <LinkCard title="Understand the schema" - description="The 22 element categories, their fields and typed links." + description="The 22 element types, their fields and typed links." href="/docs/schema/" /> <LinkCard From 55f501219fc2cf1c5773e88fcff652c4de9c9d85 Mon Sep 17 00:00:00 2001 From: Titus <titusoosting@gmail.com> Date: Wed, 28 Oct 2026 23:44:22 +0100 Subject: [PATCH 4/7] Changelog: the World graph section and the word element type One entry under 2026-10-28 for the new section, the moves and the word. The intro's pointer to onlyworlds.com's own log is its own line and names it by its current name and address, Changelog at /changelog (the old What's new address redirects there). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- src/content/docs/docs/changelog.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/content/docs/docs/changelog.md b/src/content/docs/docs/changelog.md index 04ed60d3..fd72d3f9 100644 --- a/src/content/docs/docs/changelog.md +++ b/src/content/docs/docs/changelog.md @@ -3,10 +3,13 @@ title: Changelog description: What changed for developers on OnlyWorlds (the API, the clients and these docs), newest first. --- -What changed for developers, newest first: the API on onlyworlds.com, the clients and tools these docs describe, and the docs themselves. Each day lists what a page now says; every release of a package is in its own changelog: [TypeScript SDK](https://github.com/OnlyWorlds/sdk/blob/main/CHANGELOG.md), [Unity SDK](https://github.com/OnlyWorlds/unity-sdk/blob/main/Packages/com.onlyworlds.sdk/CHANGELOG.md), [Python package](https://github.com/OnlyWorlds/python-sdk/blob/main/CHANGELOG.md). Everything that shipped across OnlyWorlds, for everyone, is on [What's new](https://www.onlyworlds.com/whats-new); this page stays the developer log. +What changed for developers, newest first: the API on onlyworlds.com, the clients and tools these docs describe, and the docs themselves. Each day lists what a page now says; every release of a package is in its own changelog: [TypeScript SDK](https://github.com/OnlyWorlds/sdk/blob/main/CHANGELOG.md), [Unity SDK](https://github.com/OnlyWorlds/unity-sdk/blob/main/Packages/com.onlyworlds.sdk/CHANGELOG.md), [Python package](https://github.com/OnlyWorlds/python-sdk/blob/main/CHANGELOG.md). + +What changed on onlyworlds.com for everyone is on its own [Changelog](https://www.onlyworlds.com/changelog); this page stays the developer log. ## 2026-10-29 +- **A World graph section, and element type as the one word for the 22.** [World graph](/docs/world-graph) sits between Schema and Tools: an overview of a world as typed elements and links and the three ways to read part of one, then [Lenses](/docs/lenses), [the draught](/docs/world-graph/draught) as a concept and [A world as a graph](/docs/lenses/graph). The lens routes move to the API section as [Lenses](/docs/development/api/lenses), and their old address points there; [the draught's route](/docs/development/api/draught) keeps its page and its address, and names its Character "the Character" or "they". The API section moves down the menu, after Games, and [A worked example](/docs/schema/example) closes the Schema section. Every page now says element type, never category, and the docs' word check refuses the old word; [Fields](/docs/schema/fields#base-fields) says how supertype and subtype nest inside an element type, and the addresses under `/docs/schema/element_categories/` stay. - **Sharper definitions on the [Creature](/docs/schema/element_categories/creature), [Collective](/docs/schema/element_categories/collective), [Family](/docs/schema/element_categories/family), [Species](/docs/schema/element_categories/species) and [Title](/docs/schema/element_categories/title) pages**, from an outside review of the docs: a Creature is told from a Character by reasoning and social complexity, not by how much the story follows it; a Collective has no formal governance of its own, though it can have a `composition` and an Institution as `operator`; a Family's tie is one that passes down; a Species is a biological kind or one set apart by origin or culture; and Title describes a convention for who held it when, a Relation with supertype `Tenure`. The schema page, [Conventions](/docs/schema/conventions) and the LLM guide carry the same wording. - **[Python](/docs/development/python#what-it-covers) 0.83.2**: the doctor reads a Law with supertype Charter and no mark as lore, not a finding, as the checks profile says; its house rules are never applied. - **[Public worlds](/docs/development/api/public#what-a-visitor-sees)**: an element's page reads its whole address, a moment and a lens included; the owner, signed in, goes on to their own page for it; a public Pin, Marker or Zone leads to the world's page. From 6fd056886f9512db6e148c59a80ed98d0130f990 Mon Sep 17 00:00:00 2001 From: Titus <titusoosting@gmail.com> Date: Wed, 28 Oct 2026 23:52:42 +0100 Subject: [PATCH 5/7] World graph: the overview keeps to what a reader can check (an uncited study and an internal test taken out; the four ideas named as four) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- src/content/docs/docs/world-graph.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/docs/world-graph.md b/src/content/docs/docs/world-graph.md index 969fe6ed..5ad2df47 100644 --- a/src/content/docs/docs/world-graph.md +++ b/src/content/docs/docs/world-graph.md @@ -17,7 +17,7 @@ Because a world is a graph, you can read part of it: start from a few elements a ## Related ideas -The idea of reading part of a large structure from a focus has a long history. They help place it: +Reading part of a large structure from a focus has a long history, and four earlier ideas help place it: - **Fisheye views.** Furnas ("Generalized Fisheye Views", CHI 1986) gave every item a degree of interest: its a priori importance minus its distance from the current focus. A view shows the items at or above a threshold, or the n most interesting. A lens's anchors and budget echo it, and "most linked" is one way to rank by importance. - **Magic Lenses.** Bier, Stone, Pier, Buxton and DeRose ("Toolglass and Magic Lenses", SIGGRAPH 1993) described a movable see-through filter that changes how the objects beneath it are shown. Editing there was done by other tools, used beside the lens or combined with it. An OnlyWorlds lens stays a reading. @@ -28,6 +28,6 @@ The idea of reading part of a large structure from a focus has a long history. T Knowledge kept for AI agents comes in several forms today. Markdown knowledge bases link files without saying what a link means. Graph and ontology platforms type their knowledge, and the ones we've read fill it by binding, syncing or mining other sources. Enterprise search fills its index by pulling from connected tools. A world is a typed layer whose elements people write on purpose, alone or with their AI, and which can live as a [folder of files](/docs/schema/folders). -That difference has a known edge. Graphs built by an LLM from documents carry duplicates, because the common tools merge entities by matching names (shown in preprints on LLM-built graphs). In a world, links and identity rest on ids, so nothing merges two elements because their names match. +In a world, links and identity rest on ids, so two elements are never merged because their names match. -Whether an AI answers better from a world than from the same content as files is not known. The one test so far, an internal one on a single document of about 15,000 tokens turned into a world, sat at the ceiling for both (110 of 110 questions from the files, 109 of 110 from the world). +Whether an AI answers better from a world than from the same content as files is not yet known. From 3b4edaa18735b2209a87766f517f22258741d47d Mon Sep 17 00:00:00 2001 From: Titus <titusoosting@gmail.com> Date: Thu, 29 Oct 2026 00:00:20 +0100 Subject: [PATCH 6/7] World graph: name matching in common graph-building tools, with the two papers that show it Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- src/content/docs/docs/world-graph.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/docs/world-graph.md b/src/content/docs/docs/world-graph.md index 5ad2df47..0d9d5c88 100644 --- a/src/content/docs/docs/world-graph.md +++ b/src/content/docs/docs/world-graph.md @@ -28,6 +28,6 @@ Reading part of a large structure from a focus has a long history, and four earl Knowledge kept for AI agents comes in several forms today. Markdown knowledge bases link files without saying what a link means. Graph and ontology platforms type their knowledge, and the ones we've read fill it by binding, syncing or mining other sources. Enterprise search fills its index by pulling from connected tools. A world is a typed layer whose elements people write on purpose, alone or with their AI, and which can live as a [folder of files](/docs/schema/folders). -In a world, links and identity rest on ids, so two elements are never merged because their names match. +Several common graph-building tools merge entities by matching their names ([GraphRAG](https://arxiv.org/abs/2404.16130); [Zheng et al. 2025](https://arxiv.org/abs/2510.14271)). In a world, links and identity rest on ids, so two elements are never merged because their names match. Whether an AI answers better from a world than from the same content as files is not yet known. From 780a2194e0e0d4df895d658ed580a0531c72ae9d Mon Sep 17 00:00:00 2001 From: Titus <titusoosting@gmail.com> Date: Thu, 29 Oct 2026 00:53:15 +0100 Subject: [PATCH 7/7] Creature: a being's place in the story does not decide its element type (the one public word, after the sharper definitions merged) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- src/content/docs/docs/schema/element_categories/creature.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/docs/schema/element_categories/creature.md b/src/content/docs/docs/schema/element_categories/creature.md index 90f8ed98..d82d1e5e 100644 --- a/src/content/docs/docs/schema/element_categories/creature.md +++ b/src/content/docs/docs/schema/element_categories/creature.md @@ -7,7 +7,7 @@ sidebar: <img src="/icons/creature.png" alt="" width="48" height="48" class="ow-type-icon" /> -Creatures are living entities within a world that exhibit behavior and agency but lack the strategic reasoning or social complexity of Characters. Their role is typically reactive over proactive, but they can still play important parts in a world's ecology, mythology, or atmosphere. How much the story follows a being does not decide its category: a warhorse at the centre of a saga is a Creature unless it reasons and chooses as a person does. +Creatures are living entities within a world that exhibit behavior and agency but lack the strategic reasoning or social complexity of Characters. Their role is typically reactive over proactive, but they can still play important parts in a world's ecology, mythology, or atmosphere. How much the story follows a being does not decide its element type: a warhorse at the centre of a saga is a Creature unless it reasons and chooses as a person does. Creatures help populate the world with living presence. They interact with: