> For the complete documentation index, see [llms.txt](https://docs.kobotai.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kobotai.co/world/readme.md).

# World Protocol

World Protocol is an open protocol for discovery and interaction across independent virtual worlds. WorldDevKit is its framework-neutral TypeScript implementation.

The Level 1 release focuses on public discovery and entity reads. It gives world operators a small Fetch API server adapter, an environment-neutral client, runtime contracts and schemas, and a reusable conformance suite.

## Packages

| Package                | Purpose                                                                 |
| ---------------------- | ----------------------------------------------------------------------- |
| `@worlddevkit/spec`    | TypeScript contracts and dependency-free JSON Schemas                   |
| `@worlddevkit/server`  | Framework-neutral Fetch API handler, pagination, CORS and rate limiting |
| `@worlddevkit/client`  | World discovery, typed reads, pagination and errors                     |
| `@worlddevkit/testing` | Level 1 conformance runner for world implementations                    |
| `@worlddevkit/core`    | Framework-neutral entities and money values                             |
| `@worlddevkit/geo`     | Privacy-safe public location projection                                 |

## Install

```sh
npm install @worlddevkit/client @worlddevkit/spec
```

For a world server:

```sh
npm install @worlddevkit/server @worlddevkit/spec
```

For conformance testing:

```sh
npm install --save-dev @worlddevkit/testing
```

## Minimal client

```ts
import { WorldClient } from '@worlddevkit/client'

const world = await WorldClient.connect('https://world.example')
const stores = await world.listEntities('wp:store', { limit: 20 })
```

A compatible world publishes `/.well-known/world.json` and mounts its Level 1 API at the endpoint declared by that document.

## Minimal server

```ts
import { createWorldHandler } from '@worlddevkit/server'
import { WORLD_PROTOCOL_VERSION } from '@worlddevkit/spec'

const handler = createWorldHandler({
  world: {
    protocol: WORLD_PROTOCOL_VERSION,
    id: 'https://world.example',
    name: 'Example World',
    endpoints: { api: 'https://world.example/api/world/v0' },
    entityTypes: ['wp:store'],
    actions: ['wp:discover'],
  },
  source: {
    async list() {
      return []
    },
    async get() {
      return null
    },
  },
})
```

See the [five-minute quickstart](/world/quickstart.md), [Level 1 API reference](/world/reference/level-1-api.md), [OpenAPI 3.1 document](https://github.com/KobotAI/world-protocol/tree/main/docs/reference/openapi.yaml), [coding-agent guide](/world/guides/build-a-world.md), package READMEs and [`examples/`](/world/project/examples.md) for complete usage. Public documentation is published under `https://docs.kobotai.co/world` using `gitbook-docs.yaml`, `.gitbook.yaml`, and `SUMMARY.md`.

## Development

Requirements: Node.js 20+ and pnpm 10.17.1.

```sh
pnpm install
pnpm quickstart

# In another terminal
pnpm --dir examples/client-node quickstart

# Full validation
pnpm test
pnpm typecheck
```

Each package remains independently installable and has its own frozen lockfile. Release artifacts are staged and verified as a clean external consumer before publishing.

## Releases

Releases are performed by the guarded `WorldDevKit Release` GitHub Actions workflow using npm trusted publishing and GitHub OIDC. Source package manifests remain private as an accidental-publish guard; the release staging script creates audited public manifests.

## Status

World Protocol and WorldDevKit are pre-1.0. Level 1 APIs follow semantic versioning, but breaking changes may occur in minor versions until 1.0.

## License

Code is licensed under Apache-2.0. Contributions require Developer Certificate of Origin sign-off; see `CONTRIBUTING.md`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.kobotai.co/world/readme.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.