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/, …).

​
⚠️ 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).

​
⚠️ 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 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 Inference API tab 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.