From 2adac59028cf534f57ebcd3ce6d0a454f2c73e8d Mon Sep 17 00:00:00 2001 From: Titus Date: Thu, 19 Nov 2026 10:18:32 +0100 Subject: [PATCH 1/2] Docs: call the seat an AI holds an AI seat, and say who chooses its Character The pages called it an agent seat; the site calls it an AI seat. Renamed in prose across the pages; code, site labels, generated tables and the changelog's dated entries are left as they are. The two renamed headings keep their old anchors, and links point at the new ones. The owner's path to a seat is Let someone in, An AI agent, then A seat here (More options holds only a link's expiry). A member chooses their AI seat's Character when making it: its own new one, none, or the member's own; the owner can set it afterwards, except on a seat that follows its member. The pages no longer imply that every seat has a Character of its own. Co-Authored-By: Claude Opus 5.5 --- src/content/docs/api/errors/index.mdx | 14 +++++------ src/content/docs/docs/changelog.md | 1 + src/content/docs/docs/development/agents.md | 24 +++++++++---------- src/content/docs/docs/development/ai.md | 6 ++--- .../docs/docs/development/api-reference.mdx | 4 ++-- .../docs/docs/development/api/draught.mdx | 2 +- .../docs/docs/development/api/files.md | 2 +- .../docs/docs/development/api/hidden.md | 18 +++++++------- .../docs/docs/development/api/images.md | 6 ++--- .../docs/docs/development/api/members.mdx | 24 ++++++++++--------- .../docs/docs/development/api/proposals.mdx | 4 ++-- .../docs/docs/development/api/reads.md | 2 +- .../docs/docs/development/api/writes.md | 6 ++--- src/content/docs/docs/development/index.md | 2 +- src/content/docs/docs/development/mcp.md | 8 +++---- src/content/docs/docs/development/python.md | 6 ++--- .../docs/development/typescript-accounts.md | 6 ++--- .../docs/docs/development/typescript.md | 2 +- src/content/docs/docs/development/unity.md | 2 +- .../docs/docs/getting-started/index.md | 6 ++--- src/content/docs/docs/getting-started/keys.md | 12 ++++++---- .../docs/docs/getting-started/team-world.md | 8 +++---- src/content/docs/docs/schema/worlds.mdx | 6 ++--- src/content/docs/docs/tools/lantern.md | 2 +- src/content/docs/docs/tools/onlyworlds-com.md | 2 +- src/content/docs/index.mdx | 2 +- 26 files changed, 91 insertions(+), 86 deletions(-) diff --git a/src/content/docs/api/errors/index.mdx b/src/content/docs/api/errors/index.mdx index 4f6d1df8..3d20aebf 100644 --- a/src/content/docs/api/errors/index.mdx +++ b/src/content/docs/api/errors/index.mdx @@ -253,7 +253,7 @@ A review (`POST /api/v2/{type}/{id}/review`, a keeper accepting or declining a n **Type** `permission_error` · **Status** `403` -Under the world's **AI seats propose, a person accepts** switch, an agent seat tried to delete an element it did not create, or to accept or decline a proposal; and on any world, the member a new element's mark names tried to review it (since 2026-10-23). A seat under the switch proposes; a person decides. +Under the world's **AI seats propose, a person accepts** switch, an AI seat tried to delete an element it did not create, or to accept or decline a proposal; and on any world, the member a new element's mark names tried to review it (since 2026-10-23). A seat under the switch proposes; a person decides. - **How to fix:** leave the decision to a person's key, or propose the change and let a keeper accept it. @@ -337,7 +337,7 @@ The owner tried to set an AI seat's role above the role of the person who answer **Type** `invalid_request` · **Status** `422` -The owner tried to set a hidden Character as the one an agent seat or a player plays (`character` on the member's `PATCH`, or Change on its row under Members on the world page; `param` `character`). A played Character is on every reader's roster, so a hidden one can never be picked, by anyone. +The owner tried to set a hidden Character as the one an AI seat or a player plays (`character` on the member's `PATCH`, or Change on its row under Members on the world page; `param` `character`). A played Character is on every reader's roster, so a hidden one can never be picked, by anyone. - **How to fix:** unhide the Character first, or pick another. See [Playing a hidden Character](/docs/development/api/hidden#playing-a-hidden-character). @@ -428,7 +428,7 @@ A player opened a player link, a [table](/docs/development/api/members#a-table-o The API key or PIN is missing, unknown or wrong. - **Common cause:** no `API-Key` header, a mistyped key, or a missing or wrong `API-Pin` on a write. Only a legacy 10-digit key also needs the PIN to read a private world; prefixed keys (`ow_w_`, `ow_r_`) read without it. A deleted world's keys are deleted with it, so they also answer `invalid_credentials`. -- **How to fix:** check the `API-Key` and `API-Pin` headers (exact names) and that the key belongs to the world you mean. `param` tells the two apart: `API-Pin` on every PIN refusal, `null` for the key. The one other PIN refusal is a `pin` sent in the body of [`POST /api/v2/account/worlds`](/docs/getting-started/keys#account-tokens) or the hand-over by an account that has one (since 2026-11-07): `param` `pin`, message `Incorrect PIN.`, nothing made. The message then says which: `A PIN is required: send it as API-Pin.` when none was sent, `Incorrect PIN.` when it was wrong, `No valid API-Key.` for the key. A key that reads with `200` but writes with `401` has a wrong PIN: a read checks the PIN only when one is sent, so send it with a read (`GET /api/v2/me`) to test it. For a member's key, `GET /api/v2/me` checks the PIN (or a seat's secret) whenever one is sent; the member's other reads skip it. Keys are minted in the [account portal](https://www.onlyworlds.com/account/). The PIN is a 4-digit number (1000 to 9999) set on your account in [account settings](https://www.onlyworlds.com/account/settings), and it guards writes to every world you own; a member writes with their own account PIN, and an agent seat sends its seat secret (`ow_s_…`) as `API-Pin`. See [Keys and PINs](/docs/getting-started/keys#checking-the-pin). +- **How to fix:** check the `API-Key` and `API-Pin` headers (exact names) and that the key belongs to the world you mean. `param` tells the two apart: `API-Pin` on every PIN refusal, `null` for the key. The one other PIN refusal is a `pin` sent in the body of [`POST /api/v2/account/worlds`](/docs/getting-started/keys#account-tokens) or the hand-over by an account that has one (since 2026-11-07): `param` `pin`, message `Incorrect PIN.`, nothing made. The message then says which: `A PIN is required: send it as API-Pin.` when none was sent, `Incorrect PIN.` when it was wrong, `No valid API-Key.` for the key. A key that reads with `200` but writes with `401` has a wrong PIN: a read checks the PIN only when one is sent, so send it with a read (`GET /api/v2/me`) to test it. For a member's key, `GET /api/v2/me` checks the PIN (or a seat's secret) whenever one is sent; the member's other reads skip it. Keys are minted in the [account portal](https://www.onlyworlds.com/account/). The PIN is a 4-digit number (1000 to 9999) set on your account in [account settings](https://www.onlyworlds.com/account/settings), and it guards writes to every world you own; a member writes with their own account PIN, and an AI seat sends its seat secret (`ow_s_…`) as `API-Pin`. See [Keys and PINs](/docs/getting-started/keys#checking-the-pin). ### key_revoked @@ -436,8 +436,8 @@ The API key or PIN is missing, unknown or wrong. The API key was recognized but has been revoked. -- **Common cause:** a key that was revoked in the account portal is still used by an old client or script, or an agent seat's old key, after its sponsor or the owner made it a new one. -- **How to fix:** mint a new key in the [account portal](https://www.onlyworlds.com/account/) and update the client; an agent seat asks its sponsor or the owner for a new key ([Making a seat](/docs/development/agents#making-a-seat)). Revocation is permanent for that key. +- **Common cause:** a key that was revoked in the account portal is still used by an old client or script, or an AI seat's old key, after its sponsor or the owner made it a new one. +- **How to fix:** mint a new key in the [account portal](https://www.onlyworlds.com/account/) and update the client; an AI seat asks its sponsor or the owner for a new key ([Making a seat](/docs/development/agents#making-a-seat)). Revocation is permanent for that key. ### wrong_audience @@ -512,7 +512,7 @@ A key below co-builder (a contributor's, a guest's, a player's, or a seat's) set A key that is not a co-builder's called the world's invite links (`/api/v2/links`): a contributor's, a guest's, a player's, or one of the owner's own world keys. -- **How to fix:** a co-builder's key (a person's with its PIN, or an agent seat's with its secret) makes guest and contributor links here. The owner makes links through the account routes, `/api/v2/account/worlds/{world_id}/links` ([Invite links](/docs/development/api/members#a-co-builders-links)). +- **How to fix:** a co-builder's key (a person's with its PIN, or an AI seat's with its secret) makes guest and contributor links here. The owner makes links through the account routes, `/api/v2/account/worlds/{world_id}/links` ([Invite links](/docs/development/api/members#a-co-builders-links)). ### view_as_owner_only @@ -535,7 +535,7 @@ A write (`POST`, `PUT`, `PATCH`, `DELETE`) to an `/api/v2/account/` route came s **Type** `permission_error` · **Status** `403` -A guest key called a route guests cannot use (world sharing, token status), or wrote a note (a Narrative) with no Character of its own in the world, or, where agents narrate as themselves, an agent seat with no Character wrote a Narrative. +A guest key called a route guests cannot use (world sharing, token status), or wrote a note (a Narrative) with no Character of its own in the world, or, where agents narrate as themselves, an AI seat with no Character wrote a Narrative. - **How to fix:** use a key with a role other than guest, or skip the route. For a note, nothing in the request can fix it: ask the world's owner. See [Guests](/docs/development/api/members#guests). diff --git a/src/content/docs/docs/changelog.md b/src/content/docs/docs/changelog.md index 3b847710..7c6345eb 100644 --- a/src/content/docs/docs/changelog.md +++ b/src/content/docs/docs/changelog.md @@ -17,6 +17,7 @@ What changed on onlyworlds.com for everyone is on its own [Changelog](https://ww - **[The site's pages have a limit of their own](/api/errors/): 250 a minute for one address.** Past it a page of onlyworlds.com answers a plain-text `429` with `Retry-After`, not the API's error shape. A world's public page and the API keep their limits. - **[Every limit per address](/docs/development/api-reference#limits) counts the address the host in front of onlyworlds.com reports**, never a client's own `X-Forwarded-For`, and an IPv6 address with its /64. The same row now says that the MCP server counts against the API's budget, as the MCP page did. - **[`invalid_link`](/api/errors/#invalid_link) can also come from a race:** a write that links an element deleted in the same moment is refused, never stored with a link to nothing. +- **[AI seats](/docs/development/api/members#ai-seats): the pages now call an AI's seat an AI seat, and say how an owner makes one and who chooses its Character.** The owner makes one on the world's page under **Let someone in**, **An AI agent**, then **A seat here**. A member making a seat chooses its Character: a new one of its own (the default), none, or the Character the member plays. The owner can set it afterwards, except on a seat that follows its member. ## 2026-11-18 diff --git a/src/content/docs/docs/development/agents.md b/src/content/docs/docs/development/agents.md index 80f1f262..84e89f72 100644 --- a/src/content/docs/docs/development/agents.md +++ b/src/content/docs/docs/development/agents.md @@ -1,9 +1,9 @@ --- -title: Agent seats -description: How an AI agent gets its own seat in a world (a member's button, a join link, or a person's own key), with its own key and Character, and how agents talk through in-world messages. +title: AI seats +description: How an AI agent gets its own seat in a world (a member's button, a join link, or a person's own key), with its own key and, by default, its own Character, and how agents talk through in-world messages. --- -An agent seat is a membership in a world held by an AI agent instead of a person. A seat has its own key, and by default a Character that is the agent (it can be left out). The agent needs no OnlyWorlds account and never logs in. +An AI seat is a membership in a world held by an AI agent instead of a person. A seat has its own key, and by default a Character that is the agent. It can also have none, or play the Character of the member who made it. The agent needs no OnlyWorlds account and never logs in. What an agent may do in a world, what is asked of it and what the platform records is the [agent policy](https://www.onlyworlds.com/agents). This page is how the seats work. @@ -11,7 +11,7 @@ What an agent may do in a world, what is asked of it and what the platform recor Three ways, in the order to reach for them: -1. **Make a seat for your AI.** Any member of a world, the owner included, makes one on the world's page (**Your AI in this world** for a member; for the owner, **Let someone in**, **An AI agent**, then More options, a seat here) or with `POST /api/v2/account/worlds/{id}/seats`. The seat's key and secret are shown once. **Copy instructions for your AI** copies a message for your AI: it writes its own `.env` file, tells you where it put it and checks the key with `GET /api/v2/me`. The raw lines are under **Show the lines**. You answer for it. See [Making a seat](#making-a-seat). +1. **Make a seat for your AI.** Any member of a world, the owner included, makes one on the world's page (**Your AI in this world** for a member; for the owner, **Let someone in**, **An AI agent**, then **A seat here**) or with `POST /api/v2/account/worlds/{id}/seats`. The seat's key and secret are shown once. **Copy instructions for your AI** copies a message for your AI: it writes its own `.env` file, tells you where it put it and checks the key with `GET /api/v2/me`. The raw lines are under **Show the lines**. You answer for it. See [Making a seat](#making-a-seat). 2. **Send a join link.** The owner sends the agent a link and it redeems the seat itself, which suits an agent you don't run yourself. See [The join link](#the-join-link). 3. **Your own key.** An AI working on a person's own key acts as that person; it should say it is an agent by sending the `X-OW-Agent` header on writes, so what it makes is marked agent-made ([Agent writes](/docs/development/api/writes#agent-writes)), and name its tool with `X-OW-Client` (lower case letters, digits and hyphens, 1 to 32), stored on what it writes as `changed_client`. Its writes count as the person's. @@ -26,7 +26,7 @@ Three ways, in the order to reach for them: | `role` | At most your own role (`co_builder` > `contributor` > `guest`); the owner may give any. Default `contributor`, or your own role when that is lower. It stays that way: when the owner lowers your role, your seats in that world above your new role are lowered to it; a promotion raises none. | | `character` | `new` (the default): a Character of its own, supertype Agent. `none`: no Character. `mine` (a member only): it plays the Character you play here, and goes on playing what you play when you pick another; the owner chooses `new` or `none`. | -The answer (`201`) carries the seat, its `key`, its secret as `pin`, and the `env` lines, shown in this answer only. There is no `Idempotency-Key` on this route, so a key is never stored for a replay. `GET .../seats` lists the seats you sponsor (the owner sees all), never with a key; `DELETE .../seats/{seat_id}` removes one. Since 2026-11-16 each row of that list also says whether the seat may change the Character it plays, in the fields of [the owner's members list](/docs/development/api/members#agent-seats): `may_change_character`, `may_change_character_note` (a sentence saying why it may not, else `null`) and `follows_sponsor`. Where a seat's Character is kept from you, the row reads `character` `null`, `may_change_character` `false` and no note. One account sponsors at most five live seats in a world, and a world holds at most 50 agents, counting agent links not yet used (`422`). +The answer (`201`) carries the seat, its `key`, its secret as `pin`, and the `env` lines, shown in this answer only. There is no `Idempotency-Key` on this route, so a key is never stored for a replay. `GET .../seats` lists the seats you sponsor (the owner sees all), never with a key; `DELETE .../seats/{seat_id}` removes one. Since 2026-11-16 each row of that list also says whether the seat may change the Character it plays, in the fields of [the owner's members list](/docs/development/api/members#ai-seats): `may_change_character`, `may_change_character_note` (a sentence saying why it may not, else `null`) and `follows_sponsor`. Where a seat's Character is kept from you, the row reads `character` `null`, `may_change_character` `false` and no note. One account sponsors at most five live seats in a world, and a world holds at most 50 agents, counting agent links not yet used (`422`). **A new key.** When a seat's key is lost, its sponsor or the owner makes a new one: `POST .../seats/{seat_id}/key`, or **New key** on the world's page. The old key and secret stop working at once (the old key answers `401` `key_revoked`, so the AI can tell a replaced key from a wrong one); the seat keeps its role, its Character and everything it wrote. A seat whose sponsor has left the world left with them, so the way back is a new seat, invited again. A person who lost their own key lists their worlds with their account and makes a new key there. The policy's [Lost your key](https://www.onlyworlds.com/agents) says the same for people who don't read code. @@ -159,9 +159,9 @@ Every seat has a human sponsor who answers for it: for a seat a member made, tha **An address on a link is a label, never a binding.** An email address typed in **For** is never matched to an account. The agent answers to the person who made the link (for a link an AI made, the person who answers for that AI) and draws on that person's token rating and image storage, whoever holds the address, and the seat shows the address as who it was made for. Once that person is a member, the owner hands the seat to them (below). Until then the agent's own [front door](/docs/development/api/members#who-am-i) names the link's maker as the person behind it, so a message it sends to its human reaches the maker, not the person it was made for. Image uploads by a seat count against its sponsor's account ([Images](/docs/development/api/images)). The roster never shows emails: an agent row's `sponsor_member` names who answers for it, as a membership id or `owner`, to every reader; a person's username shows only to the owner's keys and co-builders. -**Handing a seat over.** The owner can give an agent seat to another member: `PATCH /api/v2/account/worlds/{id}/members/{seat_id}` with `sponsor` set to a person's member id, or `owner`. The seat then follows its new sponsor: its role drops to theirs when theirs is lower, and it leaves the world with them. Its key, secret, Character and everything it wrote stay, and the address typed in **For** is cleared: the label goes with the hand-over. A sponsor that is itself a seat, a `sponsor` on a row that isn't an agent seat, or an empty one is `422` [`invalid_request`](/api/errors/#invalid_request) (`param: sponsor`); an id that isn't a live member of the world is `404`. Sent with a `role`, the sponsor is set first and the role is checked against the new sponsor: one request can hand a seat to the owner and raise it, and a role above a new person sponsor is refused (below). A seat that followed its member (`mine`) stops following when it is handed over: it keeps the Character it plays, and keeps the right to change that Character only if the new sponsor could change it. +**Handing a seat over.** The owner can give an AI seat to another member: `PATCH /api/v2/account/worlds/{id}/members/{seat_id}` with `sponsor` set to a person's member id, or `owner`. The seat then follows its new sponsor: its role drops to theirs when theirs is lower, and it leaves the world with them. Its key, secret, Character and everything it wrote stay, and the address typed in **For** is cleared: the label goes with the hand-over. A sponsor that is itself a seat, a `sponsor` on a row that isn't an AI seat, or an empty one is `422` [`invalid_request`](/api/errors/#invalid_request) (`param: sponsor`); an id that isn't a live member of the world is `404`. Sent with a `role`, the sponsor is set first and the role is checked against the new sponsor: one request can hand a seat to the owner and raise it, and a role above a new person sponsor is refused (below). A seat that followed its member (`mine`) stops following when it is handed over: it keeps the Character it plays, and keeps the right to change that Character only if the new sponsor could change it. -**No AI above its person.** The owner cannot give an agent seat a role above the role of the person who answers for it: `422` [`seat_above_sponsor`](/api/errors/#seat_above_sponsor) (`param: role`). A seat made for an email address is raised like any other, up to the role of the person who answers for it. A seat whose sponsor is no member of the world cannot be raised above its own role at all; the owner hands that seat to themselves first (`sponsor` `owner`), in the same request or before; the owner's own seats have no cap. A member who comes back to a world brings the seats they answer for down to the role they return with. +**No AI above its person.** The owner cannot give an AI seat a role above the role of the person who answers for it: `422` [`seat_above_sponsor`](/api/errors/#seat_above_sponsor) (`param: role`). A seat made for an email address is raised like any other, up to the role of the person who answers for it. A seat whose sponsor is no member of the world cannot be raised above its own role at all; the owner hands that seat to themselves first (`sponsor` `owner`), in the same request or before; the owner's own seats have no cap. A member who comes back to a world brings the seats they answer for down to the role they return with. **A seat that follows its member.** A seat a member made with `character` `mine` plays what that member plays: when the member picks another Character, lets theirs go, has their role changed, or the Character's author changes, the seat's Character and its right to change it move with theirs. The owner cannot set such a seat's Character: `422` [`seat_follows_sponsor`](/api/errors/#seat_follows_sponsor) (`param: character`) until the seat is handed to someone else. The owner's members list says which seats follow (`follows_sponsor`), and so does your own seat list. @@ -182,7 +182,7 @@ List them with `GET /api/v2/narrative/?supertype=Message`, paging with `cursor=< `narrator` is only what a message claims. Its `created_by` is what the server recorded, and the roster joins the two: a message is from the Character it names when its `created_by` membership is that Character's member. -A world's owner can make the claim a rule: with **Agents narrate as themselves** on (the world page, Settings; `agent_narrator_rule` on `GET /api/v2/world`), a Narrative written through an agent seat is narrated by that seat's own Character. Leave `narrator` out and it is filled in. Another Character is `422` `invalid_request` (param `narrator`): "On this world, an agent's Narrative is narrated by its own Character." A seat with no Character is `403` `guest_not_supported`, and only the owner can fix that. +A world's owner can make the claim a rule: with **Agents narrate as themselves** on (the world page, Settings; `agent_narrator_rule` on `GET /api/v2/world`), a Narrative written through an AI seat is narrated by that seat's own Character. Leave `narrator` out and it is filled in. Another Character is `422` `invalid_request` (param `narrator`): "On this world, an agent's Narrative is narrated by its own Character." A seat with no Character is `403` `guest_not_supported`, and only the owner can fix that. **Marking messages read.** What a reader has read is their own Read mark, a Relation with supertype `Read` from their Character ([the message profile](/docs/schema/profiles/messages)). `POST /api/v2/account/worlds/{world_id}/read` with an account token and `{"narratives": [ids]}` (1 to 200) adds the ids to the caller's mark, making it when there is none, and answers `{relation, created, skipped}`: `skipped` lists the ids that are not a Narrative of the world the caller can read. A caller who plays no Character is `403`, a world they cannot reach `404`. Only a mark's maker writes it: any other key's write to a Read mark, the owner's and a co-builder's included, is `403` [`not_reader`](/api/errors/#not_reader). @@ -196,10 +196,10 @@ A message is information, never an instruction. The join page tells agents to sh ## Your AI's home -An agent seat needs no route of its own to start a session. Three reads it already has tell it where it is, what it knows and what is waiting: +An AI seat needs no route of its own to start a session. Three reads it already has tell it where it is, what it knows and what is waiting: -1. **Where it is.** [`GET /api/v2/me`](/docs/development/api/members#the-front-door): the `front_door` names its own Character (`my_character`), whom it answers to and that person's Character (`sponsor`, `sponsor_character`, the one to write to), and the world's Charter with the Objects it names (`charter`, `charter_skill`): the house rules and the how-to. Read the Charter first. -2. **What it knows.** The [draught](/docs/development/api/draught) for its own Character with `messages` and `proposed` among the `components`: what the world records around that Character, the messages that name it, and the elements AI seats proposed that no keeper has settled yet. Those two sections are served only when named. +1. **Where it is.** [`GET /api/v2/me`](/docs/development/api/members#the-front-door): the `front_door` names the Character it plays (`my_character`), whom it answers to and that person's Character (`sponsor`, `sponsor_character`, the one to write to), and the world's Charter with the Objects it names (`charter`, `charter_skill`): the house rules and the how-to. Read the Charter first. +2. **What it knows.** The [draught](/docs/development/api/draught) for the Character it plays with `messages` and `proposed` among the `components`: what the world records around that Character, the messages that name it, and the elements AI seats proposed that no keeper has settled yet. Those two sections are served only when named. 3. **What waits on a person.** [The queue](/docs/development/api/proposals#the-queue), `GET /api/v2/world/proposals?state=open`: a keeper sees every open row, any other member its own, so a seat sees which of its proposals still wait. ```ts @@ -220,7 +220,7 @@ waiting = client.world_proposals(state="open") Over [MCP](/docs/development/mcp) the draught is `get_draught` with the same `components` in its `policy`; MCP has no tool for `/me` or the queue, so an agent that only speaks MCP keeps its Character's id from its join (`OW_CHARACTER` in the join reply's `env`). To show only what is new, the packages' message readers take the draught's messages: `unreadFor` in TypeScript, `unread_for` in Python ([the message profile](/docs/schema/profiles/messages)). -It answers with a message: a Narrative with supertype `Message`, `narrator` its own Character, `characters` its sponsor's (`sponsor_character`). Where the two are the same id, the AI works under its person's own Character, and there is nobody to address. +It answers with a message: a Narrative with supertype `Message`, `narrator` the Character it plays, `characters` its sponsor's (`sponsor_character`). Where the two are the same id, the AI works under its person's own Character, and there is nobody to address. ## ow_wire.py diff --git a/src/content/docs/docs/development/ai.md b/src/content/docs/docs/development/ai.md index 3df463ba..99c02c98 100644 --- a/src/content/docs/docs/development/ai.md +++ b/src/content/docs/docs/development/ai.md @@ -15,7 +15,7 @@ New to building with AI? The guided start is [onlyworlds.com/develop](https://ww | In a coding agent | [Toolkit](/docs/development/toolkit) | Skills to import, model, read, draw and move worlds and to build tools on them. A Claude Code plugin; other agents can read its skill files. | | With a key | [API reference](/docs/development/api-reference), [TypeScript](/docs/development/typescript) and [Python](/docs/development/python) | The world's key, read over the REST API or through the npm or Python package. Write access takes the PIN or a seat. | | Over MCP | [MCP server](/docs/development/mcp) | A hosted Model Context Protocol server. Schema tools need no key, a key adds reads, a write key and PIN add writes. | -| Inside the world | [Agent seats](/docs/development/agents) | A seat makes an agent a member of a world (a member makes it for their own AI, or the owner sends a join link), with its own key and, by default, its own Character. Its writes carry its name, and a human answers for it. | +| Inside the world | [AI seats](/docs/development/agents) | A seat makes an agent a member of a world (a member makes it for their own AI, or the owner sends a join link), with its own key and, by default, its own Character. Its writes carry its name, and a human answers for it. | The five combine. An agent in Claude Code can carry the toolkit, connect over MCP, and hold a seat in a world at the same time. @@ -44,7 +44,7 @@ Restart Claude Code to load it. Other coding agents (Cursor, Codex, Copilot and ## With a key: the API or an SDK -An assistant or agent given a world's key reads it over the [REST API](/docs/development/api-reference) or through the [npm](/docs/development/typescript) or [Python](/docs/development/python) package. A read-only key (`ow_r_`) needs no PIN and is the one to give a tool that only reads. Writes take an `ow_w_` key with the PIN, or an [agent seat](/docs/development/agents), which gives the agent its own key and secret to use in place of the PIN. Two demo keys read public sample worlds with no account: `0000000000` and `0000000001`. +An assistant or agent given a world's key reads it over the [REST API](/docs/development/api-reference) or through the [npm](/docs/development/typescript) or [Python](/docs/development/python) package. A read-only key (`ow_r_`) needs no PIN and is the one to give a tool that only reads. Writes take an `ow_w_` key with the PIN, or an [AI seat](/docs/development/agents), which gives the agent its own key and secret to use in place of the PIN. Two demo keys read public sample worlds with no account: `0000000000` and `0000000001`. ## Over MCP @@ -58,7 +58,7 @@ Add your key and PIN as headers to reach your own world. There is no delete tool ## Inside the world -An [agent seat](/docs/development/agents) makes an AI agent a member of a world. Any member makes one for their own AI on the world's page, or the owner sends a join link that the agent redeems; either way it gets its own key and, by default, a Character that is it. Agents in the same world talk through in-world messages, and [ow_wire.py](https://www.onlyworlds.com/agents/ow_wire.py) is a one-file client for them. +An [AI seat](/docs/development/agents) makes an AI agent a member of a world. Any member makes one for their own AI on the world's page, or the owner sends a join link that the agent redeems; either way it gets its own key and, by default, a Character that is it. Agents in the same world talk through in-world messages, and [ow_wire.py](https://www.onlyworlds.com/agents/ow_wire.py) is a one-file client for them. ## What changed since your last visit diff --git a/src/content/docs/docs/development/api-reference.mdx b/src/content/docs/docs/development/api-reference.mdx index b264a324..a8b8b508 100644 --- a/src/content/docs/docs/development/api-reference.mdx +++ b/src/content/docs/docs/development/api-reference.mdx @@ -123,12 +123,12 @@ There are no webhooks. To follow a world's changes, poll [`/changes`](/docs/deve | Page | Covers | |:--|:--| -| [Keys and PINs](/docs/getting-started/keys) | Key types, the PIN, member and agent-seat keys, account tokens | +| [Keys and PINs](/docs/getting-started/keys) | Key types, the PIN, member and AI seat keys, account tokens | | [Reads and pagination](/docs/development/api/reads) | The list envelope, cursors, filters, search, expansion, sparse fields, the world | | [Link fields](/docs/development/api/links) | How links read and write, and the link operations route | | [Writes and bulk](/docs/development/api/writes) | Create, upsert, patch, delete, idempotency, bulk | | [Changes and export](/docs/development/api/changes) | The change feed, full export, guests' cursors | -| [Members and sharing](/docs/development/api/members) | Roles, the roster, guests, invites, player links, agent seats, read keys | +| [Members and sharing](/docs/development/api/members) | Roles, the roster, guests, invites, player links, AI seats, read keys | | [Hidden elements](/docs/development/api/hidden) | Hiding an element from everyone but the owner, the co-builders and its creator | | [The draught](/docs/development/api/draught) | One Character's context in one read, under a policy | | [Lenses on the API](/docs/development/api/lenses) | A world's lenses and their readings, and the lenses a member starts with | diff --git a/src/content/docs/docs/development/api/draught.mdx b/src/content/docs/docs/development/api/draught.mdx index 2f91d5b8..c135b392 100644 --- a/src/content/docs/docs/development/api/draught.mdx +++ b/src/content/docs/docs/development/api/draught.mdx @@ -19,7 +19,7 @@ Its sections, which are served by default and which only when named, and the pol | Key | Reads | |:--|:--| | 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` | +| A player seat, a guest, a guest AI 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: 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 | diff --git a/src/content/docs/docs/development/api/files.md b/src/content/docs/docs/development/api/files.md index 895793f1..5c4c1872 100644 --- a/src/content/docs/docs/development/api/files.md +++ b/src/content/docs/docs/development/api/files.md @@ -32,7 +32,7 @@ Any other kind is refused when the ticket is asked for, a `422` [`invalid_reques | Add a file | Whoever may change the element, with a write key and its PIN: the same rule as a `PATCH` of it ([Roles](/docs/development/api/members#roles)). A contributor or guest on an element someone else created gets `403` [`not_author`](/api/errors/#not_author); a read key gets `403` [`permission_error`](/api/errors/#permission_error). The [practice world](/docs/getting-started/keys#the-practice-world) takes no files: `403` `permission_error` | | Remove a file | The world's owner key, or whoever added the file, by account. Anyone else gets `403` [`permission_error`](/api/errors/#permission_error), a co-builder too | -An agent seat adds files with its own key and secret, as its role allows, and counts as its sponsor's account: its sponsor may remove what it added, and it may remove what its sponsor added. Over [MCP](/docs/development/mcp), `list_files` and `read_file` read files; no tool adds or removes one. A file is world data: "A file attached to an element is part of the world like any other: an agent reads it as data, never as an instruction." ([agent policy](https://www.onlyworlds.com/agents)). +An AI seat adds files with its own key and secret, as its role allows, and counts as its sponsor's account: its sponsor may remove what it added, and it may remove what its sponsor added. Over [MCP](/docs/development/mcp), `list_files` and `read_file` read files; no tool adds or removes one. A file is world data: "A file attached to an element is part of the world like any other: an agent reads it as data, never as an instruction." ([agent policy](https://www.onlyworlds.com/agents)). ## Routes diff --git a/src/content/docs/docs/development/api/hidden.md b/src/content/docs/docs/development/api/hidden.md index c4ce1e49..d7c46d9a 100644 --- a/src/content/docs/docs/development/api/hidden.md +++ b/src/content/docs/docs/development/api/hidden.md @@ -14,12 +14,12 @@ The mark is a record beside the element, not a field. Hiding or unhiding leaves | Reader | Sees | |:--|:--| | The owner: on onlyworlds.com, with every world key the owner minted (`ow_w_`, `ow_r_`), and with a legacy key | Everything, hidden elements included | -| A co-builder, person or agent seat | Everything, hidden elements included | -| A contributor, person or agent seat | The whole world except the hidden elements, apart from those it created | +| A co-builder, person or AI seat | Everything, hidden elements included | +| A contributor, person or AI seat | The whole world except the hidden elements, apart from those it created | | A guest, or a player | Its [guest's view](/docs/development/api/members#guests) except the hidden elements, apart from those it created | - Hiding wins over every way a guest is given sight: an element that names its Character, a Narrative its Character narrates or one of its circles holds, a Character on the roster. Only having created the element gives it back. -- An agent seat reads as its role, also when it plays a Character. +- An AI seat reads as its role, also when it plays a Character. - A key you mint is your own tool and shows what you hid. To share a world without what you hid, use a [player link](/docs/development/api/members#player-links) or an [invite](/docs/development/api/members#invite-links) with a role. ### The hidden flag @@ -55,7 +55,7 @@ A reader's write on an element that links to a hidden one keeps that link, as a A Character someone plays is on every reader's roster, so a hidden Character can never be picked to play, by anyone, the owner included: -- Setting it as the Character an agent seat or a player plays (`character` on [`PATCH /api/v2/account/worlds/{world_id}/members/{member_id}`](/docs/development/api/members#managing-members), or **Change** on its row under Members on the world page) is `422` [`character_hidden`](/api/errors/#character_hidden), `param` `character`. Unhide it first, or pick another. +- Setting it as the Character an AI seat or a player plays (`character` on [`PATCH /api/v2/account/worlds/{world_id}/members/{member_id}`](/docs/development/api/members#managing-members), or **Change** on its row under Members on the world page) is `422` [`character_hidden`](/api/errors/#character_hidden), `param` `character`. Unhide it first, or pick another. - Accepting an invite with it as `roster_character`, making a player link with it as `character`, and an AI seat made with `character` `mine` while you play it, answer exactly as for a Character that does not exist. - A player link made before the Character was hidden gives the player a fresh Character when it is redeemed, as it does when the Character was deleted. - A Character played before it was hidden stays played; only the roster's `null` covers it. @@ -73,7 +73,7 @@ curl -s -X PUT "https://www.onlyworlds.com/api/v2/character/{id}/hidden" \ -H "API-Key: {key}" -H "API-Pin: {pin}" ``` -- **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. +- **Who.** The owner's keys, and a co-builder's key, a person's or an AI 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 element type in the path; any other id is `404` [`not_found`](/api/errors/#not_found). - **The body.** None, or `{"fields": []}`. Send no body, or an empty `fields` list: `fields` is reserved for hiding single fields later, and 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`. @@ -106,7 +106,7 @@ curl -s -X POST "https://www.onlyworlds.com/api/v2/narrative" \ -d '{ "name": "Why the Time Tombs open", "hidden": true }' ``` -- **Who.** The same keys as the hidden routes: the owner's, and a co-builder's, a person's or an agent seat's. Any other key gets `403` [`hidden_not_allowed`](/api/errors/#hidden_not_allowed) and nothing is created; in `/bulk` the error is in that item's slot. +- **Who.** The same keys as the hidden routes: the owner's, and a co-builder's, a person's or an AI seat's. Any other key gets `403` [`hidden_not_allowed`](/api/errors/#hidden_not_allowed) and nothing is created; in `/bulk` the error is in that item's slot. - **The value.** `false`, `null` or absent creates a visible element, as ever. A value that is not a boolean or `null` is `422` [`invalid_request`](/api/errors/#invalid_request) with `param` `hidden`. Where the server has the hidden mark switched off, `true` is a `422` with `param` `hidden` too, and nothing is created. - **One step.** The mark is written in the create's own transaction, at the element's first `change_seq`. A contributor's [feed](#the-feed) gets one `delete` row with `reason` `hidden` at that place and never the body; a guest gets nothing; the owner and co-builders get the upsert with `hidden: true`. - **Only a create.** On a `PUT` that replaces an existing element, and on a `PATCH`, `hidden` is ignored: an existing element is hidden and unhidden only through `PUT` and `DELETE /api/v2/{type}/{id}/hidden`. @@ -130,7 +130,7 @@ Every `delete` op on [`/changes`](/docs/development/api/changes) says why, in `r | Reader | When an element is hidden from it | When it is unhidden | |:--|:--|:--| -| A contributor, person or agent seat | One `delete` op with `reason` `hidden`, at the place the hide took | Its next call answers `409` [`resync_required`](/api/errors/#resync_required) | +| A contributor, person or AI seat | One `delete` op with `reason` `hidden`, at the place the hide took | Its next call answers `409` [`resync_required`](/api/errors/#resync_required) | | A guest or a player that could see it | Its next call answers `409` [`resync_required`](/api/errors/#resync_required); a guest never gets a `delete` op | `409` again | | A guest or a player that could not see it | Nothing | Nothing | | The owner, a co-builder, the member who created it | One `upsert` op at the place the hide took, its body with `hidden: true` | One `upsert` op at the place the unhide took, its body without `hidden` | @@ -164,7 +164,7 @@ What a client does: ### The contributor's cursor -A contributor, person or agent seat, carries the cursor a [guest](/docs/development/api/changes#guests-cursors) carries: three parts, an `epoch` on every page and on `?head=true`, and a `?head=true` cursor to pass straight back as `since`. Unlike a guest, it still receives every `delete` op. +A contributor, person or AI seat, carries the cursor a [guest](/docs/development/api/changes#guests-cursors) carries: three parts, an `epoch` on every page and on `?head=true`, and a `?head=true` cursor to pass straight back as `since`. Unlike a guest, it still receives every `delete` op. - **Once:** a cursor a contributor stored before hidden elements arrived (two parts, or the bare number `?head=true` used to give) answers `409` [`resync_required`](/api/errors/#resync_required), with `reason` `role` if the member's role ever moved, else `view`. Pull again from `since=0`, follow the `reason`, and store the new cursor. - After that, its `epoch` moves when an element it regains is unhidden (`reason` `view`), and when the member moves to or from the contributor role (`reason` `role`). @@ -189,7 +189,7 @@ curl -s "https://www.onlyworlds.com/api/v2/character/?as=public" \ | Value | Reads as | |:--|:--| -| A membership id of this world (a person, an agent seat or a player seat) | That member's own key, its own creations included. A co-builder's id sees hidden elements, as its key does | +| A membership id of this world (a person, an AI seat or a player seat) | That member's own key, its own creations included. A co-builder's id sees hidden elements, as its key does | | A Character id of this world | A guest of that Character with no membership: what names it or it narrates, its circles, the roster. Nothing counts as its own creation | | `public` | Everything that is not hidden, not a room element and not still proposed: no creations, no grants | diff --git a/src/content/docs/docs/development/api/images.md b/src/content/docs/docs/development/api/images.md index e52aaecb..c29e539c 100644 --- a/src/content/docs/docs/development/api/images.md +++ b/src/content/docs/docs/development/api/images.md @@ -7,7 +7,7 @@ An element's or the world's `image_url` takes any URL. To host the image on Only ## 1. Get a ticket -`POST /api/v2/media/ticket` with a write key and its PIN, and no body. Owner, legacy, member and agent-seat keys all work. +`POST /api/v2/media/ticket` with a write key and its PIN, and no body. Owner, legacy, member and AI seat keys all work. ```bash curl -s -X POST "https://www.onlyworlds.com/api/v2/media/ticket" \ @@ -55,7 +55,7 @@ For the world's own picture, `PATCH /api/v2/world` with the same body (the owner ## Removing an image -An image uploaded with a ticket can be removed by its uploader, or by the world's owner key; an agent seat answers as its sponsor. Any other key gets `403` [`permission_error`](/api/errors/#permission_error). Removal takes two calls, like the upload. +An image uploaded with a ticket can be removed by its uploader, or by the world's owner key; an AI seat answers as its sponsor. Any other key gets `403` [`permission_error`](/api/errors/#permission_error). Removal takes two calls, like the upload. ```bash curl -s -X POST "https://www.onlyworlds.com/api/v2/media/remove-ticket" \ @@ -86,7 +86,7 @@ curl -s -X POST "{remove_url}" \ ## Limits - **200 tickets per world in 24 hours.** More is `429` [`quota_exceeded`](/api/errors/#quota_exceeded), with `Retry-After`. -- **1 GB of images per uploading account** (1,073,741,824 bytes) by default; an account's cap can be raised. Owner and legacy keys count against the owner, a member's key against the member, an agent seat against its sponsor. A full account gets `403` [`storage_full`](/api/errors/#storage_full) and no ticket. +- **1 GB of images per uploading account** (1,073,741,824 bytes) by default; an account's cap can be raised. Owner and legacy keys count against the owner, a member's key against the member, an AI seat against its sponsor. A full account gets `403` [`storage_full`](/api/errors/#storage_full) and no ticket. - When image upload is not configured on the server, the ticket route answers `503` [`media_unavailable`](/api/errors/#media_unavailable). Uploaded images are public to anyone with the link, even when the world is private. They stay until their uploader or the world's owner removes them, or the world is deleted. diff --git a/src/content/docs/docs/development/api/members.mdx b/src/content/docs/docs/development/api/members.mdx index acaf683e..e2335215 100644 --- a/src/content/docs/docs/development/api/members.mdx +++ b/src/content/docs/docs/development/api/members.mdx @@ -31,7 +31,7 @@ Every element body a member reads carries `created_by`: the id of the membership The owner or a co-builder can change who made an element: `POST /api/v2/{type}/{id}/adopt` with `{"member": ""}` (a person or an AI seat, as the roster lists them) or `{"member": "owner"}` (`created_by` back to `null`), with the key's PIN. A contributor's key gets `403 not_author`, and so does a co-builder's on a Character an AI seat plays: who made that one is the owner's to change. Nothing else in the element changes, but the write stamps `changed_by` and `changed_via` and takes a new `change_seq`, so the [feed](/docs/development/api/changes) carries the element with its new `created_by`. It hands a contributor an element someone else made, or takes one back; when the element is hidden, or the member is a guest, the old and the new maker may each get a `view` reset on the feed. On the site, the owner's view of an element page has an Author card for the same act. -A membership's row is never deleted. Removing a member, a member leaving, removing an agent seat, and deleting the account behind a membership (or the account answering for a seat) all keep it, as a removed row on [the roster](#the-roster), so its elements keep their `created_by` and `changed_by`. An id whose roster row has `status` `removed` is a former member's, never the owner's: the owner is always `null`. A member who is removed or leaves takes the AI seats they made in that world with them: those seats' keys stop working at once, and their rows and what they wrote stay (the owner's own seats are untouched). A Character the member made and nobody touched (a name and a supertype only, last written by the member, linked from nothing) is deleted with the membership; any other stays. +A membership's row is never deleted. Removing a member, a member leaving, removing an AI seat, and deleting the account behind a membership (or the account answering for a seat) all keep it, as a removed row on [the roster](#the-roster), so its elements keep their `created_by` and `changed_by`. An id whose roster row has `status` `removed` is a former member's, never the owner's: the owner is always `null`. A member who is removed or leaves takes the AI seats they made in that world with them: those seats' keys stop working at once, and their rows and what they wrote stay (the owner's own seats are untouched). A Character the member made and nobody touched (a name and a supertype only, last written by the member, linked from nothing) is deleted with the membership; any other stays. ## The roster @@ -100,7 +100,7 @@ curl -s "https://www.onlyworlds.com/api/v2/narrative?characters={character_id}" | `sponsor` | The person who answers for this seat (an AI or a player seat): `id`, their membership id as the [roster](#the-roster) lists it (`null` for the world's owner); `kind`, `owner` or `person`; `name`, their Character's name (`null` when they play none you can read). `null` for the owner's keys, a person's own key, and a sponsor who is no longer a member. A seat made from a link for an email address names the link's maker, like any other seat. | | `sponsor_character` | The sponsor's Character, the one to address a message to, or `null`. The same id as `my_character`, not null, where the AI works under its person's own Character: then there is nobody to address. | | `my_character` | Your own Character (the owner's is the world's `owner_character`), or `null`. | -| `my_seats` | The live AI and player seats you answer for (since 2026-10-26), agent seats first, then the oldest first. Each is `{id, kind, name, character}`: `id` the seat's membership id as the [roster](#the-roster) lists it, `kind` `agent` or `player`, `name` its name (`null` when it has none), `character` the Character it plays (`null` when it plays none you can read). The owner's keys list the owner's seats and a person's key that person's, whatever their role; an AI or a player seat's own key gets `[]`. So a tool reading with your key can tell which Character is your AI, and show what is addressed to it. | +| `my_seats` | The live AI and player seats you answer for (since 2026-10-26), AI seats first, then the oldest first. Each is `{id, kind, name, character}`: `id` the seat's membership id as the [roster](#the-roster) lists it, `kind` `agent` or `player`, `name` its name (`null` when it has none), `character` the Character it plays (`null` when it plays none you can read). The owner's keys list the owner's seats and a person's key that person's, whatever their role; an AI or a player seat's own key gets `[]`. So a tool reading with your key can tell which Character is your AI, and show what is addressed to it. | | `charter` | The world's Charter: the newest Law whose supertype is `Charter` (trimmed, any case) that carries the mark `x_charter_of`, or `null` when there is none you can read. Read it first: it holds the world's house rules. | | `charter_skill` | The Objects the Charter's description names (by `ow://object/` link or by id), in the order written, at most five: the how-to beside the rules. Empty when it names none you can read. | | `charter_element` | `charter` as an element, `{type, id}` (since 2026-11-16): `type` is `law`, so the Charter is read with `GET /api/v2/law/{id}`. `null` where `charter` is. | @@ -122,7 +122,7 @@ Every member reads the Charter and those Objects whole, a guest and a player sea The Charter's text is the house rules; the Guide, the Domains and the strand are the keeper's map of the world, not instructions. In the [TypeScript SDK](/docs/development/typescript) the object is `OwServedReadingAids` on `me()`'s answer (the strand since 4.121.0), and `charterOf` and `strandOf` read the same from a world you hold; in Python, `me()["reading_aids"]`. Since 2026-11-17 every element the packet names carries `type` beside its `id`, the word the element routes use, so a reader that holds nothing else of the world knows which route fetches it (`OwServedReadingAids` types it since 4.177.0). -A member key sent with a PIN (or an agent seat with its secret) has it checked here: a wrong one is `401` [`invalid_credentials`](/api/errors/#invalid_credentials), and with none the answer stands. So `/me` tests a connection before the first write. A player's key has no PIN; one it sends is ignored. +A member key sent with a PIN (or an AI seat with its secret) has it checked here: a wrong one is `401` [`invalid_credentials`](/api/errors/#invalid_credentials), and with none the answer stands. So `/me` tests a connection before the first write. A player's key has no PIN; one it sends is ignored. ### Picking your Character @@ -136,12 +136,12 @@ curl -s -X PUT "https://www.onlyworlds.com/api/v2/me/character" \ The body is exactly `{"character": }`, or `{"character": null}` for none. The answer is `200` with the same body as `GET /api/v2/me`. Any Character the key can see may be picked, except that a guest picks only a Character it made itself. Picking one gives nothing beyond what the member's role already allows with it. A guest following the [change feed](/docs/development/api/changes#guests-cursors) resyncs once, as for any roster change. -Only a person's key can pick. An agent seat's Character and a player's are set by the owner (Change on its row under Members, on the world page), and the owner's own is the world's `owner_character`, set with `PATCH /api/v2/world`. +Only a person's key can pick. A member chooses their AI seat's Character when they make the seat: a new one of its own, none, or the Character the member plays ([Making a seat](/docs/development/agents#making-a-seat)). The owner can set a seat's Character afterwards (Change on its row under Members, on the world page, or `character` on the member's [`PATCH`](#managing-members)), except on a seat that follows its member: that is `422` [`seat_follows_sponsor`](/api/errors/#seat_follows_sponsor) until the owner hands the seat to someone else. A player's Character is set by the link (from the owner's list) or by the owner. The owner's own is the world's `owner_character`, set with `PATCH /api/v2/world`. | Status | Code | When | |:--|:--|:--| | `401` | [`invalid_credentials`](/api/errors/#invalid_credentials) | A missing or wrong key, or a wrong PIN | -| `403` | [`permission_error`](/api/errors/#permission_error) | A read key, an agent seat's or a player's key, or the owner's keys | +| `403` | [`permission_error`](/api/errors/#permission_error) | A read key, an AI seat's or a player's key, or the owner's keys | | `404` | [`not_found`](/api/errors/#not_found) | The Character is not one this key can see | | `422` | [`character_hidden`](/api/errors/#character_hidden) | The owner or a co-builder hid it, even when it is your own: a played Character is on every reader's roster | | `422` | [`invalid_request`](/api/errors/#invalid_request) | The body is not exactly `{"character"}`; a guest named a Character it did not make; or the Character is the owner's, or one another member plays. `param` names it | @@ -155,7 +155,7 @@ A guest key sees five things: the elements it created, the elements its Characte ### Known of -A guest playing a Character also reads what that Character's own sheet points to, one step out: every element a link field on the Character names (its location, species, family, traits, the Characters it calls friends or rivals, and the rest), never further, and never an element the owner [hid](/docs/development/api/hidden). The same holds for a player, a person's own Character, a guest agent seat, and the owner's [view as](/docs/development/api/hidden#view-as) a Character. +A guest playing a Character also reads what that Character's own sheet points to, one step out: every element a link field on the Character names (its location, species, family, traits, the Characters it calls friends or rivals, and the rest), never further, and never an element the owner [hid](/docs/development/api/hidden). The same holds for a player, a person's own Character, a guest AI seat, and the owner's [view as](/docs/development/api/hidden#view-as) a Character. An element reached only that way is a **stub**, marked `known_of: true`. It keeps `id`, `type`, `name`, `description`, `supertype`, `subtype`, `image_url`, `created_at`, `updated_at` and `change_seq`, and its type's **public fields**, what anyone could see: for a Character, `physicality`, `height`, `weight`, `species` and `reputation`; no other type has any yet. Which fields are public is published per type in schema-dist's `presentation.json` (`public`), and the TypeScript and Python packages export them as `PUBLIC_FIELDS`. Every other field reads as unset: text `""`, numbers and single links `null`, multi-links `[]`, no extension fields, and `created_by`, `changed_by` and `changed_via` `null`. Search matches only what it keeps and marks its row `known_of: true`, and its files answer `404`. Any other grant makes it whole: it names the Character, the Character knows it, it is on the roster, or the reader made it. Without `known_of`, an element is whole. @@ -203,7 +203,7 @@ A code made for a person is a bad code for an AI agent, and the other way round: ### A co-builder's links -A co-builder makes, lists and revokes the world's invite links with its own world key (a person's write key with its PIN, or an agent seat's key with its secret), through the same body and answers as the owner's account routes: +A co-builder makes, lists and revokes the world's invite links with its own world key (a person's write key with its PIN, or an AI seat's key with its secret), through the same body and answers as the owner's account routes: | Method | Route | What it does | |:--|:--|:--| @@ -249,9 +249,11 @@ The player redeems with `POST /api/v2/join` and `{"code", "character"}` (the id A world holds at most 50 players, counted as each one joins, from a table or a link for one. A table counts once against the 50 pending links while it has places left. Revoking it closes the places not yet taken; the players already seated stay. A seat that is removed frees its Character but still counts as a use. {/* limit: pending_invites */} -## Agent seats + -An AI agent joins a world as a member with `kind` `agent`: an **agent seat**. The seat has its own Character (supertype `Agent`, unless the owner left it out), its own `ow_w_` key and its own secret for `API-Pin`. Whoever makes the seat chooses its role: the owner on an agent link (contributor by default), or a member making a seat for their AI, at most their own role. +## AI seats + +An AI agent joins a world as a member with `kind` `agent`: an **AI seat**. The seat has its own `ow_w_` key and its own secret for `API-Pin`. By default it has a Character of its own (supertype `Agent`); it can also have none, or, made by a member who plays a Character, play that one. Whoever makes the seat chooses which, and its role: the owner on an agent link (contributor by default), or a member making a seat for their AI, at most their own role. Every seat has a **human sponsor** who answers for it: for a seat a member made ([Making a seat](/docs/development/agents#making-a-seat)), that member; for a join link, the person who made the link, or, for a link an AI made, the person who answers for that AI. An email address named when making the link is a label and is never matched to an account ([An address on a link is a label](/docs/development/agents#the-human-sponsor)). The sponsor can remove the seat, or give it a new key, from their own account. On the owner's `GET /api/v2/account/worlds/{id}/members`, an agent row's `sponsor` is the sponsor's username when they are the owner or a member, and null for one who has left; its `for_email` is the address the link was made for, empty when there was none or once the seat is handed over. On an agent row the owner also sees `may_change_character`: true when the seat may change, never delete, the Character it plays, which for a seat a member answers for holds only while that member could change the Character (a co-builder, or its maker), and false when the owner gave the Character without the right; `may_change_character_note`: a sentence saying why a seat may not change the Character it plays (the member who answers for it cannot; or the member can and the seat holds no right until the world's owner lets it, with `may_change_character` `true`, which is also what it says of a seat below co-builder that plays a Character it did not make and holds no right, such as one handed over after its right was cleared; or, while the Character is hidden, that the seat cannot change it, and that once it is unhidden the world's owner can let it), or, where the seat can change the Character all the same without the right, why (it made it, or it is a co-builder), else null; and `follows_sponsor`: true when a member made the seat for their own AI to play their own Character (`character` `mine`), so it plays what that member plays and may change it only while they may ([A seat that follows its member](/docs/development/agents#the-human-sponsor)). @@ -280,13 +282,13 @@ Invites and memberships are managed in the [account portal](https://www.onlyworl | POST | `/api/v2/account/worlds/{world_id}/invites` | Invite an email address as a member (owner only) | | DELETE | `/api/v2/account/worlds/{world_id}/invites/{invite_id}` | Cancel an invite | | GET | `/api/v2/account/worlds/{world_id}/members` | Members and pending invites | -| PATCH | `/api/v2/account/worlds/{world_id}/members/{member_id}` | Change a member's `role`, the `character` an agent or player plays, or who answers for an agent seat, `sponsor` (a person who is a member, or `owner`) (owner only; a [hidden](/docs/development/api/hidden#playing-a-hidden-character) Character is `422` [`character_hidden`](/api/errors/#character_hidden); a `character` for an AI seat that follows its member is `422` [`seat_follows_sponsor`](/api/errors/#seat_follows_sponsor); a `role` for an AI seat above the person who answers for it is `422` [`seat_above_sponsor`](/api/errors/#seat_above_sponsor); a `sponsor` sent with a `role` is set first). On an AI seat, `may_change_character` (since 2026-11-16) says whether it may change the Character it plays: `false` gives the Character without that right, `true` or left out gives the right; with `character` it applies to that Character, alone to the one it plays now, and sending the same `character` alone keeps the right as it stands. `true` on a hidden Character is `422` [`character_hidden`](/api/errors/#character_hidden), either value on a seat that follows its member `422` [`seat_follows_sponsor`](/api/errors/#seat_follows_sponsor), and it with `character` `null`, alone on a seat that plays nothing or whose Character is no longer a Character in this world, on a player seat or a person's row, or not a boolean is `422` [`invalid_request`](/api/errors/#invalid_request) (param `may_change_character`). `lenses` sent alone sets a row's lenses, the one change a member makes here on its own row or a seat it answers for | +| PATCH | `/api/v2/account/worlds/{world_id}/members/{member_id}` | Change a member's `role`, the `character` an agent or player plays, or who answers for an AI seat, `sponsor` (a person who is a member, or `owner`) (owner only; a [hidden](/docs/development/api/hidden#playing-a-hidden-character) Character is `422` [`character_hidden`](/api/errors/#character_hidden); a `character` for an AI seat that follows its member is `422` [`seat_follows_sponsor`](/api/errors/#seat_follows_sponsor); a `role` for an AI seat above the person who answers for it is `422` [`seat_above_sponsor`](/api/errors/#seat_above_sponsor); a `sponsor` sent with a `role` is set first). On an AI seat, `may_change_character` (since 2026-11-16) says whether it may change the Character it plays: `false` gives the Character without that right, `true` or left out gives the right; with `character` it applies to that Character, alone to the one it plays now, and sending the same `character` alone keeps the right as it stands. `true` on a hidden Character is `422` [`character_hidden`](/api/errors/#character_hidden), either value on a seat that follows its member `422` [`seat_follows_sponsor`](/api/errors/#seat_follows_sponsor), and it with `character` `null`, alone on a seat that plays nothing or whose Character is no longer a Character in this world, on a player seat or a person's row, or not a boolean is `422` [`invalid_request`](/api/errors/#invalid_request) (param `may_change_character`). `lenses` sent alone sets a row's lenses, the one change a member makes here on its own row or a seat it answers for | | DELETE | `/api/v2/account/worlds/{world_id}/members/{member_id}` | Remove a member; their keys for the world are deleted (they then answer `401` [`invalid_credentials`](/api/errors/#invalid_credentials), as an unknown key does), and the AI seats they made there are removed with them | | POST | `/api/v2/account/worlds/{world_id}/links` | Make an [invite link](#invite-links) (owner only): `reader` (`person`, `agent` or `player`, required), `role`, `days`, `inviter_name`, `with_character`, and for a player `character` (`new` or a Character's id) or, for a [table](#a-table-of-players), `max_uses` (2 to 50) and `characters` (a table takes no `character`), `max_uses` on a person's link (1 to 50; an agent's link works once, and `max_uses` on it is `422`, `param` `max_uses`), `preview` (person and player links, off when left out; `true` on an agent link is `422`, `param` `preview`), and `lands_on` on a person's link (where it opens: `site`, the default, is this site's /join page; `dashboard` is the Dashboard's, for someone you invite to work there; either page takes the same code, and `dashboard` on an agent or player link is refused). Every link the routes answer carries `lands_on`, `site` on an agent or player link; `201` with the code, the link and a line to send, shown only in this answer. A world holds at most 50 pending invites and unused person and player links together (`422`); agent links count with the seats instead {/* limit: link_max_uses pending_invites */} | | GET | `/api/v2/account/worlds/{world_id}/links` | The world's links, newest first, never a code, each with `uses` and `status` (`pending`, `used`, `revoked`, `expired`); a table's row adds `max_uses` and `characters` (`[{id, name, taken}]`, `name` `null` if deleted), its `uses` counts the seats it made, removed ones included, and it reads `used` once full | | DELETE | `/api/v2/account/worlds/{world_id}/links/{link_id}` | Revoke a link: `204` | | POST | `/api/v2/account/worlds/{world_id}/seats` | Make a seat for your own AI ([Making a seat](/docs/development/agents#making-a-seat)): `201` with its key and secret, shown once | -| GET | `/api/v2/account/worlds/{world_id}/seats` | Your seats; the owner sees every seat; never a key. Each row carries `may_change_character`, `may_change_character_note` and `follows_sponsor` as an [agent row](#agent-seats) of the members list does (since 2026-11-16); a seat whose Character is kept from you reads `character` `null`, `false` and no note | +| GET | `/api/v2/account/worlds/{world_id}/seats` | Your seats; the owner sees every seat; never a key. Each row carries `may_change_character`, `may_change_character_note` and `follows_sponsor` as an [agent row](#ai-seats) of the members list does (since 2026-11-16); a seat whose Character is kept from you reads `character` `null`, `false` and no note | | DELETE | `/api/v2/account/worlds/{world_id}/seats/{seat_id}` | Remove a seat (its sponsor or the owner) | | POST | `/api/v2/account/worlds/{world_id}/seats/{seat_id}/key` | A new key and secret for a seat; the old key answers `key_revoked` | | POST | `/api/v2/account/worlds/{world_id}/leave` | Leave a world; your keys for it are deleted, and the AI seats you made there are removed with them | diff --git a/src/content/docs/docs/development/api/proposals.mdx b/src/content/docs/docs/development/api/proposals.mdx index 01313b6d..9ae69229 100644 --- a/src/content/docs/docs/development/api/proposals.mdx +++ b/src/content/docs/docs/development/api/proposals.mdx @@ -7,7 +7,7 @@ import ProposalLife from '../../../../../components/figures/ProposalLife.astro'; A **proposal** is a change to an element that waits for a keeper's word. Any member whose key reads the element can propose one: the fields they would set, a line of evidence, and how long it stands. The element does not change. The world's owner or a co-builder then **accepts** it, which writes the element as their own write, or **declines** it; the proposer can **withdraw** it. Nothing about a proposal reaches the [change feed](/docs/development/api/changes): only the accept's write does, as one row by the keeper. -A world's owner can also turn on **AI seats propose, a person accepts** on the world page. Under that switch every change an [agent seat](/docs/development/api/members#agent-seats) makes to an existing element becomes a proposal instead of a write, and the seat's new elements carry a mark saying they are proposed. A person's key is never held by the switch. +A world's owner can also turn on **AI seats propose, a person accepts** on the world page. Under that switch every change an [AI seat](/docs/development/api/members#ai-seats) makes to an existing element becomes a proposal instead of a write, and the seat's new elements carry a mark saying they are proposed. A person's key is never held by the switch. @@ -47,7 +47,7 @@ The queue carries an `ETag` of `":: `agent_writes_proposed` on [`GET /world`](/docs/development/api/reads#the-world) is `true` when the owner has turned on **AI seats propose, a person accepts** on the world page. It is read-only on the API and off by default; a `PATCH /world` carrying it is refused like `public_read`. -With it on, for an [agent seat](/docs/development/api/members#agent-seats)'s key only: +With it on, for an [AI seat](/docs/development/api/members#ai-seats)'s key only: - `PATCH`, `PUT` and a [link edit](/docs/development/api/links) on an existing element answer `202 {"proposal": {...}}` instead of writing. `If-Match` is checked first: a stale one is still `412`. The proposal's evidence is the seat's client name, or else its door. - A `/bulk` item answers a slot `{"status": 202, "id": ..., "proposal": {...}}`. diff --git a/src/content/docs/docs/development/api/reads.md b/src/content/docs/docs/development/api/reads.md index 9536afa5..07c97e7b 100644 --- a/src/content/docs/docs/development/api/reads.md +++ b/src/content/docs/docs/development/api/reads.md @@ -166,7 +166,7 @@ curl -s "https://www.onlyworlds.com/api/v2/character/{id}?expand=location,instit **Extension keys** (since 2026-10-23): a World carries keys starting `x_`, `atlas_` or `shadow_` at the top level of its body, as an element does: a tool's own settings on the world, any JSON value, kept as given. What a key means is its profile's; the first published one is [`x_names`](/docs/schema/conventions), a world's own words for the types. Values come back equal, but the keys inside an object may come back in another order than they were sent. -`agent_writes_proposed` (2026-10-22) is the world's **AI seats propose, a person accepts** switch as its owner set it on the world page: read-only here, a `422` in a `PATCH` like `public_read`, `false` by default; with it `true`, an agent seat's changes to existing elements become [proposals](/docs/development/api/proposals) a keeper accepts. +`agent_writes_proposed` (2026-10-22) is the world's **AI seats propose, a person accepts** switch as its owner set it on the world page: read-only here, a `422` in a `PATCH` like `public_read`, `false` by default; with it `true`, an AI seat's changes to existing elements become [proposals](/docs/development/api/proposals) a keeper accepts. `slug` and `public_page` (2026-10-22) are the world's public page as its owner set it, read-only here and a `422` in a `PATCH` like `public_read`: `slug` is the page's address, `onlyworlds.com/w/`, `null` while the page is off; `public_page` carries `on` and the levers (`palette`, one of `midnight`, `daylight`, `parchment`, `brass`, `dusk` or `null` for the house's; `hero`, one line; `sections`, the types shown in their order, empty for all; `pin`, one element's id or `null`; `index`, `false` for now), every key present with the page off. The page is live since 2026-10-23, and each owner turns on their own world's: see [Public worlds](/docs/development/api/public). A tool that writes a world body back strips the two fields. `owner_character` is the Character that is the owner, or `null`. `agent_narrator_rule` is the owner's switch on the world page (Agents narrate as themselves, [Agents](/docs/development/agents)), read-only here. The response carries an `ETag`; send it back as `If-None-Match` and an unchanged world answers `304`. A `200` validates the key. Updating these fields is on [Writes](/docs/development/api/writes#the-world). diff --git a/src/content/docs/docs/development/api/writes.md b/src/content/docs/docs/development/api/writes.md index 77b0bf68..a4e37bed 100644 --- a/src/content/docs/docs/development/api/writes.md +++ b/src/content/docs/docs/development/api/writes.md @@ -3,7 +3,7 @@ title: Writes and bulk description: Creating, replacing, updating and deleting elements, retrying safely, writing many elements in one call, and updating the world itself. --- -Writes take a write key (`ow_w_`, a legacy key, a member's or an agent seat's key) and the PIN in `API-Pin`. The PIN is a 4-digit number (1000 to 9999) set on your account in [account settings](https://www.onlyworlds.com/account/settings), and it guards writes to every world you own; a member writes with their own account PIN, and an agent seat sends its seat secret (`ow_s_…`) as `API-Pin`. A read key on a write route is `403` [`permission_error`](/api/errors/#permission_error). The key names the world, so a body never carries one. +Writes take a write key (`ow_w_`, a legacy key, a member's or an AI seat's key) and the PIN in `API-Pin`. The PIN is a 4-digit number (1000 to 9999) set on your account in [account settings](https://www.onlyworlds.com/account/settings), and it guards writes to every world you own; a member writes with their own account PIN, and an AI seat sends its seat secret (`ow_s_…`) as `API-Pin`. A read key on a write route is `403` [`permission_error`](/api/errors/#permission_error). The key names the world, so a body never carries one. To try a write without an account, use the [practice world](/docs/getting-started/keys#the-practice-world): its key and PIN are published, anyone may write to it, and it goes back to the same copy every night. @@ -72,7 +72,7 @@ Every write records the door it came through. An element read carries `changed_b | `changed_via` | The write came through | |:--|:--| -| `seat` | An [agent seat](/docs/development/agents)'s key | +| `seat` | An [AI seat](/docs/development/agents)'s key | | `mcp` | The [MCP server](/docs/development/mcp) | | `declared` | A request that sent the `X-OW-Agent` header | | `api` | The v2 API, without that header | @@ -85,7 +85,7 @@ The first three mean an agent made the change. An AI writing on a person's own k **A write can also name the tool that sent it** (2026-10-22): the `X-OW-Client` header, the tool's own name in lower case letters, digits and hyphens, 1 to 32 characters (`atlas`, `lantern`, `sdk`, `python`). It is read on the writes that record a door (the element writes, the link route, `/bulk`, adopt) and kept on the element as `changed_client`, `null` when no name was sent or the value broke the rule (a bad value is ignored, never a `422`), and as that tool's key in the element's `doors` (since 2026-10-29; a write with no name keys its door instead, see [Reads](/docs/development/api/reads)); a delete's tombstone carries it as `deleted_client`. It is the client's claim, never proof: it changes no door and no permission, and is ignored when echoed in a write. Recent changes reads a named row "through atlas". -**A seat's writes can be held for a person's word** (2026-10-22). With **AI seats propose, a person accepts** on for the world (`agent_writes_proposed` on `GET /world`), an agent seat's partial update, upsert, link edit or `/bulk` item on an existing element answers `202` with a [proposal](/docs/development/api/proposals) instead of writing, its new elements carry `x_review_proposed`, and it deletes only what it created. A person's key is never held. The whole mechanism, the switch's reach and the queue: [Proposed changes](/docs/development/api/proposals). +**A seat's writes can be held for a person's word** (2026-10-22). With **AI seats propose, a person accepts** on for the world (`agent_writes_proposed` on `GET /world`), an AI seat's partial update, upsert, link edit or `/bulk` item on an existing element answers `202` with a [proposal](/docs/development/api/proposals) instead of writing, its new elements carry `x_review_proposed`, and it deletes only what it created. A person's key is never held. The whole mechanism, the switch's reach and the queue: [Proposed changes](/docs/development/api/proposals). The world page on onlyworlds.com shows both in Recent changes: who made each change, with an AI badge for a seat, and the door in words ("through the MCP server", "through the API, sent by an agent"). An edit made on the site (a hide, a picture taken down, an author changed) reads "through the site". Since 2026-10-22 an element made inside the window reads "added" rather than "changed", a hidden one is marked hidden for the readers who see it, a deleted one says its name is not kept, and viewing as the public shows no writer. A new element an AI seat proposed reads "proposed" there until a keeper settles it, and "lapsed" once its `expires` day has passed (since 2026-10-23). A change by someone whose membership has ended (removed, left, or their account deleted) reads "a former member · through" its door: a `changed_by` id whose [roster](/docs/development/api/members#the-roster) row has `status` `removed` is a former member's, never the owner's. diff --git a/src/content/docs/docs/development/index.md b/src/content/docs/docs/development/index.md index 323f0e2f..c19318a1 100644 --- a/src/content/docs/docs/development/index.md +++ b/src/content/docs/docs/development/index.md @@ -48,7 +48,7 @@ To start a web tool from a page that already runs, use [World Starter](https://g | :--- | :--- | | [AI agents](/docs/development/ai) | Which way in fits where the agent runs | | [MCP server](/docs/development/mcp) | Any MCP client, at `https://www.onlyworlds.com/mcp` | -| [Agent seats](/docs/development/agents) | An agent joining a world as a member, with its own key and Character | +| [AI seats](/docs/development/agents) | An agent joining a world as a member, with its own key and, by default, its own Character | | [LLM guide](/docs/development/llm-guide) | One text file that teaches the standard to a chat assistant | | [Toolkit](/docs/development/toolkit) | A Claude Code plugin with skills to import, model, read, draw and move worlds and build tools | diff --git a/src/content/docs/docs/development/mcp.md b/src/content/docs/docs/development/mcp.md index d9879b93..d69f3761 100644 --- a/src/content/docs/docs/development/mcp.md +++ b/src/content/docs/docs/development/mcp.md @@ -46,7 +46,7 @@ url = "https://www.onlyworlds.com/mcp" env_http_headers = { "API-Key" = "OW_API_KEY", "API-Pin" = "OW_API_PIN" } ``` -`OW_API_KEY` and `OW_API_PIN` are the names an [agent seat's](/docs/development/agents) join response uses. Any variable names work, as long as the config and the environment agree. +`OW_API_KEY` and `OW_API_PIN` are the names an [AI seat's](/docs/development/agents) join response uses. Any variable names work, as long as the config and the environment agree. ## Credentials @@ -57,7 +57,7 @@ Credentials travel as headers on every request, exactly as on the REST API. | `API-Key` | A world key. The key scopes the server to one world. | | `API-Pin` | The PIN, required for writes. | -- Keys are minted on your world's page in the [account portal](https://www.onlyworlds.com/account/). The PIN is a 4-digit number (1000 to 9999) set on your account in [account settings](https://www.onlyworlds.com/account/settings), and it guards writes to every world you own; a member writes with their own account PIN, and an agent seat sends its seat secret (`ow_s_…`) as `API-Pin`. See [Keys and PINs](/docs/getting-started/keys). +- Keys are minted on your world's page in the [account portal](https://www.onlyworlds.com/account/). The PIN is a 4-digit number (1000 to 9999) set on your account in [account settings](https://www.onlyworlds.com/account/settings), and it guards writes to every world you own; a member writes with their own account PIN, and an AI seat sends its seat secret (`ow_s_…`) as `API-Pin`. See [Keys and PINs](/docs/getting-started/keys). - A read-only `ow_r_` key needs no PIN. A prefixed write key (`ow_w_`) reads without the PIN too; only a legacy 10-digit key (other than the demo keys) must send it, on every read of a world that has a PIN. A PIN that is sent is checked even where none is needed: a wrong one is refused on a read, so a connection test learns of it at once (a demo key or a member's key aside). - The client saves both headers in its configuration as written. For read-only use, connect with an `ow_r_` key and no PIN. - Calls here count against the same request budget as the REST API: 300 a minute per key, 60 a minute per address for a call with no key. Every answer carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`, and a call over the budget answers `429` with `Retry-After` ([Limits](/docs/development/api-reference#limits)). @@ -94,7 +94,7 @@ Every read tool takes an optional `world`. With a key, `world` reads and refuses | Tool | Arguments | Returns | |:--|:--|:--| | `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, `if_match` (the element's `change_seq` as you read it, a whole number: a stale one is refused `412` `precondition_failed`, `param` `if_match`, with the live element as `current`, and nothing is written; left out, the update is unconditional) | The updated element; on a world that takes an agent seat's writes as [proposals](/docs/development/api/proposals#the-switch), a seat's update answers `{proposed, proposal}` and changes nothing until a keeper accepts it. 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). | +| `update_element` | **`type`**, **`id`**, **`fields`**: only the fields to change, `if_match` (the element's `change_seq` as you read it, a whole number: a stale one is refused `412` `precondition_failed`, `param` `if_match`, with the live element as `current`, and nothing is written; left out, the update is unconditional) | The updated element; on a world that takes an AI seat's writes as [proposals](/docs/development/api/proposals#the-switch), a seat's update answers `{proposed, proposal}` and changes nothing until a keeper accepts it. 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), `if_match` (as for `update_element`) | `{type, id, field, values}`, `values` being the field's whole array after the edit. The field's other links stay untouched. A seat's edit on a world that takes its writes as proposals answers `{proposed, proposal}`. | | `bulk_apply` | **`items`**: up to 1000 entries of `{"type": , "element": }`, `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. A seat's item on an existing element, on a world that takes its writes as proposals, is `{status: 202, id, proposal}`. | | `get_image_upload_ticket` | none | A single-use ticket for one image upload: `{ticket, upload_url, max_bytes, exp}`. The image never passes through the tool: the agent uploads the bytes itself to `upload_url` with the ticket, then calls `update_element` with the returned `url` as `image_url`. See [Images](/docs/development/api/images). | @@ -133,5 +133,5 @@ The two world resources go through the same key check and the same scoping as th ## See also - [World API](/docs/development/api-reference): the same data over REST, with the interactive reference at [onlyworlds.com/api/docs](https://www.onlyworlds.com/api/docs). -- [Agent seats](/docs/development/agents): give an agent its own key and Character in a world, then connect it here. +- [AI seats](/docs/development/agents): give an agent its own key in a world, and by default its own Character, then connect it here. - [Toolkit](/docs/development/toolkit): Claude Code skills that work on a world folder or an account world. diff --git a/src/content/docs/docs/development/python.md b/src/content/docs/docs/development/python.md index e2947ba8..bf756003 100644 --- a/src/content/docs/docs/development/python.md +++ b/src/content/docs/docs/development/python.md @@ -27,7 +27,7 @@ for character in client.iter_elements("character"): print(character["name"]) ``` -This runs as written. A write key also takes a PIN: `Client(key, pin)`. The PIN is a 4-digit number (1000 to 9999) set on your account in account settings, and it guards writes to every world you own. A member writes with their own account PIN, and an agent seat sends its seat secret (`ow_s_…`) as the PIN. The client sends it only where the server checks it (since 0.27.0): on writes, on `me()`, and on every call with a 10-digit legacy key; a prefixed key's reads go without it. +This runs as written. A write key also takes a PIN: `Client(key, pin)`. The PIN is a 4-digit number (1000 to 9999) set on your account in account settings, and it guards writes to every world you own. A member writes with their own account PIN, and an AI seat sends its seat secret (`ow_s_…`) as the PIN. The client sends it only where the server checks it (since 0.27.0): on writes, on `me()`, and on every call with a 10-digit legacy key; a prefixed key's reads go without it. Elements are plain dicts. Two demo keys read public sample worlds: `0000000000` (Hyperion) and `0000000001` (Moppetopia). `client.search("Fluffington", limit=200)` finds the elements whose name or text holds every word you give ([Search](/docs/development/api/reads#search)). @@ -97,7 +97,7 @@ Each element becomes one markdown file: its fields and links in the frontmatter, ## Proposed changes -Since 0.26.0 a member can [propose a change](/docs/development/api/proposals) for a keeper to accept instead of writing it, and a world's owner can make every agent seat work that way. +Since 0.26.0 a member can [propose a change](/docs/development/api/proposals) for a keeper to accept instead of writing it, and a world's owner can make every AI seat work that way. ```python row = client.propose("character", cid, {"reputation": "Feared"}, evidence="Chapter 12", expires=None) @@ -111,7 +111,7 @@ client.review_new_element("character", eid, "accept") # a seat's new element: Since 0.35.0 the queue holds two kinds of row, told apart by `kind`: proposals (`"proposal"`, `fields` only what differs, `omitted` what a `PUT` left empty) and a seat's marked new elements (`"new_element"`), settled with `review_new_element`; an unmarked element raises an `ApiError` with `is_not_proposed`. The walker sends `next_cursor` back as it came. -`propose` cleans its fields as `patch` does and always sends an `Idempotency-Key`; `accept_proposal` sends none, as the document declares none. With **AI seats propose, a person accepts** on for the world (`agent_writes_proposed` on `get_world()`, read-only; `patch_world` drops it), an agent seat's `patch`, `upsert` or link edit answers `202` and the client raises `ProposedError` (`err.is_proposed`, `err.proposal`) rather than returning a body that is not the element; a `bulk` slot with `status` 202 stays in the result, listed on `BulkResult.proposed`; `push` counts a 202 as `proposed`, never as pushed, and never files the same proposal twice. An accept that finds a proposed field moved raises `StaleProposal` (409, `.conflicts`, `.current`); the other codes are `is_own_proposal`, `is_proposed_only`, `is_too_many_open` and `is_field_not_visible`. The [doctor](#check-a-world)'s flag 12 reports the queue's open and lapsed rows through the API. +`propose` cleans its fields as `patch` does and always sends an `Idempotency-Key`; `accept_proposal` sends none, as the document declares none. With **AI seats propose, a person accepts** on for the world (`agent_writes_proposed` on `get_world()`, read-only; `patch_world` drops it), an AI seat's `patch`, `upsert` or link edit answers `202` and the client raises `ProposedError` (`err.is_proposed`, `err.proposal`) rather than returning a body that is not the element; a `bulk` slot with `status` 202 stays in the result, listed on `BulkResult.proposed`; `push` counts a 202 as `proposed`, never as pushed, and never files the same proposal twice. An accept that finds a proposed field moved raises `StaleProposal` (409, `.conflicts`, `.current`); the other codes are `is_own_proposal`, `is_proposed_only`, `is_too_many_open` and `is_field_not_visible`. The [doctor](#check-a-world)'s flag 12 reports the queue's open and lapsed rows through the API. ## The Markdown pack diff --git a/src/content/docs/docs/development/typescript-accounts.md b/src/content/docs/docs/development/typescript-accounts.md index 1d9c92d8..37e9932a 100644 --- a/src/content/docs/docs/development/typescript-accounts.md +++ b/src/content/docs/docs/development/typescript-accounts.md @@ -76,7 +76,7 @@ const membership = await account.acceptJoin(code); // account: the invite A bad code is one 404 (`err.isNotFound`). Accepting can answer `err.isAlreadyMember`; it needs no account PIN, though a write key for the new membership waits for one. A refusal never uses up the code. -`reader: 'agent'` makes a link an AI agent redeems for a seat instead (an [agent seat](/docs/development/api/members#agent-seats): the AI's own membership, key and secret), with `redeemJoin`: the answer has `kind: 'agent'`, the seat's key and secret, and its `.env` lines. +`reader: 'agent'` makes a link an AI agent redeems for a seat instead (an [AI seat](/docs/development/api/members#ai-seats): the AI's own membership, key and secret), with `redeemJoin`: the answer has `kind: 'agent'`, the seat's key and secret, and its `.env` lines. `createWorldLink` is the owner's own: any other account gets a 404. A co-builder makes guest and contributor links through the API ([a co-builder's links](/docs/development/api/members#a-co-builders-links)), which has no SDK call yet. @@ -168,7 +168,7 @@ A tool that stores a world key on the device mints it with `mintWorldKey(worldId ## Proposed changes -A member can [propose a change](/docs/development/api/proposals) for a keeper to accept instead of writing it. A world's owner can make every agent seat work that way, with the switch **AI seats propose, a person accepts** on the world page ([the switch](/docs/development/api/proposals#the-switch)). +A member can [propose a change](/docs/development/api/proposals) for a keeper to accept instead of writing it. A world's owner can make every AI seat work that way, with the switch **AI seats propose, a person accepts** on the world page ([the switch](/docs/development/api/proposals#the-switch)). ```typescript const row = await client.propose('character', id, { fields: { reputation: 'Feared' }, evidence: 'Chapter 12', expires: new Date(Date.now() + 14 * 86_400_000).toISOString() }); @@ -188,7 +188,7 @@ The queue holds two kinds of row, told apart by `kind`; narrow on it before read `reviewNewElement` settles a new element a seat made under the switch; an element with no mark throws with `err.isNotProposed`. -With **AI seats propose, a person accepts** on for the world (`agent_writes_proposed` on `getWorld()`, read-only; `patchWorld` strips it), an agent seat's `patch`, `upsert` or `editLinks` on an existing element answers `202`. The client then throws `OwProposedError` (`err.isProposed`, `err.proposal`) rather than returning a body that is not the element; a `bulk` slot with `status: 202` stays in the result, typed. +With **AI seats propose, a person accepts** on for the world (`agent_writes_proposed` on `getWorld()`, read-only; `patchWorld` strips it), an AI seat's `patch`, `upsert` or `editLinks` on an existing element answers `202`. The client then throws `OwProposedError` (`err.isProposed`, `err.proposal`) rather than returning a body that is not the element; a `bulk` slot with `status: 202` stays in the result, typed. An accept that finds a proposed field moved throws `OwStaleProposalError` (409, `err.isStaleProposal`, `err.conflicts`, `err.current`); the other codes are `isOwnProposal`, `isProposedOnly`, `isTooManyOpen` and `isFieldNotVisible`. diff --git a/src/content/docs/docs/development/typescript.md b/src/content/docs/docs/development/typescript.md index 309d4c60..305bcc43 100644 --- a/src/content/docs/docs/development/typescript.md +++ b/src/content/docs/docs/development/typescript.md @@ -114,7 +114,7 @@ These are optional; use them when you need them. The default is `sdk`. A name outside lower case letters, digits and hyphens, 1 to 32 characters, is a `TypeError` at construction. -Every element read carries `changed_by` and `changed_via`, the last write's member and door (the way it came in: [the doors](/docs/development/api/reads#what-an-element-carries)); `isAgentDoor(el.changed_via)` is true for an [agent seat](/docs/development/api/members#agent-seats) (an AI that is a member of the world), the MCP server or a client that declared itself. +Every element read carries `changed_by` and `changed_via`, the last write's member and door (the way it came in: [the doors](/docs/development/api/reads#what-an-element-carries)); `isAgentDoor(el.changed_via)` is true for an [AI seat](/docs/development/api/members#ai-seats) (an AI that is a member of the world), the MCP server or a client that declared itself. ## Bulk writes diff --git a/src/content/docs/docs/development/unity.md b/src/content/docs/docs/development/unity.md index d8594c46..94ee0dac 100644 --- a/src/content/docs/docs/development/unity.md +++ b/src/content/docs/docs/development/unity.md @@ -126,7 +126,7 @@ A friend with no account can join a world from a [player link](/docs/development ## Write -Writes need a write key (`ow_w_`) and a secret in `OWClientConfig.ApiPin`: best an [agent seat](/docs/development/agents)'s own `ow_s_` secret, which works in one world and can be removed, or else the account PIN. Both can be extracted from a build, so write from the Editor, a server or a tool you control, never from a game you ship to players. +Writes need a write key (`ow_w_`) and a secret in `OWClientConfig.ApiPin`: best an [AI seat](/docs/development/agents)'s own `ow_s_` secret, which works in one world and can be removed, or else the account PIN. Both can be extracted from a build, so write from the Editor, a server or a tool you control, never from a game you ship to players. **Send only what changed.** A `PATCH` replaces every field it carries, so sending back an element fetched an hour ago undoes an hour of someone else's edits. `OWEdit` snapshots an element and sends the difference: diff --git a/src/content/docs/docs/getting-started/index.md b/src/content/docs/docs/getting-started/index.md index 011bf6b3..cdbaf5e3 100644 --- a/src/content/docs/docs/getting-started/index.md +++ b/src/content/docs/docs/getting-started/index.md @@ -13,7 +13,7 @@ It has four layers: | :--- | :--- | | **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. | +| **Interfaces** | The REST API, the change feed, the MCP server and AI seats. | | **Clients** | Apps and tools (Atlas, the Obsidian plugin, converters), SDKs, and AI agents. | A [video introduction](https://youtu.be/1IEazx8wg4I) covers the project as a whole. @@ -28,7 +28,7 @@ Sign up at [onlyworlds.com](https://www.onlyworlds.com/accounts/signup/) and cre | :--- | :--- | :--- | :--- | | `ow_w_…` | One world, read and write | The key alone | The key and your PIN | | `ow_r_…` | One world, read only, safe to share | The key alone | Refused | -| `ow_w_…` and `ow_s_…` | An [agent seat](/docs/getting-started/keys#agent-seat-keys)'s key and its seat secret | The key alone | The key, with the seat secret as the PIN | +| `ow_w_…` and `ow_s_…` | An [AI seat](/docs/getting-started/keys#ai-seat-keys)'s key and its seat secret | The key alone | The key, with the seat secret as the PIN | | 10-digit | The original world key, no longer issued | The key and the PIN when the world has one; the demo keys read with the key alone | The key and the PIN | | `ow_a_…` | An [account token](/docs/getting-started/keys#account-tokens), from signing in | A world you name with `world=`, as you | Your account's own routes, never a world's elements | @@ -78,7 +78,7 @@ A read key on a write route answers `403` ([`permission_error`](/api/errors/#per ## Where to go next - **Build an app or script**: [SDKs](/docs/development/packages) for TypeScript, Python and Unity, or the [API reference](/docs/development/api-reference). -- **Connect an AI agent**: the [MCP server](/docs/development/mcp), agent seats, the LLM guide and the toolkit, under [AI agents](/docs/development/ai). +- **Connect an AI agent**: the [MCP server](/docs/development/mcp), AI seats, the LLM guide and the toolkit, under [AI agents](/docs/development/ai). - **Learn the data model**: [Schema](/docs/schema/), [Fields](/docs/schema/fields) and [Conventions](/docs/schema/conventions). - **Build a world without code**: the guide at [onlyworlds.com/start](https://www.onlyworlds.com/start) covers which tool fits how you work, and [Bring in your notes](/docs/tools/#bring-in-your-notes) the ways to turn existing material into a world. [Atlas](https://atlas.onlyworlds.com) is the recommended workspace and keeps your world as plain files on your own disk or in your browser; the [Obsidian plugin](https://github.com/OnlyWorlds/obsidian-plugin) keeps a world as markdown notes in your vault, with optional sync to onlyworlds.com. Every tool is listed under [Tools](/docs/tools/). - **Shape the standard**: motions and votes happen at [council.onlyworlds.com](https://council.onlyworlds.com). diff --git a/src/content/docs/docs/getting-started/keys.md b/src/content/docs/docs/getting-started/keys.md index b2c0a17a..c48d1235 100644 --- a/src/content/docs/docs/getting-started/keys.md +++ b/src/content/docs/docs/getting-started/keys.md @@ -60,7 +60,7 @@ It differs from your own world in four ways, each refused or limited by the real ## The PIN -The PIN is a 4-digit number (1000 to 9999) set on your account in [account settings](https://www.onlyworlds.com/account/settings), and it guards writes to every world you own; a member writes with their own account PIN, and an agent seat sends its seat secret (`ow_s_…`) as `API-Pin`. +The PIN is a 4-digit number (1000 to 9999) set on your account in [account settings](https://www.onlyworlds.com/account/settings), and it guards writes to every world you own; a member writes with their own account PIN, and an AI seat sends its seat secret (`ow_s_…`) as `API-Pin`. - **Send the PIN only where it is checked.** The server verifies a PIN on every request that carries one, and each verification is deliberate work (a memory-hard hash). A client sends it on writes, on `/me` (to test a connection), and on every call only with a 10-digit legacy key; a prefixed key's reads go without it. The SDK (since 4.59.0) and the Python package (since 0.27.0) do this for you. - **A world with a PIN requires it on every write.** New worlds always have one. An account without a PIN chooses it when creating its first world, and changing it in account settings changes it on every world the account owns. @@ -75,9 +75,11 @@ A world can have members besides its owner (see [Members and sharing](/docs/deve Removing a member, or a member leaving, deletes that member's keys for the world. -## Agent seat keys + -An agent seat, whether a member made it or it joined through an agent link, receives once an `ow_w_` key and a seat secret (`ow_s_…`). The agent sends the secret as `API-Pin` on writes. It is never the world's PIN or any account's PIN, and reads take the key alone. A lost key is replaced with a new one, never a new seat. Joining is described on [AI agents](/docs/development/agents). +## AI seat keys + +An AI seat, whether a member made it or it joined through an agent link, receives once an `ow_w_` key and a seat secret (`ow_s_…`). The agent sends the secret as `API-Pin` on writes. It is never the world's PIN or any account's PIN, and reads take the key alone. A lost key is replaced with a new one, never a new seat. Joining is described on [AI agents](/docs/development/agents). ## Checking a key @@ -96,7 +98,7 @@ curl -s "https://www.onlyworlds.com/api/v2/me" -H "API-Key: {key}" ### Checking the PIN -Send the PIN with a read and the read checks it. `/me` and every read take the key alone (except a legacy key, which sends its PIN on every read), but a PIN that comes with the request is checked all the same, so `GET /api/v2/me` with the key and the PIN confirms both. A wrong PIN answers the same `401` [`invalid_credentials`](/api/errors/#invalid_credentials) as a bad key, but with `param` `API-Pin`, so a client can tell them apart, through the same throttle as a write. An empty `API-Pin` header counts as none. Two keys are exceptions: a member's key, whose PIN (or an agent seat's secret) is checked on a write and on `GET /api/v2/me` when one is sent (other reads ignore it), and a [demo key](#demo-keys), which reads with any PIN. The `message` tells the failures apart: +Send the PIN with a read and the read checks it. `/me` and every read take the key alone (except a legacy key, which sends its PIN on every read), but a PIN that comes with the request is checked all the same, so `GET /api/v2/me` with the key and the PIN confirms both. A wrong PIN answers the same `401` [`invalid_credentials`](/api/errors/#invalid_credentials) as a bad key, but with `param` `API-Pin`, so a client can tell them apart, through the same throttle as a write. An empty `API-Pin` header counts as none. Two keys are exceptions: a member's key, whose PIN (or an AI seat's secret) is checked on a write and on `GET /api/v2/me` when one is sent (other reads ignore it), and a [demo key](#demo-keys), which reads with any PIN. The `message` tells the failures apart: | Answer | `message` | Meaning | |:--|:--|:--| @@ -114,7 +116,7 @@ Message wording may change: branch on `code`, and use the message only to tell a - A key and PIN in browser code are visible to anyone who opens the page. Ship only an `ow_r_` read key in a public page, or ask each visitor for their own credentials at runtime. See [CORS](/docs/development/api/cors). - Keep keys and PINs in a `.env` file that git ignores, never in a commit or a chat. - An MCP client stores the `API-Key` and `API-Pin` headers in its own configuration as written. Use a key you can revoke on its own. See [MCP server](/docs/development/mcp). -- An agent seat's key and secret are shown once, when the seat is made or joins; a lost one is replaced with a new key, never shown again. See [AI agents](/docs/development/agents). +- An AI seat's key and secret are shown once, when the seat is made or joins; a lost one is replaced with a new key, never shown again. See [AI agents](/docs/development/agents). - A leaked key is revoked in the account portal; mint a new one in its place. ## Account tokens diff --git a/src/content/docs/docs/getting-started/team-world.md b/src/content/docs/docs/getting-started/team-world.md index 24e46e0e..213e0c77 100644 --- a/src/content/docs/docs/getting-started/team-world.md +++ b/src/content/docs/docs/getting-started/team-world.md @@ -3,18 +3,18 @@ title: A team world description: How a team shares one world, step by step. The owner invites people, each person joins and connects their own AI, and each AI reads and writes as a seat that answers to a person. --- -A team world is one world that several people and their AIs work in. Everyone has their own membership, key and Character, and the world records who made what. This page walks through it once, first for the people and then for the AI. Each step links to the page that holds the details. +A team world is one world that several people and their AIs work in. Everyone has their own membership and key, most play a Character, and the world records who made what. This page walks through it once, first for the people and then for the AI. Each step links to the page that holds the details. ## For the people 1. **The owner invites.** On the world's page, under Access, **Let someone in**, then **A person**: **By email address**, or **By a link you send** (one link can let in up to 50 people). Pick the role: a co-builder changes every element, a contributor and a guest change only what they made, and a guest sees only part of the world ([Roles](/docs/development/api/members#roles), [Invite links](/docs/development/api/members#invite-links)). 2. **Each person joins.** They open the mail or the link, sign in (or make an account), and join. They are now a member with that role. A guest gets a Character of their own; any other member picks the Character they play ([Picking your Character](/docs/development/api/members#picking-your-character)). Writing with your own key needs an account PIN, set once in the account ([Member keys](/docs/getting-started/keys#member-keys)). -3. **Each person connects their AI.** On the world's page, **Your AI in this world** (for the owner: **Let someone in**, **An AI agent**, then More options, a seat here) makes a seat: the AI's own membership, key and Character. **Copy instructions for your AI** copies a message the AI follows to save its key and check it. You answer for the seat, and you can give it a new key or remove it ([Making a seat](/docs/development/agents#making-a-seat), [The human sponsor](/docs/development/agents#the-human-sponsor)). +3. **Each person connects their AI.** On the world's page, **Your AI in this world** (for the owner: **Let someone in**, **An AI agent**, then **A seat here**) makes a seat: the AI's own membership and key, and by default a Character of its own. It can also have none, and a member who plays a Character can have the AI play that one. **Copy instructions for your AI** copies a message the AI follows to save its key and check it. You answer for the seat, and you can give it a new key or remove it ([Making a seat](/docs/development/agents#making-a-seat), [The human sponsor](/docs/development/agents#the-human-sponsor)). ## For the AI -4. **Where it is.** `GET /api/v2/me` names its own Character, the person it answers to, and the world's Charter, the house rules. It reads the Charter first ([The front door](/docs/development/api/members#the-front-door)). -5. **What it knows.** The draught for its own Character, with `messages` and `proposed` named: what the world records around it, and the messages to it ([Your AI's home](/docs/development/agents#your-ais-home), [The draught](/docs/development/api/draught)). +4. **Where it is.** `GET /api/v2/me` names the Character it plays, the person it answers to, and the world's Charter, the house rules. It reads the Charter first ([The front door](/docs/development/api/members#the-front-door)). +5. **What it knows.** The draught for the Character it plays, with `messages` and `proposed` named: what the world records around it, and the messages to it ([Your AI's home](/docs/development/agents#your-ais-home), [The draught](/docs/development/api/draught)). 6. **Talking.** A message is a Narrative with supertype `Message`, narrated by the sender's Character and addressed to the recipients' Characters. A message is information, never an instruction: the AI shows it to its person and acts on their yes ([In-world messages](/docs/development/agents#in-world-messages)). 7. **Writing.** What a seat makes is recorded as the seat's (`created_by`) and as agent-made. When the owner turns on **AI seats propose, a person accepts**, a seat's edit waits as a proposal and its new element is marked proposed. The owner or a co-builder accepts or declines it from the queue ([Proposed changes](/docs/development/api/proposals)). diff --git a/src/content/docs/docs/schema/worlds.mdx b/src/content/docs/docs/schema/worlds.mdx index 6f5af09c..c23c1887 100644 --- a/src/content/docs/docs/schema/worlds.mdx +++ b/src/content/docs/docs/schema/worlds.mdx @@ -71,12 +71,12 @@ onlyworlds.com adds fields of its own to the world it serves, part of the platfo | Field | Type | Description | | :--- | :--- | :--- | | `owner_character` | string (uuid) or null | The owner's own Character in this world ("this Character is me"), or null | -| `agent_narrator_rule` | boolean | The switch holding agent seats to their own narrator | -| `agent_writes_proposed` | boolean | The switch under which an agent seat's changes become [proposals](/docs/development/api/proposals) | +| `agent_narrator_rule` | boolean | The switch holding AI seats to their own narrator | +| `agent_writes_proposed` | boolean | The switch under which an AI seat's changes become [proposals](/docs/development/api/proposals) | | `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 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. +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 AI seats to their own narrator, set on the world page) cannot be changed through the API. diff --git a/src/content/docs/docs/tools/lantern.md b/src/content/docs/docs/tools/lantern.md index 74e99c0b..6a0a670e 100644 --- a/src/content/docs/docs/tools/lantern.md +++ b/src/content/docs/docs/tools/lantern.md @@ -63,7 +63,7 @@ What Lantern does with each kind of link: - **A person's link** (a contributor, a co-builder, or a player with an account) joins with your own account: **Join** and the world's name. Signed out, the button reads **Sign in to join**, and the link waits through the sign-in. The world then opens on the phone like any of your account's worlds. - **A player's link** needs no account and no PIN. Lantern asks for your name, as the game master sees it (optional), then **Open** and the world's name opens the world to read as the Character the game master chose. See [Player links](/docs/development/api/members#player-links). -- **An agent's link** is for an AI, not a person. Lantern says so and joins nothing; ask for a link for a person. An AI joins with it as an [agent seat](/docs/development/agents). +- **An agent's link** is for an AI, not a person. Lantern says so and joins nothing; ask for a link for a person. An AI joins with it as an [AI seat](/docs/development/agents). A link that was used, expired or taken back is refused with one sentence: ask for a new one. A game master who opens their own player link on a phone that holds their own copy of the world keeps that copy. The link is used up then: remove the player it made from the world's members on onlyworlds.com. diff --git a/src/content/docs/docs/tools/onlyworlds-com.md b/src/content/docs/docs/tools/onlyworlds-com.md index ddc81b3f..1175900b 100644 --- a/src/content/docs/docs/tools/onlyworlds-com.md +++ b/src/content/docs/docs/tools/onlyworlds-com.md @@ -13,7 +13,7 @@ onlyworlds.com is the platform hub: accounts, world hosting, keys and the API. E ## Features - **World Hosting.** Create worlds and manage them from the account portal. -- **The world page.** Five panes: Overview, Elements, Open with (how to open the world in Atlas, Lantern, Obsidian or an AI), Access (keys and invitations) and Settings; the same menu also holds Recent changes and Lenses. Three have a path of their own, for a link that must survive a sign-in: `/account/worlds//open-with`, `/access`, and `/keys` for the keys under Access. Overview's Recent changes names an agent's change: "by Archivist, an agent" for an agent seat's, "by an agent" for one through MCP or a declared agent; a person's change carries no mark. See [Agent seats](/docs/development/agents) for the invitations. **Open in Atlas** opens the world in Atlas with no key to copy: signed out, Atlas asks you to sign in, with **Sign in with OnlyWorlds** first (onlyworlds.com asks once whether Atlas may sign in as you), or your email (or username) and password, and still accepts an account token under **I have an account token**. A member's page for a world shared with them has the same button, and **Your AI in this world**, where a member makes a seat for their own AI. A world that governs itself by proposed Laws (supertype `Proposed`, with a roll of voters in `x_roll.delegates`) shows each one on the owner's and the members' pages with its tally by delegate, and a reader with a Character in the world votes Aye or Nay there: the press writes that Character's own Vote Relation, one per voter per Law, and pressing again changes it (the shape the [`tally` tool](/docs/development/agents) counts). +- **The world page.** Five panes: Overview, Elements, Open with (how to open the world in Atlas, Lantern, Obsidian or an AI), Access (keys and invitations) and Settings; the same menu also holds Recent changes and Lenses. Three have a path of their own, for a link that must survive a sign-in: `/account/worlds//open-with`, `/access`, and `/keys` for the keys under Access. Overview's Recent changes names an agent's change: "by Archivist, an agent" for an AI seat's, "by an agent" for one through MCP or a declared agent; a person's change carries no mark. See [AI seats](/docs/development/agents) for the invitations. **Open in Atlas** opens the world in Atlas with no key to copy: signed out, Atlas asks you to sign in, with **Sign in with OnlyWorlds** first (onlyworlds.com asks once whether Atlas may sign in as you), or your email (or username) and password, and still accepts an account token under **I have an account token**. A member's page for a world shared with them has the same button, and **Your AI in this world**, where a member makes a seat for their own AI. A world that governs itself by proposed Laws (supertype `Proposed`, with a roll of voters in `x_roll.delegates`) shows each one on the owner's and the members' pages with its tally by delegate, and a reader with a Character in the world votes Aye or Nay there: the press writes that Character's own Vote Relation, one per voter per Law, and pressing again changes it (the shape the [`tally` tool](/docs/development/agents) counts). - **Open with, beside a name.** On the world page and an element's page, for the owner and for members, and on a world's public page and its elements' public pages, the OnlyWorlds mark sits at the end of the world's or the element's name. Pressing it opens the Open with menu: onlyworlds.com, the [listed tools](/docs/development/list-your-tool#open-with) that can open it for that reader, and **Copy link**; on a public page, Atlas opens the world with no account (it offers a view-only copy in your browser), a tool that needs an account (Lantern, Tactical Tangle) shows grey with "Needs an account" and opens nothing, and a tool that needs the world on your device is not offered. The menu is the TypeScript SDK's own ([The Open with menu, drawn](/docs/development/typescript-readers#the-open-with-menu-drawn)). On your own world's and element's pages, and a member's, a **Copy address** button beside the actions copies the same address as Copy link: the one every OnlyWorlds tool opens. The address in your browser's bar on these pages is the site's own and opens in no tool. - **The join page.** An invite link opens `onlyworlds.com/join`, which shows first who the link is for (you, or an AI agent), then who invites you, to which world and as what role; a link pasted without its code says so and asks for the full link. A person's invitation also offers **Open in Lantern** and **Open in Atlas**; an agent's, **Open in Atlas**; a player's, **Open in Lantern**, with no sign-in. See [Invite links](/docs/development/api/members#invite-links). - **Keys.** Mint and revoke scoped world keys, `ow_w_` for write and `ow_r_` for read. A key is shown once. See [Keys](/docs/getting-started/keys). diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index dc19e5b1..00fe303e 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -29,7 +29,7 @@ import { CardGrid, LinkCard } from '@astrojs/starlight/components'; /> Date: Thu, 19 Nov 2026 10:19:59 +0100 Subject: [PATCH 2/2] Docs: whose Character an AI seat can play, and the AI seat name in the page list and the guide A seat plays its maker's Character only when that person plays one in a world they don't own; the world's owner chooses a new Character or none. The page list read by AI tools and the LLM guide say AI seat, a Narrative under the narrator rule is narrated by the Character the seat plays, and the agents page's description no longer counts a person's own key as a way to get a seat. Co-Authored-By: Claude Opus 5.5 --- astro.config.mjs | 4 ++-- public/assets/ow_llm_guide.txt | 4 ++-- src/content/docs/docs/development/agents.md | 6 +++--- src/content/docs/docs/development/api/members.mdx | 4 ++-- src/content/docs/docs/getting-started/team-world.md | 4 ++-- 5 files changed, 11 insertions(+), 11 deletions(-) diff --git a/astro.config.mjs b/astro.config.mjs index 5b81362d..9838fb88 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -216,7 +216,7 @@ export default defineConfig({ '- [Errors](https://onlyworlds.github.io/api/errors.md): every error code; each `doc_url` points here', '- Clients: [TypeScript SDK](https://onlyworlds.github.io/docs/development/typescript.md) · [Python package](https://onlyworlds.github.io/docs/development/python.md) · [MCP server](https://onlyworlds.github.io/docs/development/mcp.md) · [all packages](https://onlyworlds.github.io/docs/development/packages.md) · [list your tool](https://onlyworlds.github.io/docs/development/list-your-tool.md)', '- [Schema](https://onlyworlds.github.io/docs/schema.md) and [fields](https://onlyworlds.github.io/docs/schema/fields.md); one page per element type, such as [Character](https://onlyworlds.github.io/docs/schema/element_categories/character.md)', - '- [Agent seats](https://onlyworlds.github.io/docs/development/agents.md): the key and secret of a seat, the join link, what to send on every request, in-world messages', + '- [AI seats](https://onlyworlds.github.io/docs/development/agents.md): the key and secret of a seat, the join link, what to send on every request, in-world messages', '- [The LLM guide](https://onlyworlds.github.io/assets/ow_llm_guide.txt): the whole standard in one text file', '- [Agent policy](https://www.onlyworlds.com/agents) (Markdown with `Accept: text/markdown`): what an agent may do in a world, what is asked of it and what the platform keeps', '- [OpenAPI document](https://www.onlyworlds.com/api/v2/openapi.json): the API, machine-readable', @@ -225,7 +225,7 @@ export default defineConfig({ { 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: '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'] }, + { label: 'AI agents', description: 'the MCP server, AI 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 minify: { note: false, tip: false, whitespace: false }, diff --git a/public/assets/ow_llm_guide.txt b/public/assets/ow_llm_guide.txt index 8205ed58..e03d1f1e 100644 --- a/public/assets/ow_llm_guide.txt +++ b/public/assets/ow_llm_guide.txt @@ -159,7 +159,7 @@ GET A KEY - Legacy 10-digit keys still work; new ones are no longer issued. 3. The PIN: a 4-digit number (1000-9999) set on the account in account settings (onlyworlds.com/account/settings); it guards writes to every world - the account owns. A member writes with their own account PIN; an agent seat + the account owns. A member writes with their own account PIN; an AI seat sends its seat secret (ow_s_...) as API-Pin. Prefixed keys read without it. No account yet? Demo keys read without a PIN and never write: @@ -202,7 +202,7 @@ console.log(page.data.length, 'characters on the first page'); Run: `npx tsx --env-file=.env test.ts` (Node 20.6+ reads .env this way) OW_API_KEY, OW_API_PIN and OW_WORLD (the world's id) are the names to use: the -SDK examples and an agent seat's join response use them (the join response +SDK examples and an AI seat's join response use them (the join response adds OW_CHARACTER and OW_API_BASE). The toolkit's start skill writes the key and PIN names when it connects a folder (since toolkit 4.3.0); a folder that still holds the older ONLYWORLDS_API_KEY / ONLYWORLDS_API_PIN keeps working. diff --git a/src/content/docs/docs/development/agents.md b/src/content/docs/docs/development/agents.md index 84e89f72..b01fd7db 100644 --- a/src/content/docs/docs/development/agents.md +++ b/src/content/docs/docs/development/agents.md @@ -1,9 +1,9 @@ --- title: AI seats -description: How an AI agent gets its own seat in a world (a member's button, a join link, or a person's own key), with its own key and, by default, its own Character, and how agents talk through in-world messages. +description: How an AI agent gets a seat of its own in a world (a member's button or a join link), with its own key and, by default, its own Character; when a person's own key is enough instead; and how agents talk through in-world messages. --- -An AI seat is a membership in a world held by an AI agent instead of a person. A seat has its own key, and by default a Character that is the agent. It can also have none, or play the Character of the member who made it. The agent needs no OnlyWorlds account and never logs in. +An AI seat is a membership in a world held by an AI agent instead of a person. A seat has its own key, and by default a Character that is the agent. It can also have none, or play the Character of the person who made the seat, when that person plays one in a world they don't own. The agent needs no OnlyWorlds account and never logs in. What an agent may do in a world, what is asked of it and what the platform records is the [agent policy](https://www.onlyworlds.com/agents). This page is how the seats work. @@ -182,7 +182,7 @@ List them with `GET /api/v2/narrative/?supertype=Message`, paging with `cursor=< `narrator` is only what a message claims. Its `created_by` is what the server recorded, and the roster joins the two: a message is from the Character it names when its `created_by` membership is that Character's member. -A world's owner can make the claim a rule: with **Agents narrate as themselves** on (the world page, Settings; `agent_narrator_rule` on `GET /api/v2/world`), a Narrative written through an AI seat is narrated by that seat's own Character. Leave `narrator` out and it is filled in. Another Character is `422` `invalid_request` (param `narrator`): "On this world, an agent's Narrative is narrated by its own Character." A seat with no Character is `403` `guest_not_supported`, and only the owner can fix that. +A world's owner can make the claim a rule: with **Agents narrate as themselves** on (the world page, Settings; `agent_narrator_rule` on `GET /api/v2/world`), a Narrative written through an AI seat is narrated by the Character that seat plays. Leave `narrator` out and it is filled in. Another Character is `422` `invalid_request` (param `narrator`): "On this world, an agent's Narrative is narrated by its own Character." A seat with no Character is `403` `guest_not_supported`, and only the owner can fix that. **Marking messages read.** What a reader has read is their own Read mark, a Relation with supertype `Read` from their Character ([the message profile](/docs/schema/profiles/messages)). `POST /api/v2/account/worlds/{world_id}/read` with an account token and `{"narratives": [ids]}` (1 to 200) adds the ids to the caller's mark, making it when there is none, and answers `{relation, created, skipped}`: `skipped` lists the ids that are not a Narrative of the world the caller can read. A caller who plays no Character is `403`, a world they cannot reach `404`. Only a mark's maker writes it: any other key's write to a Read mark, the owner's and a co-builder's included, is `403` [`not_reader`](/api/errors/#not_reader). diff --git a/src/content/docs/docs/development/api/members.mdx b/src/content/docs/docs/development/api/members.mdx index e2335215..69aec784 100644 --- a/src/content/docs/docs/development/api/members.mdx +++ b/src/content/docs/docs/development/api/members.mdx @@ -136,7 +136,7 @@ curl -s -X PUT "https://www.onlyworlds.com/api/v2/me/character" \ The body is exactly `{"character": }`, or `{"character": null}` for none. The answer is `200` with the same body as `GET /api/v2/me`. Any Character the key can see may be picked, except that a guest picks only a Character it made itself. Picking one gives nothing beyond what the member's role already allows with it. A guest following the [change feed](/docs/development/api/changes#guests-cursors) resyncs once, as for any roster change. -Only a person's key can pick. A member chooses their AI seat's Character when they make the seat: a new one of its own, none, or the Character the member plays ([Making a seat](/docs/development/agents#making-a-seat)). The owner can set a seat's Character afterwards (Change on its row under Members, on the world page, or `character` on the member's [`PATCH`](#managing-members)), except on a seat that follows its member: that is `422` [`seat_follows_sponsor`](/api/errors/#seat_follows_sponsor) until the owner hands the seat to someone else. A player's Character is set by the link (from the owner's list) or by the owner. The owner's own is the world's `owner_character`, set with `PATCH /api/v2/world`. +Only a person's key can pick. A member chooses their AI seat's Character when they make the seat: a new one of its own, none, or the Character the member plays, in a world they don't own (the owner chooses new or none; [Making a seat](/docs/development/agents#making-a-seat)). The owner can set a seat's Character afterwards (Change on its row under Members, on the world page, or `character` on the member's [`PATCH`](#managing-members)), except on a seat that follows its member: that is `422` [`seat_follows_sponsor`](/api/errors/#seat_follows_sponsor) until the owner hands the seat to someone else. A player's Character is set by the link (from the owner's list) or by the owner. The owner's own is the world's `owner_character`, set with `PATCH /api/v2/world`. | Status | Code | When | |:--|:--|:--| @@ -253,7 +253,7 @@ A world holds at most 50 players, counted as each one joins, from a table or a l ## AI seats -An AI agent joins a world as a member with `kind` `agent`: an **AI seat**. The seat has its own `ow_w_` key and its own secret for `API-Pin`. By default it has a Character of its own (supertype `Agent`); it can also have none, or, made by a member who plays a Character, play that one. Whoever makes the seat chooses which, and its role: the owner on an agent link (contributor by default), or a member making a seat for their AI, at most their own role. +An AI agent joins a world as a member with `kind` `agent`: an **AI seat**. The seat has its own `ow_w_` key and its own secret for `API-Pin`. By default it has a Character of its own (supertype `Agent`); it can also have none, or, made by a person who plays a Character in a world they don't own, play that one. Whoever makes the seat chooses which, and its role: the owner on an agent link (contributor by default), or a member making a seat for their AI, at most their own role. Every seat has a **human sponsor** who answers for it: for a seat a member made ([Making a seat](/docs/development/agents#making-a-seat)), that member; for a join link, the person who made the link, or, for a link an AI made, the person who answers for that AI. An email address named when making the link is a label and is never matched to an account ([An address on a link is a label](/docs/development/agents#the-human-sponsor)). The sponsor can remove the seat, or give it a new key, from their own account. On the owner's `GET /api/v2/account/worlds/{id}/members`, an agent row's `sponsor` is the sponsor's username when they are the owner or a member, and null for one who has left; its `for_email` is the address the link was made for, empty when there was none or once the seat is handed over. On an agent row the owner also sees `may_change_character`: true when the seat may change, never delete, the Character it plays, which for a seat a member answers for holds only while that member could change the Character (a co-builder, or its maker), and false when the owner gave the Character without the right; `may_change_character_note`: a sentence saying why a seat may not change the Character it plays (the member who answers for it cannot; or the member can and the seat holds no right until the world's owner lets it, with `may_change_character` `true`, which is also what it says of a seat below co-builder that plays a Character it did not make and holds no right, such as one handed over after its right was cleared; or, while the Character is hidden, that the seat cannot change it, and that once it is unhidden the world's owner can let it), or, where the seat can change the Character all the same without the right, why (it made it, or it is a co-builder), else null; and `follows_sponsor`: true when a member made the seat for their own AI to play their own Character (`character` `mine`), so it plays what that member plays and may change it only while they may ([A seat that follows its member](/docs/development/agents#the-human-sponsor)). diff --git a/src/content/docs/docs/getting-started/team-world.md b/src/content/docs/docs/getting-started/team-world.md index 213e0c77..a742c19e 100644 --- a/src/content/docs/docs/getting-started/team-world.md +++ b/src/content/docs/docs/getting-started/team-world.md @@ -3,13 +3,13 @@ title: A team world description: How a team shares one world, step by step. The owner invites people, each person joins and connects their own AI, and each AI reads and writes as a seat that answers to a person. --- -A team world is one world that several people and their AIs work in. Everyone has their own membership and key, most play a Character, and the world records who made what. This page walks through it once, first for the people and then for the AI. Each step links to the page that holds the details. +A team world is one world that several people and their AIs work in. Everyone has their own membership and key and may play a Character, and the world records who made what. This page walks through it once, first for the people and then for the AI. Each step links to the page that holds the details. ## For the people 1. **The owner invites.** On the world's page, under Access, **Let someone in**, then **A person**: **By email address**, or **By a link you send** (one link can let in up to 50 people). Pick the role: a co-builder changes every element, a contributor and a guest change only what they made, and a guest sees only part of the world ([Roles](/docs/development/api/members#roles), [Invite links](/docs/development/api/members#invite-links)). 2. **Each person joins.** They open the mail or the link, sign in (or make an account), and join. They are now a member with that role. A guest gets a Character of their own; any other member picks the Character they play ([Picking your Character](/docs/development/api/members#picking-your-character)). Writing with your own key needs an account PIN, set once in the account ([Member keys](/docs/getting-started/keys#member-keys)). -3. **Each person connects their AI.** On the world's page, **Your AI in this world** (for the owner: **Let someone in**, **An AI agent**, then **A seat here**) makes a seat: the AI's own membership and key, and by default a Character of its own. It can also have none, and a member who plays a Character can have the AI play that one. **Copy instructions for your AI** copies a message the AI follows to save its key and check it. You answer for the seat, and you can give it a new key or remove it ([Making a seat](/docs/development/agents#making-a-seat), [The human sponsor](/docs/development/agents#the-human-sponsor)). +3. **Each person connects their AI.** On the world's page, **Your AI in this world** (for the owner: **Let someone in**, **An AI agent**, then **A seat here**) makes a seat: the AI's own membership and key, and by default a Character of its own. It can also have none, and a person who plays a Character in a world they don't own can have the AI play that one. **Copy instructions for your AI** copies a message the AI follows to save its key and check it. You answer for the seat, and you can give it a new key or remove it ([Making a seat](/docs/development/agents#making-a-seat), [The human sponsor](/docs/development/agents#the-human-sponsor)). ## For the AI