Skip to main content

​
AGENTS.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

​
Project Overview

Rhombus Developer Documentation site built with Mintlify. Documents the complete Rhombus Systems API (all endpoints) with auto-generated content from an OpenAPI spec that syncs nightly from production.

​
Development Commands

# Start local dev server (run from repo root where docs.json lives)
mint dev

# Start on custom port
mint dev --port 3333

# Validate all links
mint broken-links

# Update Mintlify CLI
mint update

# Update OpenAPI spec from production API
./scripts/update-openapi.sh

# Update AI context files (llms.txt, llms-full.txt)
python3 scripts/update-llms-files.py

# Generate endpoint docs from OpenAPI spec
python3 scripts/generate-endpoint-docs.py

# Update docs.json navigation structure
python3 scripts/update-docs-navigation.py
Prerequisites: Node.js 19+, Mintlify CLI (npm i -g mint), Python 3.11+ (for scripts).

​
Architecture

​
Content lives at the root

All MDX files and docs.json live in the repo root — there is no docs/ subdirectory. mint dev must be run from the root.

​
Content types

  1. Hand-written MDX — implementation guides, quickstart, MCP docs (index.mdx, implementations/, low-code-no-code/)
  2. Auto-generated API docs — all endpoint pages under the API Reference tab, driven entirely by api-reference/openapi.json
  3. AI context files — llms.txt and llms-full.txt, regenerated weekly by GitHub Actions

​
docs.json — the central config

  • Controls all navigation, theming, and site behavior
  • 3 tabs: Guides, Integrations, API Reference
  • API endpoints are referenced via the openapi key pointing to api-reference/openapi.json — do not manually create endpoint pages
  • Mintlify auto-generates all API Reference endpoint pages from the OpenAPI spec

​
Localization

Translated content mirrors the English structure in de/, es/, zh/ directories. All English content lives in root-level files and implementations/.

​
Reusable snippets

Shared MDX content goes in snippets/ — includes changelog-author.jsx React component.

​
Automation (GitHub Actions)

  • update-openapi.yml — Nightly at midnight UTC: fetches latest OpenAPI spec, detects changes, auto-generates changelog entries, commits to main
  • update-llms-files.yml — Weekly (Sundays 1 AM UTC) + on push to relevant files: regenerates llms.txt and llms-full.txt
Do not modify these workflows without understanding the full pipeline (change detection → changelog generation → commit with retry logic).

​
Scripts (scripts/)

  • update-openapi.sh — Manual OpenAPI spec fetch with validation and backup
  • update-llms-files.py — Generates AI context files from project structure and OpenAPI spec
  • detect_openapi_changes.py — Compares old/new specs, produces a change report JSON
  • generate_changelog_entry.py — Converts change report into MDX changelog entry
  • insert_changelog_entry.py — Inserts generated entry into changelog.mdx
  • generate-endpoint-docs.py — Generates endpoint documentation from OpenAPI spec
  • update-docs-navigation.py — Updates navigation structure in docs.json
  • add-service-level-navigation.py / improve-endpoint-navigation.py — Navigation enhancement utilities

​
Working Standards

  • Always ask for clarification rather than making assumptions
  • Search for existing content before adding new pages to avoid duplication
  • Start by making the smallest reasonable changes
  • Push back on ideas when it leads to better documentation — cite sources
  • Never use --no-verify or skip pre-commit hooks

​
MDX page requirements

Every .mdx file must have YAML frontmatter with at least title and description. Use second-person voice (“you”). Match style and formatting of existing pages.

​
Mintlify components

  • Steps — sequential procedures
  • Tabs — platform-specific alternatives
  • CodeGroup — same concept in multiple languages
  • Accordions — progressive disclosure
  • RequestExample / ResponseExample — API endpoint docs
  • ParamField / ResponseField / Expandable — API parameter and response documentation
  • Callouts: <Note>, <Tip>, <Warning>, <Info>, <Check>

​
API-specific conventions

  • All API requests use base URL https://api2.rhombussystems.com
  • Authentication headers: x-auth-scheme: api-token + x-auth-apikey: YOUR_API_KEY
  • Media endpoints use https://media.rhombussystems.com
  • Code examples should be complete, runnable, with realistic data
  • Use relative paths for internal links, absolute URLs only for external