docs: document canonical server-minted world IDs

getting-started.mdx

@@ -26,11 +26,9 @@ if you believe you should have access.
 
 ## 2. Create a world
 
-After signing in, click **Create world**. Give your world a name and an ID. The
-ID must be unique across all worlds in the platform.
-
-World IDs are public and used in API requests. Choose something descriptive like
-`my-knowledge-base` or `project-context`.
+After signing in, click **Create world** and enter a display name. The platform
+mints the world's ID; you do not choose one. Use the returned `id` in API
+requests.
 
 ## 3. Import data
 

guides/company-brain.mdx

@@ -31,11 +31,13 @@ and carry provenance you can trace to their source.
     Worlds stores facts in isolated worlds. Create one for the company brain:
 
     ```bash
-    wazoo worlds create company-brain --name "Company Brain"
+    wazoo worlds create --name "Company Brain"
+    export WORLD_ID="w_123e4567-e89b-42d3-a456-426614174000"
     ```
 
-    The world ID `company-brain` is public and used in every data-plane
-    request. Choose a descriptive ID so agents can find the right world.
+    The Worlds API mints an immutable `w_<UUIDv4>` ID and returns it as `id`.
+    Replace the sample `WORLD_ID` with that exact value; the display name is not
+    an ID, and create requests expose no caller-selected ID or slug field.
 
   </Step>
   <Step title="Model the core schemas">
@@ -98,7 +100,7 @@ and carry provenance you can trace to their source.
 
     ```bash
     wiki export brain/decisions/ADR-004.md -f turtle -o brain/ADR-004.ttl
-    wazoo worlds import company-brain --file ./brain/ADR-004.ttl
+    wazoo worlds import "$WORLD_ID" --file ./brain/ADR-004.ttl
     ```
 
     The import endpoint accepts Turtle, JSON-LD, N-Triples, N-Quads, and Trig.
@@ -134,13 +136,13 @@ and carry provenance you can trace to their source.
 Search the brain for the decision you imported:
 
 ```bash
-wazoo worlds search company-brain --query "company context engine"
+wazoo worlds search "$WORLD_ID" --query "company context engine"
 ```
 
 Then confirm the fact exists in the graph with a SPARQL query:
 
 ```bash
-wazoo worlds sparql company-brain --query "SELECT * WHERE { ?s ?p ?o } LIMIT 10"
+wazoo worlds sparql "$WORLD_ID" --query "SELECT * WHERE { ?s ?p ?o } LIMIT 10"
 ```
 
 The search returns the ADR document, and the SPARQL query returns its quads.

guides/entity-resolution.mdx

@@ -127,7 +127,7 @@ of the substrate. Import these quads through the normal
 Search the world for the mention's name and take the top candidates:
 
 ```bash
-curl -s -X POST "https://data.wazoo.dev/worlds/my-world-id/search" \
+curl -s -X POST "https://data.wazoo.dev/worlds/w_123e4567-e89b-42d3-a456-426614174000/search" \
   -H "Authorization: Bearer $WORLDS_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{ "query": "Sarah Chen", "topK": 5 }'
@@ -241,7 +241,7 @@ extraction-based memory layers have to build by hand.
 Search the world for both names and confirm they resolve to one subject:
 
 ```bash
-curl -s -X POST "https://data.wazoo.dev/worlds/my-world-id/search" \
+curl -s -X POST "https://data.wazoo.dev/worlds/w_123e4567-e89b-42d3-a456-426614174000/search" \
   -H "Authorization: Bearer $WORLDS_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{ "query": "Sarah" }'
@@ -250,7 +250,7 @@ curl -s -X POST "https://data.wazoo.dev/worlds/my-world-id/search" \
 Then verify the resolution exists in the graph:
 
 ```bash
-curl -s -X POST "https://data.wazoo.dev/worlds/my-world-id/sparql" \
+curl -s -X POST "https://data.wazoo.dev/worlds/w_123e4567-e89b-42d3-a456-426614174000/sparql" \
   -H "Authorization: Bearer $WORLDS_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{

platform/api.mdx

@@ -59,9 +59,36 @@ The Platform API covers these management resources:
 | Users             | `/v1/users/me`                                                          |
 | Stripe webhook    | `/v1/stripe/webhook`                                                    |
 
-Public `worldId` values must match `^[a-z][a-z0-9-]{2,62}$`. Internal `uid`
-values use prefixes such as `w_...` so they cannot be confused with public path
-IDs.
+`worlds-api` mints each immutable world ID as `w_<UUIDv4>`. The Platform API
+stores it as `world_id`, and both APIs expose the unchanged value as `id`.
+Create requests define a display name but no caller-selected ID or slug field.
+Use `world.id` as the `worldId` path parameter.
+
+```http
+POST /v1/worlds
+Authorization: Bearer wzp_YOUR_PLATFORM_TOKEN
+Content-Type: application/json
+
+{
+  "world": {
+    "displayName": "My World",
+    "region": "auto"
+  }
+}
+
+HTTP/1.1 201 Created
+
+{
+  "world": {
+    "id": "w_123e4567-e89b-42d3-a456-426614174000",
+    "displayName": "My World",
+    "region": "auto",
+    "state": "ACTIVE",
+    "restorable": false,
+    "backend": "worlds-api"
+  }
+}
+```
 
 ## Data-plane boundary
 

platform/typescript-sdk.mdx

@@ -64,29 +64,32 @@ console.log(data?.worlds);
 // Create a world
 const created = await createWorld({
   body: {
-    worldId: "support-knowledge",
     world: { displayName: "Support Knowledge", region: "auto" },
   },
 });
+const worldId = created.data!.world.id;
 
 // Get a world by ID
 const world = await getWorld({
-  path: { worldId: "support-knowledge" },
+  path: { worldId },
 });
 
 // Update display name
 await updateWorld({
-  path: { worldId: "support-knowledge" },
+  path: { worldId },
   body: {
     updateMask: "displayName",
     world: { displayName: "Support Knowledge Base" },
   },
 });
 
 // Soft-delete (recoverable for 30 days)
-await deleteWorld({ path: { worldId: "support-knowledge" } });
+await deleteWorld({ path: { worldId } });
 ```
 
+`world.id` is the immutable `w_<UUIDv4>` ID minted by the Worlds API. Reuse it
+unchanged as the `worldId` path value.
+
 Creating a platform world provisions per-World graph storage. Use
 `data.wazoo.dev`, the generated [`@worlds/client`](/projects/worlds), or the
 embedded [`@worlds/sdk`](/projects/worlds) for graph data operations inside that
@@ -131,16 +134,16 @@ import {
 } from "@wazoo/client";
 
 const { data } = await listWorldTokens({
-  path: { worldId: "support-knowledge" },
+  path: { worldId },
 });
 
 const created = await createWorldToken({
-  path: { worldId: "support-knowledge" },
+  path: { worldId },
 });
 console.log(created.data?.token); // one-time secret
 
 await deleteWorldToken({
-  path: { worldId: "support-knowledge", tokenUid: created.data!.token.uid },
+  path: { worldId, tokenUid: created.data!.token.uid },
 });
 ```
 
@@ -150,12 +153,12 @@ await deleteWorldToken({
 import { getWorldUsage, getWorldLimits } from "@wazoo/client";
 
 const usage = await getWorldUsage({
-  path: { worldId: "support-knowledge" },
+  path: { worldId },
 });
 console.log(usage.data?.usage.total);
 
 const limits = await getWorldLimits({
-  path: { worldId: "support-knowledge" },
+  path: { worldId },
 });
 ```
 
@@ -165,7 +168,7 @@ const limits = await getWorldLimits({
 import { getWorldBilling } from "@wazoo/client";
 
 const billing = await getWorldBilling({
-  path: { worldId: "support-knowledge" },
+  path: { worldId },
 });
 console.log(billing.data?.billing.state);
 ```

projects/worlds.mdx

@@ -60,18 +60,26 @@ curl -s -X POST "https://api.wazoo.dev/v1/worlds" \
   -H "Authorization: Bearer $WAZOO_PLATFORM_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
-    "worldId": "quickstart-cloud",
     "world": { "displayName": "My First World", "region": "auto" }
   }'
 ```
 
+The Worlds API mints one immutable `w_<UUIDv4>` ID and returns it as `world.id`.
+Create requests include the display name and expose no caller-selected ID or
+slug field. Set `WORLD_ID` to that exact returned value before running the
+requests below.
+
+```bash
+export WORLD_ID="w_123e4567-e89b-42d3-a456-426614174000"
+```
+
 ### Mint a world token
 
 Data-plane requests use a `wzw_` token scoped to a single world. Save the
 returned secret immediately; it is shown only once:
 
 ```bash
-curl -s -X POST "https://api.wazoo.dev/v1/worlds/quickstart-cloud/auth/tokens" \
+curl -s -X POST "https://api.wazoo.dev/v1/worlds/$WORLD_ID/auth/tokens" \
   -H "Authorization: Bearer $WAZOO_PLATFORM_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{ "name": "quickstart" }'
@@ -82,7 +90,7 @@ Save it as `WORLDS_TOKEN`.
 ### Import, search, and query
 
 ```bash
-curl -s -X POST "https://data.wazoo.dev/worlds/quickstart-cloud/import" \
+curl -s -X POST "https://data.wazoo.dev/worlds/$WORLD_ID/import" \
   -H "Authorization: Bearer $WORLDS_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
@@ -92,7 +100,7 @@ curl -s -X POST "https://data.wazoo.dev/worlds/quickstart-cloud/import" \
 ```
 
 ```bash
-curl -s -X POST "https://data.wazoo.dev/worlds/quickstart-cloud/search" \
+curl -s -X POST "https://data.wazoo.dev/worlds/$WORLD_ID/search" \
   -H "Authorization: Bearer $WORLDS_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
@@ -102,7 +110,7 @@ curl -s -X POST "https://data.wazoo.dev/worlds/quickstart-cloud/search" \
 ```
 
 ```bash
-curl -s -X POST "https://data.wazoo.dev/worlds/quickstart-cloud/sparql" \
+curl -s -X POST "https://data.wazoo.dev/worlds/$WORLD_ID/sparql" \
   -H "Authorization: Bearer $WORLDS_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{

quickstart.mdx

@@ -29,13 +29,14 @@ If you prefer calling the Wazoo Platform API directly using HTTP/cURL:
       -H "Authorization: Bearer wzp_YOUR_PLATFORM_TOKEN" \
       -H "Content-Type: application/json" \
       -d '{
-        "worldId": "my-agent-world",
         "world": {
           "displayName": "My Agent World",
           "region": "auto"
         }
       }'
     ```
+    The Worlds API mints an immutable `w_<UUIDv4>` ID and returns it as
+    `world.id`, which callers reuse unchanged in later requests.
   </Step>
 </Steps>
 

reference/cli/usage.mdx

@@ -24,11 +24,11 @@ wazoo usage <worldId> [options]
 ### Check usage for a world
 
 ```bash
-wazoo usage dev-world-01
+wazoo usage w_123e4567-e89b-42d3-a456-426614174000
 ```
 
 ### View usage metrics as JSON
 
 ```bash
-wazoo usage dev-world-01 --json
+wazoo usage w_123e4567-e89b-42d3-a456-426614174000 --json
 ```

reference/cli/worlds.mdx

@@ -12,16 +12,19 @@ data from the command line.
 
 Create a new isolated memory world.
 
+The Worlds API mints an immutable `w_<UUIDv4>` ID. The response's `id` is reused
+unchanged as `worldId` in subsequent commands.
+
 ```bash
-wazoo worlds create <world-id> --name "My Knowledge Base"
+wazoo worlds create --name "My Knowledge Base"
 ```
 
 ### `wazoo worlds get`
 
 Retrieve specific world details by ID.
 
 ```bash
-wazoo worlds get <world-id>
+wazoo worlds get <worldId>
 ```
 
 ### `wazoo worlds list`
@@ -40,29 +43,29 @@ Import text, files, or RDF knowledge graph data into a world. Supports Turtle,
 JSON-LD, N-Triples, N-Quads, and Trig.
 
 ```bash
-wazoo worlds import <world-id> --file ./data.ttl
+wazoo worlds import <worldId> --file ./data.ttl
 ```
 
 ### `wazoo worlds export`
 
 Export world graph quads/triples.
 
 ```bash
-wazoo worlds export <world-id> --format turtle
+wazoo worlds export <worldId> --format turtle
 ```
 
 ### `wazoo worlds search`
 
 Perform hybrid vector + graph pattern search across world memory.
 
 ```bash
-wazoo worlds search <world-id> --query "agent architecture"
+wazoo worlds search <worldId> --query "agent architecture"
 ```
 
 ### `wazoo worlds sparql`
 
 Execute raw graph queries and pattern matching (SPARQL) against a world graph.
 
 ```bash
-wazoo worlds sparql <world-id> --query "SELECT * WHERE { ?s ?p ?o } LIMIT 10"
+wazoo worlds sparql <worldId> --query "SELECT * WHERE { ?s ?p ?o } LIMIT 10"
 ```

skills/wazoo.mdx

@@ -81,6 +81,10 @@ The skill reads two environment variables, one per plane:
 | `WAZOO_PLATFORM_TOKEN` | `wzp_` | Control plane | World creation, token management, usage inspection          |
 | `WORLDS_TOKEN`         | `wzw_` | Data plane    | Graph import, hybrid search, graph queries (SPARQL), export |
 
+The Worlds API mints an immutable `w_<UUIDv4>` world ID. The create response
+exposes it as `world.id`, which you reuse unchanged. Create requests expose no
+caller-selected ID or slug field.
+
 ## What it covers
 
 ### Control plane