signalwire · hey-august · Aug 19, 2026 · Aug 17, 2026 · Aug 17, 2026 · Aug 17, 2026
diff --git a/fern/products/browser-sdk/pages/v4/guides/build-voice-video/device-management.mdx b/fern/products/browser-sdk/pages/v4/guides/build-voice-video/device-management.mdx
@@ -254,6 +254,7 @@ Save the page below as `devices-demo.html` and open it over HTTPS (or `localhost
 Pick a different mic, camera, or speaker before dialing. The log records each pick as `preference: …` — that's the `client.select*` branch in action. Plug or unplug a USB headset to see `deviceRecovered$` fire.
 
 <Accordion title="devices-demo.html — full source">
+
 ```html
 <!doctype html>
 <html lang="en">
@@ -442,6 +443,7 @@ Pick a different mic, camera, or speaker before dialing. The log records each pi
   </body>
 </html>
 ```
+
 </Accordion>
 
 ### Switch a device mid-call

diff --git a/fern/products/browser-sdk/pages/v4/guides/build-voice-video/inbound-calls.mdx b/fern/products/browser-sdk/pages/v4/guides/build-voice-video/inbound-calls.mdx
@@ -217,6 +217,7 @@ Once registered, the log prints the user's dialable `/private/<name>` address(es
 Leave the page open — when the call arrives, the **Caller** line populates and the **Answer** / **Decline** buttons enable. After you accept, **Hang up** enables so you can end the call.
 
 <Accordion title="inbound-demo.html — full source">
+
 ```html
 <!doctype html>
 <html lang="en">
@@ -376,6 +377,7 @@ Leave the page open — when the call arrives, the **Caller** line populates and
   </body>
 </html>
 ```
+
 </Accordion>
 
 ### Place a test call

diff --git a/fern/products/browser-sdk/pages/v4/guides/build-voice-video/messaging-chat.mdx b/fern/products/browser-sdk/pages/v4/guides/build-voice-video/messaging-chat.mdx
@@ -199,6 +199,7 @@ The demo touches: `client.directory$` (to list addresses),
 same conversation).
 
 <Accordion title="messaging-chat-demo.html — full source">
+
 ```html
 <!doctype html>
 <html lang="en">
@@ -416,6 +417,7 @@ same conversation).
   </body>
 </html>
 ```
+
 </Accordion>
 
 ## Reference

diff --git a/fern/products/browser-sdk/pages/v4/guides/build-voice-video/outbound-calls.mdx b/fern/products/browser-sdk/pages/v4/guides/build-voice-video/outbound-calls.mdx
@@ -132,6 +132,7 @@ Create a SAT against your project — the [Authentication guide](/docs/browser-s
 Copy the returned `token`, save the page below as `outbound-demo.html`, and open it over HTTPS (or `localhost`). Paste the SAT and a destination, toggle the **Send audio** / **Send video** checkboxes to match the call shape you want, click **Dial**, and watch the log — it records every status the call moves through. The checkboxes map directly onto the `audio` and `video` keys of `dial()`'s [`DialOptions`](/docs/browser-sdk/v4/reference/interfaces/dial-options).
 
 <Accordion title="outbound-demo.html — full source">
+
 ```html
 <!doctype html>
 <html lang="en">
@@ -241,6 +242,7 @@ Copy the returned `token`, save the page below as `outbound-demo.html`, and open
   </body>
 </html>
 ```
+
 </Accordion>
 
 You should see `Status: connected` once the destination picks up. If `dial()` rejects with `CallCreateError`, the token's scope doesn't reach the destination — re-check `allowed_addresses` or the token's project.

diff --git a/fern/products/browser-sdk/pages/v4/guides/getting-started/authentication.mdx b/fern/products/browser-sdk/pages/v4/guides/getting-started/authentication.mdx
@@ -341,6 +341,7 @@ The Project API Token can issue a SAT for any user in your project. Use a develo
 Copy the returned `token`, save the page below as `auth-demo.html`, and open it in a browser. Paste the SAT into the input, click **Authenticate**, and watch the log. It reports whether the SDK was able to open a session with the SAT.
 
 <Accordion title="auth-demo.html — full source">
+
 ```html
 <!doctype html>
 <html lang="en">
@@ -399,6 +400,7 @@ Copy the returned `token`, save the page below as `auth-demo.html`, and open it
   </body>
 </html>
 ```
+
 </Accordion>
 
 You should see `Authenticated — WebSocket open.` in the log. If you see `Failed: InvalidCredentialsError`, the SAT is expired, malformed, or issued for a different SignalWire space than the SDK is connecting to. Create a fresh one and try again.

diff --git a/...wser-sdk/pages/v4/web-components/index.md → ...ser-sdk/pages/v4/web-components/index.mdx b/...wser-sdk/pages/v4/web-components/index.md → ...ser-sdk/pages/v4/web-components/index.mdx
diff --git a/...pages/v4/web-components/sw-audio-level.md → ...ages/v4/web-components/sw-audio-level.mdx b/...pages/v4/web-components/sw-audio-level.md → ...ages/v4/web-components/sw-audio-level.mdx
@@ -65,7 +65,7 @@ _Class: `SwAudioLevel` · Module: `packages/web-components/src/components/sw-aud
 
 | Name               | Privacy | Description                                                                                                                            | Parameters | Return | Inherited From |
 | ------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------ | -------------- |
-| `releaseResources` | public  | Public method to release all audio resources immediately&#xA;Call this before stopping the MediaStream tracks to ensure proper cleanup |            | `void` |                |
+| `releaseResources` | public  | Public method to release all audio resources immediately. Call this before stopping the MediaStream tracks to ensure proper cleanup |            | `void` |                |
 
 ### Attributes
 

diff --git a/...ges/v4/web-components/sw-call-controls.md → ...es/v4/web-components/sw-call-controls.mdx b/...ges/v4/web-components/sw-call-controls.md → ...es/v4/web-components/sw-call-controls.mdx
diff --git a/...ages/v4/web-components/sw-call-dialpad.md → ...ges/v4/web-components/sw-call-dialpad.mdx b/...ages/v4/web-components/sw-call-dialpad.md → ...ges/v4/web-components/sw-call-dialpad.mdx
diff --git a/.../pages/v4/web-components/sw-call-media.md → ...pages/v4/web-components/sw-call-media.mdx b/.../pages/v4/web-components/sw-call-media.md → ...pages/v4/web-components/sw-call-media.mdx
diff --git a/...ges/v4/web-components/sw-call-provider.md → ...es/v4/web-components/sw-call-provider.mdx b/...ges/v4/web-components/sw-call-provider.md → ...es/v4/web-components/sw-call-provider.mdx
diff --git a/...pages/v4/web-components/sw-call-status.md → ...ages/v4/web-components/sw-call-status.mdx b/...pages/v4/web-components/sw-call-status.md → ...ages/v4/web-components/sw-call-status.mdx
diff --git a/...pages/v4/web-components/sw-call-widget.md → ...ages/v4/web-components/sw-call-widget.mdx b/...pages/v4/web-components/sw-call-widget.md → ...ages/v4/web-components/sw-call-widget.mdx
diff --git a/...ges/v4/web-components/sw-click-to-call.md → ...es/v4/web-components/sw-click-to-call.mdx b/...ges/v4/web-components/sw-click-to-call.md → ...es/v4/web-components/sw-click-to-call.mdx
diff --git a/...s/v4/web-components/sw-device-selector.md → .../v4/web-components/sw-device-selector.mdx b/...s/v4/web-components/sw-device-selector.md → .../v4/web-components/sw-device-selector.mdx
diff --git a/...k/pages/v4/web-components/sw-directory.md → .../pages/v4/web-components/sw-directory.mdx b/...k/pages/v4/web-components/sw-directory.md → .../pages/v4/web-components/sw-directory.mdx
diff --git a/...ages/v4/web-components/sw-local-camera.md → ...ges/v4/web-components/sw-local-camera.mdx b/...ages/v4/web-components/sw-local-camera.md → ...ges/v4/web-components/sw-local-camera.mdx
diff --git a/...web-components/sw-participant-controls.md → ...eb-components/sw-participant-controls.mdx b/...web-components/sw-participant-controls.md → ...eb-components/sw-participant-controls.mdx
diff --git a/...ages/v4/web-components/sw-participants.md → ...ges/v4/web-components/sw-participants.mdx b/...ages/v4/web-components/sw-participants.md → ...ges/v4/web-components/sw-participants.mdx
diff --git a/.../pages/v4/web-components/sw-self-media.md → ...pages/v4/web-components/sw-self-media.mdx b/.../pages/v4/web-components/sw-self-media.md → ...pages/v4/web-components/sw-self-media.mdx
diff --git a/...dk/pages/v4/web-components/sw-ui-alert.md → ...k/pages/v4/web-components/sw-ui-alert.mdx b/...dk/pages/v4/web-components/sw-ui-alert.md → ...k/pages/v4/web-components/sw-ui-alert.mdx
diff --git a/...ges/v4/web-components/sw-ui-background.md → ...es/v4/web-components/sw-ui-background.mdx b/...ges/v4/web-components/sw-ui-background.md → ...es/v4/web-components/sw-ui-background.mdx
diff --git a/...es/v4/web-components/sw-ui-call-layout.md → ...s/v4/web-components/sw-ui-call-layout.mdx b/...es/v4/web-components/sw-ui-call-layout.md → ...s/v4/web-components/sw-ui-call-layout.mdx
diff --git a/...v4/web-components/sw-ui-content-drawer.md → ...4/web-components/sw-ui-content-drawer.mdx b/...v4/web-components/sw-ui-content-drawer.md → ...4/web-components/sw-ui-content-drawer.mdx
diff --git a/...es/v4/web-components/sw-ui-control-bar.md → ...s/v4/web-components/sw-ui-control-bar.mdx b/...es/v4/web-components/sw-ui-control-bar.md → ...s/v4/web-components/sw-ui-control-bar.mdx
diff --git a/.../pages/v4/web-components/sw-ui-dialpad.md → ...pages/v4/web-components/sw-ui-dialpad.mdx b/.../pages/v4/web-components/sw-ui-dialpad.md → ...pages/v4/web-components/sw-ui-dialpad.mdx
diff --git a/...k/pages/v4/web-components/sw-ui-dropup.md → .../pages/v4/web-components/sw-ui-dropup.mdx b/...k/pages/v4/web-components/sw-ui-dropup.md → .../pages/v4/web-components/sw-ui-dropup.mdx
diff --git a/...sdk/pages/v4/web-components/sw-ui-icon.md → ...dk/pages/v4/web-components/sw-ui-icon.mdx b/...sdk/pages/v4/web-components/sw-ui-icon.md → ...dk/pages/v4/web-components/sw-ui-icon.mdx
diff --git a/...dk/pages/v4/web-components/sw-ui-modal.md → ...k/pages/v4/web-components/sw-ui-modal.mdx b/...dk/pages/v4/web-components/sw-ui-modal.md → ...k/pages/v4/web-components/sw-ui-modal.mdx
diff --git a/...-components/sw-ui-responsive-container.md → ...components/sw-ui-responsive-container.mdx b/...-components/sw-ui-responsive-container.md → ...components/sw-ui-responsive-container.mdx
diff --git a/...s/v4/web-components/sw-ui-split-button.md → .../v4/web-components/sw-ui-split-button.mdx b/...s/v4/web-components/sw-ui-split-button.md → .../v4/web-components/sw-ui-split-button.mdx
diff --git a/...4/web-components/sw-ui-transcript-view.md → .../web-components/sw-ui-transcript-view.mdx b/...4/web-components/sw-ui-transcript-view.md → .../web-components/sw-ui-transcript-view.mdx
diff --git a/fern/products/browser-sdk/versions/v4.yml b/fern/products/browser-sdk/versions/v4.yml
@@ -118,58 +118,58 @@ navigation:
       - section: Web Components
         contents:
           - page: Overview
-            path: ../pages/v4/web-components/index.md
+            path: ../pages/v4/web-components/index.mdx
           - page: sw-audio-level
-            path: ../pages/v4/web-components/sw-audio-level.md
+            path: ../pages/v4/web-components/sw-audio-level.mdx
           - page: sw-call-controls
-            path: ../pages/v4/web-components/sw-call-controls.md
+            path: ../pages/v4/web-components/sw-call-controls.mdx
           - page: sw-call-dialpad
-            path: ../pages/v4/web-components/sw-call-dialpad.md
+            path: ../pages/v4/web-components/sw-call-dialpad.mdx
           - page: sw-call-media
-            path: ../pages/v4/web-components/sw-call-media.md
+            path: ../pages/v4/web-components/sw-call-media.mdx
           - page: sw-call-provider
-            path: ../pages/v4/web-components/sw-call-provider.md
+            path: ../pages/v4/web-components/sw-call-provider.mdx
           - page: sw-call-status
-            path: ../pages/v4/web-components/sw-call-status.md
+            path: ../pages/v4/web-components/sw-call-status.mdx
           - page: sw-call-widget
-            path: ../pages/v4/web-components/sw-call-widget.md
+            path: ../pages/v4/web-components/sw-call-widget.mdx
           - page: sw-click-to-call
-            path: ../pages/v4/web-components/sw-click-to-call.md
+            path: ../pages/v4/web-components/sw-click-to-call.mdx
           - page: sw-device-selector
-            path: ../pages/v4/web-components/sw-device-selector.md
+            path: ../pages/v4/web-components/sw-device-selector.mdx
           - page: sw-directory
-            path: ../pages/v4/web-components/sw-directory.md
+            path: ../pages/v4/web-components/sw-directory.mdx
           - page: sw-local-camera
-            path: ../pages/v4/web-components/sw-local-camera.md
+            path: ../pages/v4/web-components/sw-local-camera.mdx
           - page: sw-participant-controls
-            path: ../pages/v4/web-components/sw-participant-controls.md
+            path: ../pages/v4/web-components/sw-participant-controls.mdx
           - page: sw-participants
-            path: ../pages/v4/web-components/sw-participants.md
+            path: ../pages/v4/web-components/sw-participants.mdx
           - page: sw-self-media
-            path: ../pages/v4/web-components/sw-self-media.md
+            path: ../pages/v4/web-components/sw-self-media.mdx
           - page: sw-ui-alert
-            path: ../pages/v4/web-components/sw-ui-alert.md
+            path: ../pages/v4/web-components/sw-ui-alert.mdx
           - page: sw-ui-background
-            path: ../pages/v4/web-components/sw-ui-background.md
+            path: ../pages/v4/web-components/sw-ui-background.mdx
           - page: sw-ui-call-layout
-            path: ../pages/v4/web-components/sw-ui-call-layout.md
+            path: ../pages/v4/web-components/sw-ui-call-layout.mdx
           - page: sw-ui-content-drawer
-            path: ../pages/v4/web-components/sw-ui-content-drawer.md
+            path: ../pages/v4/web-components/sw-ui-content-drawer.mdx
           - page: sw-ui-control-bar
-            path: ../pages/v4/web-components/sw-ui-control-bar.md
+            path: ../pages/v4/web-components/sw-ui-control-bar.mdx
           - page: sw-ui-dialpad
-            path: ../pages/v4/web-components/sw-ui-dialpad.md
+            path: ../pages/v4/web-components/sw-ui-dialpad.mdx
           - page: sw-ui-dropup
-            path: ../pages/v4/web-components/sw-ui-dropup.md
+            path: ../pages/v4/web-components/sw-ui-dropup.mdx
           - page: sw-ui-icon
-            path: ../pages/v4/web-components/sw-ui-icon.md
+            path: ../pages/v4/web-components/sw-ui-icon.mdx
           - page: sw-ui-modal
-            path: ../pages/v4/web-components/sw-ui-modal.md
+            path: ../pages/v4/web-components/sw-ui-modal.mdx
           - page: sw-ui-responsive-container
-            path: ../pages/v4/web-components/sw-ui-responsive-container.md
+            path: ../pages/v4/web-components/sw-ui-responsive-container.mdx
           - page: sw-ui-split-button
-            path: ../pages/v4/web-components/sw-ui-split-button.md
+            path: ../pages/v4/web-components/sw-ui-split-button.mdx
           - page: sw-ui-transcript-view
-            path: ../pages/v4/web-components/sw-ui-transcript-view.md
+            path: ../pages/v4/web-components/sw-ui-transcript-view.mdx
 
   - tab: click-to-call
diff --git a/package.json b/package.json
@@ -18,6 +18,8 @@
     "fern-check": "fern check",
     "fern-md-check": "fern docs md check",
     "check-links": "node scripts/check-links.js",
+    "check-md-exports": "node scripts/check-md-exports.js",
+    "test:scripts": "node --test \"scripts/**/*.test.js\"",
     "format:specs": "yarn workspace signalwire-docs-specs format",
     "format:specs:check": "yarn workspace signalwire-docs-specs format:check",
     "postman:build": "node scripts/postman/build-collection.mjs build",

diff --git a/scripts/README.md b/scripts/README.md
@@ -0,0 +1,79 @@
+# Scripts
+
+Maintenance and QA tooling for the docs repo. All scripts are plain Node (no
+dependencies beyond what's in `package.json`) and share conventions: hand-rolled
+`--flag` parsing with `-h`/`--help`, the shared logger in `utils/logger.js`
+(`LOGGER_LEVEL=debug` for verbose output), and exit codes suitable for CI.
+
+| Script | yarn alias | Purpose |
+|--------|------------|---------|
+| `check-links.js` | `yarn check-links` | Validate every link on the published site (lychee over the sitemap, plus local git-based verification of GitHub blob/tree/tag URLs). |
+| `check-md-exports.js` | `yarn check-md-exports` | Audit the `.md` exports and `llms.txt` indexes served for AI consumption. |
+| `check-md-exports.test.js` | `yarn test:scripts` | Fixture tests locking in `check-md-exports.js`'s detection heuristics. |
+| `postman/` | `yarn postman:build` / `postman:publish` | Build and publish the Postman collection from the OpenAPI specs. |
+| `utils/logger.js` | — | Shared leveled logger (text/JSON, collectors) used by the scripts above. |
+
+## check-md-exports.js
+
+Fern serves a machine-readable version of every docs page (append `.md` to the
+page URL) and per-product `llms.txt` indexes, which we advertise to AI tooling.
+This script audits that surface end to end — it exists because those exports
+have broken structurally before while the HTML site looked fine
+([#525](https://github.com/signalwire/docs/issues/525)).
+
+It crawls the `llms.txt` tree, fetches every listed `.md` export (~3,200 pages),
+and runs tiered checks per page:
+
+- **error** (exit code 1): soft/hard 404s for listed pages, near-empty bodies,
+  Fern components leaking unrendered (`<ParamField …>` verbatim in the export),
+  and *orphaned descriptions* — the #525 signature, a Properties/Parameters
+  section reduced to bare description blocks with zero defined terms.
+- **warn**: parameter terms with no description, raw HTML with class attributes
+  (visual-component leak-through, tracked under
+  [#388](https://github.com/signalwire/docs/issues/388)), HTML entity residue,
+  unknown JSX-ish tags in prose.
+- **info** (hidden without `--include-info`): floating link-reference
+  definitions, `sitemap.xml` vs `llms.txt` coverage diff.
+
+Code fences and inline code spans are stripped before the component/HTML checks,
+so code samples never false-positive.
+
+### Common invocations
+
+```bash
+# Full production audit (~3,200 pages; allow ~10–25 min depending on network)
+yarn check-md-exports
+
+# Iterate on one product, or one page
+yarn check-md-exports --product swml
+yarn check-md-exports --url https://signalwire.com/docs/swml/reference/errors.md
+
+# Audit a PR preview deployment
+yarn check-md-exports --base-url https://signalwire-preview-<id>.docs.buildwithfern.com/docs
+
+# Verify every <ParamField path="…"> from the MDX sources appears in the
+# deployed export. Reads the working tree by default, so a branch that is
+# ahead of / behind the deployed main reports drift — pass --source-ref to
+# read sources from the ref the site was actually built from.
+yarn check-md-exports --cross-check --product swml
+yarn check-md-exports --source-ref origin/main --product swml
+
+# Reports
+yarn check-md-exports --json report.json --output report.md
+```
+
+Run `yarn check-md-exports --help` for the full flag list (`--limit`,
+`--concurrency`, `--list`, `--no-sitemap-check`, …).
+
+### Exit codes
+
+`0` clean or warn/info only · `1` error-tier findings (CI-ready; not currently
+wired into a workflow) · `2` runtime/config error.
+
+### Tests
+
+`yarn test:scripts` runs the fixture suite in `check-md-exports.test.js` —
+canned markdown encoding the #525 regression shape, the legitimate page styles
+that must *not* fire, and the URL-mapping rules for `--cross-check`. If you tune
+a heuristic in `check-md-exports.js`, every fixture must still pass; add a new
+fixture for whatever prompted the tuning.