Skip to main content

​
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 (the old /inference-api/reference/models URL redirects there via docs.json).

​
⚠️ Two different hosts — the API is api.flex.ai, the dashboard is tokens.flex.ai

Getting these the wrong way round is the easiest mistake to make on this site, because tokens.flex.ai legitimately appears in both roles historically. tokens.flex.ai/v1/* keeps serving the identical API surface unchanged and indefinitely — customers have it hardcoded, and nothing about it is deprecated. The change is only in what we advertise, so never “fix” a customer’s existing tokens.flex.ai/v1 usage, and never rewrite a dashboard link to api.flex.ai (it does not serve the browser app). The OpenAPI servers: list carries both, api.flex.ai first — that ordering is what makes generated SDKs and “Try it” default to the canonical host without breaking anyone who pinned the original.

​
⚠️ Never reference staging

These are customer-facing docs. 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.