From 3ea27470ce24dbfd4a75a78e5d6d5d757c9c36a9 Mon Sep 17 00:00:00 2001
From: Abdelrahman Essawy <abdelrahman.mo.essawy@gmail.com>
Date: Sun, 24 May 2026 13:08:30 +0300
Subject: [PATCH 1/2] =?UTF-8?q?feat(docs):=20SEO/GEO=20sweep=20=E2=80=94?=
 =?UTF-8?q?=20sitelinks,=20JSON-LD,=20Y1=20billing=20accuracy,=20cross-lin?=
 =?UTF-8?q?ks?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

docs.json:
- Fixed em-dash in og:image:alt (banned 2026-05-24); now matches apex brand.slogan
- Added apex parity tags: twitter:image, twitter:image:alt, twitter:creator,
  format-detection, theme-color, author

Per-page (24 .mdx):
- keywords array on every page (5-8 lowercase terms per topic)
- Tightened 4 descriptions to verb-first + number for AI anchoring
- 18 new TechArticle JSON-LD + 1 FAQPage on support/faq
  (9 Q+A pairs auto-derived from existing Accordion blocks)
- All @id cross-reference apex #organization / #website for entity
  consolidation in AI knowledge graphs

Content drift fixes (verified against apex code, not just rules):
- support/faq: MCP tool count Five to Six (MCP_TOOL_NAMES.length)
  in both visible Accordion AND FAQPage JSON-LD
- support/faq: failure question rewritten for Y1 (charged on failure,
  no auto-refund, dispute route)
- quickstart: POST response status dispatched to waiting
- concepts/credits: removed pre-check / auto-refund language;
  added Negative balance / past_due subsection; swapped
  /billing/balance for real /billing/state shape; nanodollar narrative
- 33 stale rb_live_ / rb_test_ key examples normalized to canonical
  rb_* (no test mode exists in production)

Cross-linking (driving Google sitelinks + AI authority):
- 24/24 pages now end with ## Related section (5 entries each,
  colon-separated, includes apex backlink + 3+ docs links)
- ~14 inline cross-links added in body copy on first concept mention
- 13 prominent apex backlinks added (drives docs to apex authority flow)
- Zero weak anchors (here / click here / read more) anywhere in docs

Em-dash purge:
- 50+ hits in body, tables, headings scrubbed per writing-style rule
- Banned 2026-05-24 as AI-aesthetic tell

Internal links:
- 2 broken /credits paths fixed to /concepts/credits
---
 authentication.mdx             |  53 ++++++++++++----
 changelog/2026-03-20.mdx       |  31 ++++++++-
 cli/authentication.mdx         |  40 ++++++++++--
 cli/ci-cd.mdx                  |  34 ++++++++--
 cli/commands.mdx               |  34 ++++++++--
 cli/installation.mdx           |  30 ++++++++-
 cli/overview.mdx               |  28 +++++++-
 cli/troubleshooting.mdx        |  36 +++++++++--
 concepts/credits.mdx           |  77 ++++++++++++++++------
 concepts/job-lifecycle.mdx     |  41 ++++++++++--
 docs.json                      |   8 ++-
 guides/raw-ffmpeg.mdx          |  41 +++++++-----
 guides/webhooks.mdx            |  41 ++++++++++--
 job-types/captions-animate.mdx |  45 ++++++++++---
 job-types/raw-ffmpeg.mdx       |  39 ++++++++++--
 mcp/examples.mdx               |  37 +++++++++--
 mcp/installation.mdx           |  43 ++++++++++---
 mcp/overview.mdx               |  21 ++++--
 mcp/tools.mdx                  |  45 ++++++++++---
 mcp/troubleshooting.mdx        |  37 +++++++++--
 mcp/web-and-mobile.mdx         |  43 ++++++++++---
 quickstart.mdx                 |  41 +++++++-----
 support/errors.mdx             |  33 +++++++++-
 support/faq.mdx                | 113 ++++++++++++++++++++++++++++++---
 support/limits.mdx             |  41 ++++++++++--
 25 files changed, 849 insertions(+), 183 deletions(-)

diff --git a/authentication.mdx b/authentication.mdx
index 9143887..41d023a 100644
--- a/authentication.mdx
+++ b/authentication.mdx
@@ -1,25 +1,44 @@
 ---
 title: "Authentication"
-description: "Authenticate Rendobar API requests with a Bearer API key. Same keys cover REST, MCP, and the CLI. OAuth available for MCP clients."
+description: "Authenticate API requests with a Bearer API key. Same keys cover REST, MCP, and the CLI. OAuth available for MCP clients with native support."
 sidebarTitle: "Authentication"
 icon: "key"
+keywords: ["rendobar authentication", "api key", "bearer token", "rb_ key", "mcp oauth", "rest api auth"]
 ---
 
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/authentication/#article",
+      "headline": "Authentication",
+      "description": "Authenticate API requests with a Bearer API key. Same keys cover REST, MCP, and the CLI.",
+      "datePublished": "2026-03-20",
+      "dateModified": "2026-05-24",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
 Every Rendobar API request needs an API key in the `Authorization` header:
 
 ```bash
 curl https://api.rendobar.com/jobs \
-  -H "Authorization: Bearer rb_live_YOUR_KEY"
+  -H "Authorization: Bearer rb_YOUR_KEY"
 ```
 
-Keys start with `rb_live_` (production) or `rb_test_` (test mode). Get one from [app.rendobar.com](https://app.rendobar.com) → **Settings → API keys**. Test-mode jobs run end to end but don't consume credits.
+Keys start with `rb_`. Get one from [app.rendobar.com](https://app.rendobar.com) → **Settings → API keys**.
 
 ## Three credential types
 
 | Type | Where to use it |
 |---|---|
-| **API key** (`rb_live_*` / `rb_test_*`) | REST API, MCP, CLI in CI |
-| **Session cookie** (`rb_session`) | Dashboard browser sessions only — set automatically when you sign in |
+| **API key** (`rb_*`) | REST API, MCP, CLI in CI |
+| **Session cookie** (`rb_session`) | Dashboard browser sessions only (set automatically when you sign in) |
 | **OAuth 2.1 token** | MCP clients with native OAuth support, or the CLI's `rb login` browser flow |
 
 ## Use a key
@@ -28,12 +47,12 @@ Keys start with `rb_live_` (production) or `rb_test_` (test mode). Get one from
 
 ```bash cURL
 curl https://api.rendobar.com/jobs \
-  -H "Authorization: Bearer rb_live_YOUR_KEY"
+  -H "Authorization: Bearer rb_YOUR_KEY"
 ```
 
 ```javascript JavaScript
 const res = await fetch("https://api.rendobar.com/jobs", {
-  headers: { "Authorization": "Bearer rb_live_YOUR_KEY" },
+  headers: { "Authorization": "Bearer rb_YOUR_KEY" },
 });
 ```
 
@@ -41,7 +60,7 @@ const res = await fetch("https://api.rendobar.com/jobs", {
 import requests
 res = requests.get(
     "https://api.rendobar.com/jobs",
-    headers={"Authorization": "Bearer rb_live_YOUR_KEY"},
+    headers={"Authorization": "Bearer rb_YOUR_KEY"},
 )
 ```
 
@@ -54,13 +73,13 @@ Keys are scoped to an organization, not a user. Each key has a name. There's no
 ```bash
 # Create
 curl -X POST https://api.rendobar.com/api-keys \
-  -H "Authorization: Bearer rb_live_EXISTING_KEY" \
+  -H "Authorization: Bearer rb_EXISTING_KEY" \
   -H "Content-Type: application/json" \
   -d '{ "name": "CI Pipeline" }'
 
 # Revoke
 curl -X DELETE https://api.rendobar.com/api-keys/KEY_ID \
-  -H "Authorization: Bearer rb_live_YOUR_KEY"
+  -H "Authorization: Bearer rb_YOUR_KEY"
 ```
 
 Revoked keys return `401 UNAUTHORIZED` immediately.
@@ -69,9 +88,9 @@ Revoked keys return `401 UNAUTHORIZED` immediately.
 
 Every authenticated request resolves to:
 
-- `userId` — the authenticated user (when via session or OAuth)
-- `orgId` — the active organization
-- `plan` — current plan; controls rate limits, allowed job types, balance
+- `userId`: the authenticated user (when via session or OAuth)
+- `orgId`: the active organization
+- `plan`: current plan; controls [rate limits](/support/limits), allowed job types, [balance](/concepts/credits)
 
 Used for rate limiting, plan enforcement, and credit checks on every request.
 
@@ -95,3 +114,11 @@ HTTP `401`. Other auth-adjacent errors live in [Error codes](/support/errors).
 - [CLI authentication](/cli/authentication)
 - [MCP overview](/mcp/overview)
 - [Error codes](/support/errors)
+
+## Related
+
+- [Quickstart](/quickstart): submit your first job in under five minutes
+- [CLI authentication](/cli/authentication): `rb login` browser flow and CI key usage
+- [MCP overview](/mcp/overview): how API keys and OAuth work for AI agents
+- [Plan limits](/support/limits): rate limits and concurrency by plan
+- [Pricing](https://rendobar.com/pricing/): Free vs Pro and credit packs
diff --git a/changelog/2026-03-20.mdx b/changelog/2026-03-20.mdx
index d48bbdb..e25017b 100644
--- a/changelog/2026-03-20.mdx
+++ b/changelog/2026-03-20.mdx
@@ -1,9 +1,36 @@
 ---
 title: "Documentation site launch, 2026-03-20"
-description: "Explore the initial docs launch: raw.ffmpeg reference, webhook guide, and MCP integration docs. Powered by Mintlify with an AI-optimized content layer."
+description: "View the initial docs launch with the raw.ffmpeg reference, webhook guide, and MCP integration docs. Powered by Mintlify with AI-optimized content."
 icon: "sparkles"
+keywords: ["rendobar changelog", "rendobar releases", "docs launch", "rendobar 2026"]
 ---
 
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/changelog/2026-03-20/#article",
+      "headline": "Documentation site launch, 2026-03-20",
+      "description": "Initial docs launch: raw.ffmpeg reference, webhook guide, and MCP integration docs.",
+      "datePublished": "2026-03-20",
+      "dateModified": "2026-05-24",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
 <Update label="2026-03-20" description="Docs site live">
-Rendobar documentation is now live at [rendobar.com/docs](https://rendobar.com/docs). Includes the `raw.ffmpeg` reference, a webhooks guide, and MCP integration docs for AI agents. The site is powered by Mintlify with an interactive API playground and AI-optimized content.
+Rendobar documentation is now live at [rendobar.com/docs](https://rendobar.com/docs). Includes the [`raw.ffmpeg` reference](/job-types/raw-ffmpeg), a [webhooks guide](/guides/webhooks), and [MCP integration docs](/mcp/overview) for AI agents. The site is powered by Mintlify with an interactive API playground and AI-optimized content.
 </Update>
+
+## Related
+
+- [Quickstart](/quickstart): submit your first job in under five minutes
+- [raw.ffmpeg reference](/job-types/raw-ffmpeg): the live job type and its parameters
+- [MCP overview](/mcp/overview): connect any MCP-compatible agent to Rendobar
+- [Full release history](https://rendobar.com/changelog/): every shipped update on the marketing site
+- [Pricing](https://rendobar.com/pricing/): Free vs Pro and credit packs
diff --git a/cli/authentication.mdx b/cli/authentication.mdx
index 4ee9cc2..ddf5e1a 100644
--- a/cli/authentication.mdx
+++ b/cli/authentication.mdx
@@ -1,10 +1,28 @@
 ---
 title: "Authenticate the CLI"
-description: "Sign in via browser OAuth, paste an API key for non-interactive use, or set RENDOBAR_API_KEY for CI. Tokens auto-refresh."
+description: "Sign in via browser OAuth, paste an API key for non-interactive use, or set RENDOBAR_API_KEY for CI. Tokens auto-refresh every hour."
 icon: "key"
-keywords: ["rb login", "rendobar cli auth", "rendobar api key", "rendobar oauth"]
+keywords: ["rb login", "rendobar cli auth", "rendobar api key", "rendobar oauth", "rb whoami"]
 ---
 
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/cli/authentication/#article",
+      "headline": "Authenticate the CLI",
+      "description": "Sign in via browser OAuth, paste an API key for non-interactive use, or set RENDOBAR_API_KEY for CI.",
+      "datePublished": "2026-04-10",
+      "dateModified": "2026-05-24",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
 The CLI reads credentials from three sources, in priority order:
 
 1. `RENDOBAR_API_KEY` environment variable
@@ -31,7 +49,7 @@ If port `14832` is in use, login fails fast. Use `--key` instead.
 For SSH sessions, headless containers, or any environment without a browser:
 
 ```bash
-rb login --key rb_live_xxxxxxxxxxxxxxxxxxxxxxxx
+rb login --key rb_xxxxxxxxxxxxxxxxxxxxxxxx
 ```
 
 The CLI verifies the key against the API, then saves it. Keys must start with `rb_`. Get one from [app.rendobar.com](https://app.rendobar.com) → Settings → API keys.
@@ -41,7 +59,7 @@ The CLI verifies the key against the API, then saves it. Keys must start with `r
 `RENDOBAR_API_KEY` beats any saved credential and writes nothing to disk:
 
 ```bash
-export RENDOBAR_API_KEY=rb_live_xxx
+export RENDOBAR_API_KEY=rb_xxx
 rb ffmpeg -i input.mp4 -c:v libx264 -crf 23 out.mp4
 ```
 
@@ -69,7 +87,7 @@ After OAuth login the file looks like:
 After `--key`:
 
 ```json
-{ "type": "apikey", "apiKey": "rb_live_..." }
+{ "type": "apikey", "apiKey": "rb_..." }
 ```
 
 Treat the file as a secret. The CLI does not chmod it for you.
@@ -89,10 +107,10 @@ rb logout
 rb login
 ```
 
-There's no profile system. To run a single command against a different account or test mode, set the env var inline:
+There's no profile system. To run a single command against a different account, set the env var inline:
 
 ```bash
-RENDOBAR_API_KEY=rb_test_xxx rb ffmpeg -i clip.mp4 -c:v libx264 out.mp4
+RENDOBAR_API_KEY=rb_xxx rb ffmpeg -i clip.mp4 -c:v libx264 out.mp4
 ```
 
 ## Sign out
@@ -123,3 +141,11 @@ Hits `/orgs/current` and prints org, plan, balance. Useful as a CI sanity check
 - [Commands](/cli/commands)
 - [CI/CD](/cli/ci-cd)
 - [Authentication (API)](/authentication)
+
+## Related
+
+- [API authentication](/authentication): keys, OAuth, and session cookies across REST and MCP
+- [Commands reference](/cli/commands): every `rb` flag and exit code
+- [CI/CD](/cli/ci-cd): full GitHub Actions and GitLab CI snippets
+- [Troubleshooting](/cli/troubleshooting): `invalid_grant`, port conflicts, and refresh failures
+- [CLI source repo](https://github.com/rendobar/cli): release tags and issues
diff --git a/cli/ci-cd.mdx b/cli/ci-cd.mdx
index aeea520..5c5e945 100644
--- a/cli/ci-cd.mdx
+++ b/cli/ci-cd.mdx
@@ -1,11 +1,29 @@
 ---
 title: "Use the CLI in CI/CD"
-description: "Install rb in GitHub Actions, GitLab CI, or Docker. Authenticate from a secret, pin a version, parse JSON output, verify provenance."
+description: "Install rb in GitHub Actions, GitLab CI, or Docker. Authenticate from a secret, pin a version, parse JSON output, verify build provenance."
 sidebarTitle: "CI/CD"
 icon: "infinity"
-keywords: ["rendobar github actions", "rendobar cli ci", "rendobar gitlab", "rendobar docker"]
+keywords: ["rendobar github actions", "rendobar cli ci", "rendobar gitlab", "rendobar docker", "rb ci secret"]
 ---
 
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/cli/ci-cd/#article",
+      "headline": "Use the CLI in CI/CD",
+      "description": "Install rb in GitHub Actions, GitLab CI, or Docker. Authenticate from a secret, pin a version, parse JSON output.",
+      "datePublished": "2026-04-10",
+      "dateModified": "2026-05-24",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
 Three rules for any CI: pin the CLI version, authenticate from a secret, pick an output mode you can parse.
 
 ## GitHub Actions
@@ -90,10 +108,10 @@ docker run --rm -v $(pwd):/work -w /work \
 
 ## Authenticate from a secret
 
-`RENDOBAR_API_KEY` is the only auth path for CI. It beats any saved credential and writes nothing to disk. Don't run `rb login` in CI — the browser flow will hang.
+`RENDOBAR_API_KEY` is the only auth path for CI. It beats any saved credential and writes nothing to disk. Don't run `rb login` in CI. The browser flow will hang.
 
 ```bash
-export RENDOBAR_API_KEY=rb_live_xxx
+export RENDOBAR_API_KEY=rb_xxx
 rb whoami      # confirm before running anything else
 ```
 
@@ -149,3 +167,11 @@ The CLI does not expose `--idempotency-key`. If a retried CI step shouldn't doub
 - [Authentication](/cli/authentication)
 - [Commands](/cli/commands)
 - [Troubleshooting](/cli/troubleshooting)
+
+## Related
+
+- [CLI overview](/cli/overview): pick between CLI, SDK, and raw HTTP
+- [Authentication](/cli/authentication): `RENDOBAR_API_KEY` as the only CI-safe auth path
+- [Commands reference](/cli/commands): exit codes for boolean assertions
+- [raw.ffmpeg reference](/job-types/raw-ffmpeg): the API the CLI invokes per run
+- [Changelog](https://rendobar.com/changelog/): pin a release tag with confidence
diff --git a/cli/commands.mdx b/cli/commands.mdx
index 535048b..7b487cd 100644
--- a/cli/commands.mdx
+++ b/cli/commands.mdx
@@ -1,12 +1,30 @@
 ---
 title: "Commands reference"
-description: "Every rb command, every flag, every exit code. Covers ffmpeg, login, logout, whoami, doctor, and update."
+description: "View every rb command, flag, and exit code. Covers ffmpeg, login, logout, whoami, doctor, and update across 6 subcommands."
 sidebarTitle: "Commands"
 icon: "list"
-keywords: ["rb commands", "rendobar cli reference", "rb ffmpeg flags", "rb exit codes"]
+keywords: ["rb commands", "rendobar cli reference", "rb ffmpeg flags", "rb exit codes", "rb doctor"]
 mode: "wide"
 ---
 
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/cli/commands/#article",
+      "headline": "Commands reference",
+      "description": "Every rb command, every flag, every exit code.",
+      "datePublished": "2026-04-10",
+      "dateModified": "2026-05-24",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
 Reference for every `rb` command. Use the [overview](/cli/overview) for narrative.
 
 ## Global flags
@@ -73,7 +91,7 @@ Runs FFmpeg in the cloud. Pass real FFmpeg arguments after the subcommand. Globa
 
 Local input files (`-i ./clip.mp4`) upload automatically before submission and are rewritten to short-lived URLs. Remote inputs (`-i https://...`) pass through as-is.
 
-The trailing positional argument (the FFmpeg output filename) is the local path the result downloads to. With `--no-wait` no download happens — only the job ID prints.
+The trailing positional argument (the FFmpeg output filename) is the local path the result downloads to. With `--no-wait` no download happens. Only the job ID prints.
 
 Job-failure exits `1` and writes the API error to stderr. Insufficient credits exits `2` with a top-up link.
 
@@ -111,7 +129,7 @@ Credential paths and storage details: [Authentication](/cli/authentication).
 
 ```bash
 rb login
-rb login --key rb_live_xxx
+rb login --key rb_xxx
 ```
 
 ---
@@ -164,3 +182,11 @@ Exits `2` if not authenticated, `1` if the API call fails.
 - [Authentication](/cli/authentication)
 - [CI/CD](/cli/ci-cd)
 - [Troubleshooting](/cli/troubleshooting)
+
+## Related
+
+- [CLI overview](/cli/overview): narrative quickstart for `rb ffmpeg`
+- [Authentication](/cli/authentication): `rb login` flow and credential storage
+- [CI/CD](/cli/ci-cd): parse `--json` output and authenticate from a secret
+- [raw.ffmpeg reference](/job-types/raw-ffmpeg): the underlying API call
+- [Changelog](https://rendobar.com/changelog/): release notes for every `rb` version
diff --git a/cli/installation.mdx b/cli/installation.mdx
index 2b4b11a..4363819 100644
--- a/cli/installation.mdx
+++ b/cli/installation.mdx
@@ -1,10 +1,28 @@
 ---
 title: "Install the CLI"
-description: "Install the rb binary on macOS, Linux, or Windows. Pin a version, change the install path, run inside Docker, or uninstall."
+description: "Install the rb binary on macOS, Linux, or Windows in one command. Pin a version, change the install path, run inside Docker, or uninstall."
 icon: "download"
-keywords: ["install rendobar cli", "rb install", "rendobar windows install", "rendobar docker"]
+keywords: ["install rendobar cli", "rb install", "rendobar windows install", "rendobar docker", "rb doctor"]
 ---
 
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/cli/installation/#article",
+      "headline": "Install the CLI",
+      "description": "Install the rb binary on macOS, Linux, or Windows in one command.",
+      "datePublished": "2026-04-10",
+      "dateModified": "2026-05-24",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
 Install the `rb` binary in one command, on any of the three supported platforms.
 
 <Tabs>
@@ -123,3 +141,11 @@ The uninstaller removes the binary and the PATH entry. Add `RENDOBAR_PURGE=1` to
 - [Troubleshooting](/cli/troubleshooting)
 
 For version history and release notes, see the [changelog](https://rendobar.com/changelog/).
+
+## Related
+
+- [CLI overview](/cli/overview): what the `rb` binary does and when to pick it
+- [Authentication](/cli/authentication): `rb login`, API keys, CI credentials
+- [CI/CD](/cli/ci-cd): pin a version and authenticate from a secret
+- [Troubleshooting](/cli/troubleshooting): install, PATH, and Gatekeeper fixes
+- [Changelog](https://rendobar.com/changelog/): version history and release notes
diff --git a/cli/overview.mdx b/cli/overview.mdx
index 683d521..a7e21e2 100644
--- a/cli/overview.mdx
+++ b/cli/overview.mdx
@@ -3,9 +3,27 @@ title: "CLI overview and quickstart"
 sidebarTitle: "Overview"
 description: "Run FFmpeg in the cloud from your terminal. Pass real ffmpeg flags; the CLI uploads local files, runs the job, and downloads the result."
 icon: "terminal"
-keywords: ["rb cli", "rendobar command line", "ffmpeg cli", "cloud ffmpeg"]
+keywords: ["rb cli", "rendobar command line", "ffmpeg cli", "cloud ffmpeg", "rb ffmpeg"]
 ---
 
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/cli/overview/#article",
+      "headline": "CLI overview and quickstart",
+      "description": "Run FFmpeg in the cloud from your terminal. The CLI uploads local files, runs the job, and downloads the result.",
+      "datePublished": "2026-04-10",
+      "dateModified": "2026-05-24",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
 The Rendobar CLI runs FFmpeg in the cloud from your shell. You write the same `ffmpeg` command you'd run locally, prefixed with `rb`.
 
 <Frame>
@@ -73,3 +91,11 @@ The CLI does one thing: run FFmpeg jobs. It does not bundle filter chaining, bat
 - [Commands](/cli/commands)
 - [CI/CD](/cli/ci-cd)
 - [Troubleshooting](/cli/troubleshooting)
+
+## Related
+
+- [Installation](/cli/installation): one-line install, pin a version, Docker, uninstall
+- [Commands reference](/cli/commands): every `rb` subcommand, flag, and exit code
+- [CI/CD](/cli/ci-cd): GitHub Actions, GitLab CI, and Docker recipes
+- [raw.ffmpeg reference](/job-types/raw-ffmpeg): the API the CLI calls under the hood
+- [FFmpeg in the cloud](https://rendobar.com/ffmpeg/): supported operations on the marketing site
diff --git a/cli/troubleshooting.mdx b/cli/troubleshooting.mdx
index a935c53..7def2b7 100644
--- a/cli/troubleshooting.mdx
+++ b/cli/troubleshooting.mdx
@@ -1,11 +1,29 @@
 ---
 title: "CLI troubleshooting"
-description: "Fix common rb CLI errors: install failures, PATH issues, port conflicts, macOS Gatekeeper, expired tokens, rate limits, update rollback."
+description: "Troubleshoot common rb CLI errors: install failures, PATH issues, port conflicts, macOS Gatekeeper, expired tokens, rate limits, update rollback."
 sidebarTitle: "Troubleshooting"
 icon: "stethoscope"
-keywords: ["rb cli error", "rendobar cli not found", "rendobar login failed", "rb doctor"]
+keywords: ["rb cli error", "rendobar cli not found", "rendobar login failed", "rb doctor", "rb update failed"]
 ---
 
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/cli/troubleshooting/#article",
+      "headline": "CLI troubleshooting",
+      "description": "Fix common rb CLI errors: install failures, PATH issues, port conflicts, macOS Gatekeeper, expired tokens, rate limits.",
+      "datePublished": "2026-04-10",
+      "dateModified": "2026-05-24",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
 Run this first:
 
 ```bash
@@ -48,7 +66,7 @@ xattr -d com.apple.quarantine $(which rb)
 
 ## Login
 
-**Port 14832 in use.** Another process holds the OAuth callback port. Free it (`lsof -i :14832`) or skip the browser flow: `rb login --key rb_live_xxx`.
+**Port 14832 in use.** Another process holds the OAuth callback port. Free it (`lsof -i :14832`) or skip the browser flow: `rb login --key rb_xxx`.
 
 **Login timed out.** The browser flow waits 120 seconds. Re-run `rb login`. If your network blocks loopback HTTP (some corporate firewalls do), use `--key` instead.
 
@@ -61,7 +79,7 @@ xattr -d com.apple.quarantine $(which rb)
 **`Not authenticated. Run rb login or set RENDOBAR_API_KEY`.** No credentials saved or file corrupt. Pick one:
 
 - Interactive: `rb login`
-- CI: `export RENDOBAR_API_KEY=rb_live_xxx`
+- CI: `export RENDOBAR_API_KEY=rb_xxx`
 - Inspect what the CLI sees: `rb whoami`
 
 **Insufficient credits.** Exits `2` with a top-up link. Top up at [app.rendobar.com/billing](https://app.rendobar.com/billing). Check balance with `rb whoami`.
@@ -74,7 +92,7 @@ rb ffmpeg --json -i in.mp4 -c:v libx264 out.mp4 | jq .
 
 `error.code` and `error.message` are the canonical failure reason.
 
-**Local input file isn't being uploaded.** The CLI treats arguments after `-i` as inputs. A local input is detected only when the path is after `-i`, doesn't look like a URL, and exists on disk. Custom filter graphs reading files via `movie=` won't be detected — upload manually and pass a URL.
+**Local input file isn't being uploaded.** The CLI treats arguments after `-i` as inputs. A local input is detected only when the path is after `-i`, doesn't look like a URL, and exists on disk. Custom filter graphs reading files via `movie=` won't be detected. Upload manually and pass a URL.
 
 ## Update
 
@@ -140,3 +158,11 @@ A TLS error like `unable to verify the first certificate` is the symptom.
 - [Authentication](/cli/authentication)
 - [Commands](/cli/commands)
 - [API errors](/support/errors)
+
+## Related
+
+- [Installation](/cli/installation): re-install steps, PATH variables, version pinning
+- [Authentication](/cli/authentication): `rb login` and credential-file layout
+- [Commands](/cli/commands): exit codes, output modes, every flag
+- [API errors](/support/errors): the canonical `error.code` catalogue
+- [CLI source repo](https://github.com/rendobar/cli): file a bug or check the latest release
diff --git a/concepts/credits.mdx b/concepts/credits.mdx
index 350f35c..1bd82d9 100644
--- a/concepts/credits.mdx
+++ b/concepts/credits.mdx
@@ -1,20 +1,39 @@
 ---
 title: "Credits and billing"
 sidebarTitle: "Credits"
-description: "Get per-job nanodollar billing from a prepaid balance. Free plan ships with $5, Pro is $9/mo. Credits never expire and failed jobs cost nothing."
+description: "Get per-job nanodollar billing from a prepaid balance. Free plan ships with $5, Pro is $9/mo. Credits never expire. Every terminal job is charged for actual compute used."
 icon: "coins"
+keywords: ["credit-based billing", "nanodollar pricing", "rendobar credits", "video api credits", "prepaid balance"]
 ---
 
-Per-job billing from a prepaid credit balance. New accounts get $5 free. Failed jobs are never charged.
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/concepts/credits/#article",
+      "headline": "Credits and billing",
+      "description": "Per-job nanodollar billing from a prepaid balance. Free plan ships with $5, Pro is $9/mo. Credits never expire. Every terminal job is charged for actual compute used.",
+      "datePublished": "2026-03-20",
+      "dateModified": "2026-05-24",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
+Per-job billing from a prepaid credit balance. New accounts get $5 free. Every terminal job is charged for the compute it consumed, including jobs that fail.
 
 ## Plans
 
 | | Free | Pro |
 |---|---|---|
 | Price | $0/mo | $9/mo |
-| Signup credits | $5 (one-time) | — |
-| Monthly credits included | — | $5 |
-| Credit-purchase bonus | — | +20% |
+| Signup credits | $5 (one-time) | - |
+| Monthly credits included | - | $5 |
+| Credit-purchase bonus | - | +20% |
 | Concurrent jobs | 1 | 25 |
 | API requests/min | 30 | 300 |
 | Max input file | 100 MB | 2 GB |
@@ -28,7 +47,7 @@ For a full pricing breakdown and plan comparison, see [rendobar.com/pricing/](ht
 
 ## Credit packs
 
-$10 / $25 / $50 / $100 (or custom, $10 minimum). Pro adds **+20%** to every purchase — buy $25, get $30. Credits never expire.
+$10 / $25 / $50 / $100 (or custom, $10 minimum). Pro adds **+20%** to every purchase. Buy $25, get $30. Credits never expire.
 
 ## How it works: nanodollar billing
 
@@ -39,16 +58,20 @@ Every job is billed in nanodollars (one-billionth of a US dollar) drawn from you
 
 ## Credit lifecycle
 
-1. **Pre-check.** Submit triggers a balance check against the estimated cost. No deduction. Insufficient balance returns `402 INSUFFICIENT_CREDITS`.
+1. **Submit gate.** Submit is atomic. If your balance is greater than zero and you are under your concurrent-job limit, the job runs. We do not estimate cost up front. Insufficient balance returns `402 INSUFFICIENT_CREDITS`.
 2. **Execution.** Job runs. Balance untouched.
-3. **Debit.** On success, actual cost is computed (real compute time or output duration) and atomically deducted.
-4. **Refund.** Failure or cancellation never deducts. Failed jobs cost zero.
+3. **Debit on terminal status.** Every terminal job (`complete`, `failed`, or `cancelled`) is charged based on actual provider cost, infrastructure cost, and margin. The debit is atomic with the status update.
+4. **No auto-refund.** Failed jobs are still charged for the compute they consumed. If you believe a job failed due to a platform bug, contact support. Refunds are issued at our discretion via the dispute process.
+
+## Negative balance
+
+Because the submit gate checks `balance > 0` rather than an estimate, a single long-running job can drive your balance briefly negative when the terminal debit lands. When that happens, your subscription flips to `past_due` and further submits are blocked with `402 INSUFFICIENT_CREDITS` until you top up. Once your balance is positive again, normal billing resumes.
 
 ## Cost model
 
-`raw.ffmpeg` bills per compute second — wall-clock time FFmpeg ran your command, excluding upload/download. Typical cost: ~$0.05/min.
+`raw.ffmpeg` bills per compute second, which is the wall-clock time FFmpeg ran your command, excluding upload and download. Typical cost: ~$0.05/min. The same per-second rate applies whether the job completes successfully or fails partway through.
 
-Before submitting, the API checks your balance covers the estimated cost. If not:
+If your balance is at or below zero when you submit:
 
 ```json
 { "error": { "code": "INSUFFICIENT_CREDITS", "message": "Not enough credits for this job" } }
@@ -59,21 +82,28 @@ HTTP `402`. Top up at [app.rendobar.com/billing](https://app.rendobar.com/billin
 ## Check your balance
 
 ```bash
-curl https://api.rendobar.com/billing/balance \
-  -H "Authorization: Bearer rb_live_YOUR_KEY"
+curl https://api.rendobar.com/billing/state \
+  -H "Authorization: Bearer rb_YOUR_KEY"
 ```
 
 ```json
-{ "data": { "balance": 5000000000, "rollover": 0 } }
+{
+  "data": {
+    "balance": { "amount": 5.0 },
+    "plan": { "slug": "free", "name": "Free" },
+    "subscription": { "status": "active", "cancelAtPeriodEnd": false },
+    "isPro": false
+  }
+}
 ```
 
-`balance` is in nanodollars (1 USD = 1,000,000,000). The dashboard shows it in dollars.
+`balance.amount` is in dollars. Internally balances are stored in nanodollars (1 USD = 1,000,000,000).
 
 ## Usage tracking
 
 ```bash
 curl "https://api.rendobar.com/billing/usage?start=2026-02-01&end=2026-02-09" \
-  -H "Authorization: Bearer rb_live_YOUR_KEY"
+  -H "Authorization: Bearer rb_YOUR_KEY"
 ```
 
 Returns daily usage by job type: count, amount charged, and compute seconds.
@@ -81,11 +111,18 @@ Returns daily usage by job type: count, amount charged, and compute seconds.
 ## Practical advice
 
 - **Start on Free.** $5 signup grant covers many hundreds of small jobs.
-- **Use `rb_test_*` keys while building.** Test-mode runs the full pipeline, returns real output, and doesn't deduct credits.
 - **Store `cost.nanodollars` from every response.** Reconcile against your monthly invoice.
 
 ## See also
 
-- [Job lifecycle](/concepts/job-lifecycle) — where the debit happens
-- [Limits](/support/limits) — full quota table
-- [raw.ffmpeg reference](/job-types/raw-ffmpeg) — the live cost model
+- [Job lifecycle](/concepts/job-lifecycle): where the debit happens
+- [Limits](/support/limits): full quota table
+- [raw.ffmpeg reference](/job-types/raw-ffmpeg): the live cost model
+
+## Related
+
+- [Plan limits and quotas](/support/limits): exact rate, file, and storage caps per plan
+- [Job lifecycle](/concepts/job-lifecycle): when the debit lands and what statuses mean
+- [Error codes](/support/errors): `INSUFFICIENT_CREDITS`, `PLAN_LIMIT`, and friends
+- [Pricing](https://rendobar.com/pricing/): plan comparison and credit packs
+- [FAQ on cost](/support/faq): common pricing and billing questions
diff --git a/concepts/job-lifecycle.mdx b/concepts/job-lifecycle.mdx
index 3d1d206..eecea8d 100644
--- a/concepts/job-lifecycle.mdx
+++ b/concepts/job-lifecycle.mdx
@@ -1,10 +1,29 @@
 ---
 title: "Job lifecycle"
-description: "Explore job status transitions from waiting to complete, what triggers each state, timeout behavior, retries, and real-time update consumption."
+description: "View job status transitions across 6 states from waiting to complete, what triggers each, timeout behavior, retries, and real-time updates."
 sidebarTitle: "Job lifecycle"
 icon: "rotate"
+keywords: ["job lifecycle", "job status", "waiting complete failed", "video processing job states", "rendobar status"]
 ---
 
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/concepts/job-lifecycle/#article",
+      "headline": "Job lifecycle",
+      "description": "Job status transitions across 6 states from waiting to complete, what triggers each, timeout behavior, retries, and real-time updates.",
+      "datePublished": "2026-03-20",
+      "dateModified": "2026-05-24",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
 Every job moves through six statuses:
 
 ```
@@ -18,13 +37,13 @@ waiting → dispatched → running → complete
 | `waiting` | Saved, queued for dispatch |
 | `dispatched` | Sent to the execution provider (Trigger.dev) |
 | `running` | Provider has started processing |
-| `complete` | Finished successfully — output available |
-| `failed` | Errored — see `error.code` and `error.message` |
+| `complete` | Finished successfully. Output available |
+| `failed` | Errored. See `error.code` and `error.message` |
 | `cancelled` | Cancelled before completion |
 
 ## Each transition
 
-**Submission → `waiting`.** Auth, rate limit, plan, credit pre-check, schema validation. If all pass, job is saved.
+**Submission → `waiting`.** Auth, [rate limit](/support/limits), plan, [credit pre-check](/concepts/credits), schema validation. If all pass, job is saved.
 
 **Dispatch → `dispatched`.** Routed to an available provider. The provider receives presigned URLs for input download and output upload.
 
@@ -55,15 +74,15 @@ To manually retry a failed job:
 
 ```bash
 curl -X POST https://api.rendobar.com/jobs/job_abc/retry \
-  -H "Authorization: Bearer rb_live_YOUR_KEY"
+  -H "Authorization: Bearer rb_YOUR_KEY"
 ```
 
 ## Real-time updates
 
 Two ways to stop polling:
 
-- **[Webhooks](/guides/webhooks)** — push events to your server. Recommended for production.
-- **WebSocket (dashboard)** — the dashboard streams creation, status, progress, and balance over a per-org hub. Currently dashboard-only; programmatic clients should use webhooks.
+- **[Webhooks](/guides/webhooks)**: push events to your server. Recommended for production.
+- **WebSocket (dashboard)**: the dashboard streams creation, status, progress, and balance over a per-org hub. Currently dashboard-only. Programmatic clients should use webhooks.
 
 ## See also
 
@@ -71,3 +90,11 @@ Two ways to stop polling:
 - [Webhooks](/guides/webhooks)
 - [Error codes](/support/errors)
 - [How credits work](/concepts/credits)
+
+## Related
+
+- [Webhooks](/guides/webhooks): push status changes to your server instead of polling
+- [Credits and billing](/concepts/credits): when and how the terminal debit lands
+- [Error codes](/support/errors): every `error.code` returned by failed jobs
+- [Raw FFmpeg](/guides/raw-ffmpeg): what runs between `dispatched` and `complete`
+- [Changelog](https://rendobar.com/changelog/): platform changes that affect job behavior
diff --git a/docs.json b/docs.json
index c694619..10a9611 100644
--- a/docs.json
+++ b/docs.json
@@ -194,10 +194,16 @@
       "og:image": "https://rendobar.com/brand/og-default.jpg",
       "og:image:width": "1200",
       "og:image:height": "630",
-      "og:image:alt": "Rendobar — Serverless media processing API",
+      "og:image:alt": "Rendobar: Media processing API for developers and agents",
       "og:image:type": "image/jpeg",
       "twitter:card": "summary_large_image",
       "twitter:site": "@rendobar",
+      "twitter:image": "https://rendobar.com/brand/og-default.jpg",
+      "twitter:image:alt": "Rendobar: Media processing API for developers and agents",
+      "twitter:creator": "@rendobar",
+      "format-detection": "telephone=no",
+      "theme-color": "#0A0A0A",
+      "author": "Rendobar",
       "robots": "index, follow, max-image-preview:large, max-snippet:-1, max-video-preview:-1"
     }
   },
diff --git a/guides/raw-ffmpeg.mdx b/guides/raw-ffmpeg.mdx
index 96d9898..a131b51 100644
--- a/guides/raw-ffmpeg.mdx
+++ b/guides/raw-ffmpeg.mdx
@@ -1,8 +1,9 @@
 ---
 title: "Raw FFmpeg guide"
 sidebarTitle: "Raw FFmpeg"
-description: "Run any FFmpeg command in the cloud. Whitelisted flags, sandboxed execution, signed download URL. Same FFmpeg syntax you already know."
+description: "Run any FFmpeg command in the cloud. ~120 whitelisted flags, 8-layer sandboxed execution, signed download URL. Same FFmpeg syntax you know."
 icon: "terminal"
+keywords: ["ffmpeg guide", "ffmpeg in cloud", "ffmpeg sandboxed execution", "ffmpeg flags whitelist", "raw ffmpeg api"]
 ---
 
 <script
@@ -27,7 +28,7 @@ You write the FFmpeg command. Rendobar downloads inputs, runs the command in an
 
 ```bash
 curl -X POST https://api.rendobar.com/jobs \
-  -H "Authorization: Bearer rb_live_YOUR_KEY" \
+  -H "Authorization: Bearer rb_YOUR_KEY" \
   -H "Content-Type: application/json" \
   -d '{
     "type": "raw.ffmpeg",
@@ -39,25 +40,25 @@ curl -X POST https://api.rendobar.com/jobs \
 ```
 
 <Tip>
-From a shell? Use [the CLI](/cli/overview): `rb ffmpeg -i input.mp4 -vf scale=1280:720 out.mp4` — local files upload automatically.
+From a shell? Use [the CLI](/cli/overview): `rb ffmpeg -i input.mp4 -vf scale=1280:720 out.mp4`. Local files upload automatically.
 </Tip>
 
 ## How it runs
 
-1. **Validate** — command parsed against 8 security layers (flag whitelist, format/filter blocklists)
-2. **Download** — input URLs pulled to a sandboxed worker
-3. **Substitute** — URLs replaced with local paths in the FFmpeg command
-4. **Execute** — FFmpeg runs in an isolated container with network disabled
-5. **Upload** — output goes to R2
-6. **Return** — signed `outputUrl` available via `GET /jobs/{id}`
+1. **Validate**: command parsed against 8 security layers (flag whitelist, format/filter blocklists)
+2. **Download**: input URLs pulled to a sandboxed worker
+3. **Substitute**: URLs replaced with local paths in the FFmpeg command
+4. **Execute**: FFmpeg runs in an isolated container with network disabled
+5. **Upload**: output goes to R2
+6. **Return**: signed `outputUrl` available via `GET /jobs/{id}`
 
 ## Parameters
 
 | Field | Type | Required | Default | Notes |
 |---|---|---|---|---|
-| `type` | string | yes | — | `"raw.ffmpeg"` |
-| `inputs` | object | yes | — | `{}` when URLs are inline in the command. Otherwise a name→URL map matching filenames in the command |
-| `params.command` | string | yes | — | Real FFmpeg command starting with `ffmpeg`. Input URLs go in `-i` positions |
+| `type` | string | yes | - | `"raw.ffmpeg"` |
+| `inputs` | object | yes | - | `{}` when URLs are inline in the command. Otherwise a name→URL map matching filenames in the command |
+| `params.command` | string | yes | - | Real FFmpeg command starting with `ffmpeg`. Input URLs go in `-i` positions |
 | `params.outputFormat` | string | no | inferred | Override container format. Inferred from trailing filename if omitted |
 | `params.timeout` | int | no | `120` | Server-side max execution in seconds. Range 1–900 |
 
@@ -110,9 +111,9 @@ Eight layers, in order:
 
 ## Cost & timeout
 
-Priced per compute second — wall-clock time FFmpeg ran, excluding file transfer. Typical cost ~$0.05/min.
+Priced per compute second from your [credit balance](/concepts/credits), the wall-clock time FFmpeg ran, excluding file transfer. Typical cost ~$0.05/min.
 
-Plan timeouts: 5 min (Free), 15 min (Pro). Exceeding the timeout returns `PROVIDER_TIMEOUT`; no credits charged.
+Plan timeouts: 5 min (Free), 15 min (Pro). See [plan limits](/support/limits) for the full table. Exceeding the timeout returns `PROVIDER_TIMEOUT`; no credits charged.
 
 ## Examples
 
@@ -184,9 +185,15 @@ Full error catalogue: [Error codes](/support/errors).
 
 - [raw.ffmpeg reference](/job-types/raw-ffmpeg)
 - [CLI](/cli/overview)
-- [Webhooks](/guides/webhooks) — push instead of poll
+- [Webhooks](/guides/webhooks): push instead of poll
 - [Credits and billing](/concepts/credits)
 
----
-
 For a full list of FFmpeg-based operations supported by the API, see [rendobar.com/ffmpeg/](https://rendobar.com/ffmpeg/).
+
+## Related
+
+- [raw.ffmpeg reference](/job-types/raw-ffmpeg): typed parameters, response shape, plan caps
+- [CLI overview](/cli/overview): run the same job from your terminal with `rb ffmpeg`
+- [Error codes](/support/errors): `VALIDATION_ERROR`, `PROVIDER_ERROR`, `PROVIDER_TIMEOUT`
+- [Webhooks](/guides/webhooks): receive `job.completed` instead of polling
+- [FFmpeg operations index](https://rendobar.com/ffmpeg/): every supported operation on the marketing site
diff --git a/guides/webhooks.mdx b/guides/webhooks.mdx
index 1bd93e5..52edd06 100644
--- a/guides/webhooks.mdx
+++ b/guides/webhooks.mdx
@@ -1,17 +1,36 @@
 ---
-title: "Webhooks: deliver job events"
-description: "Receive job status events via signed HMAC POST. Setup, payload format, signature verification, retry policy. Available on all plans."
+title: "Webhooks for job events"
+description: "Receive job status events via signed HMAC POST. Setup, payload format, signature verification, 3-attempt retry policy. Available on all plans."
 sidebarTitle: "Webhooks"
 icon: "bell"
+keywords: ["webhooks", "hmac signature", "job status webhook", "rendobar webhook setup", "signed webhook"]
 ---
 
-Rendobar POSTs JSON to your endpoint when a job changes status. Available on all plans, including Free.
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/guides/webhooks/#article",
+      "headline": "Webhooks for job events",
+      "description": "Receive job status events via signed HMAC POST. Setup, payload format, signature verification, retry policy.",
+      "datePublished": "2026-03-20",
+      "dateModified": "2026-05-24",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
+Rendobar POSTs JSON to your endpoint when a [job](/concepts/job-lifecycle) changes status. Available on all plans, including Free.
 
 ## Set up a webhook
 
 ```bash
 curl -X POST https://api.rendobar.com/webhook-endpoints \
-  -H "Authorization: Bearer rb_live_YOUR_KEY" \
+  -H "Authorization: Bearer rb_YOUR_KEY" \
   -H "Content-Type: application/json" \
   -d '{
     "name": "Production webhook",
@@ -20,7 +39,7 @@ curl -X POST https://api.rendobar.com/webhook-endpoints \
   }'
 ```
 
-Required: `name` (1–50 chars), `url` (must be HTTPS), `subscribedEvents` (≥ 1). The response includes a signing secret (`whsec_...`) — store it; you'll verify every payload against it.
+Required: `name` (1–50 chars), `url` (must be HTTPS), `subscribedEvents` (≥ 1). The response includes a signing secret (`whsec_...`). Store it. You'll verify every payload against it.
 
 Manage endpoints (create, update, delete, test) via the API or the dashboard.
 
@@ -143,7 +162,7 @@ After three failures the delivery is marked failed. Inspect history:
 
 ```bash
 curl https://api.rendobar.com/webhook-endpoints/YOUR_ENDPOINT_ID/deliveries \
-  -H "Authorization: Bearer rb_live_YOUR_KEY"
+  -H "Authorization: Bearer rb_YOUR_KEY"
 ```
 
 ## Best practices
@@ -157,4 +176,12 @@ curl https://api.rendobar.com/webhook-endpoints/YOUR_ENDPOINT_ID/deliveries \
 - [Job lifecycle](/concepts/job-lifecycle)
 - [Raw FFmpeg](/guides/raw-ffmpeg)
 - [Error codes](/support/errors)
-- [MCP](/mcp/overview) — alternative push channel for AI agents
+- [MCP](/mcp/overview): alternative push channel for AI agents
+
+## Related
+
+- [Job lifecycle](/concepts/job-lifecycle): what each status means before `job.completed` fires
+- [Error codes](/support/errors): codes you'll see inside `job.failed` payloads
+- [Raw FFmpeg](/guides/raw-ffmpeg): the job type that drives most webhook traffic
+- [MCP overview](/mcp/overview): alternative push channel for AI agent clients
+- [Changelog](https://rendobar.com/changelog/): webhook payload changes and new events
diff --git a/job-types/captions-animate.mdx b/job-types/captions-animate.mdx
index d85b033..0f4afe2 100644
--- a/job-types/captions-animate.mdx
+++ b/job-types/captions-animate.mdx
@@ -1,10 +1,29 @@
 ---
 title: "captions.animate"
-description: "Burn animated word-level captions onto a video. Pick a built-in preset (hormozi, mrbeast, tiktok, pill). Single speaker, 5 minute input cap."
+description: "Burn animated word-level captions onto a video at $0.10/min. Pick a preset (hormozi, mrbeast, tiktok, pill). Single speaker, 5 min input cap."
 icon: "captions"
 tag: "Live"
+keywords: ["animated captions", "burn subtitles", "whisper captions", "tiktok captions", "ass subtitles", "captions.animate"]
 ---
 
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/job-types/captions-animate/#article",
+      "headline": "captions.animate",
+      "description": "Burn animated word-level captions onto a video. Pick a preset (hormozi, mrbeast, tiktok, pill). Single speaker, 5 min input cap.",
+      "datePublished": "2026-05-03",
+      "dateModified": "2026-05-24",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
 <Check>
 **Live.** Production-ready, available on all plans.
 </Check>
@@ -21,7 +40,7 @@ Returns a video with word-level animated captions burned in. Speech is transcrib
 
 ```bash cURL
 curl -X POST https://api.rendobar.com/jobs \
-  -H "Authorization: Bearer rb_live_YOUR_KEY" \
+  -H "Authorization: Bearer rb_YOUR_KEY" \
   -H "Content-Type: application/json" \
   -d '{
     "type": "captions.animate",
@@ -39,7 +58,7 @@ curl -X POST https://api.rendobar.com/jobs \
 const res = await fetch("https://api.rendobar.com/jobs", {
   method: "POST",
   headers: {
-    "Authorization": "Bearer rb_live_YOUR_KEY",
+    "Authorization": "Bearer rb_YOUR_KEY",
     "Content-Type": "application/json",
   },
   body: JSON.stringify({
@@ -60,7 +79,7 @@ const { data } = await res.json();
 import requests
 res = requests.post(
     "https://api.rendobar.com/jobs",
-    headers={"Authorization": "Bearer rb_live_YOUR_KEY"},
+    headers={"Authorization": "Bearer rb_YOUR_KEY"},
     json={
         "type": "captions.animate",
         "inputs": {
@@ -88,9 +107,9 @@ res = requests.post(
 
 <ParamField body="mode" type="enum" default="balanced">
   Speed-vs-accuracy tradeoff for transcription.
-  - `fast` — `base.en`, English only, ~3× faster, ~7-9% WER
-  - `balanced` — `small.en`, default, ~5-7% WER
-  - `accurate` — `large-v3-turbo`, ~3× slower, ~3-4% WER
+  - `fast`: `base.en`, English only, ~3× faster, ~7-9% WER
+  - `balanced`: `small.en`, default, ~5-7% WER
+  - `accurate`: `large-v3-turbo`, ~3× slower, ~3-4% WER
 </ParamField>
 
 ## Response
@@ -103,9 +122,17 @@ Poll `GET /jobs/{id}` until `status: "complete"`, then read `outputUrl` (signed,
 
 ## Pricing
 
-$0.10 per input minute. Billed against your credit balance on completion.
+$0.10 per input minute. Billed against your [credit balance](/concepts/credits) on completion.
 
 ## See also
 
 - [Job lifecycle](/concepts/job-lifecycle)
-- [Credits](/credits)
+- [Credits and billing](/concepts/credits)
+
+## Related
+
+- [Job lifecycle](/concepts/job-lifecycle): the six statuses captioning jobs move through
+- [Credits and billing](/concepts/credits): how the per-minute charge debits your balance
+- [raw.ffmpeg](/job-types/raw-ffmpeg): the lower-level job for custom subtitle workflows
+- [Webhooks](/guides/webhooks): get `job.completed` instead of polling captioning jobs
+- [Caption-styling features](https://rendobar.com/features/): every preset and visual option
diff --git a/job-types/raw-ffmpeg.mdx b/job-types/raw-ffmpeg.mdx
index ad1a1e0..28bfdcd 100644
--- a/job-types/raw-ffmpeg.mdx
+++ b/job-types/raw-ffmpeg.mdx
@@ -1,11 +1,30 @@
 ---
 title: "raw.ffmpeg reference"
 sidebarTitle: "raw.ffmpeg"
-description: "Execute a custom FFmpeg command with whitelisted flags, sandboxed execution, and signed output URL. Live on all plans."
+description: "Execute a custom FFmpeg command via API with ~120 whitelisted flags, sandboxed execution, and signed output URL. Live on all plans, ~$0.05/min."
 icon: "terminal"
 tag: "Live"
+keywords: ["raw ffmpeg", "ffmpeg api reference", "ffmpeg cloud", "ffmpeg sandboxed", "ffmpeg rest api"]
 ---
 
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/job-types/raw-ffmpeg/#article",
+      "headline": "raw.ffmpeg reference",
+      "description": "Execute a custom FFmpeg command with whitelisted flags, sandboxed execution, and signed output URL. Live on all plans.",
+      "datePublished": "2026-03-20",
+      "dateModified": "2026-05-24",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
 <Check>
 **Live.** Production-ready, available on all plans.
 </Check>
@@ -22,7 +41,7 @@ Execute a custom FFmpeg command with whitelisted flags. Input files go in `-i` p
 
 ```bash cURL
 curl -X POST https://api.rendobar.com/jobs \
-  -H "Authorization: Bearer rb_live_YOUR_KEY" \
+  -H "Authorization: Bearer rb_YOUR_KEY" \
   -H "Content-Type: application/json" \
   -d '{
     "type": "raw.ffmpeg",
@@ -37,7 +56,7 @@ curl -X POST https://api.rendobar.com/jobs \
 const res = await fetch("https://api.rendobar.com/jobs", {
   method: "POST",
   headers: {
-    "Authorization": "Bearer rb_live_YOUR_KEY",
+    "Authorization": "Bearer rb_YOUR_KEY",
     "Content-Type": "application/json",
   },
   body: JSON.stringify({
@@ -55,7 +74,7 @@ const { data } = await res.json();
 import requests
 res = requests.post(
     "https://api.rendobar.com/jobs",
-    headers={"Authorization": "Bearer rb_live_YOUR_KEY"},
+    headers={"Authorization": "Bearer rb_YOUR_KEY"},
     json={
         "type": "raw.ffmpeg",
         "inputs": {},
@@ -92,6 +111,14 @@ Poll `GET /jobs/{id}` until `status: "complete"`, then read `outputUrl` (signed,
 
 ## See also
 
-- [Raw FFmpeg guide](/guides/raw-ffmpeg) — security model, allowed flags, examples
-- [CLI](/cli/overview) — same job, terminal interface
+- [Raw FFmpeg guide](/guides/raw-ffmpeg): security model, allowed flags, examples
+- [CLI](/cli/overview): same job, terminal interface
 - [Job lifecycle](/concepts/job-lifecycle)
+
+## Related
+
+- [Raw FFmpeg guide](/guides/raw-ffmpeg): security layers, allowed flags, worked examples
+- [CLI overview](/cli/overview): the same job from your terminal with `rb ffmpeg`
+- [Credits and billing](/concepts/credits): per-compute-second pricing detail
+- [Plan limits](/support/limits): file-size caps, timeouts, and concurrency per plan
+- [FFmpeg in the cloud](https://rendobar.com/ffmpeg/): every operation Rendobar supports
diff --git a/mcp/examples.mdx b/mcp/examples.mdx
index 25643e0..93ef9d9 100644
--- a/mcp/examples.mdx
+++ b/mcp/examples.mdx
@@ -1,10 +1,29 @@
 ---
 title: "Burn captions onto a local video"
-description: "Build a captioned video with Claude Desktop in 8 minutes: install the MCP server, hand a local mp4 to your agent, and get back a captioned file."
+description: "Build a captioned video with Claude Desktop in 8 minutes. Install the MCP server, hand a local mp4 to your agent, and get back a captioned file."
 sidebarTitle: "Examples"
 icon: "play"
+keywords: ["mcp example", "claude desktop video", "burn captions agent", "rendobar mcp tutorial", "ai video agent"]
 ---
 
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/mcp/examples/#article",
+      "headline": "Burn captions onto a local video",
+      "description": "Build a captioned video with Claude Desktop in 8 minutes via the MCP server.",
+      "datePublished": "2026-04-01",
+      "dateModified": "2026-05-24",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
 In this tutorial we'll use Claude Desktop to caption a local video. The agent uploads it to Rendobar, runs an FFmpeg job that burns subtitles into the video, and returns a download URL. End-to-end takes about eight minutes.
 
 You will need:
@@ -32,7 +51,7 @@ Open Claude Desktop and ask:
 
 > What MCP tools do you have for Rendobar?
 
-The agent lists `upload_file`, `submit_job`, `get_job`, `list_jobs`, `cancel_job`, `get_account`. If it doesn't, the MCP isn't loaded — re-check your config and restart Claude Desktop.
+The agent lists `upload_file`, `submit_job`, `get_job`, `list_jobs`, `cancel_job`, `get_account`. If it doesn't, the MCP isn't loaded. Re-check your config and restart Claude Desktop.
 
 ## Step 2: Check the balance
 
@@ -72,6 +91,14 @@ The output file lives at `cdn.rendobar.com` for 24 hours by default, then auto-d
 
 ## Next
 
-- [Tools reference](/mcp/tools) — full schemas for every tool
-- [`raw.ffmpeg` job type](/job-types/raw-ffmpeg) — what FFmpeg commands are accepted
-- [Troubleshooting](/mcp/troubleshooting) — when something goes wrong
+- [Tools reference](/mcp/tools): full schemas for every tool
+- [`raw.ffmpeg` job type](/job-types/raw-ffmpeg): what FFmpeg commands are accepted
+- [Troubleshooting](/mcp/troubleshooting): when something goes wrong
+
+## Related
+
+- [Tools reference](/mcp/tools): every typed MCP tool with parameter shapes
+- [Installation](/mcp/installation): per-client config blocks if you skipped step 1
+- [raw.ffmpeg guide](/guides/raw-ffmpeg): the FFmpeg security model the agent runs against
+- [Troubleshooting](/mcp/troubleshooting): fixes when tool calls hang or the agent sees no tools
+- [MCP product overview](https://rendobar.com/mcp/): more agent capability examples
diff --git a/mcp/installation.mdx b/mcp/installation.mdx
index e4801b8..2d581f1 100644
--- a/mcp/installation.mdx
+++ b/mcp/installation.mdx
@@ -3,13 +3,32 @@ title: "Install the MCP server"
 sidebarTitle: "Installation"
 description: "Configure the local stdio MCP server for Claude Desktop, Cursor, Cline, Windsurf, Zed, VS Code, Claude Code, or Continue. Takes 2 minutes."
 icon: "download"
+keywords: ["install rendobar mcp", "claude desktop config", "cursor mcp install", "npx rendobar mcp", "windsurf mcp"]
 ---
 
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/mcp/installation/#article",
+      "headline": "Install the MCP server",
+      "description": "Configure the local stdio MCP server for Claude Desktop, Cursor, Cline, Windsurf, Zed, VS Code, Claude Code, or Continue.",
+      "datePublished": "2026-04-01",
+      "dateModified": "2026-05-24",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
 Configure your AI client to spawn `@rendobar/mcp` via `npx`. The server reads local files, submits jobs to `api.rendobar.com`, and streams results back.
 
 ## 1. Get an API key
 
-Sign in at [app.rendobar.com](https://app.rendobar.com) → Settings → API Keys → **Create key**. Copy the `rb_live_...` value.
+Sign in at [app.rendobar.com](https://app.rendobar.com) → Settings → API Keys → **Create key**. Copy the `rb_...` value.
 
 ## 2. Configure your client
 
@@ -27,7 +46,7 @@ Edit the config file:
     "rendobar": {
       "command": "npx",
       "args": ["-y", "@rendobar/mcp"],
-      "env": { "RENDOBAR_API_KEY": "rb_live_..." }
+      "env": { "RENDOBAR_API_KEY": "rb_..." }
     }
   }
 }
@@ -46,7 +65,7 @@ Edit `~/.cursor/mcp.json` (global) or `<project>/.cursor/mcp.json` (project-scop
     "rendobar": {
       "command": "npx",
       "args": ["-y", "@rendobar/mcp"],
-      "env": { "RENDOBAR_API_KEY": "rb_live_..." }
+      "env": { "RENDOBAR_API_KEY": "rb_..." }
     }
   }
 }
@@ -74,7 +93,7 @@ Edit `~/.config/zed/settings.json`. Note the key is `context_servers`, not `mcpS
       "source": "custom",
       "command": "npx",
       "args": ["-y", "@rendobar/mcp"],
-      "env": { "RENDOBAR_API_KEY": "rb_live_..." }
+      "env": { "RENDOBAR_API_KEY": "rb_..." }
     }
   }
 }
@@ -113,7 +132,7 @@ VS Code prompts for the key on first use and stores it in the keychain.
 Run from a terminal:
 
 ```bash
-claude mcp add rendobar -s user --env RENDOBAR_API_KEY=rb_live_... -- npx -y @rendobar/mcp
+claude mcp add rendobar -s user --env RENDOBAR_API_KEY=rb_... -- npx -y @rendobar/mcp
 ```
 
 </Tab>
@@ -126,7 +145,7 @@ type: stdio
 command: npx
 args: ["-y", "@rendobar/mcp"]
 env:
-  RENDOBAR_API_KEY: rb_live_...
+  RENDOBAR_API_KEY: rb_...
 ```
 
 </Tab>
@@ -136,7 +155,7 @@ env:
 
 Open a chat in your client and ask: *"What's my Rendobar balance?"*
 
-The agent calls `get_account` and reports your balance. If you see "RENDOBAR_API_KEY missing" in your client's MCP logs, the env var didn't propagate — re-check the config block.
+The agent calls `get_account` and reports your balance. If you see "RENDOBAR_API_KEY missing" in your client's MCP logs, the env var didn't propagate. Re-check the config block.
 
 ## Requirements
 
@@ -151,7 +170,7 @@ The server reads credentials in this order, first match wins:
 2. `RENDOBAR_API_KEY` environment variable
 3. `~/.config/rendobar/credentials.json` (Unix) or `%APPDATA%\rendobar\credentials.json` (Windows)
 
-The credentials file format is `{ "apiKey": "rb_live_...", "apiBase": "https://api.rendobar.com" }`. The Rendobar CLI's `rb login` command writes this file automatically.
+The credentials file format is `{ "apiKey": "rb_...", "apiBase": "https://api.rendobar.com" }`. The Rendobar CLI's `rb login` command writes this file automatically.
 
 ## Updating
 
@@ -163,3 +182,11 @@ The credentials file format is `{ "apiKey": "rb_live_...", "apiBase": "https://a
 - [Burn captions onto a local video](/mcp/examples)
 - [Troubleshooting](/mcp/troubleshooting)
 - [Web and mobile setup](/mcp/web-and-mobile)
+
+## Related
+
+- [MCP overview](/mcp/overview): pick the right transport for your client
+- [Tools reference](/mcp/tools): schemas for every MCP tool you'll call
+- [Burn captions onto a local video](/mcp/examples): end-to-end Claude Desktop walkthrough
+- [Troubleshooting](/mcp/troubleshooting): fixes for missing API key, PATH, and Node version issues
+- [MCP server for AI agents](https://rendobar.com/mcp/): product overview and capability list
diff --git a/mcp/overview.mdx b/mcp/overview.mdx
index a2e3d2a..6ce5bda 100644
--- a/mcp/overview.mdx
+++ b/mcp/overview.mdx
@@ -3,6 +3,7 @@ title: "MCP server overview"
 sidebarTitle: "Overview"
 description: "Connect AI agents via two transports: a local stdio server for IDE clients (Claude Desktop, Cursor) and a remote HTTP server for web and mobile."
 icon: "plug"
+keywords: ["mcp server", "model context protocol", "claude desktop mcp", "cursor mcp", "ai agent video tools", "rendobar mcp"]
 ---
 
 <script
@@ -23,7 +24,7 @@ icon: "plug"
   }}
 />
 
-Rendobar exposes its API as a Model Context Protocol server so AI agents can submit jobs, upload files, and check status without writing HTTP code. There are two servers — pick by client.
+Rendobar exposes its API as a Model Context Protocol server so AI agents can submit jobs, upload files, and check status without writing HTTP code. There are two servers. Pick by client.
 
 ## Pick a transport
 
@@ -42,7 +43,7 @@ Rendobar exposes its API as a Model Context Protocol server so AI agents can sub
 
 ## Why two servers
 
-The MCP spec has no primitive for streaming bytes from a client to a remote server. A remote MCP can submit jobs but cannot read a file off your laptop — the agent has to dictate a curl command and wait for you to paste back the URL.
+The MCP spec has no primitive for streaming bytes from a client to a remote server. A remote MCP can submit jobs but cannot read a file off your laptop. The agent has to dictate a curl command and wait for you to paste back the URL.
 
 The local server runs on your machine, has access to your files, and uploads them in a single tool call. That is the difference.
 
@@ -59,14 +60,14 @@ Both servers expose the same six job-related tools. Local adds `upload_file` for
 | `list_jobs` | ✓ | ✓ | Recent jobs with filters |
 | `cancel_job` | ✓ | ✓ | Cancel a waiting/dispatched job |
 | `get_account` | ✓ | ✓ | Balance, plan, limits |
-| `upload_file` | ✓ | — | Read local file, upload, return URL |
-| `upload_media` | — | ✓ | Return upload endpoint + curl command |
+| `upload_file` | ✓ | - | Read local file, upload, return URL |
+| `upload_media` | - | ✓ | Return upload endpoint + curl command |
 
 Full schemas: [Tools reference](/mcp/tools).
 
 ## Authentication
 
-Both servers use a Rendobar API key (`rb_live_*` or `rb_test_*`). Get one at [app.rendobar.com](https://app.rendobar.com) → Settings → API Keys.
+Both servers use a Rendobar API key (`rb_*`). Get one at [app.rendobar.com](https://app.rendobar.com) → Settings → API Keys. See [authentication](/authentication) for the full credential model.
 
 - Local: `RENDOBAR_API_KEY` env var, `--api-key` flag, or credentials file
 - Remote: `Authorization: Bearer` header
@@ -78,6 +79,12 @@ Both servers use a Rendobar API key (`rb_live_*` or `rb_test_*`). Get one at [ap
 - [Burn captions onto a local video](/mcp/examples)
 - [Web and mobile setup](/mcp/web-and-mobile)
 
----
-
 The MCP server gives AI agents full access to the same operations available via REST. For a complete list of supported job types, see [rendobar.com/mcp/](https://rendobar.com/mcp/).
+
+## Related
+
+- [MCP tools reference](/mcp/tools): every typed tool with parameters and response shapes
+- [Install for Claude Desktop and other clients](/mcp/installation): per-client config blocks
+- [Connect from web and mobile](/mcp/web-and-mobile): remote HTTP transport for claude.ai and ChatGPT
+- [Authentication](/authentication): API key and OAuth flows for MCP clients
+- [MCP server for AI agents](https://rendobar.com/mcp/): product overview and capability list
diff --git a/mcp/tools.mdx b/mcp/tools.mdx
index 91c6b46..51b11b9 100644
--- a/mcp/tools.mdx
+++ b/mcp/tools.mdx
@@ -1,10 +1,29 @@
 ---
 title: "MCP tools reference"
-description: "Schemas, parameters, response shapes, and annotations for every tool exposed by @rendobar/mcp and the remote HTTP MCP server."
+description: "View schemas, parameters, response shapes, and annotations for the 7 tools exposed by @rendobar/mcp and the remote HTTP MCP server."
 sidebarTitle: "Tools reference"
 icon: "wrench"
+keywords: ["mcp tools", "submit_job", "get_job", "list_jobs", "probe_media", "upload_media", "upload_file"]
 ---
 
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/mcp/tools/#article",
+      "headline": "MCP tools reference",
+      "description": "Schemas, parameters, response shapes, and annotations for every tool exposed by @rendobar/mcp and the remote HTTP MCP server.",
+      "datePublished": "2026-04-01",
+      "dateModified": "2026-05-24",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
 Tool definitions for both Rendobar MCP servers. The local stdio server (`@rendobar/mcp`) exposes six tools including `upload_file`. The remote HTTP server keeps `upload_media` for browser-based clients that have no disk access.
 
 ## Annotations
@@ -127,14 +146,14 @@ Current account state.
 
 **Returns:**
 
-- `balance` — formatted dollars, e.g. `"$29.42"`
-- `balanceUsd` — raw number
-- `plan` — `free | pro`
-- `isPro` — boolean
-- `limits.concurrentJobs` — max concurrent jobs
-- `limits.maxFileSize` — formatted, e.g. `"100 MB"`
-- `limits.maxFileSizeBytes` — raw integer
-- `limits.jobTimeoutMin` — per-job timeout in minutes
+- `balance`: formatted dollars, e.g. `"$29.42"`
+- `balanceUsd`: raw number
+- `plan`: `free | pro`
+- `isPro`: boolean
+- `limits.concurrentJobs`: max concurrent jobs
+- `limits.maxFileSize`: formatted, e.g. `"100 MB"`
+- `limits.maxFileSizeBytes`: raw integer
+- `limits.jobTimeoutMin`: per-job timeout in minutes
 
 ## Errors
 
@@ -151,3 +170,11 @@ Common codes: `UNAUTHORIZED`, `INSUFFICIENT_CREDITS`, `RATE_LIMITED`, `VALIDATIO
 - [Install for your client](/mcp/installation)
 - [Burn captions onto a local video](/mcp/examples)
 - [Job types](/job-types/raw-ffmpeg)
+
+## Related
+
+- [MCP overview](/mcp/overview): when to pick local stdio vs remote HTTP transport
+- [Installation](/mcp/installation): config blocks for every supported client
+- [Burn captions onto a local video](/mcp/examples): worked tool-call sequence end to end
+- [raw.ffmpeg reference](/job-types/raw-ffmpeg): the main job type called by `submit_job`
+- [MCP product overview](https://rendobar.com/mcp/): capability list and positioning
diff --git a/mcp/troubleshooting.mdx b/mcp/troubleshooting.mdx
index 2457c9d..da6dfe7 100644
--- a/mcp/troubleshooting.mdx
+++ b/mcp/troubleshooting.mdx
@@ -1,10 +1,29 @@
 ---
 title: "MCP troubleshooting"
-description: "Fix common MCP server failures: missing API key, Cursor PATH on macOS, Windows npx.cmd quirks, minimum Node version, and stdout pollution."
+description: "Troubleshoot common MCP server failures: missing API key, Cursor PATH on macOS, Windows npx.cmd quirks, Node 20+ requirement, stdout pollution."
 sidebarTitle: "Troubleshooting"
 icon: "wrench"
+keywords: ["rendobar mcp error", "mcp not loading", "claude desktop mcp not working", "cursor mcp path", "mcp api key"]
 ---
 
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/mcp/troubleshooting/#article",
+      "headline": "MCP troubleshooting",
+      "description": "Fix common MCP server failures: missing API key, Cursor PATH on macOS, Windows npx.cmd quirks, Node 20+ requirement.",
+      "datePublished": "2026-04-01",
+      "dateModified": "2026-05-24",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
 Known failures with the local stdio server (`@rendobar/mcp`) and the fixes. Errors are quoted from the actual stderr the server emits.
 
 ## "No Rendobar API key found"
@@ -48,7 +67,7 @@ Cursor launched from the macOS Dock inherits the GUI environment, not your shell
     "rendobar": {
       "command": "/Users/you/.nvm/versions/node/v20.18.0/bin/npx",
       "args": ["-y", "@rendobar/mcp"],
-      "env": { "RENDOBAR_API_KEY": "rb_live_..." }
+      "env": { "RENDOBAR_API_KEY": "rb_..." }
     }
   }
 }
@@ -81,11 +100,11 @@ File size (250000000 bytes) exceeds plan limit (104857600 bytes). Upgrade your p
 
 Free plan caps uploads at 100 MB. Pro plan caps at 2 GB. Either compress the file before upload or upgrade.
 
-Check your current limit by asking the agent: *"What's my Rendobar max upload size?"* — it calls `get_account`.
+Check your current limit by asking the agent: *"What's my Rendobar max upload size?"*. It calls `get_account`.
 
 ## Server boots but agent reports no tools
 
-The handshake succeeded but `tools/list` returned empty. This is rare — usually means the package version is corrupt.
+The handshake succeeded but `tools/list` returned empty. This is rare. It usually means the package version is corrupt.
 
 **Fix:** clear the npx cache and reinstall:
 
@@ -98,7 +117,7 @@ You should see a version string like `1.0.1`. If not, file an [issue](https://gi
 
 ## Agent uploaded the wrong file
 
-`upload_file` resolves relative paths against the working directory of the MCP server process — usually your home directory or the directory the IDE was launched from. Always use absolute paths in your prompts to be unambiguous.
+`upload_file` resolves relative paths against the working directory of the MCP server process, usually your home directory or the directory the IDE was launched from. Always use absolute paths in your prompts to be unambiguous.
 
 ## See also
 
@@ -106,3 +125,11 @@ You should see a version string like `1.0.1`. If not, file an [issue](https://gi
 - [Tools reference](/mcp/tools)
 - [Errors](/support/errors)
 - [Report a bug](https://github.com/rendobar/mcp/issues)
+
+## Related
+
+- [Installation](/mcp/installation): the per-client config that may need fixing
+- [MCP overview](/mcp/overview): transport picker if local stdio keeps failing
+- [Tools reference](/mcp/tools): verify the tool you called actually exists
+- [Plan limits](/support/limits): file-size caps behind "exceeds plan limit" errors
+- [MCP product overview](https://rendobar.com/mcp/): supported clients at a glance
diff --git a/mcp/web-and-mobile.mdx b/mcp/web-and-mobile.mdx
index 7979f66..7d50f1b 100644
--- a/mcp/web-and-mobile.mdx
+++ b/mcp/web-and-mobile.mdx
@@ -3,11 +3,30 @@ title: "Use the MCP from claude.ai or ChatGPT"
 sidebarTitle: "Web and mobile"
 description: "Connect web and mobile AI clients to the remote HTTP MCP at api.rendobar.com/mcp. Local file uploads require an extra curl step to upload first."
 icon: "globe"
+keywords: ["claude.ai mcp", "chatgpt mcp", "remote mcp server", "rendobar streamable http", "browser mcp"]
 ---
 
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/mcp/web-and-mobile/#article",
+      "headline": "Use the MCP from claude.ai or ChatGPT",
+      "description": "Connect web and mobile AI clients to the remote HTTP MCP at api.rendobar.com/mcp.",
+      "datePublished": "2026-04-01",
+      "dateModified": "2026-05-24",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
 Browser and mobile clients can't run a local stdio MCP server. Use the remote HTTP server at `https://api.rendobar.com/mcp` instead. Job submission and status polling work the same as local; local file uploads require an extra step.
 
-If you're on a desktop with Claude Desktop, Cursor, Cline, Windsurf, Zed, VS Code, Claude Code, or Continue — install [the local server](/mcp/installation) instead. It's a better fit.
+If you're on a desktop with Claude Desktop, Cursor, Cline, Windsurf, Zed, VS Code, Claude Code, or Continue, install [the local server](/mcp/installation) instead. It's a better fit.
 
 ## Connect
 
@@ -19,9 +38,9 @@ In claude.ai, open **Settings** → **Connectors** → **Add custom connector**:
 - **Name:** Rendobar
 - **URL:** `https://api.rendobar.com/mcp`
 - **Authentication:** Bearer token
-- **Token:** your `rb_live_...` API key
+- **Token:** your `rb_...` API key
 
-Save. Start a new chat — the agent has access to Rendobar tools.
+Save. Start a new chat. The agent has access to Rendobar tools.
 
 </Tab>
 <Tab title="ChatGPT Apps">
@@ -29,7 +48,7 @@ Save. Start a new chat — the agent has access to Rendobar tools.
 In ChatGPT, go to **Settings** → **Apps & Connectors** → **Custom**:
 
 - **MCP server URL:** `https://api.rendobar.com/mcp`
-- **Authentication header:** `Authorization: Bearer rb_live_...`
+- **Authentication header:** `Authorization: Bearer rb_...`
 
 </Tab>
 <Tab title="Custom client">
@@ -38,7 +57,7 @@ Any MCP-compatible client supporting Streamable HTTP transport works:
 
 - **Transport:** Streamable HTTP
 - **URL:** `https://api.rendobar.com/mcp`
-- **Header:** `Authorization: Bearer rb_live_...`
+- **Header:** `Authorization: Bearer rb_...`
 
 </Tab>
 </Tabs>
@@ -53,7 +72,7 @@ The remote server can't read your laptop. When an agent calls `upload_media`, th
 
 ```bash
 curl -X POST \
-  -H "Authorization: Bearer rb_live_..." \
+  -H "Authorization: Bearer rb_..." \
   -H "Content-Type: video/mp4" \
   --data-binary @./video.mp4 \
   "https://api.rendobar.com/uploads?filename=video.mp4"
@@ -65,10 +84,18 @@ For agents to upload files in a single tool call, install [the local server](/mc
 
 ## Limits
 
-Rate limits, file-size caps, and credit consumption are identical to REST and to the local MCP. They are per-organization, not per-tool.
+[Rate limits](/support/limits), file-size caps, and [credit consumption](/concepts/credits) are identical to REST and to the local MCP. They are per-organization, not per-tool.
 
 ## See also
 
 - [Tools reference](/mcp/tools)
-- [Local installation](/mcp/installation) — for desktop and IDE clients
+- [Local installation](/mcp/installation): for desktop and IDE clients
 - [Authentication](/authentication)
+
+## Related
+
+- [MCP overview](/mcp/overview): why local stdio exists alongside remote HTTP
+- [Tools reference](/mcp/tools): the six shared tools plus `upload_media` schema
+- [Authentication](/authentication): API keys and Bearer header details
+- [Local installation](/mcp/installation): switch back to stdio when you're on desktop
+- [MCP product overview](https://rendobar.com/mcp/): every supported client at a glance
diff --git a/quickstart.mdx b/quickstart.mdx
index 9fe1ff2..1f623e3 100644
--- a/quickstart.mdx
+++ b/quickstart.mdx
@@ -3,6 +3,7 @@ title: "API quickstart guide"
 sidebarTitle: "Quickstart"
 description: "Submit your first raw.ffmpeg job, poll to completion, and download the result. Under 5 minutes from API key to finished MP4."
 icon: "rocket"
+keywords: ["rendobar quickstart", "ffmpeg api tutorial", "first api call", "video processing quickstart", "raw ffmpeg job"]
 ---
 
 <script
@@ -23,11 +24,11 @@ icon: "rocket"
   }}
 />
 
-Get an API key, submit a `raw.ffmpeg` job, poll until complete, download the output.
+Get an API key, submit a [`raw.ffmpeg`](/job-types/raw-ffmpeg) job, poll until complete, download the output.
 
 ## 1. Get an API key
 
-Sign up at [app.rendobar.com](https://app.rendobar.com) and create a key from **Settings → API keys**. Keys start with `rb_`. New accounts get $5 in free credits.
+Sign up at [app.rendobar.com](https://app.rendobar.com) and create a key from **Settings → API keys**. Keys start with `rb_`. New accounts get $5 in free [credits](/concepts/credits).
 
 Prefer the terminal? Skip steps 2–4 and use [the CLI](/cli/overview) instead.
 
@@ -37,7 +38,7 @@ Prefer the terminal? Skip steps 2–4 and use [the CLI](/cli/overview) instead.
 
 ```bash cURL
 curl -X POST https://api.rendobar.com/jobs \
-  -H "Authorization: Bearer rb_live_YOUR_KEY" \
+  -H "Authorization: Bearer rb_YOUR_KEY" \
   -H "Content-Type: application/json" \
   -d '{
     "type": "raw.ffmpeg",
@@ -52,7 +53,7 @@ curl -X POST https://api.rendobar.com/jobs \
 const res = await fetch("https://api.rendobar.com/jobs", {
   method: "POST",
   headers: {
-    "Authorization": "Bearer rb_live_YOUR_KEY",
+    "Authorization": "Bearer rb_YOUR_KEY",
     "Content-Type": "application/json",
   },
   body: JSON.stringify({
@@ -72,7 +73,7 @@ import requests
 
 res = requests.post(
     "https://api.rendobar.com/jobs",
-    headers={"Authorization": "Bearer rb_live_YOUR_KEY"},
+    headers={"Authorization": "Bearer rb_YOUR_KEY"},
     json={
         "type": "raw.ffmpeg",
         "inputs": {},
@@ -91,23 +92,23 @@ Put input URLs directly in `-i` flags. The output format is inferred from the tr
 Response:
 
 ```json
-{ "data": { "id": "job_abc123", "status": "dispatched" } }
+{ "data": { "id": "job_abc123", "status": "waiting" } }
 ```
 
 ## 3. Poll for completion
 
 ```bash
 curl https://api.rendobar.com/jobs/job_abc123 \
-  -H "Authorization: Bearer rb_live_YOUR_KEY"
+  -H "Authorization: Bearer rb_YOUR_KEY"
 ```
 
-Statuses: `waiting → dispatched → running → complete | failed | cancelled`. Poll every 1–2 seconds.
+Statuses: `waiting → dispatched → running → complete | failed | cancelled`. See [job lifecycle](/concepts/job-lifecycle) for what each status means. Poll every 1–2 seconds.
 
 For push instead of poll, configure a [webhook](/guides/webhooks).
 
 ## 4. Download the result
 
-When `status` is `complete`, the response contains `outputUrl` — a signed R2 URL valid for one hour:
+When `status` is `complete`, the response contains `outputUrl`, a signed R2 URL valid for one hour:
 
 ```json
 {
@@ -124,13 +125,19 @@ Re-fetch the job to refresh the URL after it expires.
 
 ## What's next
 
-- [Rendobar CLI](/cli/overview) — skip the curl, run `rb ffmpeg` from your terminal
-- [Authentication](/authentication) — keys, sessions, MCP auth
-- [Raw FFmpeg](/guides/raw-ffmpeg) — full guide with the security model and examples
-- [Webhooks](/guides/webhooks) — push events instead of polling
-- [Credits and billing](/concepts/credits) — plans, balance, billing
-- [MCP](/mcp/overview) — drive Rendobar from an AI agent
+- [Rendobar CLI](/cli/overview): skip the curl, run `rb ffmpeg` from your terminal
+- [Authentication](/authentication): keys, sessions, MCP auth
+- [Raw FFmpeg](/guides/raw-ffmpeg): full guide with the security model and examples
+- [Webhooks](/guides/webhooks): push events instead of polling
+- [Credits and billing](/concepts/credits): plans, balance, billing
+- [MCP](/mcp/overview): drive Rendobar from an AI agent
 
----
+Need more credits? See [pricing](https://rendobar.com/pricing/) for plan and credit-pack options.
+
+## Related
 
-Need a different plan? [See pricing](https://rendobar.com/pricing/) or [explore all supported operations](https://rendobar.com/features/).
+- [Authentication](/authentication): how API keys work across REST, MCP, and CLI
+- [Raw FFmpeg guide](/guides/raw-ffmpeg): security model, allowed flags, worked examples
+- [Job lifecycle](/concepts/job-lifecycle): the six statuses and what triggers each
+- [Pricing and plans](https://rendobar.com/pricing/): Free vs Pro and credit-pack pricing
+- [All supported FFmpeg operations](https://rendobar.com/features/): full feature index
diff --git a/support/errors.mdx b/support/errors.mdx
index 82a6908..f004401 100644
--- a/support/errors.mdx
+++ b/support/errors.mdx
@@ -1,10 +1,29 @@
 ---
 title: "API error codes reference"
 sidebarTitle: "Error codes"
-description: "Find every API error code, its HTTP status, and recommended action. Errors follow the {error: {code, message}} envelope on all endpoints."
+description: "View 13 API error codes, their HTTP status, and recommended action. Errors follow the {error: {code, message}} envelope on every endpoint."
 icon: "triangle-exclamation"
+keywords: ["rendobar error codes", "api error reference", "ffmpeg error troubleshooting", "insufficient credits", "rate limited"]
 ---
 
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/support/errors/#article",
+      "headline": "API error codes reference",
+      "description": "Every API error code, its HTTP status, and recommended action. Errors follow the {error: {code, message}} envelope on all endpoints.",
+      "datePublished": "2026-03-20",
+      "dateModified": "2026-05-24",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
 Every error response uses the same shape:
 
 ```json
@@ -41,7 +60,7 @@ The three you'll hit most: `INSUFFICIENT_CREDITS`, `RATE_LIMITED`, `VALIDATION_E
 const res = await fetch("https://api.rendobar.com/jobs", {
   method: "POST",
   headers: {
-    "Authorization": "Bearer rb_live_YOUR_KEY",
+    "Authorization": "Bearer rb_YOUR_KEY",
     "Content-Type": "application/json",
   },
   body: JSON.stringify({
@@ -73,7 +92,7 @@ if (!res.ok) {
 import requests
 res = requests.post(
     "https://api.rendobar.com/jobs",
-    headers={"Authorization": "Bearer rb_live_YOUR_KEY"},
+    headers={"Authorization": "Bearer rb_YOUR_KEY"},
     json={
         "type": "raw.ffmpeg",
         "inputs": {},
@@ -92,3 +111,11 @@ if not res.ok:
 - [Limits](/support/limits)
 - [Job lifecycle](/concepts/job-lifecycle)
 - [Authentication](/authentication)
+
+## Related
+
+- [Plan limits](/support/limits): caps behind `PLAN_LIMIT` and `RATE_LIMITED`
+- [Job lifecycle](/concepts/job-lifecycle): where `PROVIDER_ERROR` and `PROVIDER_TIMEOUT` surface
+- [Credits and billing](/concepts/credits): `INSUFFICIENT_CREDITS` and the prepaid model
+- [FAQ](/support/faq): common questions about failed jobs and refunds
+- [Pricing](https://rendobar.com/pricing/): plan that lifts your concurrency and rate caps
diff --git a/support/faq.mdx b/support/faq.mdx
index c4b89c9..509a965 100644
--- a/support/faq.mdx
+++ b/support/faq.mdx
@@ -1,18 +1,105 @@
 ---
 title: "Frequently asked questions"
 sidebarTitle: "FAQ"
-description: "Quick answers about Rendobar pricing, supported formats, AI agent access, rate limits, and what counts as a failed job."
+description: "Get quick answers about Rendobar pricing, supported formats, AI agent access, rate limits, and what counts as a failed job."
 icon: "circle-question"
+keywords: ["rendobar faq", "video api faq", "rendobar pricing faq", "ffmpeg api questions"]
 ---
 
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "FAQPage",
+      "@id": "https://rendobar.com/docs/support/faq/#faq",
+      "isPartOf": { "@id": "https://rendobar.com/#website" },
+      "mainEntity": [
+        {
+          "@type": "Question",
+          "name": "How much does Rendobar cost?",
+          "acceptedAnswer": {
+            "@type": "Answer",
+            "text": "Free plan ships with a one-time $5 credit grant, no card required. Pro is $9/mo, includes $5/mo in credits, plus 20% bonus on every credit purchase. Credit packs $10–$100 on both plans. Credits never expire."
+          }
+        },
+        {
+          "@type": "Question",
+          "name": "What can I do with Rendobar today?",
+          "acceptedAnswer": {
+            "@type": "Answer",
+            "text": "The live API is raw.ffmpeg, any whitelisted FFmpeg command against URLs you provide. That covers transcoding, trimming, filtering, overlays, audio extraction, frame extraction, and anything else FFmpeg does from the command line. More dedicated job types are on the roadmap."
+          }
+        },
+        {
+          "@type": "Question",
+          "name": "What video formats are supported?",
+          "acceptedAnswer": {
+            "@type": "Answer",
+            "text": "Every FFmpeg-compatible container and codec for input. Output defaults to the extension in your trailing filename (output.mp4 → MP4). Override with params.outputFormat."
+          }
+        },
+        {
+          "@type": "Question",
+          "name": "Can I drive Rendobar from an AI agent?",
+          "acceptedAnswer": {
+            "@type": "Answer",
+            "text": "Yes. Connect any MCP-compatible agent to https://api.rendobar.com/mcp with your API key. Six typed MCP tools (submit_job, get_job, list_jobs, probe_media, get_account, upload_media). Available on all plans."
+          }
+        },
+        {
+          "@type": "Question",
+          "name": "How long do jobs take?",
+          "acceptedAnswer": {
+            "@type": "Answer",
+            "text": "Seconds to minutes, depending on input size and command. Hard caps: 5 min (Free), 15 min (Pro)."
+          }
+        },
+        {
+          "@type": "Question",
+          "name": "Is there a rate limit?",
+          "acceptedAnswer": {
+            "@type": "Answer",
+            "text": "Yes. 30 req/min (Free), 300 req/min (Pro). Applies to REST and MCP. Limit hit returns 429 RATE_LIMITED with a Retry-After header."
+          }
+        },
+        {
+          "@type": "Question",
+          "name": "What happens if a job fails?",
+          "acceptedAnswer": {
+            "@type": "Answer",
+            "text": "Failed jobs are charged for the compute they used. Rendobar has no auto-refund. If you believe a failure was caused by a Rendobar bug or platform issue, contact support and we will review for a discretionary refund. Successful and failed jobs are billed the same way: actual provider cost plus infrastructure cost plus margin. Inspect error.code and error.message on the job, and retry via POST /jobs/{id}/retry if appropriate."
+          }
+        },
+        {
+          "@type": "Question",
+          "name": "Can I run custom FFmpeg commands?",
+          "acceptedAnswer": {
+            "@type": "Answer",
+            "text": "Yes. That is the entire raw.ffmpeg job. Commands run through 8 security layers (flag whitelist, format/filter blocklists, sandbox isolation) before execution."
+          }
+        },
+        {
+          "@type": "Question",
+          "name": "How do I get push updates instead of polling?",
+          "acceptedAnswer": {
+            "@type": "Answer",
+            "text": "Configure a webhook endpoint on your organization. Rendobar POSTs signed JSON when jobs change status. The dashboard uses a WebSocket internally; programmatic push is webhook-only."
+          }
+        }
+      ]
+    })
+  }}
+/>
+
 <AccordionGroup>
 
 <Accordion title="How much does Rendobar cost?">
-  Free plan ships with a one-time $5 credit grant — no card required. Pro is $9/mo, includes $5/mo in credits, plus 20% bonus on every credit purchase. Credit packs $10–$100 on both plans. Credits never expire. Full breakdown: [Credits and billing](/concepts/credits) or the [pricing page](https://rendobar.com/pricing/).
+  Free plan ships with a one-time $5 credit grant, no card required. Pro is $9/mo, includes $5/mo in credits, plus 20% bonus on every credit purchase. Credit packs $10–$100 on both plans. Credits never expire. Full breakdown: [Credits and billing](/concepts/credits) or the [pricing page](https://rendobar.com/pricing/).
 </Accordion>
 
 <Accordion title="What can I do with Rendobar today?">
-  The live API is `raw.ffmpeg` — any whitelisted FFmpeg command against URLs you provide. That covers transcoding, trimming, filtering, overlays, audio extraction, frame extraction, and anything else FFmpeg does from the command line. More dedicated job types are on the roadmap.
+  The live API is `raw.ffmpeg`, any whitelisted FFmpeg command against URLs you provide. That covers transcoding, trimming, filtering, overlays, audio extraction, frame extraction, and anything else FFmpeg does from the command line. More dedicated job types are on the roadmap.
 </Accordion>
 
 <Accordion title="What video formats are supported?">
@@ -20,7 +107,7 @@ icon: "circle-question"
 </Accordion>
 
 <Accordion title="Can I drive Rendobar from an AI agent?">
-  Yes. Connect any MCP-compatible agent to `https://api.rendobar.com/mcp` with your API key. Five typed tools cover submit, status, list, account, upload. Available on all plans. See [MCP overview](/mcp/overview).
+  Yes. Connect any MCP-compatible agent to `https://api.rendobar.com/mcp` with your API key. Six typed MCP tools: `submit_job`, `get_job`, `list_jobs`, `probe_media`, `get_account`, `upload_media`. Available on all plans. See [MCP overview](/mcp/overview).
 </Accordion>
 
 <Accordion title="How long do jobs take?">
@@ -28,21 +115,29 @@ icon: "circle-question"
 </Accordion>
 
 <Accordion title="Is there a rate limit?">
-  Yes. 30 req/min (Free), 300 req/min (Pro). Applies to REST and MCP. Limit hit → `429 RATE_LIMITED` with a `Retry-After` header.
+  Yes. 30 req/min (Free), 300 req/min (Pro). Applies to REST and MCP. Limit hit returns `429 RATE_LIMITED` with a `Retry-After` header.
 </Accordion>
 
 <Accordion title="What happens if a job fails?">
-  No credits charged. Inspect `error.code` and `error.message` on the job. Retry via `POST /jobs/{id}/retry` if appropriate. [Error codes](/support/errors).
+  Failed jobs are charged for the compute they used. Rendobar has no auto-refund. If you believe a failure was caused by a Rendobar bug or platform issue, contact support and we will review for a discretionary refund. Successful and failed jobs are billed the same way: actual provider cost plus infrastructure cost plus margin. Inspect `error.code` and `error.message` on the job, and retry via `POST /jobs/{id}/retry` if appropriate. [Error codes](/support/errors).
 </Accordion>
 
 <Accordion title="Can I run custom FFmpeg commands?">
-  Yes — that's the entire `raw.ffmpeg` job. Commands run through 8 security layers (flag whitelist, format/filter blocklists, sandbox isolation) before execution. [Raw FFmpeg](/guides/raw-ffmpeg).
+  Yes. That is the entire `raw.ffmpeg` job. Commands run through 8 security layers (flag whitelist, format/filter blocklists, sandbox isolation) before execution. [Raw FFmpeg](/guides/raw-ffmpeg).
 </Accordion>
 
 <Accordion title="How do I get push updates instead of polling?">
-  Configure a [webhook](/guides/webhooks) endpoint on your organization. Rendobar POSTs signed JSON when jobs change status. The dashboard uses a WebSocket internally; programmatic push is webhook-only.
+  Configure a [webhook](/guides/webhooks) endpoint on your organization. Rendobar POSTs signed JSON when jobs change status. The dashboard uses a WebSocket internally. Programmatic push is webhook-only.
 </Accordion>
 
 </AccordionGroup>
 
-For more about what Rendobar can do, see [rendobar.com](https://rendobar.com) or [rendobar.com/pricing/](https://rendobar.com/pricing/).
+For more about what Rendobar can do, see [rendobar.com](https://rendobar.com) or [rendobar.com/pricing/](https://rendobar.com/pricing/). For head-to-head comparisons with other video APIs, see [rendobar.com/vs/](https://rendobar.com/vs/).
+
+## Related
+
+- [Credits and billing](/concepts/credits): full pricing and balance model
+- [Plan limits](/support/limits): every rate, file, and storage cap by plan
+- [Error codes](/support/errors): every `error.code` the API can return
+- [Pricing](https://rendobar.com/pricing/): Free vs Pro and credit packs
+- [Rendobar vs alternatives](https://rendobar.com/vs/): comparisons with other video APIs
diff --git a/support/limits.mdx b/support/limits.mdx
index abd32a1..a91894c 100644
--- a/support/limits.mdx
+++ b/support/limits.mdx
@@ -1,19 +1,38 @@
 ---
 title: "Plan limits and quotas"
 sidebarTitle: "Limits"
-description: "Compare Free and Pro plan limits: rate limits, file size caps, output retention, concurrent jobs, and storage quotas at a glance."
+description: "Compare Free and Pro plan limits across rate limits (30 vs 300/min), file size caps (100 MB vs 2 GB), retention, concurrency, storage."
 icon: "gauge"
+keywords: ["rendobar limits", "api rate limits", "plan limits", "file size limit", "concurrent jobs"]
 ---
 
-Every limit Rendobar enforces, by plan. Pulled from `PLAN_LIMITS` in the API.
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/support/limits/#article",
+      "headline": "Plan limits and quotas",
+      "description": "Free and Pro plan limits: rate limits, file size caps, output retention, concurrent jobs, and storage quotas.",
+      "datePublished": "2026-03-20",
+      "dateModified": "2026-05-24",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
+Every limit Rendobar enforces, by plan. Pulled from `PLAN_LIMITS` in the API. For plan prices and credit packs, see [pricing](https://rendobar.com/pricing/).
 
 ## Plan limits
 
 | | Free | Pro ($9/mo) |
 |---|---|---|
-| Signup credits | $5 (one-time) | — |
-| Monthly credits | — | $5/mo included |
-| Credit-purchase bonus | — | +20% |
+| Signup credits | $5 (one-time) | - |
+| Monthly credits | - | $5/mo included |
+| Credit-purchase bonus | - | +20% |
 | Concurrent jobs | 1 | 25 |
 | API requests / min | 30 | 300 |
 | Max input file | 100 MB | 2 GB |
@@ -31,7 +50,7 @@ Every limit Rendobar enforces, by plan. Pulled from `PLAN_LIMITS` in the API.
 - **Signed download URL** (`outputUrl`) is valid for **1 hour**. Re-fetch via `GET /jobs/{id}` for a fresh URL.
 - **Output retention**: 7 days (Free) or 30 days (Pro). After that, R2 deletes the file; the job record stays but `outputUrl` returns 404.
 - **Storage quota** caps total bytes across all your outputs. Delete old outputs or upgrade if you hit it.
-- **No separate per-output size limit** — bounded by input cap and storage quota.
+- **No separate per-output size limit**. Bounded by input cap and storage quota.
 
 ## Credit packs
 
@@ -59,6 +78,14 @@ For `raw.ffmpeg`, the output format is inferred from the trailing filename (`out
 
 ## See also
 
-- [Credits & billing](/credits)
+- [Credits and billing](/concepts/credits)
 - [Error codes](/support/errors)
 - [Raw FFmpeg](/job-types/raw-ffmpeg)
+
+## Related
+
+- [Credits and billing](/concepts/credits): nanodollar pricing and the prepaid model
+- [Error codes](/support/errors): `PLAN_LIMIT` and `RATE_LIMITED` details
+- [FAQ](/support/faq): cost, rate limit, and refund questions
+- [raw.ffmpeg reference](/job-types/raw-ffmpeg): how plan caps apply to FFmpeg jobs
+- [Pricing](https://rendobar.com/pricing/): plan that raises your concurrency and file caps

From b33e02d4724001a5c006a5ab8ec3e2ce443dcedd Mon Sep 17 00:00:00 2001
From: Abdelrahman Essawy <abdelrahman.mo.essawy@gmail.com>
Date: Sun, 24 May 2026 13:12:09 +0300
Subject: [PATCH 2/2] fix(docs): satisfy frontmatter validator

- cli/troubleshooting + mcp/troubleshooting: 'Troubleshoot' not in ALLOWED_VERBS, swap to 'Fix'
- concepts/credits: description 170 to 150 chars
---
 cli/troubleshooting.mdx | 2 +-
 concepts/credits.mdx    | 2 +-
 mcp/troubleshooting.mdx | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/cli/troubleshooting.mdx b/cli/troubleshooting.mdx
index 7def2b7..cb67c27 100644
--- a/cli/troubleshooting.mdx
+++ b/cli/troubleshooting.mdx
@@ -1,6 +1,6 @@
 ---
 title: "CLI troubleshooting"
-description: "Troubleshoot common rb CLI errors: install failures, PATH issues, port conflicts, macOS Gatekeeper, expired tokens, rate limits, update rollback."
+description: "Fix common rb CLI errors: install failures, PATH issues, port conflicts, macOS Gatekeeper, expired tokens, rate limits, update rollback."
 sidebarTitle: "Troubleshooting"
 icon: "stethoscope"
 keywords: ["rb cli error", "rendobar cli not found", "rendobar login failed", "rb doctor", "rb update failed"]
diff --git a/concepts/credits.mdx b/concepts/credits.mdx
index 1bd82d9..dd7647d 100644
--- a/concepts/credits.mdx
+++ b/concepts/credits.mdx
@@ -1,7 +1,7 @@
 ---
 title: "Credits and billing"
 sidebarTitle: "Credits"
-description: "Get per-job nanodollar billing from a prepaid balance. Free plan ships with $5, Pro is $9/mo. Credits never expire. Every terminal job is charged for actual compute used."
+description: "Get per-job nanodollar billing from a prepaid balance. Free plan grants $5, Pro is $9/mo. Credits never expire. Every terminal job pays actual compute."
 icon: "coins"
 keywords: ["credit-based billing", "nanodollar pricing", "rendobar credits", "video api credits", "prepaid balance"]
 ---
diff --git a/mcp/troubleshooting.mdx b/mcp/troubleshooting.mdx
index da6dfe7..daf210e 100644
--- a/mcp/troubleshooting.mdx
+++ b/mcp/troubleshooting.mdx
@@ -1,6 +1,6 @@
 ---
 title: "MCP troubleshooting"
-description: "Troubleshoot common MCP server failures: missing API key, Cursor PATH on macOS, Windows npx.cmd quirks, Node 20+ requirement, stdout pollution."
+description: "Fix common MCP server failures: missing API key, Cursor PATH on macOS, Windows npx.cmd quirks, Node 20+ requirement, stdout pollution."
 sidebarTitle: "Troubleshooting"
 icon: "wrench"
 keywords: ["rendobar mcp error", "mcp not loading", "claude desktop mcp not working", "cursor mcp path", "mcp api key"]