​

Documentation Quality Overhaul — 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.

• Staging URL wss://ws.itg.rhombussystems.com:8443/websocket — REMOVE, internal only
• Rhombus CLI at github.com/RhombusSystems/rhombus-cli — EXISTS, keep reference but do not expand (separate article later)
• Support email — always support@rhombus.com (never api@rhombus.com)
• Docs URL — always https://api-docs.rhombus.community (never apidocs.rhombussystems.com)
• Endpoint count — use stable phrase “800+” everywhere (actual count: 892, changes nightly)
• Stub pages — build from actual OpenAPI spec endpoints
• WebSocket filenames — rename to remove redundant websocket- prefix

​

Task 1: Frontmatter Sweep — All 25 Pages

• Step 1: Add keywords and fix frontmatter on root pages

• Step 2: Add keywords and fix frontmatter on implementation pages

• Step 3: Add keywords and fix frontmatter on integration pages

• Step 4: Add keywords and fix frontmatter on WebSocket pages

• Step 5: Validate and commit

python3 scripts/check-content-quality.py
mint validate
git add -A *.mdx implementations/*.mdx low-code-no-code/*.mdx websocket/*.mdx api-reference/*.mdx
git commit -m "fix: add missing keywords, icons, and fix descriptions across all pages"

​

Task 2: Rename WebSocket Files — Remove Redundant Prefix

• Rename: websocket/websocket-overview.mdx → websocket/overview.mdx
• Rename: websocket/websocket-authentication.mdx → websocket/authentication.mdx
• Rename: websocket/websocket-event-monitoring.mdx → websocket/event-monitoring.mdx
• Rename: websocket/websocket-connection-lifecycle.mdx → websocket/connection-lifecycle.mdx
• Rename: websocket/websocket-stomp-protocol.mdx → websocket/stomp-protocol.mdx
• Rename: websocket/websocket-code-examples.mdx → websocket/code-examples.mdx
• Rename: websocket/websocket-troubleshooting.mdx → websocket/troubleshooting.mdx
• Modify: docs.json (WebSocket navigation group)
• Modify: All WebSocket .mdx files (internal links)
• Step 1: Rename all 7 files

cd websocket
mv websocket-overview.mdx overview.mdx
mv websocket-authentication.mdx authentication.mdx
mv websocket-event-monitoring.mdx event-monitoring.mdx
mv websocket-connection-lifecycle.mdx connection-lifecycle.mdx
mv websocket-stomp-protocol.mdx stomp-protocol.mdx
mv websocket-code-examples.mdx code-examples.mdx
mv websocket-troubleshooting.mdx troubleshooting.mdx
cd ..

• Step 2: Update docs.json navigation

"group": "WebSocket",
"pages": [
  "websocket/websocket-overview",
  "websocket/websocket-authentication",
  "websocket/websocket-event-monitoring",
  "websocket/websocket-connection-lifecycle",
  "websocket/websocket-stomp-protocol",
  "websocket/websocket-code-examples",
  "websocket/websocket-troubleshooting"
]

"group": "WebSocket",
"pages": [
  "websocket/overview",
  "websocket/authentication",
  "websocket/event-monitoring",
  "websocket/connection-lifecycle",
  "websocket/stomp-protocol",
  "websocket/code-examples",
  "websocket/troubleshooting"
]

• Step 3: Update all internal links in WebSocket pages

• websocket/overview.mdx: Update 4 Card hrefs from /websocket/websocket-* to /websocket/*
• websocket/authentication.mdx: Update link to /websocket/connection-lifecycle
• websocket/stomp-protocol.mdx: Update link to /websocket/code-examples
• Any other cross-references between WebSocket pages
• Step 4: Validate and commit

python3 -c "import json; json.load(open('docs.json')); print('Valid JSON')"
mint broken-links
git add -A
git commit -m "refactor: rename websocket files to remove redundant prefix

Rename websocket/websocket-*.mdx to websocket/*.mdx for cleaner URLs.
Update docs.json navigation and all internal cross-references."

​

Task 3: Rewrite index.mdx

• Modify: index.mdx

• Step 1: Remove the marketing Info callout and “Why Choose Rhombus” section

• Step 2: Fix code examples with real endpoints

const response = await fetch('https://api2.rhombussystems.com/api/camera/getMinimalCameraStateList', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-auth-scheme': 'api-token',
    'x-auth-apikey': 'YOUR_API_KEY'
  },
  body: JSON.stringify({})
});

const data = await response.json();
console.log(`Found ${data.cameraStates.length} cameras`);

curl -X POST https://api2.rhombussystems.com/api/camera/getMinimalCameraStateList \
  -H "Content-Type: application/json" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_API_KEY" \
  -d '{}'

• Step 3: Fix the auth headers display

x-auth-scheme: api-token
x-auth-apikey: YOUR_API_KEY

• Step 4: Stabilize endpoint count and add links to “What You Can Build” cards

• Camera Management → /implementations/streaming-video
• Access Control → /implementations/qr-code-access-control
• Environmental Monitoring → /implementations/iot-sensors
• Analytics & Insights → /api-reference/overview
• Event Management → /webhooks
• Device Administration → /api-reference/overview
• Step 5: Validate and commit

mint validate
git add index.mdx
git commit -m "fix: rewrite index page with real code examples, remove marketing fluff

Replace placeholder URLs with real endpoints, fix auth header display,
stabilize endpoint count to '800+', add navigation links to cards."

​

Task 4: Clean Up Changelog

• Modify: changelog.mdx

• Step 1: Fix endpoint totals

• Step 2: Trim the November 2025 “New Documentation Launch” entry

• Step 3: Trim the November 2025 “Documentation Navigation Restructure” entry

• Step 4: Remove emoji from headings

• Step 5: Remove internal endpoint references

• Step 6: Validate and commit

mint validate
git add changelog.mdx
git commit -m "fix: clean up changelog — fix counts, trim bloated entries, remove emoji"

​

Task 5: Fix Code Examples in Camera Guides

• Modify: implementations/streaming-video.mdx
• Modify: implementations/video-player.mdx
• Modify: implementations/advanced-implementation.mdx
• Modify: implementations/retrieving-audio.mdx
• Modify: implementations/backup-footage-local-storage.mdx
• Step 1: Fix streaming-video.mdx

1. Fix syntax error around line 83-84: broken header object 'x-auth-apikey: YOUR_API_KEY' should be 'x-auth-apikey': 'YOUR_API_KEY'
2. Fix unused apiKey parameter around line 62 — use it instead of hardcoding
3. Fix incorrect thumbnail URL around line 799 to match the pattern from line 25
4. Replace generic “Next Steps” section with linked Cards to related pages
5. Fix json language tag on binary layout example (line ~43) to text

• Step 2: Fix video-player.mdx

1. Fix duplicate streaming key in player.updateSettings() (around line 270-296) — merge into one object
2. Fix email mismatch: change mailto:api@rhombus.com to mailto:support@rhombus.com (around line 699)
3. Add auth headers to troubleshooting curl examples (around lines 545-553)

• Step 3: Fix advanced-implementation.mdx

1. Fix keywords: replace ["rtsp", "sync video"] with ["ISOBMFF", "timestamp", "synchronization", "multi-camera", "video sync"]
2. Fix json language tag on binary layout example to text
3. Fix email mismatch: change mailto:api@rhombus.com to mailto:support@rhombus.com
4. Update deprecated datetime.datetime.utcfromtimestamp() calls to datetime.datetime.fromtimestamp(ts, tz=datetime.timezone.utc)
5. Add #include <iostream> to C++ example

• Step 4: Fix retrieving-audio.mdx

1. Remove unnecessary --- horizontal rules (lines 39, 152, 248, 265, 308)
2. Fix off-by-one: range(1, int(num_segments)) → range(1, int(num_segments) + 1) (line ~226)
3. Link API Reference endpoint names to actual documentation pages

• Step 5: Fix backup-footage-local-storage.mdx

1. Fix Steps component misuse (lines 29-49): replace ### Heading markdown inside <Steps> with proper <Step title="..."> components
2. Fix json language tag on file naming convention to text
3. Use environment variable pattern for email credentials instead of hardcoded placeholders
4. Add missing import datetime in webhook example

• Step 6: Validate and commit

mint validate
mint broken-links
git add implementations/
git commit -m "fix: resolve code bugs, email mismatches, and component issues in camera guides"

​

Task 6: Fix Integration Pages

• Modify: low-code-no-code/zapier.mdx
• Modify: low-code-no-code/make.mdx
• Modify: low-code-no-code/n8n.mdx
• Modify: documentation-mcp.mdx
• Step 1: Fix zapier.mdx

1. Remove specific “8,000+” app count from description — replace with “thousands of apps”
2. Fix Authentication code block (line ~56-62): the https://console... URL in a bash fence is not a command. Change to plain text or wrap in a Note callout with a link.
3. Replace the pricing table with a link to Zapier’s pricing page: For current pricing, see [Zapier Pricing](https://zapier.com/pricing).

• Step 2: Fix make.mdx

1. Fix Authentication code block — same issue as Zapier (URL in bash fence)
2. Replace pricing table with link: For current pricing, see [Make Pricing](https://www.make.com/en/pricing).
3. Verify rate limit claim (“1000 req/hr”) — add link to /rate-limits page

• Step 3: Fix n8n.mdx

1. Either complete the Custom Rhombus Node TypeScript example (lines ~409-451) or remove it — incomplete skeletons violate content standards
2. Remove or rephrase the community templates claim if Rhombus-specific templates don’t actually exist on n8n’s site
3. Update Docker Compose environment variables to current n8n conventions (remove deprecated N8N_BASIC_AUTH_* vars)

• Step 4: Fix documentation-mcp.mdx

1. Verify link /implementations/video-player is not broken
2. Tighten the introductory paragraph (single long sentence)

• Step 5: Validate and commit

mint validate
mint broken-links
git add low-code-no-code/ documentation-mcp.mdx
git commit -m "fix: clean up integration pages — remove stale pricing, fix code blocks"

​

Task 7: Rewrite Alarm Monitoring Guide

• Modify: implementations/alarm-monitoring.mdx

• Alert Monitoring: orgStatus, locationStatus, enableMonitoringForLocation, disableMonitoringForLocation, getAlertMonitoringSettingsForLocation
• Threat Cases: getAlertMonitoringThreatCases, escalateThreatCaseToAlarm, dismissThreatCase, cancelThreatCase
• PINs: createPinForLocation, deletePinForLocation
• Policy Alerts: getPolicyAlerts, dismissPolicyAlertV2
• Step 1: Write the new page content

1. Overview — What alarm monitoring does, how it integrates with Rhombus cameras and sensors
2. Prerequisites — API key, alarm monitoring license, configured location
3. Check Monitoring Status — orgStatus and locationStatus with CodeGroup (Python, JavaScript, cURL)
4. Enable/Disable Monitoring — enableMonitoringForLocation / disableMonitoringForLocation with CodeGroup
5. Manage Threat Cases — getAlertMonitoringThreatCases, escalateThreatCaseToAlarm, dismissThreatCase with CodeGroup and response examples
6. Manage PINs — createPinForLocation, deletePinForLocation with CodeGroup
7. Work with Policy Alerts — getPolicyAlerts, dismissPolicyAlertV2 with CodeGroup
8. Next Steps — Cards linking to related pages

• Use CodeGroup with Python, JavaScript, and cURL
• Include auth headers (x-auth-scheme: api-token, x-auth-apikey: YOUR_API_KEY)
• Use https://api2.rhombussystems.com base URL
• Include realistic response examples
• Be complete and runnable
• Step 2: Validate and commit

mint validate
mint broken-links
git add implementations/alarm-monitoring.mdx
git commit -m "feat: rewrite alarm monitoring guide with complete API workflows

Add monitoring status checks, threat case management, PIN management,
and policy alert workflows with multi-language code examples."

​

Task 8: Rewrite IoT Sensors Guide

• Modify: implementations/iot-sensors.mdx

• Climate: getMinimalClimateStateList, getClimateEventsForSensor, getConfig, updateDetails
• Climate Policies: createClimatePolicy, getClimatePolicies, updateClimatePolicy
• Environmental Gateways: getMinimalEnvironmentalGatewayStates, getEventsForEnvironmentalGateway
• Related sensors: Door (4 endpoints), Occupancy (4 endpoints)
• Step 1: Write the new page content

1. Overview — Rhombus IoT sensor capabilities (temperature, humidity, air quality, occupancy, door sensors)
2. Prerequisites — API key, sensors deployed
3. List All Sensors — getMinimalClimateStateList with CodeGroup (Python, JavaScript, cURL) and response example
4. Read Sensor Data — getClimateEventsForSensor with CodeGroup, showing temperature/humidity data
5. Configure Sensors — getConfig and updateDetails with CodeGroup
6. Set Up Climate Alerts — createClimatePolicy with CodeGroup showing threshold configuration
7. Environmental Gateways — getMinimalEnvironmentalGatewayStates with CodeGroup
8. Export Sensor Data — /api/export/climateEvents for CSV download
9. Next Steps — Cards linking to related pages

• Step 2: Validate and commit

mint validate
mint broken-links
git add implementations/iot-sensors.mdx
git commit -m "feat: rewrite IoT sensors guide with complete API workflows

Add sensor listing, climate data reading, configuration, alert policies,
gateway management, and data export with multi-language code examples."

​

Task 9: Fix WebSocket Content Issues

• Modify: websocket/overview.mdx (after Task 2 rename)
• Modify: websocket/event-monitoring.mdx
• Modify: websocket/connection-lifecycle.mdx
• Modify: websocket/stomp-protocol.mdx
• Modify: websocket/code-examples.mdx
• Modify: websocket/troubleshooting.mdx
• Modify: websocket/authentication.mdx

• Step 1: Fix overview.mdx

• Step 2: Fix event-monitoring.mdx

1. Expand the entity types table (line ~70-71): replace vague “Other entities” with known types from the API, or add a Note stating the full list is available via the WebSocket connection itself
2. Rewrite line ~74: remove the --all-events CLI flag reference. Replace with: “To receive all event types, omit the entity-type filter from your SUBSCRIBE destination.”
3. Add error handling to integration pattern examples (Slack webhook, webhook relay)

• Step 3: Fix connection-lifecycle.mdx

1. Fix the reconnection example (line ~299-322): implement actual exponential backoff instead of flat time.sleep(5):

def connect_with_backoff(url, max_retries=10):
    for attempt in range(max_retries):
        try:
            ws = websocket.create_connection(url)
            return ws
        except Exception as e:
            delay = min(5 * (2 ** attempt), 60)
            print(f"Connection failed: {e}. Retrying in {delay}s...")
            time.sleep(delay)
    raise ConnectionError("Max retries exceeded")

• Step 4: Fix stomp-protocol.mdx

• Step 5: Fix code-examples.mdx

<Tabs>
  <Tab title="Python">
    [Python complete example]
  </Tab>
  <Tab title="JavaScript">
    [JavaScript complete example]
  </Tab>
  <Tab title="Go">
    [Go complete example]
  </Tab>
</Tabs>

• Step 6: Fix troubleshooting.mdx

1. Fix the docs URL: change https://apidocs.rhombussystems.com to https://api-docs.rhombus.community
2. Fix the wscat/websocat section (line ~229-248): rename section to “Test with websocat” since that’s what the content actually demonstrates
3. Supplement the curl connectivity test with a proper TCP check: nc -zv ws.rhombussystems.com 8443

• Step 7: Fix authentication.mdx

1. Fix Go snippet missing imports (time, log, fmt)
2. Standardize placeholder tokens: use YOUR_API_KEY consistently (not your-api-token)

• Step 8: Validate and commit

mint validate
mint broken-links
git add websocket/
git commit -m "fix: resolve WebSocket content issues — staging URL, heartbeat, tabs, troubleshooting"

​

Task 10: Fix Remaining Page Issues

• Modify: resources.mdx
• Modify: webhooks.mdx
• Modify: implementations/qr-code-access-control.mdx
• Modify: implementations/webhook-listener.mdx
• Step 1: Fix resources.mdx

• Step 2: Fix webhooks.mdx

1. Fix the generic /api-reference link (line ~57) — link to a more specific section or remove the link text and say “See the API Reference for webhook integration endpoints”
2. Add a sample webhook payload (JSON) showing what a typical event notification looks like — this is the most common thing developers look for
3. Link each CRUD operation bullet (Create, List, Update, Delete) to corresponding API endpoint descriptions

• Step 3: Fix qr-code-access-control.mdx

1. Replace external API URL (line ~73) with internal root-relative link
2. Remove or condense the “Benefits” section (lines ~419-447) — it reads like marketing
3. Update the stale date in example response (2024-08-01)

• Step 4: Fix webhook-listener.mdx

1. Fix broken bold formatting on line ~684: ****Third Party Integrations ->Webhooks**** → proper markdown
2. Merge redundant “Next Steps” and “Additional Resources” sections into one

• Step 5: Validate and commit

mint validate
mint broken-links
git add resources.mdx webhooks.mdx implementations/qr-code-access-control.mdx implementations/webhook-listener.mdx
git commit -m "fix: clean up resources, webhooks, QR code, and webhook listener pages"

​

Task 11: Final Validation

• Step 1: Run mint validate

mint validate

• Step 2: Run mint broken-links

mint broken-links

• Step 3: Run mint a11y

mint a11y

• Step 4: Run content quality check

python3 scripts/check-content-quality.py

• Step 5: Verify page count and structure

find . -name "*.mdx" -not -path "./api-reference/*" | wc -l
wc -l docs.json

• Step 6: Start dev server for manual spot check

mint dev