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

# CLAUDE

# CLAUDE.md — flexaihq/docs

This is the FlexAI documentation site (Mintlify, published at `https://docs.flex.ai`). Config is `docs.json`; content is `.mdx` under the section folders (`getting-started/`, `core-services/`, `platform-services/`, `cli/`, `blueprints/`, `inference-api/`, …).

## Voice & tone

All published docs follow the house voice & tone guide at `.github/VOICE-AND-TONE.md`: **capability-first** framing, benefit-before-caveat, second person, confident-not-apologetic. Read it before writing or reviewing a page — tone work never changes a fact, command, limit, or URL.

## ⚠️ `inference-api/` is synced from `flexaihq/token-service` — prose round-trips, generated files don't

The `inference-api/` + `snippets/inference-api/` trees are **synced from `flexaihq/token-service`** by its `.github/workflows/sync-docs.yaml` (the *forward* sync), which opens/updates the PR on branch `auto/sync-token-service-docs`. The source-of-truth is `token-service/docs/content/`.

**Prose ROUND-TRIPS — safe to edit here, including in the Mintlify UI.** Hand-written pages — `overview.mdx`, `quickstart.mdx`, `guides/*.mdx`, and `reference/*.mdx` *except* `errors.mdx` — are mirrored back to `token-service/docs/content/` by `reverse-sync-prose.yaml` whenever they change on `main`. So a Mintlify edit committed to `main` publishes immediately **and** opens a reflect-back PR upstream (`auto/sync-docs-prose`) for engineers to review. `docs/content/` stays canonical; the next forward sync is a no-op. (Publish-first: the Mintlify editor must be configured to commit to `main`.)

**Generated files NEVER round-trip — never edit them anywhere:**

* `inference-api/reference/errors.mdx` — rendered by `scripts/generate-docs.py`
* `inference-api/openapi.yaml` — copied from `token-service/docs/openapi.yaml`
* `snippets/inference-api/billing-constants.mdx` — generated from backend constants

`guard-synced-docs.yaml` fails any PR that touches the **generated** files above (prose PRs pass). To change generated content, edit the upstream source/generator in `token-service`. Full playbook: `token-service/docs/authoring-inference-api-docs.md`.

* There is **no model catalog page** — the public model list lives at [https://flex.ai/models](https://flex.ai/models) (the old `/inference-api/reference/models` URL redirects there via `docs.json`).

## ⚠️ Never reference staging — published docs use `tokens.flex.ai` only

These are **customer-facing** docs. The production Inference API domain is `https://tokens.flex.ai`. The staging surface `tokens.flexsystems.ai` is **internal** and must **never** appear in any published page — no base URLs, examples, links, or OpenAPI servers.

* This applies site-wide (every published `.mdx` and `inference-api/openapi.yaml`), not just the Token Factory (Inference API) tab.
* For `inference-api/**` content, the canonical home is **upstream** in `flexaihq/token-service` (`docs/content/`, `docs/openapi.yaml`, or the generator). Generated files edited here are overwritten by the sync; prose edits round-trip upstream — so never introduce a staging URL either way. Token-service's `sync-docs.yaml` guard blocks a staging URL from reaching the synced payload, and `reverse-sync-prose.yaml` re-checks prose on the way back.
* `no-staging-refs.yaml` is the receiver-side backstop: it fails any PR (and push to `main`) whose published content contains `tokens.flexsystems.ai`.

## `docs.json` (navigation) IS owned here

The nav is **not** synced — it lives only in this repo. So:

* Adding/removing/reordering an Inference API page (e.g. a new guide) is a manual edit to `docs.json` **here**, paired with the page existing upstream (the sync delivers the `.mdx`, `docs.json` makes it appear).
* The Token Factory tab (the Inference API) is the primary tab; `Platform` is second. Its `openapi` key points at `inference-api/openapi.yaml`.

## Everything else

All other sections (`platform`, `core-services`, `cli`, `blueprints`, `console`, `faq`, `best-practices`, …) are **authored directly in this repo** — edit the `.mdx` here normally. Only the `inference-api/` + `snippets/inference-api/` trees are externally owned.