diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..99a57ce
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,38 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+A hand-authored OpenAPI 3.1.0 specification for **The Lacuna Expanse** game API, written in TypeScript and assembled into a plain JS spec object that's rendered in-browser with Swagger UI. This repo is not a server or client implementation — it only defines and previews the API contract.
+
+The spec describes a *new* `/v2` layout of an existing API (not the original), and per `src/spec.ts`'s `info.description` is intended only for use with the "TLE Community" codebase.
+
+## Commands
+
+- `npm start` — runs `vite`, launching a dev server on port 3000 that renders the current spec via Swagger UI for visual inspection. This is the only script defined and the primary way to check your work.
+
+There is no lint, test, build, or spec-validation tooling in this repo (no `tsconfig.json`, no ESLint config, no CI). Prettier is configured (`.prettierrc.json`) and applied via VS Code's format-on-save (`.vscode/settings.json`); there's no `format` script, so run `npx prettier --write .` if formatting from the CLI.
+
+## Architecture
+
+**Boot path:** `index.html` → `index.ts` calls `SwaggerUI({ dom_id: '#main', spec })` using the assembled spec object from `src/spec.ts`.
+
+**Spec assembly** (`src/spec.ts`): builds the top-level OpenAPI document — `{ openapi, info, servers, paths, components }` — importing `paths` from `src/spec/paths.ts` and `components` from `src/spec/components.ts`.
+
+**Paths** are composed per resource, then merged:
+- `src/spec/paths.ts` — `export const paths = { ...empire, ...body }`. To add a new resource group, create a file under `src/spec/paths/` exporting a named object keyed by full path strings, then spread it in here.
+- `src/spec/paths/empire.ts` and `src/spec/paths/body.ts` define the actual endpoints. All are `post`, JSON-RPC style (matching the underlying game API).
+
+**Reuse helpers** (`src/spec/chunks.ts`) — every path definition composes these rather than writing raw OpenAPI objects:
+- `security()` — adds the token-auth requirement
+- `requestBodySchema(schema)` — builds a `requestBody`
+- `response200(description, resultSchema)` — standard `{id, jsonrpc, result}` 200 response
+- `response500()` — standard RPC error response (`$ref`s `components.schemas.rpc_error`)
+- `statusSchema()` — the common `{server, empire, body}` status object
+
+Per the file's own comment, these helpers intentionally go beyond strict OpenAPI-authoring convention to keep the TypeScript source DRY — the final emitted spec is still plain OpenAPI JSON.
+
+**Shared schemas** (`src/spec/components.ts`): `securitySchemes.tokenHttpAuthentication` (custom `Authorization: Token <session_id>` header) and `schemas.{body_status, empire_status, rpc_error, server_status}`. `rpc_error` enumerates the game's JSON-RPC error codes (1000–1200) with their meanings as inline comments. Reuse these via `$ref: '#/components/schemas/...'` instead of redefining shapes inline in a path.
+
+**`src/auto-captured-data.ts`** (~14k lines) is temporary reference material captured via [OpenAPI Dev Tools](https://github.com/AndrewWalsh/openapi-devtools) from live traffic against the *original* (non-`/v2`) API. It is not imported anywhere and not part of the emitted spec — treat it purely as source material to consult when hand-authoring new endpoints under `src/spec/paths/`, not as output to edit or keep in sync.