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

# Autonomous API Documentation Pipeline — Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Make the Rhombus API docs fully autonomous — Mintlify auto-generates all API endpoint pages from the OpenAPI spec, the nightly sync enriches and publishes new endpoints with zero manual intervention.

**Architecture:** Replace 800+ manual endpoint entries in `docs.json` with Mintlify's native `openapi` auto-generation on the API Reference tab. Simplify the GitHub Action pipeline to: fetch → detect changes → enrich spec → changelog → PR. Remove retired scripts and local AI files that Mintlify now auto-serves.

**Tech Stack:** Mintlify, OpenAPI 3.0, GitHub Actions, Python 3.11+

**Spec:** `docs/superpowers/specs/2026-04-09-autonomous-api-docs-design.md`

***

### Task 1: Simplify the API Reference tab in docs.json

**Files:**

* Modify: `docs.json` (lines 169-1472 — the entire API Reference tab)

This is the core change. Replace 1300+ lines of manually listed endpoints with Mintlify's auto-generation.

* [ ] **Step 1: Back up the current docs.json**

```bash theme={null}
cp docs.json docs.json.backup
```

* [ ] **Step 2: Replace the API Reference tab**

In `docs.json`, find the API Reference tab starting at line 169:

```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",
            ... hundreds more entries ...
```

Replace the **entire** API Reference tab object with:

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

The key change: `"openapi": "api-reference/openapi.json"` is now a top-level property on the tab (not nested inside groups). This tells Mintlify to auto-generate all endpoint pages and navigation from the spec. The Overview group with the hand-written `api-reference/overview.mdx` page is preserved.

* [ ] **Step 3: Validate the JSON is well-formed**

```bash theme={null}
python3 -c "import json; json.load(open('docs.json')); print('Valid JSON')"
```

Expected: `Valid JSON`

* [ ] **Step 4: Validate with Mintlify CLI**

```bash theme={null}
mint validate
```

Expected: No errors. Warnings about unused pages are acceptable.

* [ ] **Step 5: Start dev server and verify**

```bash theme={null}
mint dev
```

Open `http://localhost:3000` in a browser. Verify:

1. The API Reference tab loads
2. Endpoint pages are auto-generated (click any endpoint)
3. The Overview page still shows at the top
4. Endpoints are grouped by OpenAPI tags in the sidebar
5. The Guides and Integrations tabs are unchanged

* [ ] **Step 6: Remove the backup file**

```bash theme={null}
rm docs.json.backup
```

* [ ] **Step 7: Commit**

```bash theme={null}
git add docs.json
git commit -m "feat: replace manual API endpoint listing with Mintlify auto-generation

Replace 800+ manually listed endpoint entries in the API Reference tab
with a single openapi field. Mintlify now auto-generates all endpoint
pages and sidebar navigation from api-reference/openapi.json."
```

***

### Task 2: Update SEO configuration in docs.json

**Files:**

* Modify: `docs.json` (the `seo` and `metadata` blocks near the end of the file)

The file already has `"seo": { "indexing": "all" }` (line 1487) and a `metadata` block (line 1490). We need to merge the SEO keywords into the `seo` block using the modern Mintlify `seo.metatags` format, and keep the existing `metadata` block since it may still be in use.

* [ ] **Step 1: Update the seo block**

Find the current `seo` block at the end of `docs.json`:

```json theme={null}
"seo": {
  "indexing": "all"
}
```

Replace with:

```json theme={null}
"seo": {
  "indexing": "all",
  "metatags": {
    "robots": "index, follow",
    "language": "en",
    "category": "Technology",
    "keywords": "Rhombus API, security API, camera API, access control API, IoT sensors API, video surveillance, developer documentation, REST API, OpenAPI"
  }
}
```

Note: The existing `metadata` block (with `og:site_name`, `og:type`, `og:image`, `twitter:card`, `twitter:site`) is kept as-is — it already covers the social sharing tags.

* [ ] **Step 2: Validate JSON**

```bash theme={null}
python3 -c "import json; json.load(open('docs.json')); print('Valid JSON')"
```

Expected: `Valid JSON`

* [ ] **Step 3: Commit**

```bash theme={null}
git add docs.json
git commit -m "feat: add SEO metatags for search engine optimization

Add robots, language, category, and keywords to the seo.metatags block
for better search engine discoverability of API documentation."
```

***

### Task 3: Update the GitHub Action pipeline

**Files:**

* Modify: `.github/workflows/sync-openapi.yml`

Remove the `build-api-navigation.py` step (no longer needed) and add the enrichment steps.

* [ ] **Step 1: Replace the workflow file content**

Replace the full contents of `.github/workflows/sync-openapi.yml` with:

```yaml theme={null}
name: Sync OpenAPI Spec

on:
  schedule:
    # 9:00 AM UTC = 1:00 AM PST (2:00 AM PDT)
    - cron: '0 9 * * *'
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  sync-openapi:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Fetch latest OpenAPI spec
        run: |
          curl -sf --retry 3 --retry-delay 5 \
            "https://api2.rhombussystems.com/api/openapi/public.json" \
            -o /tmp/new-openapi.json
          python3 -c "import json; json.load(open('/tmp/new-openapi.json'))"

      - name: Detect changes
        id: detect
        run: |
          python3 scripts/detect_openapi_changes.py \
            api-reference/openapi.json \
            /tmp/new-openapi.json \
            > /tmp/change-report.json

          HAS_CHANGES=$(python3 -c "import json; r=json.load(open('/tmp/change-report.json')); print(str(r['has_changes']).lower())")
          echo "has_changes=$HAS_CHANGES" >> "$GITHUB_OUTPUT"

          SUMMARY=$(python3 -c "import json; r=json.load(open('/tmp/change-report.json')); print(r['summary'])")
          echo "summary=$SUMMARY" >> "$GITHUB_OUTPUT"

          ADDED=$(python3 -c "import json; r=json.load(open('/tmp/change-report.json')); print(len(r['endpoints_added']))")
          echo "added=$ADDED" >> "$GITHUB_OUTPUT"

          REMOVED=$(python3 -c "import json; r=json.load(open('/tmp/change-report.json')); print(len(r['endpoints_removed']))")
          echo "removed=$REMOVED" >> "$GITHUB_OUTPUT"

      - name: Update OpenAPI spec
        if: steps.detect.outputs.has_changes == 'true'
        run: cp /tmp/new-openapi.json api-reference/openapi.json

      - name: Enrich OpenAPI spec
        if: steps.detect.outputs.has_changes == 'true'
        run: |
          python3 scripts/enrich-openapi-tags.py
          python3 scripts/inject-xmint-decorators.py
          python3 scripts/add-code-samples.py

      - name: Generate changelog entry
        if: steps.detect.outputs.has_changes == 'true'
        run: |
          python3 scripts/generate_changelog_entry.py /tmp/change-report.json \
            > /tmp/new-changelog-entry.mdx

      - name: Insert changelog entry
        if: steps.detect.outputs.has_changes == 'true'
        run: |
          python3 scripts/insert_changelog_entry.py \
            changelog.mdx \
            /tmp/new-changelog-entry.mdx

      - name: Create pull request
        if: steps.detect.outputs.has_changes == 'true'
        uses: peter-evans/create-pull-request@v7
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          commit-message: "chore: sync OpenAPI spec — ${{ steps.detect.outputs.summary }}"
          branch: automated/openapi-sync
          delete-branch: true
          title: "chore: sync OpenAPI spec (${{ steps.detect.outputs.added }} added, ${{ steps.detect.outputs.removed }} removed)"
          body: |
            ## Automated OpenAPI Spec Sync

            ${{ steps.detect.outputs.summary }}

            ### Changes
            - OpenAPI spec updated from upstream
            - Spec enriched (tags, x-mint metadata, code samples)
            - Changelog entry added (if new month)

            ### Files Modified
            - `api-reference/openapi.json` — latest spec from API (enriched)
            - `changelog.mdx` — new entry added

            ---
            *This PR was automatically created by the [Sync OpenAPI Spec](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) workflow.*
          labels: |
            automated
            api-sync
```

Key changes from the original:

* Removed the "Rebuild API navigation" step (`build-api-navigation.py`)

* Added "Enrich OpenAPI spec" step running the 3 enrichment scripts in order

* Updated PR body to reflect the new pipeline (no longer mentions `docs.json` nav rebuild)

* [ ] **Step 2: Commit**

```bash theme={null}
git add .github/workflows/sync-openapi.yml
git commit -m "feat: simplify nightly sync pipeline, add enrichment step

Remove build-api-navigation.py step (Mintlify handles navigation).
Add enrichment step to run enrich-openapi-tags.py, inject-xmint-decorators.py,
and add-code-samples.py on every sync."
```

***

### Task 4: Delete retired scripts

**Files:**

* Delete: `scripts/build-api-navigation.py`

* Delete: `scripts/generate-endpoint-docs.py`

* Delete: `scripts/update-docs-navigation.py`

* Delete: `scripts/add-service-level-navigation.py`

* Delete: `scripts/improve-endpoint-navigation.py`

* Delete: `scripts/update-llms-files.py`

* [ ] **Step 1: Verify each script is no longer referenced**

```bash theme={null}
grep -rl "build-api-navigation\|generate-endpoint-docs\|update-docs-navigation\|add-service-level-navigation\|improve-endpoint-navigation\|update-llms-files" --include="*.yml" --include="*.md" --include="*.json" --include="*.sh" . | grep -v docs/superpowers | grep -v .backup
```

Expected: No matches (or only matches in files we're about to update like CLAUDE.md). If the GitHub Action still references `build-api-navigation.py`, Task 3 must be completed first.

* [ ] **Step 2: Delete the scripts**

```bash theme={null}
rm scripts/build-api-navigation.py
rm scripts/generate-endpoint-docs.py
rm scripts/update-docs-navigation.py
rm scripts/add-service-level-navigation.py
rm scripts/improve-endpoint-navigation.py
rm scripts/update-llms-files.py
```

* [ ] **Step 3: Commit**

```bash theme={null}
git add -u scripts/
git commit -m "chore: remove retired navigation and llms scripts

These scripts are no longer needed:
- build-api-navigation.py (Mintlify auto-generates navigation)
- 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)"
```

***

### Task 5: Remove local AI context files

**Files:**

* Delete: `llms.txt`
* Delete: `llms-full.txt`

Mintlify auto-serves these at `https://api-docs.rhombus.community/llms.txt` and `/llms-full.txt`. The local files override the auto-generated versions, which means they go stale. Removing them lets Mintlify keep them up to date automatically.

* [ ] **Step 1: Delete the files**

```bash theme={null}
rm llms.txt llms-full.txt
```

* [ ] **Step 2: Commit**

```bash theme={null}
git add -u llms.txt llms-full.txt
git commit -m "chore: remove local llms.txt files, let Mintlify auto-serve them

Mintlify auto-generates and hosts llms.txt and llms-full.txt at the
site root. Local files override the auto-generated versions, causing
them to go stale. Removing lets Mintlify keep them current."
```

***

### Task 6: Update CLAUDE.md

**Files:**

* Modify: `CLAUDE.md`

Update to reflect the new architecture — simplified pipeline, retired scripts, Mintlify auto-generation.

* [ ] **Step 1: Update the Maintenance Scripts section**

Find the current "Maintenance Scripts" section in `CLAUDE.md` and replace it with:

````markdown theme={null}
### Maintenance Scripts

**OpenAPI sync pipeline** (run in order, or let the GitHub Action do it):
```bash
./scripts/update-openapi.sh                          # Fetch latest spec with validation & backup
python3 scripts/detect_openapi_changes.py OLD NEW     # Compare specs → change report JSON
python3 scripts/enrich-openapi-tags.py               # Ensure all tags have descriptions
python3 scripts/inject-xmint-decorators.py           # Add x-mint SEO metadata to endpoints
python3 scripts/add-code-samples.py                  # Add x-codeSamples to key endpoints
python3 scripts/generate_changelog_entry.py REPORT    # Change report → MDX changelog entry
python3 scripts/insert_changelog_entry.py changelog.mdx ENTRY  # Insert entry into changelog
````

**Content quality**:

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

````

- [ ] **Step 2: Update the Automation section**

Find the "Automation (GitHub Actions)" section and replace with:

```markdown
### Automation (GitHub Actions)
The nightly OpenAPI sync (`.github/workflows/sync-openapi.yml`) runs at **9 AM UTC** and follows this pipeline:
1. Fetches latest spec from `https://api2.rhombussystems.com/api/openapi/public.json`
2. `detect_openapi_changes.py` — compares old/new specs, produces a change report JSON
3. Copies new spec to `api-reference/openapi.json`
4. Enrichment: `enrich-openapi-tags.py` → `inject-xmint-decorators.py` → `add-code-samples.py`
5. `generate_changelog_entry.py` + `insert_changelog_entry.py` — adds changelog entry
6. Creates a **pull request** (not a direct commit) on branch `automated/openapi-sync`
7. On merge → Mintlify auto-deploys → `llms.txt`, `llms-full.txt`, `skill.md`, `sitemap.xml` all regenerate

Can also be triggered manually via `workflow_dispatch`.
````

* [ ] **Step 3: Update the Architecture section**

Find `### docs.json Structure` and replace with:

```markdown theme={null}
### 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 `api-reference/openapi.json` — do not manually list endpoints
- **Modifying API content**: Enrich the OpenAPI spec itself (tags, descriptions, `x-mint` metadata). Navigation is auto-generated.
```

Update `### Content Types` to:

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

* [ ] **Step 4: Update the Key Files section**

Replace the Key Files list with:

```markdown theme={null}
### Key Files
- `docs.json` — Main Mintlify config. Schema: https://mintlify.com/docs.json
- `api-reference/openapi.json` — Full OpenAPI spec synced nightly from production; enriched with tags, x-mint metadata, and code samples
- `api-reference/overview.mdx` — Hand-written API reference landing page
- `custom.css` — Custom styling overrides
- `VERSIONING.md` — Plan for introducing API versioning when breaking changes occur
```

* [ ] **Step 5: Update the Critical Don'ts section**

Replace with:

```markdown theme={null}
## 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
- Modify the GitHub Action workflow without understanding the full sync pipeline
```

* [ ] **Step 6: Commit**

```bash theme={null}
git add CLAUDE.md
git commit -m "docs: update CLAUDE.md for autonomous API docs architecture

Reflect simplified pipeline (no navigation rebuild), retired scripts,
Mintlify auto-generation, and auto-served llms.txt/skill.md."
```

***

### Task 7: Update the openapi-sync skill

**Files:**

* Modify: `.claude/skills/openapi-sync/SKILL.md`

* [ ] **Step 1: Replace the skill content**

Replace the full contents of `.claude/skills/openapi-sync/SKILL.md` with:

````markdown theme={null}
---
name: openapi-sync
description: Run the full OpenAPI sync pipeline manually — fetch spec, detect changes, enrich, generate changelog
disable-model-invocation: true
---

# OpenAPI Sync Pipeline

Run the full OpenAPI sync pipeline locally. This mirrors the nightly GitHub Action (`.github/workflows/sync-openapi.yml`).

All commands run from the repo root (where `docs.json` lives).

## Steps

### 1. Save the current spec for comparison

```bash
cp api-reference/openapi.json /tmp/openapi-old.json
````

### 2. Fetch the latest OpenAPI spec

```bash theme={null}
./scripts/update-openapi.sh
```

Downloads from `https://api2.rhombussystems.com/api/openapi/public.json`, validates JSON, writes to `api-reference/openapi.json`.

### 3. Detect changes

```bash theme={null}
python3 scripts/detect_openapi_changes.py /tmp/openapi-old.json api-reference/openapi.json > /tmp/change-report.json
```

### 4. Enrich the spec

```bash theme={null}
python3 scripts/enrich-openapi-tags.py
python3 scripts/inject-xmint-decorators.py
python3 scripts/add-code-samples.py
```

### 5. Generate and insert changelog entry

```bash theme={null}
python3 scripts/generate_changelog_entry.py /tmp/change-report.json > /tmp/new-changelog-entry.mdx
python3 scripts/insert_changelog_entry.py changelog.mdx /tmp/new-changelog-entry.mdx
```

### 6. Verify

```bash theme={null}
mint broken-links
mint dev
```

Check that new endpoints appear in the API Reference tab sidebar, grouped by their OpenAPI tags. No manual `docs.json` edits needed — Mintlify auto-generates navigation.

````

- [ ] **Step 2: Commit**

```bash
git add .claude/skills/openapi-sync/SKILL.md
git commit -m "docs: update openapi-sync skill for simplified pipeline

Remove build-api-navigation step, add enrichment scripts, update
instructions to reflect Mintlify auto-generation."
````

***

### Task 8: Update the PreToolUse hook

**Files:**

* Modify: `.claude/settings.json`

The current hook blocks edits to `docs.json` that contain `api-reference/openapi.json`. This was designed to prevent manual editing of the API Reference navigation. Now that the navigation is a single `openapi` field, the hook should block any attempt to add manual endpoint entries (`METHOD /api/`) to `docs.json`.

* [ ] **Step 1: Update the PreToolUse hook**

In `.claude/settings.json`, find the PreToolUse hook command and replace it with:

```json theme={null}
"command": "FILE=$(echo \"$CLAUDE_TOOL_INPUT\" | python3 -c \"import sys,json; print(json.load(sys.stdin).get('file_path',''))\" 2>/dev/null); if [ \"$(basename \"$FILE\")\" = 'docs.json' ]; then CONTENT=$(echo \"$CLAUDE_TOOL_INPUT\" | python3 -c \"import sys,json; d=json.load(sys.stdin); print(d.get('content','') + d.get('new_string',''))\" 2>/dev/null); if echo \"$CONTENT\" | grep -qE '\"(POST|GET|PUT|DELETE|PATCH) /api/'; then echo 'BLOCK: Do not manually list API endpoints in docs.json. Mintlify auto-generates these from the OpenAPI spec.'; exit 2; fi; fi"
```

* [ ] **Step 2: Commit**

```bash theme={null}
git add .claude/settings.json
git commit -m "fix: update hook to block manual endpoint entries in docs.json

Now that Mintlify auto-generates API Reference navigation, the hook
blocks attempts to add METHOD /api/ entries to docs.json."
```

***

### Task 9: Smoke test the full setup

This is a manual verification task — no code changes.

* [ ] **Step 1: Start the dev server**

```bash theme={null}
mint dev
```

* [ ] **Step 2: Verify API Reference tab**

Open `http://localhost:3000` and check:

1. API Reference tab loads with auto-generated endpoint sidebar
2. Click several endpoints — pages render with parameters, responses, and playground
3. Overview page (`api-reference/overview`) is accessible
4. Endpoints are grouped by OpenAPI tags

* [ ] **Step 3: Verify Guides tab is unchanged**

Check that all pages under Guides still work:

* Getting Started (index, resources, rate-limits, changelog)

* Implementation Guides (streaming-video, video-player, etc.)

* Real-time Events (webhooks, websocket pages)

* [ ] **Step 4: Verify Integrations tab is unchanged**

Check Low Code / No Code and AI & LLMs pages still work.

* [ ] **Step 5: Validate links**

```bash theme={null}
mint broken-links
```

Expected: No broken links (some warnings may be acceptable for external URLs).

* [ ] **Step 6: Verify docs.json size**

```bash theme={null}
wc -l docs.json
```

Expected: \~200 lines or fewer (down from 1512).

* [ ] **Step 7: Verify retired scripts are gone**

```bash theme={null}
ls scripts/build-api-navigation.py scripts/generate-endpoint-docs.py scripts/update-docs-navigation.py scripts/add-service-level-navigation.py scripts/improve-endpoint-navigation.py scripts/update-llms-files.py 2>&1
```

Expected: All `No such file or directory`.

* [ ] **Step 8: Verify llms files are gone**

```bash theme={null}
ls llms.txt llms-full.txt 2>&1
```

Expected: `No such file or directory` for both.