> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.rhombus.community/llms.txt
> Use this file to discover all available pages before exploring further.

# CLAUDE

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is the official Rhombus API documentation site built with Mintlify. It documents all API endpoints with auto-generated content fetched live from the production OpenAPI spec on every Mintlify build.

**Live site**: [https://api-docs.rhombus.community/](https://api-docs.rhombus.community/)
**API source**: [https://api2.rhombussystems.com/api/openapi/public.json](https://api2.rhombussystems.com/api/openapi/public.json)

The Rhombus API is currently **unversioned** — a single version (`"version": "1.0"`) serves all consumers. See `VERSIONING.md` for the plan to introduce versioning when breaking changes occur.

## 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

All commands should be run from the root directory where `docs.json` lives.

### Local Development

```bash theme={null}
# 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

**Content quality**:

```bash theme={null}
python3 scripts/check-content-quality.py     # Check content quality across docs
```

### Repo guardrails

`.claude/settings.json` is checked in and installs two hooks that fire for every Claude instance working in this repo. Expect them; don't try to disable them:

* **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)

`docs.json` references the live upstream spec directly:

```json theme={null}
"openapi": "https://api2.rhombussystems.com/api/openapi/public.json"
```

Mintlify fetches the spec on every build, so there is **no local enrichment pipeline** in this repo. Two triggers cause a Mintlify rebuild:

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.

**Implications:**

* 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)

This site is bilingual. English is the default and lives at the repo root. Spanish lives in a parallel `es/` directory with **mirrored filenames and subdirectory structure**, per [Mintlify's i18n guide](https://www.mintlify.com/docs/guides/internationalization).

* **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):
  ```mdx theme={null}
  <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)
```

**Important**: All published Mintlify content (MDX files, `docs.json`, `api-reference/`) lives at the repo root — there is no `docs/` subdirectory in the published site. A local `docs/` directory may exist as scratch space (e.g., `docs/superpowers/` for the superpowers skill, or a stray `docs/llms.txt`); it's not part of the Mintlify build and should not be referenced from navigation.

### Navigation Structure

The documentation uses a 3-tab navigation system configured in `docs.json`:

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

Two distinct identity guides exist and target completely different audiences. Keep them cross-linked but separate:

| File                                                                                    | Audience                       | Purpose                                                                                                      |
| --------------------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `oauth-authentication.mdx` (Guides → Getting Started)                                   | Third-party app developers     | "Sign in with Rhombus" — OAuth 2.0 + PKCE, Rhombus as IdP for external apps. Same flow the Rhombus CLI uses. |
| `implementations/saml-sso-provisioning.mdx` (Implementation Guides → Identity & Access) | Rhombus admins / ops engineers | Programmatically configure SAML SSO + SCIM provisioning so employees sign in via corporate IdP.              |

If a user asks for "SSO docs" without qualifier, ask which side they want before touching either file. The two have bidirectional "What this isn't" callouts and Next Steps cards — preserve 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](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

Every MDX file must have:

```yaml theme={null}
---
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

Available callouts: `<Note>`, `<Tip>`, `<Warning>`, `<Info>`, `<Check>`

## 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

When verifying that a guide's endpoints, request/response fields, auth, or behavior are correct, the **primary source of truth is the private enterprise git server `git2.rhombus.corp`** (org `rhombus`), NOT the public `github.com/RhombusSystems` repos. The public repos are the customer-facing SDK/example repos the guides link to; the enterprise repos are the actual backend. The `gh` CLI is authenticated to both hosts — query the enterprise server with `gh api --hostname git2.rhombus.corp repos/rhombus/<repo>/contents/<path>` (and `gh api --hostname git2.rhombus.corp "search/code?q=...+org:rhombus"`).

Key enterprise repos: `rhombus-cloud-webservice` (the "Main API server" — endpoints, auth headers, request/response schemas, the OAuth/API-key-minting endpoints below), `rhombus-cloud-websockets` (`/topic/change` payloads, STOMP, handshake auth), `rhombus-cloud-webhooks`, `rhombus-cloud-kconsumer-alertmonitoring` / `-sqsconsumer-alertmonitoring` (alarm monitoring), `rhombus-cloud-kconsumer-accesscontrol` + `rhombus-accesscontrol-firmware` (access control), `rhombus-node-private-mcp`, `rhombus-cloud-video`.

**Guardrail:** the enterprise code is internal/proprietary. Verify behavior against it, but only publish public-API surface — never leak internal hostnames, service names, internal-only endpoints, or queue/infra topology into the public docs. Cross-check against the live OpenAPI spec, which is the public surface.

## The OpenAPI spec is not complete for every flow

The live spec at `https://api2.rhombussystems.com/api/openapi/public.json` covers most of the Rhombus API, but **not all of it**. Some flows — particularly the OAuth browser-login flow used by the Rhombus CLI and third-party apps — require endpoints on different hosts that are not exposed in the spec:

* `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)

When documenting auth, identity, or multi-host flows, the **Rhombus CLI source is the authoritative secondary reference**: [https://github.com/RhombusSystems/rhombus-cli](https://github.com/RhombusSystems/rhombus-cli) — in particular `cmd/login.go` walks the full OAuth flow. The `oauth-authentication.mdx` guide was written from that source and should be updated alongside any CLI changes.

Don't invent endpoints. If a flow isn't in the spec and the CLI doesn't exercise it (e.g., OAuth refresh-token exchange), document the supported alternative rather than guessing.