> ## Documentation Index
> Fetch the complete documentation index at: https://docs.playflowcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLAUDE

# CLAUDE.md

# Mintlify documentation

## Working relationship

* You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
* ALWAYS ask for clarification rather than making assumptions
* NEVER lie, guess, or make up information

## Project context

* Format: MDX files with YAML frontmatter
* Config: docs.json for navigation, theme, settings
* Components: Mintlify components

## Content strategy

* Document just enough for user success - not too much, not too little
* Prioritize accuracy and usability of information
* Make content evergreen when possible
* Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
* Check existing patterns for consistency
* Start by making the smallest reasonable changes

## docs.json

* Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation

## Frontmatter requirements for pages

* title: Clear, descriptive page title
* description: Concise summary for SEO/navigation

## Writing standards

* Second-person voice ("you")
* Prerequisites at start of procedural content
* Test all code examples before publishing
* Match style and formatting of existing pages
* Include both basic and advanced use cases
* Language tags on all code blocks
* Alt text on all images
* Relative paths for internal links

## Git workflow

* NEVER use --no-verify when committing
* Ask how to handle uncommitted changes before starting
* Create a new branch when no clear branch exists for changes
* Commit frequently throughout development
* NEVER skip or disable pre-commit hooks

## Do not

* Skip frontmatter on any MDX file
* Use absolute URLs for internal links
* Include untested code examples
* Make assumptions - always ask for clarification

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository Overview

This is the documentation repository for PlayFlow Cloud, a game-server orchestration platform for multiplayer games. The documentation is built using Mintlify, a modern documentation platform optimized for developer docs.

## Common Development Commands

```bash theme={null}
# Install Mintlify CLI (required for local development)
npm i -g mintlify

# Run local development server (default port 3000)
mintlify dev

# Run on custom port
mintlify dev --port 3333

# Check for broken links
mintlify broken-links

# Troubleshooting: Reinstall dependencies if dev server fails
mintlify install
```

## Architecture & Structure

### Core Configuration

* **docs.json** - Main configuration file that defines:
  * Navigation structure (tabs, groups, pages)
  * Theme settings (colors, icons, logos)
  * SEO metadata
  * API reference integration via OpenAPI specs

### Content Organization

* **MDX Format**: All documentation uses MDX (Markdown + JSX components)
* **Frontmatter**: Each page includes metadata (title, description, icon)
* **Navigation**: Two-tab structure - "Documentation" and "API Reference"

### Key Directories

* `/api-reference/` - API reference pages
  * `introduction.mdx` - API overview, auth, rate limits, error format
  * Endpoint pages are generated from the live OpenAPI spec at `https://api.computeflow.cloud/api/doc` (configured in `docs.json`). Do not check in local OpenAPI JSON files — the Hono engine serves the canonical spec.
* `/unity/` - Unity SDK documentation with lobby system and matchmaking guides
* `/guides/` - Tutorials including WebGL deployments and migration guides
* `/fundamentals/` - Core concepts like plan instance types
* `/images/` - Documentation images and diagrams
* `/logo/` - Brand assets (light/dark mode SVGs)

### Mintlify Components

Common components used throughout the docs:

* `<Card>` and `<CardGroup>` - Feature cards with icons
* `<Info>`, `<Warning>`, `<Tip>` - Callout boxes
* `<CodeGroup>` - Multi-language code examples
* `<ResponseExample>` - API response examples

### Deployment

* Automatic deployment via GitHub App integration
* Changes to main branch auto-deploy to production
* No manual build process required

## PlayFlow Context

This documentation covers:

* **Game Server Management**: On-demand server spinning, auto-scaling
* **Matchmaking System**: ELO-based, region-aware player matching
* **Lobby System**: WebSocket-powered lobbies with chat and ready-checks
* **Unity SDK**: Primary SDK focus with comprehensive guides
* **WebGL Deployments**: Browser-based game hosting
* **Global Infrastructure**: Multi-region, multi-cloud support

## Development Guidelines

1. **MDX Best Practices**:
   * Use appropriate Mintlify components for better UX
   * Include code examples in relevant languages (Unity C#, REST API)
   * Add icons to pages via frontmatter for visual hierarchy

2. **API Documentation**:
   * API reference endpoint pages are auto-generated from the live OpenAPI spec served by the engine at `https://api.computeflow.cloud/api/doc`.
   * API contract changes happen in `playflow-core/engine/` (routes, Zod schemas). Regenerate the local snapshot with `npm run generate:openapi` for inspection.
   * Don't manually edit generated API reference pages.

3. **Navigation Updates**:
   * Modify `docs.json` to add/remove pages or reorganize structure
   * Maintain logical grouping (Getting Started → SDK → Advanced)
   * Use descriptive icons from Lucide icon set

4. **Local Development**:
   * Always run `mintlify dev` to preview changes
   * Test navigation and links before committing
   * Verify images load correctly from `/images/` directory