​

CLAUDE.md

​

Project Overview

​

Prerequisites

• Node.js 22.x — .nvmrc pins this. The Mintlify CLI (mint) currently fails on Node 25+ with “mintlify is not supported on node versions 25+”. Use nvm/fnm/etc. to pin to 22 for this repo.
• Mintlify CLI (npm i -g mint)
• Python 3.11+ (for maintenance scripts)

​

Development Commands

​

Local Development

# Start Mintlify dev server
mint dev

# Start on custom port
mint dev --port 3333

# Validate all links (add --check-anchors to also validate in-page # anchors)
mint broken-links
mint broken-links --check-anchors

# Strict build validation (exits non-zero on warnings/errors) — run before pushing
mint validate

# Update Mintlify CLI
mint update

Verification before pushing: mint validate and mint broken-links --check-anchors both pass on this repo with Node 22. After pushing to main, the Mintlify build surfaces on the HEAD commit as a GitHub check-run named “Mintlify Deployment” — monitor it with gh api repos/RhombusSystems/public-api-docs/commits/<sha>/check-runs.

​

Maintenance Scripts

python3 scripts/check-content-quality.py     # Check content quality across docs

​

Repo guardrails

• PreToolUse on Edit/Write: blocks writes to docs.json that contain manual POST|GET|PUT|DELETE|PATCH /api/... lines, with the message “Do not manually list API endpoints in docs.json. Mintlify auto-generates these from the OpenAPI spec.” This is the tooling enforcement of the “Critical Don’ts” rule below.
• PostToolUse on Edit/Write: warns (does not block) when an .mdx file is written without a leading --- frontmatter block.

​

OpenAPI sync (Mintlify-native)

"openapi": "https://api2.rhombussystems.com/api/openapi/public.json"

1. Any push to main — Mintlify auto-deploys. This is the only trigger available on the free Mintlify plan, so it’s what every other mechanism in this repo ultimately funnels through.
2. .github/workflows/openapi-sync.yml — GH Actions cron, every 6 hours — fetches the live spec, canonicalizes it (jq -S), SHA256-hashes it, and compares to .openapi-sync/last-hash.txt. When the hash changes, the workflow commits the new hash + an ISO timestamp to .openapi-sync/last-checked.txt and pushes to main as github-actions[bot]. The resulting push is what triggers Mintlify; the commit history of .openapi-sync/last-hash.txt is also the audit trail for “when did the upstream spec change.” Manual runs are available via GitHub UI → Actions → “openapi-sync” → Run workflow.

Note on the Mintlify Trigger Deployment API: on paid plans you can POST https://api.mintlify.com/v1/project/update/{projectId} with a mint_… token to bypass git. We’re on the free plan, so this isn’t wired up — the GH Actions workflow above uses a commit-push as its rebuild signal instead.

• Tag descriptions, endpoint grouping, x-mint metadata, and x-codeSamples should live in the upstream public.json itself. This repo does not transform the spec.
• The changelog (changelog.mdx) is hand-written. When meaningful API changes ship, add an <Update> entry by hand in the same format as existing entries.
• The only files this repo commits about the spec are .openapi-sync/last-hash.txt and .openapi-sync/last-checked.txt. Do not commit api-reference/openapi.json — Mintlify reads the live URL; a committed copy will silently go stale.

​

Localization (English + Spanish)

• English source of truth: index.mdx, implementations/..., low-code-no-code/..., websocket/..., webhooks.mdx, etc. (root layout unchanged from before localization).
• Spanish translations: es/index.mdx, es/implementations/..., es/low-code-no-code/..., es/websocket/..., es/webhooks.mdx, etc.
• Scope of Spanish coverage: full parity for all Guides + Integrations content. Every guide page has an es/ mirror. The API Reference tab is English-only because the upstream OpenAPI spec is English; the Spanish navigation in docs.json deliberately omits the API Reference tab so users don’t 404.
  • Translated (have an es/ mirror): every root guide page (index, oauth-authentication, resources, rhombus-cli, partner-api-calls, documentation-mcp, changelog, rate-limits, webhooks, rhombus-mcp, claude-code-plugins) plus everything under implementations/, low-code-no-code/, and websocket/.
  • English-only (no es/ mirror): only api-reference/overview.mdx, snippets/, and the OpenAPI spec / API Reference tab.
  • When you add a new guide page (anything other than the API Reference / snippets), you MUST also add its es/ mirror and register it under navigation.languages[1].tabs in docs.json. Every guide page is in the Spanish set now.
• Disclaimer on every Spanish page: each Spanish file opens (immediately after frontmatter) with a <Note> callout disclosing that the translation was machine-generated and inviting feedback. Preserve this disclaimer when editing Spanish files.
• Parity rule: when you edit or add an English MDX page that’s covered by the Spanish set, you must also update the matching es/... file. Mintlify does NOT fall back from Spanish to English — a missing Spanish page renders as a 404 for Spanish users. If you add a brand-new English page and it belongs in the Spanish navigation, also add the Spanish version and reference it under navigation.languages[1].tabs in docs.json.
• In-page anchor links in Spanish pages: Mintlify generates heading slugs from the rendered (translated) heading text, keeping accents and lowercasing (e.g. ## Configuración del backend → #configuración-del-backend). So when a Spanish page links to one of its own headings, the anchor must use the translated slug, not the English one. Copying English anchors verbatim (#backend-setup) produces broken links — catch these with mint broken-links --check-anchors.
• Out of Spanish scope (intentional): api-reference/overview.mdx, snippets/, the OpenAPI spec, images. These remain English-only in v1.
• Disclaimer text (verbatim — keep consistent across files):
  <Note>
  Esta página fue traducida automáticamente. Si encuentra errores o tiene sugerencias, [contáctenos](mailto:support@rhombus.com).
  </Note>
  

​

Repository Structure

/ (root - run mint dev from here)
├── docs.json              # Mintlify config (3 tabs: Guides, Integrations, API Reference)
├── *.mdx                  # Root-level pages: index, changelog, resources, rate-limits, webhooks,
│                          #   oauth-authentication, rhombus-cli, rhombus-mcp, documentation-mcp, claude-code-plugins
├── api-reference/         # API documentation
│   └── overview.mdx       # Hand-written API reference landing page (the spec is fetched live from upstream)
├── implementations/       # Implementation guides (Cameras, Access Control, Audio, etc.)
├── low-code-no-code/      # No-code/low-code integration guides (Zapier, Make.com, N8N)
├── websocket/             # WebSocket documentation (overview, auth, STOMP protocol, events, lifecycle, troubleshooting, code examples)
├── snippets/              # Reusable React components (changelog-author.jsx)
└── scripts/               # check-content-quality.py (Python linter) +
                           # developer-guide-rate-limits-and-webhooks.md
                           # (hand-written reference draft that overlaps the
                           # published rate-limits.mdx and webhooks.mdx — kept
                           # for historical context, NOT part of the build)

​

Navigation Structure

1. Guides: Getting Started (index, resources, rhombus-cli, oauth-authentication, rate-limits, changelog) + Implementation Guides by topic (Cameras, Access Control, Alarm Monitoring, IoT Sensors, Storage & Backup, Identity & Access) + Real-time Events (Webhooks, WebSocket)
2. Integrations: Low code / no code platforms (Zapier, Make, n8n) + AI & LLMs (Documentation MCP, Rhombus API MCP, Claude Code Plugins)
3. API Reference: Complete API endpoint documentation with live testing (auto-generated from OpenAPI spec)

​

Identity guides come in a pair — don’t conflate them

​

Architecture

​

docs.json Structure

• Format: JSON with nested navigation groups; the API Reference tab uses Mintlify auto-generation from the OpenAPI spec
• API endpoints: Auto-generated by Mintlify from the live upstream spec at https://api2.rhombussystems.com/api/openapi/public.json — do not manually list endpoints
• Modifying API content: Enrich the upstream spec itself (tags, descriptions, x-mint metadata, x-codeSamples) — those changes are owned by the API team, not this repo. Navigation is auto-generated.

​

Content Types

1. Hand-written MDX: Implementation guides, quickstart, MCP documentation
2. Auto-generated API docs: All endpoint pages under API Reference tab (Mintlify generates these from the OpenAPI spec — do not manually create)
3. Auto-served AI files: llms.txt, llms-full.txt, and skill.md hosted by Mintlify at the site root

​

Key Files

• docs.json — Main Mintlify config. Schema: https://mintlify.com/docs.json
• api-reference/overview.mdx — Hand-written API reference landing page. The spec itself is fetched live from https://api2.rhombussystems.com/api/openapi/public.json via the openapi field in docs.json — there is no committed spec.
• custom.css — Custom styling overrides
• VERSIONING.md — Plan for introducing API versioning when breaking changes occur
• AGENTS.md — WARP-equivalent of this file. Overlaps heavily; when you change guidance here that also applies to other agents (commands, structure, conventions), consider mirroring it in AGENTS.md. Claude-specific behaviors (memory, skills, working relationship) stay here only.
• README.md — Public-facing repo intro. Keep stats/links accurate; don’t duplicate working guidance from this file.

​

API-Specific Conventions

• Base URL: https://api2.rhombussystems.com
• Media URL: https://media.rhombussystems.com (for media/streaming endpoints)
• Authentication headers: x-auth-scheme: api-token + x-auth-apikey: YOUR_API_KEY
• Endpoint grouping: By service area (Access Control, Camera, Climate, etc.) with subgroups: Create & Add, Get & Find, Update & Modify, Delete & Remove, Other Operations

​

Working Relationship

• Push back on ideas when it leads to better documentation - cite sources
• ALWAYS ask for clarification rather than making assumptions
• NEVER lie, guess, or make up anything
• Search for existing content before adding new pages to avoid duplication
• Start by making the smallest reasonable changes

​

Content Standards

​

Frontmatter Requirements

---
title: "Clear, descriptive page title"
description: "Concise summary for SEO/navigation"
icon: "icon-name"  # Optional
---

​

Writing Standards

• Second-person voice (“you”)
• Active voice and present tense
• Prerequisites at start of procedural content
• Test all code examples before publishing
• Match style and formatting of existing pages
• Include both basic and advanced use cases
• Language tags on all code blocks
• Alt text on all images
• Relative paths for internal links
• Start page content with h2 headings (h1 is generated from frontmatter title)

​

Code Example Requirements

• Complete, runnable examples users can copy
• Proper error handling and edge cases
• Realistic data, not placeholders
• Include expected outputs
• Never include real API keys or secrets
• Always include authentication in code examples (x-auth-apikey header)

​

Component Selection

• Steps: Sequential instructions and procedures
• Tabs: Platform-specific content or alternatives
• CodeGroup: Same concept in multiple languages
• Accordions: Progressive disclosure
• RequestExample/ResponseExample: API endpoint docs
• ParamField: API parameters
• ResponseField: API responses
• Expandable: Nested properties

​

Git Workflow

• NEVER use --no-verify when committing
• NEVER skip or disable pre-commit hooks
• Ask how to handle uncommitted changes before starting
• Create a new branch when no clear branch exists
• Commit frequently throughout development

​

Critical Don’ts

• Manually list API endpoints in docs.json — Mintlify auto-generates these from the OpenAPI spec
• Manually create endpoint pages under API Reference — Mintlify auto-generates these
• Add local llms.txt or llms-full.txt files — Mintlify auto-serves these (local files override and go stale)
• Skip frontmatter on any MDX file
• Use absolute URLs for internal links
• Re-introduce a local OpenAPI enrichment pipeline. Tag descriptions, x-mint metadata, and x-codeSamples belong in the upstream public.json spec, not in transform scripts in this repo.
• Commit api-reference/openapi.json as a local file. Mintlify reads the live URL; a committed copy will silently go stale.

​

Source of truth for verifying guide content

​

The OpenAPI spec is not complete for every flow

• https://auth.rhombussystems.com/oauth/token — OAuth token exchange (not in spec)
• https://console.rhombussystems.com/login?type=oauth&... — OAuth authorization URL (not in spec)
• POST /api/integrations/org/submitApiTokenApplication — API-key minting (the spec only has the deprecated /api/integrations/submitApiTokenApplication without /org/)
• POST /api/partner/submitApiTokenApplication — partner-side equivalent (not in spec)