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

# 2026 04 09 autonomous api docs design

# Autonomous API Documentation Pipeline

**Date:** 2026-04-09
**Status:** Approved
**Goal:** Make the Rhombus API documentation fully autonomous — new endpoints appear automatically with enriched metadata, SEO-optimized, and developer-friendly navigation — with zero manual intervention.

## Context

The Rhombus Developer Documentation site (built with Mintlify) documents 846+ API endpoints auto-generated from an OpenAPI spec that syncs nightly from production. The current setup manually lists every endpoint in `docs.json` (making it 107KB+), requiring a `build-api-navigation.py` script to rebuild navigation on every sync. Several other scripts exist to generate files that Mintlify now handles natively.

## Design

### 1. Simplified API Reference Navigation

**Change:** Replace the entire API Reference tab's 800+ manual endpoint entries in `docs.json` with Mintlify's auto-generation.

**Before (107KB+ docs.json):**

```json theme={null}
{
  "tab": "API Reference",
  "groups": [
    {
      "group": "Overview",
      "pages": ["api-reference/overview"]
    },
    {
      "group": "Cameras & Video",
      "openapi": "api-reference/openapi.json",
      "pages": [
        {
          "group": "Camera management",
          "pages": [
            "POST /api/camera/calibrateFloorplanProjection",
            "POST /api/camera/createCustomFootageSeekpoints",
            // ... 800+ more entries
          ]
        }
      ]
    }
  ]
}
```

**After (\~3KB docs.json):**

```json theme={null}
{
  "tab": "API Reference",
  "groups": [
    {
      "group": "Overview",
      "pages": ["api-reference/overview"]
    }
  ],
  "openapi": "api-reference/openapi.json"
}
```

Mintlify auto-generates all endpoint pages, groups them by OpenAPI tags, and builds sidebar navigation. The hand-written `api-reference/overview.mdx` stays as the landing page.

### 2. Simplified Nightly Sync Pipeline

**Change:** Remove navigation rebuild step. Add enrichment step.

**New pipeline (GitHub Action):**

1. Fetch spec from `https://api2.rhombussystems.com/api/openapi/public.json`
2. `detect_openapi_changes.py` — compare old/new specs, produce change report JSON
3. Copy new spec to `api-reference/openapi.json`
4. Run enrichment scripts (in order):
   * `enrich-openapi-tags.py` — ensure all tags have descriptions (drives Mintlify grouping)
   * `inject-xmint-decorators.py` — add `x-mint` metadata for SEO titles/descriptions
   * `add-code-samples.py` — add `x-codeSamples` to key endpoints
5. `generate_changelog_entry.py` + `insert_changelog_entry.py` — add changelog entry
6. Create PR on `automated/openapi-sync` branch

On merge, Mintlify auto-deploys and regenerates `llms.txt`, `llms-full.txt`, `skill.md`, and `sitemap.xml`.

### 3. OpenAPI Spec Enrichment

The OpenAPI spec's quality now directly determines navigation grouping, page titles, descriptions, and SEO. The enrichment scripts become the autonomous "value-add" layer:

* **`enrich-openapi-tags.py`** — Every tag gets a clear `description`. Tags drive Mintlify's auto-generated sidebar groups.
* **`inject-xmint-decorators.py`** — Adds `x-mint: metadata` to endpoints for SEO-optimized titles, descriptions, and keywords.
* **`add-code-samples.py`** — Adds `x-codeSamples` for richer endpoint pages with multi-language examples.

These run automatically in the nightly pipeline, so every new endpoint gets enriched metadata the same night it appears.

### 4. AI & Discovery Files

Mintlify auto-hosts these at the site root — no repo files or scripts needed:

* `https://api-docs.rhombus.community/llms.txt` — page index for AI tools
* `https://api-docs.rhombus.community/llms-full.txt` — full docs content for AI
* `https://api-docs.rhombus.community/skill.md` — capability summary for AI agents
* `https://api-docs.rhombus.community/sitemap.xml` — search engine sitemap

The `update-llms-files.py` script and local `llms.txt`/`llms-full.txt` files are retired.

### 5. SEO Configuration

**Add to `docs.json`:**

```json theme={null}
"seo": {
  "metatags": {
    "og:site_name": "Rhombus Developer Documentation",
    "og:type": "website",
    "twitter:card": "summary_large_image",
    "robots": "index, follow",
    "language": "en",
    "category": "Technology",
    "keywords": "Rhombus API, security API, camera API, access control API, IoT sensors API, video surveillance, developer documentation"
  },
  "indexing": "all"
}
```

Hand-written MDX pages should include `keywords` in frontmatter for page-level SEO. Auto-generated API pages get SEO from the spec's `summary`, `description`, and `x-mint: metadata`.

## Scripts

### Retire (7 scripts)

| Script                            | Reason                                          |
| --------------------------------- | ----------------------------------------------- |
| `build-api-navigation.py`         | Mintlify handles navigation auto-generation     |
| `generate-endpoint-docs.py`       | Mintlify auto-generates endpoint pages          |
| `update-docs-navigation.py`       | Navigation is now static + auto-generated       |
| `add-service-level-navigation.py` | Navigation helper, no longer needed             |
| `improve-endpoint-navigation.py`  | Navigation helper, no longer needed             |
| `update-llms-files.py`            | Mintlify auto-serves llms.txt and llms-full.txt |

### Keep (8 scripts)

| Script                        | Role                                             |
| ----------------------------- | ------------------------------------------------ |
| `update-openapi.sh`           | Manual spec fetch with validation & backup       |
| `detect_openapi_changes.py`   | Change detection for changelog & PR descriptions |
| `enrich-openapi-tags.py`      | Tag quality for auto-grouping                    |
| `inject-xmint-decorators.py`  | x-mint metadata for SEO                          |
| `add-code-samples.py`         | Code samples on endpoints                        |
| `generate_changelog_entry.py` | Change report to MDX changelog entry             |
| `insert_changelog_entry.py`   | Insert entry into changelog.mdx                  |
| `check-content-quality.py`    | Content quality checks for hand-written pages    |

## Files to Remove

* `llms.txt` — Mintlify auto-serves this
* `llms-full.txt` — Mintlify auto-serves this
* 7 retired scripts from `scripts/`

## Files to Modify

* `docs.json` — Replace API Reference tab, add SEO block
* `.github/workflows/sync-openapi.yml` — Simplified pipeline with enrichment step
* `CLAUDE.md` — Update to reflect new architecture
* `.claude/skills/openapi-sync/SKILL.md` — Update to reflect simplified pipeline

## Guides & Integrations Tabs

No changes in this phase. These will be improved separately in a future iteration.