diff --git a/cli/ci-cd.mdx b/cli/ci-cd.mdx
index 20922d5..449e5ed 100644
--- a/cli/ci-cd.mdx
+++ b/cli/ci-cd.mdx
@@ -122,7 +122,7 @@ Progress display goes to stderr. stdout stays empty unless you ask for it.
 | Goal | Flag | stdout |
 |---|---|---|
 | Result URL only | `--url-only` | One line, the signed download URL |
-| Full result | `--json` | JSON: `id`, `status`, `outputUrl`, `cost`, timing |
+| Full result | `--json` | JSON: `id`, `status`, `output`, `cost`, timing |
 | Exit code only | `--quiet` | (nothing) |
 | Submit and exit | `--no-wait` | One line, the job ID |
 
diff --git a/concepts/job-lifecycle.mdx b/concepts/job-lifecycle.mdx
index e550d98..2bb99f8 100644
--- a/concepts/job-lifecycle.mdx
+++ b/concepts/job-lifecycle.mdx
@@ -62,6 +62,21 @@ waiting → dispatched → running → complete
 
 Full catalogue: [Error codes](/support/errors).
 
+## Output
+
+A `complete` job carries one `output` shape, the same for every job type:
+
+```json
+{
+  "data": <job-type-specific JSON> | null,
+  "file": <File> | null,
+  "files": <File>[],
+  "expiresAt": <unix ms> | null
+}
+```
+
+Read `output.data` for a computed answer, `output.file.url` for the file to play or download, and `output.files` for the full list. The shape, the `File` type, the invariants, and the per-type `data` shapes live in one place: [Job output](/concepts/job-output).
+
 ## Timeouts
 
 Each job type has a max execution time. Exceeding it auto-fails with `PROVIDER_TIMEOUT`; credits are refunded. A background job runs every 2 minutes to detect stuck jobs that were dispatched or running but never reported back.
diff --git a/concepts/job-output.mdx b/concepts/job-output.mdx
new file mode 100644
index 0000000..5d32fa6
--- /dev/null
+++ b/concepts/job-output.mdx
@@ -0,0 +1,290 @@
+---
+title: "Job output shape"
+description: "Read the output shape every Rendobar job returns: data, file, files, and expiresAt, the File type, and the four output patterns with examples."
+sidebarTitle: "Job output"
+icon: "box-open"
+keywords: ["job output", "output shape", "output.data", "output.file", "output.files", "file type enum", "rendobar response"]
+---
+
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/concepts/job-output/#article",
+      "headline": "Job output",
+      "description": "The output shape every Rendobar job returns: data, file, files, and expiresAt, the File type, and the four output patterns.",
+      "datePublished": "2026-06-06",
+      "dateModified": "2026-06-06",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
+Every job returns the same `output` shape, no matter the type. A `complete` job carries one `output` object. Read `output.data` for a computed answer, `output.file.url` for the file to play or download, and `output.files` for the full list.
+
+```json
+{
+  "data": <job-type-specific JSON> | null,
+  "file": <File> | null,
+  "files": <File>[],
+  "expiresAt": <unix ms> | null
+}
+```
+
+`output` is present when `status` is `complete`. A `failed` job carries an `error` object instead. See [Job lifecycle](/concepts/job-lifecycle) for status transitions.
+
+## Fields
+
+<ResponseField name="data" type="object | null">
+  The computed answer for jobs that return one, such as a probe result, detections, or a transcript. `null` for jobs that only write files. The shape is job-type-specific, so each type documents its own. See [Per-type data shapes](#per-type-data-shapes).
+</ResponseField>
+
+<ResponseField name="file" type="File | null">
+  The headline result you play or download: a single output file, or a stream manifest (`.m3u8` / `.mpd`, typed `playlist`). `null` for data-only jobs and for pure file sets with no single headline. Always one of `files`.
+</ResponseField>
+
+<ResponseField name="files" type="File[]">
+  Every file the job produced, the complete list. A single-file job lists one. A stream lists the manifest plus segments. A set lists every member. `[]` for data-only jobs.
+</ResponseField>
+
+<ResponseField name="expiresAt" type="integer | null">
+  Unix ms when the file URLs expire. Present when `files` is non-empty. Re-fetch the job with `GET /jobs/{id}` to mint fresh URLs.
+</ResponseField>
+
+## Choosing file vs files
+
+`files` is the complete list of everything a job wrote. Most jobs return a single output, but some return many: an image sequence, the segments of an HLS stream, or a resolution ladder. When a job can produce more than one file, read `files`.
+
+`file` is a shortcut for the common case. When you expect a single output, read `output.file.url` and you have the result, with no need to index into the list. For a single-output job, `file` is that one file, so it is the same entry as `files[0]`. That overlap is on purpose. It keeps the everyday case a one-liner while `files` stays the honest, complete manifest of what came out.
+
+A job with no single headline sets `file` to `null`. So a `null` file is also the signal that the result is a pure set of files or a data-only answer, not one file you play or download.
+
+<Tip>
+Expecting one output? Read `output.file.url` directly. Handling a job that can write many files (frames, HLS segments, a ladder)? Iterate `output.files`. Both always agree: `file`, when set, is one of `files`.
+</Tip>
+
+## The File type
+
+Each entry in `file` and `files` is the same shape:
+
+```json
+{
+  "url": "https://api.rendobar.com/dl/job_abc123?token=<token>",
+  "path": "output.mp4",
+  "type": "video",
+  "size": 4194304,
+  "meta": { "format": "mp4", "width": 1280, "height": 720, "durationMs": 30000 }
+}
+```
+
+<ResponseField name="url" type="string">
+  Signed download or serving URL. Expires at `output.expiresAt`.
+</ResponseField>
+
+<ResponseField name="path" type="string">
+  The filename the job wrote, such as `output.mp4`.
+</ResponseField>
+
+<ResponseField name="type" type="string">
+  Open enum: `video`, `image`, `audio`, `captions`, `playlist`, `data`, or `other`. Treat it as open. Tolerate values you don't recognize, since new types can appear without a version bump.
+</ResponseField>
+
+<ResponseField name="size" type="integer">
+  File size in bytes.
+</ResponseField>
+
+<ResponseField name="meta" type="object">
+  Optional probed metadata: `format`, `width`, `height`, `durationMs`. Each field is present when known.
+</ResponseField>
+
+## Invariants
+
+Three rules hold for every job type. Code against them.
+
+- **`output.file` is always one of `output.files`** (or `null`). The headline is never a file missing from the full list.
+- **`output.expiresAt` is present whenever `output.files` is non-empty.** Data-only jobs leave both `files` empty and `expiresAt` null.
+- **A `complete` job always has `output.data` or `output.files`** (or both). It never returns an empty result.
+
+## How to consume
+
+The read path is the same every time:
+
+```ts
+const { data: job } = await res.json();
+
+// 1. The computed answer, for jobs that return one.
+if (job.output.data) {
+  console.log(job.output.data);
+}
+
+// 2. The thing to play or download.
+if (job.output.file) {
+  console.log(job.output.file.url);
+}
+
+// 3. The full list, for sets and streams.
+for (const f of job.output.files) {
+  console.log(f.path, f.type, f.size);
+}
+```
+
+You never branch on a job-type discriminator to find the result. `output.data`, `output.file`, and `output.files` mean the same thing for `ffmpeg`, `extract.metadata`, `caption.extract`, and every other type.
+
+## Output patterns
+
+Four patterns cover every job. The shape is identical. Which fields are populated depends on what the job produced.
+
+### Single file
+
+One output file. `file` is that file, `files` lists one, `data` is null. The most common pattern for transform jobs (FFmpeg, transcode, watermark).
+
+```json
+{
+  "data": null,
+  "file": {
+    "url": "https://api.rendobar.com/dl/job_abc123?token=<token>",
+    "path": "output.mp4",
+    "type": "video",
+    "size": 4194304,
+    "meta": { "format": "mp4", "width": 1280, "height": 720, "durationMs": 30000 }
+  },
+  "files": [
+    {
+      "url": "https://api.rendobar.com/dl/job_abc123?token=<token>",
+      "path": "output.mp4",
+      "type": "video",
+      "size": 4194304,
+      "meta": { "format": "mp4", "width": 1280, "height": 720, "durationMs": 30000 }
+    }
+  ],
+  "expiresAt": 1735689600000
+}
+```
+
+### Stream
+
+An HLS or DASH stream. `file` is the manifest, typed `playlist`. Point a player at `file.url` directly. `files` carries the manifest plus every segment.
+
+```json
+{
+  "data": null,
+  "file": { "url": "https://api.rendobar.com/v/job_abc123/<token>/master.m3u8", "path": "master.m3u8", "type": "playlist", "size": 412 },
+  "files": [
+    { "url": "https://api.rendobar.com/v/job_abc123/<token>/master.m3u8", "path": "master.m3u8", "type": "playlist", "size": 412 },
+    { "url": "https://api.rendobar.com/v/job_abc123/<token>/seg_000.ts", "path": "seg_000.ts", "type": "video", "size": 1048576 },
+    { "url": "https://api.rendobar.com/v/job_abc123/<token>/seg_001.ts", "path": "seg_001.ts", "type": "video", "size": 1041203 }
+  ],
+  "expiresAt": 1735689600000
+}
+```
+
+### Set
+
+An unordered set with no single headline, such as an image sequence, a `-f segment` split, or a resolution ladder. `file` is `null`. Read `files` for the list.
+
+```json
+{
+  "data": null,
+  "file": null,
+  "files": [
+    { "url": "https://api.rendobar.com/v/job_abc123/<token>/frame_000.png", "path": "frame_000.png", "type": "image", "size": 204800 },
+    { "url": "https://api.rendobar.com/v/job_abc123/<token>/frame_001.png", "path": "frame_001.png", "type": "image", "size": 205120 },
+    { "url": "https://api.rendobar.com/v/job_abc123/<token>/frame_002.png", "path": "frame_002.png", "type": "image", "size": 203904 }
+  ],
+  "expiresAt": 1735689600000
+}
+```
+
+### Data-only
+
+A job that computes an answer instead of writing files. `data` carries the result. `file` is null, `files` is empty, `expiresAt` is null.
+
+```json
+{
+  "data": {
+    "width": 1280,
+    "height": 720,
+    "durationMs": 30000,
+    "codec": "h264",
+    "fps": 30,
+    "bitrate": 2500000,
+    "audioCodec": "aac",
+    "audioChannels": 2,
+    "audioSampleRate": 48000
+  },
+  "file": null,
+  "files": [],
+  "expiresAt": null
+}
+```
+
+## Per-type data shapes
+
+`output.data` is the only part of the output that varies by job type. Transform jobs leave it `null` and return files. Analysis jobs return their result here and write no file.
+
+The rule of thumb:
+
+- **Transform jobs** (`ffmpeg`, `transcode`, `watermark.*`, `caption.burn`) return files with `data: null`.
+- **Analysis jobs** (moderation, detection, captions, transcript, OCR, metadata) return their result in `data` and usually write no file.
+
+<Info>
+**Status:** Only `ffmpeg` is live today. The other job types below are documented but not yet callable. See each [job type page](/job-types/ffmpeg) for its availability banner.
+</Info>
+
+| Job type | `data` shape | Files |
+|---|---|---|
+| `ffmpeg` | `null` | The files your command wrote |
+| `extract.metadata` | Probe result (see below) | None (data-only) |
+| `extract.scenes` | Scene cut list | None (data-only) |
+| `extract.text` | Recognized text with positions and timestamps | None (data-only) |
+| `caption.extract` | Transcript with word timings | A captions file (`.srt` / `.vtt`) |
+| `compliance.moderate` | Moderation labels with confidences | None (data-only) |
+| `compliance.gdpr.detect` | Detected regions (faces, plates) with bounding boxes | None (data-only) |
+| `watermark.detect` | Match result with confidence | None (data-only) |
+| `transcode`, `watermark.apply`, `caption.burn` | `null` | The transformed media |
+
+### extract.metadata
+
+`output.data` is the probe result. The job runs `ffprobe`, returns the result inline, and writes no file.
+
+```json
+{
+  "data": {
+    "width": 1280,
+    "height": 720,
+    "durationMs": 30000,
+    "codec": "h264",
+    "fps": 30,
+    "bitrate": 2500000,
+    "audioCodec": "aac",
+    "audioChannels": 2,
+    "audioSampleRate": 48000
+  },
+  "file": null,
+  "files": [],
+  "expiresAt": null
+}
+```
+
+| Field | Type | Meaning |
+|---|---|---|
+| `width` | integer | Frame width in pixels |
+| `height` | integer | Frame height in pixels |
+| `durationMs` | integer | Duration in milliseconds |
+| `codec` | string | Video codec, such as `h264` |
+| `fps` | number | Frames per second |
+| `bitrate` | integer | Overall bitrate in bits per second |
+| `audioCodec` | string | Audio codec, present when the file has audio |
+| `audioChannels` | integer | Channel count, present when the file has audio |
+| `audioSampleRate` | integer | Sample rate in Hz, present when the file has audio |
+
+## See also
+
+- [Job lifecycle](/concepts/job-lifecycle): the statuses a job moves through before `output` exists
+- [FFmpeg reference](/job-types/ffmpeg): the response for a file-producing job
+- [POST /jobs](/quickstart): submit a job and read the result
+- [Error codes](/support/errors): the `error` shape a `failed` job returns instead
diff --git a/docs.json b/docs.json
index dcd2187..e5fa33a 100644
--- a/docs.json
+++ b/docs.json
@@ -53,7 +53,8 @@
           {
             "group": "Concepts",
             "pages": [
-              "concepts/job-lifecycle"
+              "concepts/job-lifecycle",
+              "concepts/job-output"
             ]
           },
           {
diff --git a/guides/ffmpeg.mdx b/guides/ffmpeg.mdx
index ae34477..3f85f30 100644
--- a/guides/ffmpeg.mdx
+++ b/guides/ffmpeg.mdx
@@ -50,14 +50,72 @@ From a shell? Use [the CLI](/cli/overview): `rb ffmpeg -i input.mp4 -vf scale=12
 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}`
+6. **Return**: signed `output.file.url` available via `GET /jobs/{id}`
+
+## Input sources
+
+Most commands put the source URL straight in the command and skip `inputs` entirely. It's optional and defaults to an empty map:
+
+```json
+{
+  "type": "ffmpeg",
+  "params": {
+    "command": "ffmpeg -i https://example.com/clip.mp4 -vf scale=1280:720 output.mp4"
+  }
+}
+```
+
+Reach for the `inputs` map only when a file can't go inline: a file a filter reads by name (see below), inline text you don't want to host, an already-uploaded asset, or when you need a stable filename. Each key is a filename staged under that exact name, and the command references it by bare name.
+
+A value can be one of four shapes:
+
+| Value | Use it for |
+|---|---|
+| `"https://..."` | A remote file. Shorthand for `{ "url": "..." }` |
+| `{ "url": "https://..." }` | A remote file, explicit form |
+| `{ "content": "...text..." }` | Inline text you don't want to host (≤64 KB) |
+| `{ "ref": "asset_abc123" }` | A file you already uploaded, by its asset ID (returned by the uploads endpoint) |
+
+```json
+{
+  "type": "ffmpeg",
+  "inputs": {
+    "clip.mp4": "https://example.com/clip.mp4",
+    "logo.png": { "ref": "asset_brandlogo" }
+  },
+  "params": {
+    "command": "ffmpeg -i clip.mp4 -i logo.png -filter_complex overlay=10:10 output.mp4"
+  }
+}
+```
+
+### Auxiliary files read by a filter
+
+Some files aren't passed as `-i` arguments. Filters like `subtitles=`, `lut3d=`, and `drawtext fontfile=`, and the lists read by the `concat` demuxer, read a file by name from the working directory. Provide those through `inputs` so they're staged before the command runs.
+
+This burns a subtitle track that lives only in the request, with no file to host:
+
+```json
+{
+  "type": "ffmpeg",
+  "inputs": {
+    "video.mp4": "https://example.com/video.mp4",
+    "subs.srt": {
+      "content": "1\n00:00:01,000 --> 00:00:04,000\nRendered on Rendobar.\n"
+    }
+  },
+  "params": {
+    "command": "ffmpeg -i video.mp4 -vf subtitles=subs.srt -c:v libx264 -c:a copy output.mp4"
+  }
+}
+```
 
 ## Parameters
 
 | Field | Type | Required | Default | Notes |
 |---|---|---|---|---|
 | `type` | string | yes | - | `"ffmpeg"` |
-| `inputs` | object | yes | - | `{}` when URLs are inline in the command. Otherwise a name→URL map matching filenames in the command |
+| `inputs` | object | yes | - | Working directory for the command. Maps a filename to a source (URL, `{url}`, `{content}`, or `{ref}`). `{}` when every input is an inline `-i` URL. See [Input sources](#input-sources) |
 | `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 |
@@ -161,15 +219,131 @@ Plan timeouts: 5 min (Free), 15 min (Pro). See [plan limits](/support/limits) fo
 }
 ```
 
+## Output files
+
+The filenames your command writes define the output. You get back every file it produced.
+
+Every completed job, FFmpeg or otherwise, returns the same `output` shape. [Job output](/concepts/job-output) documents it in full. The short version:
+
+- `output.data`: the computed answer (a probe result, a transcript). `null` for FFmpeg jobs, which only write files.
+- `output.file`: the headline result you play or download, one file or a stream manifest. `null` for pure file sets.
+- `output.files`: every file the job produced, the complete list.
+- `output.expiresAt`: Unix ms when the URLs expire, present when `files` is non-empty.
+
+Each file is `{ url, path, type, size, meta? }`. The `type` is an open enum: `video`, `image`, `audio`, `captions`, `playlist`, `data`, or `other`. Tolerate values you don't recognise.
+
+A command that writes one file sets `output.file` to that file, and `output.files` to a list of one:
+
+```json
+{
+  "data": {
+    "id": "job_abc123",
+    "status": "complete",
+    "output": {
+      "data": null,
+      "file": {
+        "url": "https://api.rendobar.com/dl/job_abc123?token=<token>",
+        "path": "output.mp4",
+        "type": "video",
+        "size": 4194304,
+        "meta": { "format": "mp4", "width": 1280, "height": 720, "durationMs": 30000 }
+      },
+      "files": [
+        {
+          "url": "https://api.rendobar.com/dl/job_abc123?token=<token>",
+          "path": "output.mp4",
+          "type": "video",
+          "size": 4194304,
+          "meta": { "format": "mp4", "width": 1280, "height": 720, "durationMs": 30000 }
+        }
+      ],
+      "expiresAt": 1735689600000
+    }
+  }
+}
+```
+
+A command that writes a stream (HLS or DASH) sets `output.file` to the manifest, typed `playlist`. Point a player at `output.file.url` directly. `output.files` carries the manifest plus every segment:
+
+```json
+{
+  "type": "ffmpeg",
+  "inputs": { "video.mp4": "https://example.com/video.mp4" },
+  "params": {
+    "command": "ffmpeg -i video.mp4 -c:v libx264 -c:a aac -f hls -hls_time 6 -hls_segment_filename seg_%03d.ts master.m3u8"
+  }
+}
+```
+
+```json
+{
+  "data": {
+    "id": "job_abc123",
+    "status": "complete",
+    "output": {
+      "data": null,
+      "file": {
+        "url": "https://api.rendobar.com/v/job_abc123/<token>/master.m3u8",
+        "path": "master.m3u8",
+        "type": "playlist",
+        "size": 412
+      },
+      "files": [
+        { "url": "https://api.rendobar.com/v/job_abc123/<token>/master.m3u8", "path": "master.m3u8", "type": "playlist", "size": 412 },
+        { "url": "https://api.rendobar.com/v/job_abc123/<token>/seg_000.ts", "path": "seg_000.ts", "type": "video", "size": 1048576 },
+        { "url": "https://api.rendobar.com/v/job_abc123/<token>/seg_001.ts", "path": "seg_001.ts", "type": "video", "size": 1041203 }
+      ],
+      "expiresAt": 1735689600000
+    }
+  }
+}
+```
+
+A command that writes an unordered set (image sequence, `-f segment`, a resolution ladder) has no single headline result. `output.file` is `null`. Read `output.files` for the list:
+
+```json
+{
+  "data": {
+    "id": "job_abc123",
+    "status": "complete",
+    "output": {
+      "data": null,
+      "file": null,
+      "files": [
+        { "url": "https://api.rendobar.com/v/job_abc123/<token>/frame_000.png", "path": "frame_000.png", "type": "image", "size": 204800 },
+        { "url": "https://api.rendobar.com/v/job_abc123/<token>/frame_001.png", "path": "frame_001.png", "type": "image", "size": 205120 },
+        { "url": "https://api.rendobar.com/v/job_abc123/<token>/frame_002.png", "path": "frame_002.png", "type": "image", "size": 203904 }
+      ],
+      "expiresAt": 1735689600000
+    }
+  }
+}
+```
+
+Consuming the result is the same every time. The answer is `output.data`. The thing you play or download is `output.file.url`. The full list is `output.files`. Two invariants hold: `output.file` is always one of `output.files` (or `null`), and `output.expiresAt` is present whenever `output.files` is non-empty.
+
+URLs expire at `output.expiresAt`. Re-fetch the job with `GET /jobs/{id}` to mint fresh ones.
+
 ## Error handling
 
-FFmpeg exits non-zero → job fails with `PROVIDER_ERROR`:
+A failed job carries an `error` object with `code`, `message`, `detail`, and `retryable`. When FFmpeg exits non-zero, `error.detail` holds the last ~2 KB of the real stderr. Fetch the job to see exactly why FFmpeg stopped.
 
 ```json
-{ "error": { "code": "PROVIDER_ERROR", "message": "FFmpeg process exited with code 1" } }
+{
+  "data": {
+    "id": "job_abc123",
+    "status": "failed",
+    "error": {
+      "code": "PROVIDER_ERROR",
+      "message": "FFmpeg process exited with code 1",
+      "detail": "[in#0 @ 0x55…] Error opening input: Invalid data found when processing input\nError opening input file clip.mp4.\n",
+      "retryable": false
+    }
+  }
+}
 ```
 
-Disallowed flag → rejected before dispatch with `VALIDATION_ERROR`:
+A disallowed flag is rejected before dispatch. The request fails with the error envelope, so no job is created:
 
 ```json
 { "error": { "code": "VALIDATION_ERROR", "message": "Flag '-protocol_whitelist' is not allowed in FFmpeg commands" } }
diff --git a/guides/webhooks.mdx b/guides/webhooks.mdx
index 2816dec..5362d7c 100644
--- a/guides/webhooks.mdx
+++ b/guides/webhooks.mdx
@@ -47,8 +47,8 @@ Manage endpoints (create, update, delete, test) via the API or the dashboard.
 
 | Event | When |
 |---|---|
-| `job.completed` | Job finished successfully. Includes output URL + metadata |
-| `job.failed` | Job failed. Includes `error.code` and `error.message` |
+| `job.completed` | Job finished successfully. Carries the unified `output` and `cost` |
+| `job.failed` | Job failed. Carries the unified `error` (`code`, `message`, `detail`, `retryable`) |
 | `job.running` | Job started executing on a provider |
 | `batch.completed` | Every job in a batch finished (success or fail) |
 
@@ -62,20 +62,33 @@ X-Rendobar-Delivery: del_x1y2z3
 X-Rendobar-Attempt: 1
 ```
 
+The webhook carries the same contract as [GET /jobs/{id}](/concepts/job-output). A `job.completed` payload includes the unified `output` object. The `data` field has the structured answer for analysis jobs, `file.url` is a signed, time-limited URL, and `files` lists every produced file. Read [Job output](/concepts/job-output) for the full shape, the File type, and the four output patterns.
+
 ```json
 {
   "event": "job.completed",
   "jobId": "job_a1b2c3d4",
-  "result": {
-    "url": "https://r2.rendobar.com/...",
-    "metadata": {
-      "durationMs": 127500,
-      "width": 1920,
-      "height": 1080,
-      "fileSize": 15234567
-    }
+  "output": {
+    "data": null,
+    "file": {
+      "url": "https://api.rendobar.com/dl/job_a1b2c3d4?token=...",
+      "path": "output.mp4",
+      "type": "video",
+      "size": 15234567,
+      "meta": { "format": "mp4", "width": 1920, "height": 1080, "durationMs": 127500 }
+    },
+    "files": [
+      {
+        "url": "https://api.rendobar.com/dl/job_a1b2c3d4?token=...",
+        "path": "output.mp4",
+        "type": "video",
+        "size": 15234567,
+        "meta": { "format": "mp4", "width": 1920, "height": 1080, "durationMs": 127500 }
+      }
+    ],
+    "expiresAt": 1707440415000
   },
-  "cost": { "nanodollars": 50000000, "formatted": "$0.05" },
+  "cost": { "amount": 50000000, "currency": "USD", "formatted": "$0.05" },
   "timing": {
     "createdAt": 1707436800000,
     "startedAt": 1707436805000,
@@ -84,13 +97,20 @@ X-Rendobar-Attempt: 1
 }
 ```
 
-For `job.failed`, replace `result` with `error`:
+The `output` shape is identical for every job type. A data-only job (such as `extract.metadata`) carries its answer in `output.data` with `file` null and `files` empty. A stream job carries the manifest as `output.file` and every segment in `output.files`. See [Job output](/concepts/job-output) for each pattern.
+
+For `job.failed`, the payload carries `error` instead of `output`. The error matches the [GET /jobs](/concepts/job-output) error shape: `code`, `message`, `detail` (the provider stderr tail, or null), and `retryable`.
 
 ```json
 {
   "event": "job.failed",
   "jobId": "job_a1b2c3d4",
-  "error": { "code": "PROVIDER_ERROR", "message": "FFmpeg process exited with code 1" },
+  "error": {
+    "code": "PROVIDER_ERROR",
+    "message": "FFmpeg process exited with code 1",
+    "detail": "Conversion failed: Invalid data found when processing input",
+    "retryable": false
+  },
   "timing": { "createdAt": 1707436800000, "startedAt": 1707436805000, "completedAt": 1707436810000 }
 }
 ```
@@ -173,6 +193,7 @@ curl https://api.rendobar.com/webhook-endpoints/YOUR_ENDPOINT_ID/deliveries \
 
 ## See also
 
+- [Job output](/concepts/job-output): the canonical `output` and `error` shape this payload carries
 - [Job lifecycle](/concepts/job-lifecycle)
 - [FFmpeg](/guides/ffmpeg)
 - [Error codes](/support/errors)
diff --git a/job-types/caption-burn.mdx b/job-types/caption-burn.mdx
index 42bead7..eca6847 100644
--- a/job-types/caption-burn.mdx
+++ b/job-types/caption-burn.mdx
@@ -159,7 +159,7 @@ Omit `subtitles` to auto-transcribe. The spoken language is detected by default
 { "data": { "id": "job_abc123", "status": "dispatched" } }
 ```
 
-Poll `GET /jobs/{id}` until `status: "complete"`, then read `outputUrl` (signed, 1-hour TTL).
+Poll `GET /jobs/{id}` until `status: "complete"`, then read `output.file.url` (signed, 1-hour TTL). The burned video is a single file, so `output.files` lists that one file.
 
 ## See also
 
diff --git a/job-types/captions-animate.mdx b/job-types/captions-animate.mdx
index 725279e..d8b9bd5 100644
--- a/job-types/captions-animate.mdx
+++ b/job-types/captions-animate.mdx
@@ -118,7 +118,7 @@ res = requests.post(
 { "data": { "id": "job_abc123", "status": "dispatched" } }
 ```
 
-Poll `GET /jobs/{id}` until `status: "complete"`, then read `outputUrl` (signed, 1-hour TTL).
+Poll `GET /jobs/{id}` until `status: "complete"`, then read `output.file.url` (signed, 1-hour TTL). The captioned video is a single file, so `output.files` lists that one file.
 
 ## Pricing
 
diff --git a/job-types/ffmpeg.mdx b/job-types/ffmpeg.mdx
index 67c4612..2444563 100644
--- a/job-types/ffmpeg.mdx
+++ b/job-types/ffmpeg.mdx
@@ -29,7 +29,7 @@ keywords: ["ffmpeg api reference", "ffmpeg cloud", "ffmpeg sandboxed", "ffmpeg r
 **Live.** Production-ready, available on all plans.
 </Check>
 
-Execute a custom FFmpeg command with whitelisted flags. Input files go in `-i` positions and are downloaded into a sandbox before execution.
+Execute a custom FFmpeg command with whitelisted flags. The `inputs` map stages source files into the working directory by name. The command references them by bare name, and inline `-i` URLs also work.
 
 <Info>
 **Timeout:** 900 s max (plan-capped) · **Accepts:** video, audio, image
@@ -89,8 +89,29 @@ res = requests.post(
 
 ## Parameters
 
+<ParamField body="inputs" type="object" default="{}">
+  Working directory for the command. Optional, defaults to an empty map. Each key is a path-safe filename staged under that exact name. Each value is the source for that file. Omit it when every input is an inline `-i` URL. A value is one of:
+
+  <Expandable title="Input source shapes">
+    <ResponseField name="URL string" type="string">
+      Remote file. Shorthand for `{ "url": "..." }`.
+    </ResponseField>
+    <ResponseField name="url" type="object">
+      `{ "url": "https://..." }`. Remote file, explicit form.
+    </ResponseField>
+    <ResponseField name="content" type="object">
+      `{ "content": "...text..." }`. Inline text staged verbatim, up to 64 KB. For subtitles, `concat` lists, and LUTs with nothing to host.
+    </ResponseField>
+    <ResponseField name="ref" type="object">
+      `{ "ref": "asset_abc123" }`. A file you already uploaded, by its asset ID (returned by the uploads endpoint).
+    </ResponseField>
+  </Expandable>
+
+  Filters that read a file by name (`subtitles=`, `lut3d=`, `drawtext fontfile=`, `concat` lists) must get that file through `inputs`. They are not `-i` arguments. See the [FFmpeg guide](/guides/ffmpeg#input-sources).
+</ParamField>
+
 <ParamField body="command" type="string" required>
-  Real FFmpeg command starting with `ffmpeg`. Input URLs go in `-i` positions.
+  Real FFmpeg command starting with `ffmpeg`. Input URLs go in `-i` positions, or reference staged `inputs` files by name.
 </ParamField>
 
 <ParamField body="outputFormat" type="enum" default="inferred">
@@ -107,10 +128,34 @@ res = requests.post(
 { "data": { "id": "job_abc123", "status": "dispatched" } }
 ```
 
-Poll `GET /jobs/{id}` until `status: "complete"`, then read `outputUrl` (signed, 1-hour TTL).
+Poll `GET /jobs/{id}` until `status: "complete"`. On success the job carries an `output` object. On failure it carries an `error` object. The filenames your command writes define the output.
+
+`output` is one shape for every job type, documented in full on [Job output](/concepts/job-output). FFmpeg jobs set `output.data` to `null` and return their files in `output.file` and `output.files`. Read `output.file.url` for the file to play or download, and `output.files` for the full list.
+
+<ResponseField name="error" type="object">
+  Present when `status` is `failed`.
+
+  <Expandable title="error fields">
+    <ResponseField name="code" type="string">
+      Stable error code, e.g. `PROVIDER_ERROR`.
+    </ResponseField>
+    <ResponseField name="message" type="string">
+      Human-readable summary of what went wrong.
+    </ResponseField>
+    <ResponseField name="detail" type="string | null">
+      Extra context. For FFmpeg failures, the last ~2 KB of stderr. `null` when there is nothing to add.
+    </ResponseField>
+    <ResponseField name="retryable" type="boolean">
+      Whether re-running the same job could succeed.
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+
+See [Job output](/concepts/job-output) for the full shape and the single-file, stream, and set patterns, and [output files](/guides/ffmpeg#output-files) in the guide for worked request and response examples.
 
 ## See also
 
+- [Job output](/concepts/job-output): the output shape every job returns
 - [FFmpeg guide](/guides/ffmpeg): security model, allowed flags, examples
 - [CLI](/cli/overview): same job, terminal interface
 - [Job lifecycle](/concepts/job-lifecycle)
diff --git a/mcp/examples.mdx b/mcp/examples.mdx
index e04ff69..781a25b 100644
--- a/mcp/examples.mdx
+++ b/mcp/examples.mdx
@@ -81,7 +81,7 @@ The agent polls `get_job` every few seconds. A 30-second clip with subtitles tak
 
 ## Step 5: Download
 
-When `get_job` returns `status: "complete"`, it includes an `outputUrl`. The agent shows you a clickable link. Open it in your browser and the captioned video downloads.
+When `get_job` returns `status: "complete"`, it includes `output.file.url`. The agent shows you a clickable link. Open it in your browser and the captioned video downloads.
 
 ## What just happened
 
diff --git a/mcp/tools.mdx b/mcp/tools.mdx
index 2c21f79..4b0ae53 100644
--- a/mcp/tools.mdx
+++ b/mcp/tools.mdx
@@ -104,8 +104,8 @@ Poll a job by ID.
 
 - `waiting` / `dispatched`: `{ id, type, status }`
 - `running`: adds `progress` (0–1) and `step` (current step name)
-- `complete`: adds `cost` (e.g. `"$0.05"`), `durationMs`, `outputUrl`, `output: { format, resolution, durationMs, fileSizeBytes }`
-- `failed`: adds `error: { code, message }`
+- `complete`: adds `cost` and `output`. The `output` shape is the same for every job type: `{ data, file, files, expiresAt }`. Read `output.file.url` for the file to play or download, `output.data` for a computed answer. See [Job output](/concepts/job-output)
+- `failed`: adds `error: { code, message, detail, retryable }`
 - `cancelled`: terminal, no extra fields
 
 ## `list_jobs`
@@ -124,7 +124,7 @@ Recent jobs.
   1 to 50.
 </ParamField>
 
-**Returns:** `{ jobs: [{ id, type, status, createdAt, cost, outputUrl? }], total }`. `outputUrl` is included only when `status` is `complete`.
+**Returns:** `{ jobs: [{ id, type, status, createdAt, cost, output? }], total }`. `output` is included only when `status` is `complete`. Read `output.file.url` for the file, or `output.data` for a computed answer.
 
 ## `cancel_job`
 
diff --git a/quickstart.mdx b/quickstart.mdx
index 3c8d941..ee1e4c9 100644
--- a/quickstart.mdx
+++ b/quickstart.mdx
@@ -108,20 +108,39 @@ 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 an `output` object. The file to download is `output.file.url`, signed and valid for one hour:
 
 ```json
 {
   "data": {
     "id": "job_abc123",
     "status": "complete",
-    "outputUrl": "https://r2.rendobar.com/...",
-    "cost": { "nanodollars": 50000000, "formatted": "$0.05" }
+    "output": {
+      "data": null,
+      "file": {
+        "url": "https://r2.rendobar.com/...",
+        "path": "output.mp4",
+        "type": "video",
+        "size": 4194304,
+        "meta": { "format": "mp4", "width": 1280, "height": 720, "durationMs": 30000 }
+      },
+      "files": [
+        {
+          "url": "https://r2.rendobar.com/...",
+          "path": "output.mp4",
+          "type": "video",
+          "size": 4194304,
+          "meta": { "format": "mp4", "width": 1280, "height": 720, "durationMs": 30000 }
+        }
+      ],
+      "expiresAt": 1735689600000
+    },
+    "cost": { "amount": 50000000, "currency": "USD", "formatted": "$0.05" }
   }
 }
 ```
 
-Re-fetch the job to refresh the URL after it expires.
+Every job type returns this same `output` shape: `data` for a computed answer, `file` for the headline result, `files` for the full list. Re-fetch the job to refresh the URLs after they expire.
 
 ## What's next
 
diff --git a/snippets/poll-status.mdx b/snippets/poll-status.mdx
index 10dfd9c..fee0b42 100644
--- a/snippets/poll-status.mdx
+++ b/snippets/poll-status.mdx
@@ -1,4 +1,4 @@
-Poll `GET /jobs/{id}` until `status` is `complete`. The response then contains `outputUrl` (signed, 1-hour expiry) and `cost.formatted`.
+Poll `GET /jobs/{id}` until `status` is `complete`. The response then contains `output.file.url` (signed, 1-hour expiry) and `cost.formatted`.
 
 <CodeGroup>
 
diff --git a/support/limits.mdx b/support/limits.mdx
index a1fcb4d..a4fc3ce 100644
--- a/support/limits.mdx
+++ b/support/limits.mdx
@@ -47,8 +47,8 @@ Every limit Rendobar enforces, by plan. Pulled from `PLAN_LIMITS` in the API. Fo
 
 ## Output URLs
 
-- **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.
+- **Signed download URL** (`output.file.url`) 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 the file URLs return 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.