CLAUDE.md — Mintlify Documentation
Core Principles
- State your assumptions. If uncertain, ask. Never invent field names, steps, or behavior. Stop and ask before writing anything unconfirmed.
- Minimum docs that solves the problem. Write the least amount of content that answers the reader’s question. No filler, no pre-emptive coverage of edge cases that weren’t asked for.
- Touch only what you must. Editing one section does not licence touching others. Leave pre-existing prose you did not write as-is unless it directly contradicts a fact you’re fixing.
- Transform tasks into verifiable goals. Before writing, state what “done” looks like — e.g. “the reader can complete X from this page alone.” Use that to decide what to include and what to cut.
Content Accuracy
- Only document what is confirmed from code, the OpenAPI spec, or screenshots provided by the user.
- Enum and union values require a schema lookup. Before documenting any list of allowed values (enum, union, string literal), locate and read the actual schema file in the codebase. Do not infer values from upstream specs (e.g. OpenAI, Anthropic) — orq schemas are generated subsets that may expose fewer values. If the schema file cannot be found, omit the value list and note it as TBD.
- Never state a count of supported models without reading it from the actual data source. Omit the count and link instead if unsure.
- Do not add “Coming Soon” sections unless explicitly instructed.
Writing Style
- NEVER use em dashes (—) in content you write or edit. After writing alt text or captions, grep for
—before moving on. - Never use hyphens as separators (
**Term** - description). Use a colon:**Term**: description. - Bold all product name mentions: Orq.ai, AI Gateway, AI Chat.
- Capitalize product entity names: Evaluators, Identities, Deployments, Agents, Prompts, Threads.
- Use imperative voice. Never “you” or “your” (
"Set the filters", not"Set your filters"). Only flag or fix “you/your” in text you are writing or editing in this PR — do not touch pre-existing prose outside the PR’s scope. - Use
<Icon />components instead of describing icons in prose. - No warnings or disclaimers about AI making mistakes.
Alt Text
- Every image needs alt text describing what it actually shows — not the section heading or release label.
- Each image on the same page must have a distinct alt. Never copy-paste from an adjacent image.
- Derive alt from surrounding prose, the
Framecaption, and the filename. If none give enough context, ask. - No em dashes in alt text or captions you write.
- After adding or editing images, grep the file for repeated alt strings before moving on — copy-paste errors don’t show in rendered output.
Page titles
For title conventions (when to use plain noun phrases vs. the “Product | Page Name” pattern), see.claude/skills/mintlify-writer/references/page-structure.md#frontmatter-rules.
Mintlify Components
- Never place headings (
##,###,####) inside<Tab>components. Use bold text or prose structure inside tabs instead.
Enterprise Features
Every page for an Enterprise-only feature must include this badge immediately after the frontmatter:<Note> or other component — the badge is the only approved pattern.
Docs review — feature folder changes
When a PR or commit modifies source files for a named feature, check whetherdocumentation/mintlify/docs/ has a corresponding page. If it does, flag (do not auto-fix):
- Structure — required sections present and in order? See
.claude/skills/mintlify-writer/references/page-structure.md. - Code snippets — correct label case? See
.claude/skills/mintlify-writer/references/code-conventions.md. - Sync — is this page in the sync map? If so, note the paired page may also need updating. See
.claude/skills/mintlify-writer/references/sync-map.md.
Collaboration
- Verify claims before accepting them. Push back with evidence or honest uncertainty.
- Never present opinions as facts.