daun · daun · Jun 13, 2026 · Jun 13, 2026 · Jun 13, 2026 · Jun 13, 2026
diff --git a/README.md b/README.md
@@ -11,46 +11,47 @@
 
 ## Philosophy
 
-The main goal of this addon: **make working with videos as easy as working with images**. All the magic
-happens behind the scenes: videos are mirrored to your Mux account and can start streaming within seconds
-using the official `<mux-video>` web component as a drop-in replacement for the native video element.
+The main goal of this addon: **make working with videos as easy as working with images**.
+
+## How it works
+
+Videos uploaded to an asset container are mirrored to your Mux account. Within a few seconds, they can be streamed
+using the official `<mux-video>` web component, which is a drop-in replacement for the native video element.
 
 ## Features
 
 - **Automatic sync**  
   Mirror locally uploaded videos to your Mux account  
-- **Seamless video upload workflow**  
-  Just drop the original video files directly into the backend
+- **Standard upload workflow**  
+  Upload original video files into the control panel like any other asset
 - **No custom fieldtype required**  
   Handle and display videos like any other asset in Statamic
 - **Instant playback**  
-  Just-in-time encoding ensures videos can be streamed immediately
+  Videos can be streamed within seconds of upload, before full encoding completes
 - **Optimized streaming**  
-  Smart adaptive bitrates deliver the right resolution for your viewers' bandwith
+  Mux delivers a resolution matched to each viewer's bandwidth
 - **Customizable player**  
-  Tailor the video player component to match your site's design
-- **Real-time analytics**  
-  Get insights into your audience and video playback performance
+  Configure the Mux video player component to match your site's design
 - **Secure streaming**  
-  Protect your content using signed urls
+  Restrict access to videos using signed URLs
 
 ## Getting Started
 
 Read the docs on [Installation](https://statamic-mux.daun.ltd/installation) and
 [Connecting Mux](https://statamic-mux.daun.ltd/connecting-mux).
 
-## Responsive Video
+## Why a video service
 
-Just like image pipelines efficiently deliver optimized images for faster load times on a variety of devices
-and connections, video encoding services like Mux play a crucial role for optimizing video content.
-Video encoding demands more resources and expertise than image processing, so a dedicated service
-like Mux becomes essential for performant websites.
+Video encoding and delivery require more processing and storage than images. Serving video files directly
+from your origin server, without adaptive bitrate streaming, results in large downloads and inconsistent
+playback across devices and connections. A dedicated service handles encoding, storage, and adaptive
+delivery.
 
-## Why Mux?
+## Why Mux
 
-While there is a host of services for video encoding to choose from, Mux offers all the key
-components: encoding, storage, and delivery. It stands out with its API-first approach prioritizing
-developer productivity, as well as its official web components for creating rich, customized video players.
+Mux provides encoding, storage, and delivery through a single API. This addon uses Mux specifically because
+it exposes these features through an HTTP API and ships official web components for video playback, both of
+which the addon depends on.
 
 ## License
 

diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js
@@ -62,6 +62,7 @@ export default defineConfig({
               { text: 'mux:mirror', link: '/commands/mux-mirror' },
             ],
           },
+          { text: 'Control Panel', link: '/control-panel' },
           { text: 'GraphQL Types', link: '/graphql' },
           { text: 'Secure Playback', link: '/secure-playback' },
           { text: 'Configuration', link: '/configuration' },

diff --git a/docs/commands.md b/docs/commands.md
@@ -1,6 +1,10 @@
 # Artisan Commands
 
-The following commands are available for uploading videos manually or in regular intervals.
+The following commands upload videos manually or on a schedule.
+
+While the addon automatically uploads [mirrored videos](/upload) in the background, running the `mux:mirror`
+command on a schedule guards against misconfigured queues. If mirroring is already working, the command is a
+no-op and returns a success message.
 
 | Command | Description |
 |-------|-----------|

diff --git a/docs/commands/mux-mirror.md b/docs/commands/mux-mirror.md
@@ -2,7 +2,7 @@
 
 **Upload local videos to Mux, and remove orphaned Mux videos.**
 
-This basically runs `mux:upload` and `mux:prune` in sequence.
+Runs `mux:upload` and `mux:prune` in sequence.
 
 ```sh
 # Sync local assets to Mux

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -1,7 +1,7 @@
 # Configuration
 
-The addon config will be published to `config/mux.php` on installation. Read on
-for details on each available config option.
+The addon's config file is published to `config/mux.php` on installation. Each available option is
+described below.
 
 ## Credentials
 
@@ -81,10 +81,10 @@ return [
 
 ## Control Panel Thumbnails
 
-Configure the behavior of video thumbnails in the control panel. By default, the addon will render
-animated GIF previews of the first five seconds. This is great for editors to identify and work with
-videos, but uses more bandwidth than static images. You can disable this behavior entirely or switch
-to static images to save on bandwidth.
+Configure how video thumbnails are rendered in the control panel. By default, the addon renders
+animated GIF previews of the first five seconds, which helps editors identify videos but uses more
+bandwidth than static images. Set `animated` to `false` to use static images, or `enabled` to `false`
+to disable thumbnails entirely.
 
 ```php
 return [
@@ -129,9 +129,9 @@ return [
 Mux offers three quality levels. Learn more at
 [Choosing Video Quality](https://docs.mux.com/guides/use-video-quality-levels).
 
-- `basic` for apps with simpler needs that need to save on bandwidth & cost
-- `plus` for conistently high quality output, but incurs encoding cost
-- `premium` for premium high-detail content like sports broadcasts
+- `basic`: lower bandwidth and cost, lower quality
+- `plus`: consistently high quality, higher encoding cost
+- `premium`: highest quality, for high-detail content such as sports broadcasts
 
 ```php
 return [
@@ -172,6 +172,7 @@ return [
 
 Change the default playback behavior of video streams received from Mux.
 Applies to any videos or players rendered using the built-in Antlers tags.
+No modifiers are set by default; the entries below are examples.
 Learn more in the Mux docs on [Modifying Playback Behavior](https://docs.mux.com/guides/modify-playback-behavior).
 
 ```php
@@ -195,19 +196,18 @@ return [
 
 ## Storage Optimization
 
-Define how the addon handles original video files. In most cases, you'll want to
-stick with the default behavior and keep the original video files around to ensure
-long-term independence from any one video provider.
+Define how the addon handles original video files. By default, the original files are kept on your asset
+disk, which avoids depending solely on Mux for storage and lets you stream or download from your origin
+server as a fallback.
 
-If you need to save storage space on the server, you can configure the addon to
-replace video files with a smaller placeholder version. This will store a short
-10s clip of the video for previewing in the backend, but will require Mux for
-streaming and downloading the full video.
+To save storage space, set `store_placeholders` to `true` to replace each video file with a short clip
+(default 10 seconds, set by `placeholder_length`). The clip is used for previewing in the control panel;
+streaming and downloading the full video then requires Mux.
 
-Any videos shorter than the defined placeholder length will keep the original.
+Videos shorter than `placeholder_length` keep their original file.
 
-Note that this feature requires a [queue worker](https://laravel.com/docs/queues#running-the-queue-worker)
-to be running, as the video processing can take some time depending on the file size.
+This feature requires a running [queue worker](https://laravel.com/docs/queues#running-the-queue-worker),
+as processing can take time depending on file size.
 
 ```php
     /*
@@ -227,8 +227,8 @@ to be running, as the video processing can take some time depending on the file
 
 ## Queue Driver
 
-Define the queue driver to be used for uploads and other long-running requests to Mux.
-Leave it empty to use the default queue settings of your app.
+Define the queue connection and queue name used for uploads and other long-running requests to Mux.
+Leave `connection` empty to use your app's default queue connection.
 
 ```php
 return [
@@ -252,14 +252,12 @@ return [
 
 Configure the output and verbosity of the addon's logs.
 
-For troubleshooting uploads and getting insight into the processing of video files,
-you can increase the log level to `debug` temporarily. Make sure to set it back to
-`notice` or `warning` in production to avoid excessive log output.
+To troubleshoot uploads and see how video files are processed, increase the log level to `debug`
+temporarily. Set it back to `warning` in production to avoid excessive log output.
 
-The addon creates its own log channel, writing to `storage/logs/mux.log` and
-rotating biweekly. You can customize the log channel by either defining a `mux`
-channel of your own in `config/logging.php` or telling the addon to use a
-different channel entirely.
+The addon creates its own log channel, writing to `storage/logs/mux.log`. To customize it, either define
+your own `mux` channel in `config/logging.php`, or point the addon at a different channel via
+`MUX_LOG_CHANNEL`.
 
 ```php
 return [

diff --git a/docs/connecting-mux.md b/docs/connecting-mux.md
@@ -4,15 +4,15 @@ Register a Mux account and generate API credentials.
 
 ## Account
 
-If you haven't already, now is a good time to [register a Mux account](https://dashboard.mux.com/signup).
-Once you have an account, you need to [create an environment](https://dashboard.mux.com/environments).
-It's recommended to have separate Mux environments for each Statamic app environment like `development` and `production`.
+[Register a Mux account](https://dashboard.mux.com/signup) if you don't have one, then
+[create an environment](https://dashboard.mux.com/environments). Use a separate Mux environment for each
+Statamic app environment, e.g. `development` and `production`.
 
 ## Credentials
 
-To allow this addon to communicate with the Mux API, you'll need to create an Access Token in the
-[Access Token settings](https://dashboard.mux.com/settings/access-tokens) of your Mux account dashboard.
-Save the generated token and associated secret to your environment variables.
+The addon communicates with the Mux API using an access token. Create one in the
+[Access Token settings](https://dashboard.mux.com/settings/access-tokens) of your Mux dashboard, then save
+the generated token id and secret to your environment variables.
 
 ```env
 MUX_TOKEN_ID=b3b7fa9b-efd6-4723-bed2-032b04e61488

diff --git a/docs/control-panel.md b/docs/control-panel.md
@@ -0,0 +1,49 @@
+# Control panel
+
+The addon runs in the background and does not require manual intervention in normal operation. Even so,
+it can be useful to inspect the list of mirrored assets or browse your full Mux library. For that, you can
+enable dedicated control panel listings under **Tools → Mux** by granting the relevant permissions to
+the applicable roles.
+
+## Permissions
+
+The addon registers a permission group named **Mux**. Assign these permissions to roles under
+**Users → Permissions** in the control panel. No role has them by default.
+
+| Permission | Grants access to |
+|------------|--------|
+| **Manage Mux**  | Page showing assets mirrored to Mux |
+| **View Mux library** | Page listing all videos in the connected Mux account |
+| **Open Mux dashboard** | Opening links to the connected Mux account dashboard |
+| **Delete Mux assets** | Deleting videos from Mux via row and bulk actions |
+| **Trigger sync** | Running manual sync commands from the control panel |
+
+## Pages
+
+### Mirrored Assets
+
+Lists the local video assets in your Statamic asset containers alongside their Mux sync status.
+Use it to check which videos have been uploaded and to trigger uploads manually.
+
+Clicking an asset opens the Statamic asset editor. Per-row actions include opening the player page and
+copying the asset ID, playback ID, player URL, embed code, or thumbnail URL. Bulk actions cover uploading,
+reuploading, and deleting the selected videos on Mux.
+
+### Mux Library
+
+Lists all videos in the connected Mux account, including any that were not uploaded through this addon. Use
+it to review the full Mux library and reconcile it with your local assets. The library list is cached. The
+**Clear cache and reload** menu item fetches fresh data from the Mux API.
+
+Clicking an asset opens it in the connected Mux dashboard, if granted permission.
+
+## Manual sync
+
+Both pages include a **Sync** button that runs the addon's sync commands in the background, without needing
+shell access. Running the sync requires a working [queue worker](https://laravel.com/docs/queues#running-the-queue-worker),
+since uploads are queued.
+
+## Asset editor
+
+The [Mirror fieldtype](/upload) shows the upload status of an individual asset, both as a column in the
+asset browser and as a badge in the asset editor.
diff --git a/docs/display.md b/docs/display.md
@@ -1,12 +1,12 @@
 # Displaying Videos in Your Frontend
 
-Once uploaded to Mux, your videos are ready to be streamed within a few seconds, thanks to just-in-time encoding.
+Once uploaded to Mux, videos can be streamed within a few seconds through just-in-time encoding.
 
 ## Video Components
 
-Mux offers a set of [web components](https://github.com/muxinc/elements) that can be used as drop-in
-replacements of the native `video` element. Instead of a source file, they receive a Mux playback id to offer
-adaptive bitrate streaming.
+Mux provides a set of [web components](https://github.com/muxinc/elements) that act as drop-in
+replacements for the native `video` element. Instead of a source file, they take a Mux playback id and
+handle adaptive bitrate streaming.
 
 ### `mux-video`
 
@@ -21,9 +21,8 @@ and `loop` or events like `playing` will continue to work as expected.
 
 ### `mux-player`
 
-Wraps the native `video` element in a full-fledged customizable video player. Accepts the same attributes
-and emits the same events as a video element, but adds lots of useful interactive controls for video
-playback.
+Wraps the native `video` element in a customizable video player. Accepts the same attributes and emits the
+same events as a video element, and adds interactive playback controls.
 
 ```diff
 - <video src="/assets/video.mp4">

diff --git a/docs/graphql.md b/docs/graphql.md
@@ -6,7 +6,7 @@ Any Mux data available in the [Antlers tags](./tags) can also be queried via Gra
 
 Assuming you've added a [mirror field](/upload) called `mux` to your default asset container
 blueprint, you can query Mux data from the existing fieldname at `mux`. In your frontend, you can
-plug the returned data into  one of the official [Mux video components](/display#video-components).
+pass the returned data to one of the official [Mux video components](/display#video-components).
 
 ::: code-group
 

diff --git a/docs/index.md b/docs/index.md
@@ -17,27 +17,33 @@ hero:
 
 features:
   - title: Automatic sync
-    details: Mirror locally uploaded video files to your Mux account
+    details: Mirror locally uploaded videos to your Mux account
+    link: '/upload'
     icon: |
       <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.25" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-refresh-ccw"><path d="M21 12a9 9 0 0 0-9-9 9.75 9.75 0 0 0-6.74 2.74L3 8"/><path d="M3 3v5h5"/><path d="M3 12a9 9 0 0 0 9 9 9.75 9.75 0 0 0 6.74-2.74L21 16"/><path d="M16 16h5v5"/></svg>
-  - title: Seamless workflow
-    details: Upload original high-quality video files directly into your backend
+  - title: Standard upload workflow
+    details: Upload original video files into the control panel like any other asset
+    link: '/upload'
     icon: |
       <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.25" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-image-up"><path d="M10.3 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2v10l-3.1-3.1a2 2 0 0 0-2.814.014L6 21"/><path d="m14 19.5 3-3 3 3"/><path d="M17 22v-5.5"/><circle cx="9" cy="9" r="2"/></svg>
-  - title: Mix & match
+  - title: No custom fieldtype required
     details: Handle and display videos like any other asset in Statamic
+    link: '/upload'
     icon: |
       <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.25" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-gallery-vertical-end"><path d="M7 2h10"/><path d="M5 6h14"/><rect width="18" height="12" x="3" y="10" rx="2"/></svg>
   - title: Instant playback
-    details: Just-in-time encoding ensures videos can be streamed immediately
+    details: Videos can be streamed within seconds of upload, before full encoding completes
+    link: '/tags/mux-player'
     icon: |
       <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.25" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-gauge-circle"><path d="M15.6 2.7a10 10 0 1 0 5.7 5.7"/><circle cx="12" cy="12" r="2"/><path d="M13.4 10.6 19 5"/></svg>
   - title: Optimized streaming
-    details: Smart adaptive bitrates deliver the right resolution for your viewers' bandwith
+    details: Mux delivers a resolution matched to each viewer's bandwidth
+    link: '/tags/mux-player'
     icon: |
       <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.25" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-audio-lines"><path d="M2 10v3"/><path d="M6 6v11"/><path d="M10 3v18"/><path d="M14 8v7"/><path d="M18 5v13"/><path d="M22 10v3"/></svg>
   - title: Customizable player
-    details: Tailor the video player component to match your site's design
+    details: Configure the Mux video player component to match your site's design
+    link: '/tags/mux-player'
     icon: |
       <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.25" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-settings-2"><path d="M20 7h-9"/><path d="M14 17H5"/><circle cx="17" cy="17" r="3"/><circle cx="7" cy="7" r="3"/></svg>
 ---
diff --git a/docs/installation.md b/docs/installation.md
@@ -16,7 +16,7 @@ For Statamic 5 and Laravel 10/11 support, please use version 2.x of this addon.
 
 ## Frontend Scripts
 
-To stream videos from your frontend, you need a video player to handle adaptive bitrate streaming.
-Mux provides ready-to-go [web components](https://github.com/muxinc/elements) you can install
-through NPM or include from a CDN. If you use the built-in Antlers tags like [`mux:video`](/tags/mux-video), you
-can configure them to automatically include the required scripts.
+To stream videos on your frontend, you need a video player that handles adaptive bitrate streaming.
+Mux provides [web components](https://github.com/muxinc/elements) you can install through NPM or include
+from a CDN. The built-in Antlers tags like [`mux:video`](/tags/mux-video) can be configured to include
+the required scripts automatically.