cp docs.json docs.json.backup

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

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

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

mint validate

mint dev

rm docs.json.backup

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

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

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

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

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

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

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

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

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

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

rm llms.txt llms-full.txt

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

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

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

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

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

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

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

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

./scripts/update-openapi.sh

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

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

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

mint broken-links
mint dev

- [ ] **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."

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

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

mint dev

mint broken-links

wc -l docs.json

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

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