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

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:

{
  "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:

{
  "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

python3 -c "import json; json.load(open('docs.json')); print('Valid JSON')"

Expected: Valid JSON

Step 4: Validate with Mintlify CLI

mint validate

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

Step 5: Start dev server and verify

mint dev

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

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

Step 6: Remove the backup file

rm docs.json.backup

Step 7: Commit

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:

"seo": {
  "indexing": "all"
}

Replace with:

"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

python3 -c "import json; json.load(open('docs.json')); print('Valid JSON')"

Expected: Valid JSON

Step 3: Commit

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:

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

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

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

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

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

rm llms.txt llms-full.txt

Step 2: Commit

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:

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

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:

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

### Content Types
**Hand-written MDX**: Implementation guides, quickstart, MCP documentation
**Auto-generated API docs**: All endpoint pages under API Reference tab (Mintlify generates these from the OpenAPI spec — do not manually create)
**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:

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

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

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:

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

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

python3 scripts/detect_openapi_changes.py /tmp/openapi-old.json api-reference/openapi.json > /tmp/change-report.json

4. Enrich the spec

python3 scripts/enrich-openapi-tags.py
python3 scripts/inject-xmint-decorators.py
python3 scripts/add-code-samples.py

5. Generate and insert changelog entry

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

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:

"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

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

mint dev

Step 2: Verify API Reference tab

Open http://localhost:3000 and check:

API Reference tab loads with auto-generated endpoint sidebar
Click several endpoints — pages render with parameters, responses, and playground
Overview page (api-reference/overview) is accessible
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

mint broken-links

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

Step 6: Verify docs.json size

wc -l docs.json

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

Step 7: Verify retired scripts are gone

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

ls llms.txt llms-full.txt 2>&1

Expected: No such file or directory for both.

​Autonomous API Documentation Pipeline — Implementation Plan

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

​Task 2: Update SEO configuration in docs.json

​Task 3: Update the GitHub Action pipeline

​Task 4: Delete retired scripts

​Task 5: Remove local AI context files

​Task 6: Update CLAUDE.md

​Task 7: Update the openapi-sync skill

​2. Fetch the latest OpenAPI spec

​3. Detect changes

​4. Enrich the spec

​5. Generate and insert changelog entry

​6. Verify

​Task 8: Update the PreToolUse hook

​Task 9: Smoke test the full setup

Autonomous API Documentation Pipeline — Implementation Plan

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

Task 2: Update SEO configuration in docs.json

Task 3: Update the GitHub Action pipeline

Task 4: Delete retired scripts

Task 5: Remove local AI context files

Task 6: Update CLAUDE.md

Task 7: Update the openapi-sync skill

2. Fetch the latest OpenAPI spec

3. Detect changes

4. Enrich the spec

5. Generate and insert changelog entry

6. Verify

Task 8: Update the PreToolUse hook

Task 9: Smoke test the full setup