# 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.